This document belongs to RedNet Cloud — Enterprise Web Protection Management Platform
CLI tool: zcloud · 5 modules: guard / sys / analytics / cli_release / auth
Full API index: /api/openapi.json · Sitemap: /sitemap.xml · AI Quick Read: /llms.txt

API Documentation

Production-grade REST API documentation · 57 endpoints · 80+ chart-key data interfaces · Dual-channel authentication
Audience: integration engineers, SREs, SaaS integrators, AI agents
Reading order: §0 Conventions → §1 Authentication → jump to your business module

Table of Contents

Must Read

• §0 Overall Conventions — protocol / envelope / status codes / pagination / three audiences
• §1 Authentication (read first) — Bearer Session + API Key dual channel / scope narrowing

Public Endpoints (no auth)

• §2 CLI Release — version · install.sh · download · checksums
• §3 User Authentication — login · logout

Business Endpoints (dual-channel auth)

• §4 System Management
  • 4.1 User Management — /api/sys/users
  • 4.2 API Key Management — /api/sys/apikeys
  • 4.3 Permission Tree — /api/sys/permissions/tree
  • 4.4 Operation Audit — /api/sys/audit-logs, /api/sys/login-records
• §5 Guard Resource Management
  • 5.1 Domains — /api/guard/domains
  • 5.2 Certificates — /api/guard/certs
  • 5.3 Policies — /api/guard/policies
  • 5.4 CC Rules — /api/guard/policies/{id}/cc/rules
  • 5.5 ACL Rules — /api/guard/policies/{id}/acl/rules
  • 5.6 BW List — /api/guard/bwlist
  • 5.7 IP Forward — /api/guard/forwards
  • 5.8 DNS Scheduling — /api/guard/schedules
  • 5.9 WAF Rules — /api/guard/waf/rules

Plan Catalog

• §7 Plan Catalog — Read-only external: list · describe; admin ops excluded

Node Operations

• §8 Node Install / Upgrade — artifacts · commands · upgrades · jobs · tokens + installer-side script/package/env/report

Analytics (92 chart-keys · single-shape contract)

• §6.0 Common Calling Contract — 5-field contract / render_hint 8-word whitelist
• §6.1 Glossary · §6.2 Cross-page Batch · §6.3 Single-chart GET entry
• §6.4 Overview page · 8 chart-keys
• §6.5 Access page · 10 live + 15 planned chart-keys
• §6.6 Protect page · 12 live + 7 planned chart-keys (WAF / CC / DDoS)
• §6.7 AI page · 6 chart-keys
• §6.8 Bot page · 12 chart-keys
• §6.9 Alert page · 5 chart-keys
• §6.10 Health · 7 chart-keys
• §6.11 Ops · 8 chart-keys
• §6.12 Closure · 4 chart-keys
• §6.13 Cache · 4 chart-keys
• §6.14 Access Logs — non-chart endpoint
• §6.15 Reports — non-chart endpoint
• §6.16 CLI Mapping — 30 cobra command mapping

Reference

• §A Common Query Parameters — window / stime / etime / site_id / domain_id / target_user_id / compare / top / order
• §B Visualization Recommendations — B.1 render_hint lookup · B.2 data shape lookup
• §C Related Documentation

Full OpenAPI: /api/openapi.json · AI Quick Read: /llms.txt · Error Codes: /docs/errors · CLI: /docs/cli · Permissions: /docs/permissions

§0 Overall Conventions

The RedNet Cloud backend is a Gin-based RESTful service.

0.1 Basic Protocol

0.2 Unified Response Envelope

Every JSON response follows this three-field shape:

{
  "code": 0,
  "message": "ok",
  "data": { /* business payload, type depends on the endpoint */ }
}

Exceptions: file-export endpoints (POST /api/analytics/overview/export, GET /api/analytics/reports/:id/download, POST /api/analytics/logs/export) return raw binary or CSV/JSON streams, not wrapped in the envelope.

0.3 HTTP Status Codes

0.4 Pagination Convention

All list endpoints use page + size (not page_size):

Response shape:

{
  "code": 0,
  "data": {
    "list": [ /* ... */ ],
    "total": 42,
    "page": 1,
    "size": 20
  }
}

0.5 Cross-Module Design Markers (D*)

A few D* markers in this document come from cross-module design decisions. They warn integrators not to use fields that do not exist or have different semantics:

0.6 Three Audiences

§1 Authentication (read first)

RedNet Cloud supports two authentication channels. Pick exactly one per request:

Public endpoints (no auth) — only 5:

• GET /api/cli/version
• GET /api/cli/install.sh
• GET /api/cli/download/{filename}
• GET /api/cli/checksums.txt
• POST /api/auth/login

Every other endpoint must include one of the headers above. Examples in this doc default to Bearer; switch to API Key by replacing the header with Authorization: ApiKey zck_<prefix>.<secret> and ensure the key scopes cover the required permission.

1.1 API Key Permission Rule

effective_perms = user.RBAC ∩ key.scope

An API Key can never exceed the issuing user's current RBAC; scope can only narrow, not expand. After authentication, middleware injects the same user_id / role_id context as the session channel, so downstream RBAC/OEM isolation works identically.

Security guarantees:

• The plaintext API Key is returned exactly once in the create response; only key_hash (bcrypt digest) is stored
• If the user is locked or deleted, all API Keys under that user become invalid automatically
• If scopes is non-empty, the required permission must match one of them exactly; an empty array means full inheritance of the issuing user's RBAC
• Cross-OEM use is blocked by middleware: a 403 is returned when api_keys.oem_id mismatches the request hostname
• Optional IP allowlist allowed_ip_cidrs: if non-empty, only requests from matching CIDRs are accepted

Full API Key management endpoints are documented in §4.2.

§2 CLI Release (public endpoints)

Used for zcloud CLI self-update and one-line install. No authentication required.

GET /api/cli/version — Query latest CLI version

Purpose: clients self-check on startup; the install script /api/cli/install.sh calls this internally to decide which binary to download.

Authentication: none (public)

Input parameters: none

Output fields:

Visualization recommendation: plain text (version badge); not suitable for charts. Frontend may use this on a "System Settings - CLI version" page as a KPI card.

Example response:

{
  "code": 0,
  "message": "ok",
  "data": {
    "version": "v0.1.0-31",
    "binaries": [
      { "os": "linux",  "arch": "amd64", "download_url": "/api/cli/download/linux-amd64" },
      { "os": "linux",  "arch": "arm64", "download_url": "/api/cli/download/linux-arm64" },
      { "os": "darwin", "arch": "amd64", "download_url": "/api/cli/download/darwin-amd64" },
      { "os": "darwin", "arch": "arm64", "download_url": "/api/cli/download/darwin-arm64" }
    ]
  }
}

GET /api/cli/install.sh — One-line installer script

Purpose: install CLI on Linux/macOS in one command. Returns text/x-shellscript, suitable for curl ... | sh.

Authentication: none (public)

Input parameters: none

Output fields: a raw shell script (text); not wrapped in JSON envelope.

Visualization recommendation: not a chart; render as a code snippet.

Example:

curl -fsSL https://waf.example.com/api/cli/install.sh | sh

GET /api/cli/download/{filename} — Download a specific binary

Purpose: fetch the zcloud binary (signed) for a specific platform. filename matches the last segment of download_url returned by /api/cli/version (e.g. linux-amd64).

Authentication: none (public)

Input parameters:

Output fields: binary stream (application/octet-stream).

Visualization recommendation: not a chart.

GET /api/cli/checksums.txt — Binary checksums

Purpose: SHA256 integrity check for /api/cli/download/*. The install script fetches this before downloading the binary.

Authentication: none (public)

Input parameters: none

Output fields: plain text/plain with one <sha256> <filename> per line.

Visualization recommendation: not a chart.

§3 User Authentication

POST /api/auth/login — Login

Purpose: exchange username/password for a session token. Used by Web Console, interactive CLI login, mobile clients.

Authentication: none (public)

Input parameters (request body):

Output fields:

Visualization recommendation: login response is not charted; if need_change_password=true, the frontend should redirect to the change-password page.

Example request:

curl -X POST https://waf.example.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"'$(echo -n 'your_password' | base64)'"}'

Example response:

{
  "code": 0,
  "message": "ok",
  "data": {
    "token": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "u-admin",
    "user_name": "admin",
    "nick_name": "System Administrator",
    "need_change_password": false
  }
}

Common pitfalls:

• Sending plaintext password → backend base64-decode fails, returns generic "wrong username or password" without locating the real cause
• Reusing token across multiple endpoints → logout on one may affect others; recommend per-device login

POST /api/auth/logout — Logout

Purpose: actively invalidate the current Bearer token; subsequent requests with that token return 401.

Authentication: Bearer <token> (API Key has no logout concept; revoke via DELETE /api/sys/api-keys/:id)

Input parameters: none

Output fields: data is null.

Visualization recommendation: not a chart.

Example request:

curl -X POST https://waf.example.com/api/auth/logout \
  -H "Authorization: Bearer $TOKEN"

§4 System Management

4.1 User Management

Use case: CRUD users in the "System Settings - Users" page. All user endpoints are OEM-scoped; cross-OEM operations return 403.

GET /api/sys/users — User list (paged)

Purpose: render the user table on the "Users" page with keyword search and pagination.

Authentication: sys.user.list

Input parameters:

Output fields (data.list[]):

Visualization recommendation: table. locked column uses badges (green/red); roles rendered as chips.

Example request:

curl -H "Authorization: Bearer $TOKEN" \
  "https://waf.example.com/api/sys/users?page=1&size=20&keyword=admin"

Example response:

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "user_id": "u-001",
        "user_name": "admin",
        "nick_name": "System Administrator",
        "email": "admin@example.com",
        "mobile": "",
        "locked": 0,
        "role_ids": [1],
        "roles": [{ "role_id": 1, "name": "Super Administrator", "level": 1 }],
        "ctime": 1714521600000
      }
    ],
    "total": 42,
    "page": 1,
    "size": 20
  }
}

Common pitfalls:

• Treating role_ids as a single value → users may have multiple roles; always handle as an array
• Using level as a permission threshold → level is a display field (business hierarchy); use role_id as the permission threshold (see pitfall_role_level_vs_role_id)

POST /api/sys/users — Create user

Purpose: backend for the "Add User" form on the user management page.

Authentication: sys.user.create

Input parameters (request body):

Output fields: returns the new user object with the same shape as a list item.

Visualization recommendation: not a chart; one-shot write. Frontend should refresh the list after success.

Example request:

curl -X POST https://waf.example.com/api/sys/users \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"user_name":"u1","password":"InitPassw0rd!","nick_name":"Operator A","email":"u1@example.com"}'

DELETE /api/sys/users/{id} — Delete user

Purpose: backend for the "Delete" button on user management. Deletion cascades to sessions, API Keys, and role bindings.

Authentication: sys.user.delete

Input parameters:

Output fields: data is null.

Visualization recommendation: not a chart.

PUT /api/sys/users/{id}/password — Reset password

Purpose: an admin resets a user's password. The user is forced to change the password on next login.

Authentication: sys.user.resetpwd

Input parameters:

Output fields: data is null.

Visualization recommendation: not a chart.

Example request:

curl -X PUT https://waf.example.com/api/sys/users/u-001/password \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"password":"NewPassw0rd!"}'

Common pitfalls:

• Expecting frontend base64 encoding here → this endpoint accepts plaintext directly (login is base64 only for legacy reasons)

4.2 API Key Management

Use case: issue/revoke machine credentials in the "System Settings - API Keys" page. Pair with /api/sys/api-keys/:id/logs|stats|audit-actions for call auditing.

POST /api/sys/api-keys — Issue a new API Key

Purpose: issue a machine credential for scripts/CI/third-party systems. The plaintext api_key field is returned exactly once; the frontend must let the user copy and store it immediately.

Authentication: sys.apikey.create

Input parameters (request body):

Output fields:

Error codes:

• 1052 scope exceeds the user's RBAC boundary
• 1054 expires_in_days > 365
• 1055 name missing

Visualization recommendation: issuance is a one-shot write; frontend should use a modal with a one-time copy button + masked display (industry pattern: GitHub/Stripe).

Example request:

curl -X POST https://waf.example.com/api/sys/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"prod-integration","scopes":["guard.domain.list"],"expires_in_days":90}'

Example response:

{
  "code": 0,
  "data": {
    "key_id": "8f21c0c5-55ae-4cbd-a60a-8e64a6e2b1d0",
    "name": "prod-integration",
    "api_key": "zck_abc12345.A1b2C3d4E5f6G7h8I9j0K1L2M3n4O5p6Q7r8S9t0",
    "prefix": "zck_abc12345",
    "last4": "5t0",
    "expires_at": 1732982400000
  }
}

Common pitfalls:

• Storing the api_key field in your DB → store only key_id + prefix; hand the plaintext to the operator once
• Treating empty scopes as no permission → empty actually means full inheritance of current RBAC; pass an explicit list to narrow

GET /api/sys/api-keys — List API Keys

Purpose: render the API Keys list page with status for the current user / OEM.

Authentication: sys.apikey.list

Input parameters:

Output fields (data.list[]):

Visible scope:

• Regular users (role_id ≥ 10): only their own
• Platform users (role_id < 10: super-admin / ops / auditor): all keys in this OEM

Visualization recommendation: table. status rendered as a badge (green=active / gray=revoked); highlight rows where expires_at is < 7d. Combined with /stats, you can plot a "Top 5 Keys by call volume" bar chart.

Example request:

curl -H "Authorization: Bearer $TOKEN" \
  "https://waf.example.com/api/sys/api-keys?page=1&size=20"

DELETE /api/sys/api-keys/{id} — Revoke an API Key

Purpose: soft-revoke (status → revoked); audit trail is preserved. Middleware rejects subsequent requests where status != active.

Authentication: sys.apikey.delete

Input parameters:

Output fields: data is null.

Idempotency: re-revoking returns 200; the frontend can call repeatedly without errors.

Operable scope:

• Regular users: only their own
• Platform users: any key in this OEM (for emergency stop)

Error code: 1051 API Key not found or out of visible scope.

Visualization recommendation: not a chart; trigger from a "Revoke" button with a confirmation dialog.

Example request (using API Key as caller):

curl -X DELETE https://waf.example.com/api/sys/api-keys/8f21c0c5-55ae-4cbd-a60a-8e64a6e2b1d0 \
  -H "Authorization: ApiKey zck_abc12345.A1b2C3d4..."

GET /api/sys/api-keys/{id}/logs — Call audit log for a Key (E12)

Purpose: audit the call history of an API Key. Returns events from the audit table api_key_audit_logs.

Authentication: sys.apikey.logs

Input parameters:

Output fields (per record):

Visualization recommendation:

• Recommended chart: table + time-series line chart (call count aggregated by ctime)
• Derived metrics: success-rate stacked bar (split by status_code 2xx/4xx/5xx)

Visible scope:

• Regular users: only keys they issued
• Platform users: any key in this OEM (super-admin: all)

Error code: 1051 API Key not found or out of visible scope.

GET /api/sys/api-keys/{id}/stats — Aggregated statistics for a Key

Purpose: on the API Key detail page, show aggregate KPIs (total calls, success rate, QPS, top endpoints). Based only on event_type=call records.

Authentication: sys.apikey.stats

Input parameters:

Output fields:

Visualization recommendation:

• Recommended chart: KPI card grid (4 cards: total_calls / success rate / QPS / errors) + horizontal bar chart (top_endpoints)
• Derived metrics: pie chart (success / client_err / server_err)

Error codes: 400 since parse failed; 1051 API Key not found or out of visible scope.

Example request:

curl -H "Authorization: Bearer $TOKEN" \
  "https://waf.example.com/api/sys/api-keys/8f21c0c5-55ae-4cbd-a60a-8e64a6e2b1d0/stats?since=24h"

GET /api/sys/api-keys/audit-actions — Management action audit log (E13)

Purpose: cross-Key audit view; returns the management actions (create / revoke / renew / revoke-all) audit stream.

Authentication: sys.apikey.audit

Input parameters: page / size, standard pagination.

Output fields: same as GET /api/sys/api-keys/{id}/logs; event_type is always manage.

Visible scope:

• Regular users: only records where they are the operator (user_id = currentUserID)
• Platform users: all in this OEM (super-admin: all)

Visualization recommendation:

• Recommended chart: table sorted by ctime desc
• Derived metrics: bar chart aggregated by action (create / revoke / renew / revoke-all)

4.3 Permission Tree

GET /api/sys/permissions/tree — Permission tree

Purpose: returns the full permission tree (module / resource / action three layers + i18n names) for the current OEM. The frontend "Role Permissions" page renders the checkbox tree from this; the API Key scope picker also uses the same tree.

Authentication: authenticated session (no specific permission required)

Input parameters: optionally append Accept-Language: en-US to localize permission names.

Output fields (excerpt, data[]):

Visualization recommendation:

• Recommended chart: three-level tree (n-tree / el-tree), module → resource → action
• Reuse scenarios: API Key scope picker, role-permission checkbox tree

Example response (excerpt):

{
  "code": 0,
  "data": [
    {
      "module": "guard",
      "resources": [
        {
          "prefix": "guard.domain",
          "name": "Domains",
          "actions": [
            { "key": "list",   "name": "List domains",  "full_key": "guard.domain.list" },
            { "key": "view",   "name": "View domain",   "full_key": "guard.domain.view" },
            { "key": "create", "name": "Create domain", "full_key": "guard.domain.create" }
          ]
        }
      ]
    }
  ]
}

4.4 Operation Audit /api/sys/audit-logs · /api/sys/login-records

The console page "Log Center › Operation Audit" renders both endpoints as two tabs: operation logs and login records. Both are gated by sys.audit.view.

Data visibility (important) — narrowed in SQL at the repo layer, three tiers keyed on role_id (scopeOemID / scopeUserID in the handler):

No request parameter can target another user. keyword does LIKE against user_id / user_name, but it is ANDed with the scope clause and cannot widen it.

GET /api/sys/audit-logs — Operation logs

Purpose: audit trail of console writes — who changed what, before/after values, success or failure, and whether it was done on a customer's behalf.

Auth: sys.audit.view

Query parameters:

Response fields (excerpt of data.list[]; see the AuditLog schema in OpenAPI for the full set):

Label source of truth: a write route needs an entry in productionAuditSpecs (internal/middleware/audit_spec.go) to get a human label; query-style POSTs belong in productionReadOnlyAuditPosts and are not recorded at all. A write route in neither list lands as action=unregistered.business_operation with message=未登记业务操作; audit_spec_coverage_test.go guards against new ones.

GET /api/sys/login-records — Login records

Purpose: sign-in and staff-delegated sign-in trail — who signed in when, from which IP, using which method, and whether it succeeded.

Auth: sys.audit.view

Query parameters:

Response fields (excerpt of data.list[]; see the LoginRecord schema in OpenAPI for the full set):

§5 Guard Resource Management

📦 Guard Resource Management · 30 endpoints · used to configure protection objects (domains/certs/policies/CC&ACL rules/bwlist/forwards/schedules/WAF rules); the "configuration plane" of WAF protection.
Full schemas in /api/openapi.json. This section gives the most critical fields, enums, and common pitfalls for integration.

5.1 Domains /api/guard/domains

The domain is the core resource of Guard — every protection policy, certificate binding, and analytics aggregation anchors on domain_id.

GET /api/guard/domains — Domain list

Purpose: render the domain table on the "Protection - Domains" page; supports filtering by audit_status and keyword search.

Authentication: guard.domain.list

Input parameters:

Output fields (data.list[] = DomainVO):

Visualization recommendation:

• Recommended chart: table (primary) + top KPI cards (total / approved / pending) + switches rendered as a chip grid for switch states
• Derived metrics: pie chart (4-way split of audit_status)

Example request:

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains?page=1&size=20&audit_status=4"

Example response:

{
  "code": 0,
  "data": {
    "list": [
      {
        "domain_id": "d_8a3b1c",
        "domain": "api.example.com",
        "asset_name": "Production API gateway",
        "user_id": "u_abc",
        "policy_id": "p_default",
        "cname": "api.example.com.cname.zcloud.io",
        "auto_cert": false,
        "mode": 1,
        "audit_status": 4,
        "switches": { "waf": 1, "cc": 1, "acl": 1, "bot": 0, "cache": 1 },
        "ctime": 1714521600000,
        "utime": 1714608000000
      }
    ],
    "total": 8,
    "page": 1,
    "size": 20
  }
}

Common pitfalls:

• Paginating with page_size → the parameter is size; page_size is silently ignored
• Expecting protection_enabled / current_cert_id / origin_addr → these fields don't exist; protection switches live in the switches map; cert binding is queried via /api/guard/certs/:id/domains reverse lookup

POST /api/guard/domains — Create domain

Purpose: backend for the "Add Domain" form, creating a new protected domain.

Authentication: guard.domain.create

Input parameters (request body DomainCreateReq):

Why policy_id is required: a domain's WAF, CC, access-control, IP-list and BOT rules all live on the policy. A domain without one is proxied normally but enforces nothing — onboarded yet unprotected.

src_sites entries with the same address, port and protocol are deduplicated silently, without an error.

Either way works for certificates: pass cert_id here (domain, origins and certificate binding all happen in one transaction, rolled back as a whole on any failure), or call POST /api/guard/certs/:id/bind afterwards.

Output fields: returns DomainVO (same as a list item) with the assigned domain_id and cname.

Visualization recommendation: not a chart. After success, jump to the domain detail page or refresh the list.

GET /api/guard/domains/{id} — Domain detail

Purpose: fetch a single domain when entering the detail page.

Authentication: guard.domain.view

Input parameters: path id = domain_id.

Output fields: DomainVO, identical to a list item.

Visualization recommendation: form display. switches rendered as a switch group; audit_status as a badge.

PUT /api/guard/domains/{id} — Update domain

Purpose: edit mutable fields like asset_name, policy_id, auto_cert.

Authentication: guard.domain.edit

Input parameters (request body DomainUpdateReq):

Output fields: returns the updated DomainVO.

Visualization recommendation: not a chart.

DELETE /api/guard/domains/{id} — Delete domain

Purpose: remove the domain from the protection list. Deletion cascades to settings, cert bindings, analytics snapshots.

Authentication: guard.domain.delete

Input parameters: path id = domain_id.

Output fields: data is null.

Visualization recommendation: not a chart. Confirm twice in the UI; warn that "analytics and bindings will be cleaned up".

GET /api/guard/domains/{id}/settings — Get domain settings

Purpose: render the "Advanced Settings" tab on the domain detail page; shows current effective settings (protection module switches, cache policy, CC limits).

Authentication: guard.domain.view

Input parameters: path id = domain_id.

Output fields:

Visualization recommendation: form display; one config card per key.

GET /api/guard/domains/{id}/src-check-peers — Peers probing the same origin (read-only)

Purpose: Probes run per origin IP on the node, not per domain. When several domains of the same user point at the same origin IP, the node runs a single probe and uses the smallest interval among them — so a domain may show 60s in the UI while the origin is actually probed every 10s. This endpoint surfaces the peer configuration so the effective value is explainable.

Auth: guard.domain.settings (it reads the same domain settings; no separate permission).

Input: path id = domain_id.

Output:

Peer probe fields: detection_time_intervals (seconds, already reduced to the minimum), action (4 = alert only, 5 = switch traffic and alert), ports, fail_check_type, serial_failure_count, failure_ratio_windos, failure_ratio (integer percent 0-100).

Semantics: Strictly read-only — writes nothing and does not alter this domain's stored value. Scoped to the same user (matching zmod's where user_id = (...)); other tenants sharing the IP never appear here.

PUT /api/guard/domains/{id}/settings — Update domain settings

Purpose: modify the settings map for a domain.

Authentication: guard.domain.edit

Input parameters (request body DomainSettingsUpdateReq):

Output fields: data is null; the caller should issue a GET to fetch the new state.

Visualization recommendation: not a chart.

Common pitfalls:

• Passing top-level boolean fields → settings values are stringified JSON, not bool
• Inventing non-existent keys → backend whitelists; unknown keys return 400

PUT /api/guard/domains/{id}/origins/{service_id}/status — Toggle a service or origin

Permission: guard.domain.origin_status

Input: path id (domain ID) and service_id (src_configs[].service_id in the origin config).

Origin config carries two independent status levels: the public service (listen port + scheme) and each origin
inside it. "Service enabled, one origin individually disabled" is a state that exists in production. Origins are
located by ip+port (+optional line), never by index: an index depends on caller and stored order matching
exactly, so any add/remove in between would disable the wrong machine.

How this differs from PUT /api/guard/domains/{id}/settings: that endpoint takes the whole JSON blob, read
modified and written back by the caller. Origin config lives in the shared guard_domain_settings.service_config_setting
row that the legacy platform also reads and writes; rebuilding the blob and dropping any single key corrupts it.
This endpoint only states which entry to toggle — the JSON edit happens server-side and every other key (including
keys this platform does not recognise) is preserved verbatim. Values written are the string enums
CFGOPTION_2_ENABLE / CFGOPTION_1_DISABLE.

Still enforced: tenant isolation, and the domain must keep at least one enabled ordinary HTTP/HTTPS origin.
A status change triggers config delivery.

Output: none.

GET /api/guard/domains/{id}/dns/advance/config — Get DNS advanced settings

Purpose: query the DNS scheduling advanced settings: auto return-to-origin, minimum active node records, IPv6 checks. Fields mirror the zmod "DNS Advanced Settings" dialog and gen-server DnsAdvanceConfig.

Auth: guard.domain.settings (disp_config_setting is already on the generic settings whitelist — same data through another door, no separate permission).

Input: path id = domain_id.

Output fields (data is DnsAdvanceConfigVO):

Semantics: when either src_ipv6_check or default_ipv6_check is enabled, the records rebuild generates AAAA records for IPv6-capable nodes/origins — this is the switch for IPv4/IPv6 dual-stack access.

Example:

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/dns/advance/config"

PUT /api/guard/domains/{id}/dns/advance/config — Update DNS advanced settings

Purpose: update the DNS advanced settings. Mirrors the zmod dialog: only the four fields below are written; every other key stored in disp_config_setting (total_count/ava_ratio/max_count/auto_switch/cname, etc.) is preserved as-is.

Auth: guard.domain.settings

Input (request body DnsAdvanceConfigUpdateReq, all four required):

Output: data is null.

Semantics: saving does not touch existing DNS records; IPv6 toggles apply on the next records rebuild (POST /api/guard/schedules/domains/{id}/init), including AAAA record add/remove. Enums must be string names — numeric forms are rejected by gen-server's types.CFGOPTION.

Example:

curl -X PUT -H "Authorization: ApiKey $ZCLOUD_API_KEY" -H "Content-Type: application/json" \
  -d '{"auto_switch_case":1,"auto_return_source":"CFGOPTION_1_DISABLE","src_ipv6_check":"CFGOPTION_2_ENABLE","default_ipv6_check":"CFGOPTION_2_ENABLE"}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/dns/advance/config"

Domain Onboarding UX Revamp · Backend Interface Audit (2026-06-26)

The frontend is upgrading the domain management page into a three-stage UX: "inline row jumps → domain workbench → onboarding wizard". Audit conclusion: mostly frontend orchestration of existing endpoints; after the domain workbench (Phase 2) shipped, two backend supplements were found in practice (see "Backend supplements found in practice" below). Mapping:

Backend supplement ① (detail fields shipped)

GET /api/guard/domains/{id} now adds cert_id + nodes + shadow_cache_addr onto the existing DomainVO. settings and parsing_state still come from their existing separate endpoints (GET /domains/{id}/settings, GET /schedules/domains).

Target response shape (add 2 fields onto the existing DomainVO, aligning with frontend DomainDetailVO):

{
  "domain_id": "...", "domain": "...", "cname": "...", "switches": {},
  "cert_id": 12,
  "shadow_cache_addr": "192.168.14.103",
  "nodes": [
    { "id": 1, "ip_addr": "1.2.3.4", "node_id": "n-001", "enabled": 1, "line": 0 }
  ]
}

The frontend can directly read detail.cert_id (then GET /certs/{id} for common_name/expiry/cert_type) and detail.nodes (node table).

Wizard usage (①.5): POST /domains now consumes src_sites + cert_id directly — the domain, its origin configuration and the certificate binding all happen in one transaction, rolled back as a whole on any failure. The wizard creates everything in that single call and no longer needs the "create domain → POST /forwards per origin → POST /certs/{id}/bind/{domainId}" workaround. The step-by-step endpoints still exist, for adding origins to or rebinding certificates on an existing domain.

POST /api/guard/domains/{id}/verify — Active domain onboarding probe

Purpose: actively check origin reachability and whether public DNS points to the assigned CNAME for the onboarding wizard.

Authentication: guard.domain.verify

Input parameters: path id = domain_id.

Output fields:

Origin Groups /api/guard/domains/{id}/origin-groups

Origin group: one group = a set of protection nodes bound to the subset of origin servers they pull from, making "which node pulls from which origins" controllable (e.g. telecom nodes pull from telecom origins). Each domain has exactly one default origin group (holds all origins, cannot be deleted, fallback for ungrouped nodes); a node belongs to exactly one group within a domain; if any origin in a group is IPv6, the group must contain at least one IPv6-capable node. All 3 endpoints require guard.domain.origin_group.

GET /api/guard/domains/{id}/origin-groups — List origin groups

Purpose: list origin groups of the domain (default group first, then custom groups).

Authentication: guard.domain.origin_group

Input parameters: path id = domain_id.

Output fields (data.list[] is OriginGroupVO):

Example request:

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/origin-groups"

POST /api/guard/domains/{id}/origin-groups — Create origin group

Purpose: regroup operation — the selected nodes are pulled out of their previous groups into the new one; any custom group left empty is deleted automatically and its members fall back to the default group. Node/origin metadata is backfilled by the server; clients only send identifiers.

Authentication: guard.domain.origin_group

Input parameters (path id = domain_id; request body OriginGroupCreateReq):

Output fields: data is the created group's OriginGroupVO (same shape as list items).

Errors (400): duplicate/reserved group name, missing default group, node not bound to the domain, origin not in the domain's origin config, group contains an IPv6 origin but no IPv6-capable node.

Example request:

curl -X POST -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"telecom","node_ids":["n-a","n-b"],"src_ips":["10.0.0.1","10.0.0.2"]}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/origin-groups"

DELETE /api/guard/domains/{id}/origin-groups/{group_id} — Delete custom origin group

Purpose: delete a custom origin group; its nodes and origins are merged back into the default group. The default origin group cannot be deleted.

Authentication: guard.domain.origin_group

Input parameters: path id = domain_id, path group_id = group ID (int64).

Output fields:

Errors: 404 group not found; 400 the default group cannot be deleted.

Example request:

curl -X DELETE -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/origin-groups/5301"

PUT /api/guard/domains/{id}/audit — Domain Audit

Purpose: audit a domain. Newly created domains default to audit_status=1 (unaudited) and are not pushed to protection nodes until approved; setting 4 (approved) automatically triggers config distribution.

Authentication: platform-level roles only (role_id < 10) with guard.domain.audit; business roles receive 403 even if this permission was granted accidentally.

Input parameters (path id = domain_id; request body):

Output fields:

Errors: 400 invalid audit_status; 403 non-platform role or insufficient permission; 404 domain not found or not accessible.

Example request:

curl -X PUT -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audit_status":4}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/audit"

Domain Node Assignment /api/guard/domains/{id}/nodes

Node assignment: which protection nodes a domain is bound to determines which nodes carry and scrub its traffic. All 5 per-domain endpoints require guard.domain.node; successful assign/remove calls trigger config re-distribution, while lock only changes state without re-distribution. There is also an ops reconciliation entry POST /api/guard/domains/nodes/sync (guard.domain.edit, not exposed in the console, CLI only) — see the end of this section.

GET /api/guard/domains/{id}/nodes — List assigned nodes

Purpose: list protection nodes assigned to the domain, with lock status and node metadata.

Authentication: guard.domain.node

Input parameters: path id = domain_id.

Output fields (data.list[] is DomainAssignedNodeVO):

Errors: 404 domain not found or not accessible.

Example request:

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/nodes"

GET /api/guard/domains/{id}/nodes/available — List assignable nodes

Purpose: list nodes still assignable to the domain (account node pool minus already-assigned).

Authentication: guard.domain.node

Input parameters: path id = domain_id.

Output fields (data.list[] is AssignableNodeVO): node_id / name / machine_room / ip_addr / line / ipv6 (same meanings as the table above, without lock_status).

Errors: 404 domain not found or not accessible.

Example request:

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/nodes/available"

PUT /api/guard/domains/{id}/nodes — Assign nodes

Purpose: assign nodes to the domain (incremental; already-assigned nodes are skipped). The nodes are also synced into CNAME DNS records: with enable_parse=true the records are enabled at the same time (effective in node dispatch mode; in origin mode only last_status is synced and the records auto-enable on the next acceleration); without it the records are created but stay disabled. A successful call triggers config re-distribution.

Authentication: guard.domain.node

Input parameters (path id = domain_id; request body DomainNodeAssignReq):

Output fields (data is DomainNodeAssignResultVO):

Errors: 400 selected node cannot be assigned (not in the account node pool or already assigned); 404 domain not found or not accessible.

Example request:

curl -X PUT -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"node_ids":["n-a","n-b"],"enable_parse":false}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/nodes"

DELETE /api/guard/domains/{id}/nodes/{node_id} — Remove a node

Purpose: remove a node from the domain. A successful call triggers config re-distribution.

Authentication: guard.domain.node

Input parameters: path id = domain_id, path node_id = node ID.

Protective rejections (400):

• the node's DNS records are still enabled (disable parsing first);
• parsing was disabled less than 30 minutes ago (DNS cache blackhole protection);
• the node IP is referenced by port forwarding rules (adjust them first);
• removal would leave no default-line record in node dispatch mode (configure a default line on another node first).

Output fields:

Errors: 400 see protective rejections above; 404 domain not found or the node is not assigned to the domain.

Example request:

curl -X DELETE -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/nodes/n-a"

PATCH /api/guard/domains/{id}/nodes/{node_id}/lock — Lock/unlock a node

Purpose: lock or unlock a node of the domain. When locked (2), config rendering and distribution skip the node while the binding is kept; unlocking (1) restores it. Status-only change; does not trigger re-distribution.

Authentication: guard.domain.node

Input parameters (path id = domain_id, path node_id = node ID; request body DomainNodeLockReq):

Output fields:

Errors: 400 invalid lock status (only 1/2 allowed); 404 domain not found or the node is not assigned to the domain.

Example request:

curl -X PATCH -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lock_status":2}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/nodes/n-a/lock"

POST /api/guard/domains/nodes/sync — Node assignment reconciliation (ops)

Purpose: ops reconciliation tool — fully aligns node bindings of ALL domains with the upstream (aeg) per-user node allocation (adding missing bindings, removing surplus ones). Run it once after nodes are reclaimed to batch-clean ghost bindings. It overwrites manual per-domain fine-grained assignment; for day-to-day incremental assignment use PUT /api/guard/domains/{id}/nodes instead. The console no longer exposes this entry (CLI only: zcloud guard domains nodes sync). Changed domains trigger config re-distribution.

Authentication: guard.domain.edit. Platform-level users may target one customer via ?user_id=; business-level users only reconcile their own domains.

Input parameters: query user_id (optional) = only reconcile domains of the given user.

Output fields (data is DomainNodeSyncVO):

Example request:

curl -X POST -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/nodes/sync"

Domain Anti-Brute-Force Rules /api/guard/domains/{id}/brute-force/rules

Anti-brute-force: per-domain request-rate rules — when the same source IP / bot session exceeds the request threshold against a given URI within the counting window, the configured action is executed (block / redirect / captcha, etc.). Rules live in a shared table and are distributed to nodes; all 4 endpoints require guard.domain.bruteforce; successful create/update/delete calls trigger config re-distribution. Weak-password interception is NOT part of this group — it goes through the existing domain settings endpoints via the guard_weak_password_setting key (GET/PUT /api/guard/domains/{id}/settings).

GET /api/guard/domains/{id}/brute-force/rules — List rules

Purpose: list the domain's anti-brute-force rules (descending by rule ID).

Authentication: guard.domain.bruteforce

Input parameters: path id = domain_id.

Output fields (data.list[] is BruteForceRuleVO):

action object fields:

Errors: 404 domain not found or no access.

Example request:

curl -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/brute-force/rules"

POST /api/guard/domains/{id}/brute-force/rules — Create a rule

Purpose: create an anti-brute-force rule. The rule ID is server-generated; status is forced to true by the server (rules are enabled on creation). A successful call triggers config re-distribution.

Authentication: guard.domain.bruteforce

Input parameters (path id = domain_id; request body BruteForceRuleCreateReq, same fields as BruteForceRuleVO above without id). Notes:

• Unit fields (req_time_unit / action.block_time_unit / action.window_unit) only accept the enum-name strings ReqUnit_1_PSec / ReqUnit_2_PMin (numbers fail to parse); level only accepts ip / bot_session. Other values return 400.
• action.action_type is not hard-validated by the server and is stored as-is (aligned with the legacy platform); the valid values are those in the table above.
• Any status value in the body is ignored — the created rule is always true.

Output fields (data is the created BruteForceRuleVO, including the server-generated id).

Errors: 400 invalid body / enum value; 404 domain not found or no access.

Example request:

curl -X POST -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"login-guard","describe":"login endpoint rate limit","uri":"/login","rate":10,"rate_time":60,"req_time_unit":"ReqUnit_1_PSec","level":"ip","action":{"action_type":"block","block_time":10,"block_time_unit":"ReqUnit_2_PMin"}}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/brute-force/rules"

PUT /api/guard/domains/{id}/brute-force/rules/{rule_id} — Update a rule

Purpose: update an anti-brute-force rule — the whitelisted fields (name/describe/uri/rate/rate_time/req_time_unit/status/level/action) are overwritten as a whole row; omitted fields are written as zero values. rule_id must belong to the domain (prevents cross-domain edits of the shared table). status is stored as sent (can be used to disable a rule). A successful call triggers config re-distribution.

Authentication: guard.domain.bruteforce

Input parameters: path id = domain_id, path rule_id = rule ID; request body BruteForceRuleUpdateReq (same fields and enum constraints as create).

Output fields (data is the updated BruteForceRuleVO).

Errors: 400 invalid body / enum value or non-numeric rule_id; 404 domain not found, rule not found, or rule does not belong to the domain.

Example request:

curl -X PUT -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"login-guard","describe":"login endpoint rate limit","uri":"/login","rate":20,"rate_time":1,"req_time_unit":"ReqUnit_2_PMin","status":true,"level":"bot_session","action":{"action_type":"captcha"}}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/brute-force/rules/20220414"

DELETE /api/guard/domains/{id}/brute-force/rules/{rule_id} — Delete a rule

Purpose: delete an anti-brute-force rule (detaches it from the domain and physically deletes the row); rule_id must belong to the domain. A successful call triggers config re-distribution.

Authentication: guard.domain.bruteforce

Input parameters: path id = domain_id, path rule_id = rule ID.

Output fields:

Errors: 400 non-numeric rule_id; 404 domain not found, rule not found, or rule does not belong to the domain.

Example request:

curl -X DELETE -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/brute-force/rules/20220414"

Domain Cache Actions /api/guard/domains/{id}/cache

Cache actions: warm up / purge the domain's CDN cache. Both endpoints are asynchronous: the server builds a CDN cache instruction from the domain's node bindings and public-facing service config, then dispatches it to the nodes through the legacy-platform gen-service (zRPC cmd=554 → MQ) — send-and-return: nothing is persisted and there is no endpoint to query the execution result; a success response only means the instruction was submitted to the dispatch channel. Both endpoints require guard.domain.cache. Cache rules / advanced config / warm-up resource list are NOT part of this group — they go through the existing domain settings endpoints via the cache_config_v2_setting key (GET/PUT /api/guard/domains/{id}/settings).

POST /api/guard/domains/{id}/cache/warm — Warm up cache resources

Purpose: warm up the given resources into node caches (aligned with the legacy platform's "cache warm-up", cache instruction cmd_type=2). Asynchronous: send-and-return.

Authentication: guard.domain.cache

Input parameters (path id = domain_id; request body):

Output fields:

Errors: 400 invalid request body, no nodes assigned to the domain, or public-facing service config (service_config_setting) missing/invalid; 404 domain not found or no access; 500 dispatch channel unavailable.

Example request:

curl -X POST -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cache_res":"/index.html,/static/app.js"}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/cache/warm"

POST /api/guard/domains/{id}/cache/purge — Purge cache resources

Purpose: purge the given resources from node caches (aligned with the legacy platform's "cache purge", cache instruction cmd_type=1). Asynchronous: send-and-return.

Authentication: guard.domain.cache

Input parameters (path id = domain_id; request body):

Output fields:

Errors: 400 invalid request body, no nodes assigned to the domain, or public-facing service config (service_config_setting) missing/invalid; 404 domain not found or no access; 500 dispatch channel unavailable.

Example request:

curl -X POST -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cache_res":"/index.html,/static/app.js"}' \
  "https://waf.example.com/api/guard/domains/d_8a3b1c/cache/purge"

5.2 Certificates /api/guard/certs

Certificate flow is a two-step process: "upload PEM → bind to domain". Content-Type is application/json, not multipart/form-data.

Three certificate types (certificate_type, same values as the legacy platform's shared table):

ssl_password_file (encrypted-cert credential / private-key passphrase) is optional for types 1 and 2, and ignored for type 3 since there is no local private key.

GET /api/guard/certs — Cert list

Purpose: table on the "Protection - Certificates" page.

Authentication: guard.cert.list

Input parameters: page / size / keyword (search name/common_name).

Output fields (data.list[] = CertVO):

Field bound_domains does not exist; query bound domains via GET /api/guard/certs/{id}/domains.

Visualization recommendation:

• Recommended chart: table + near-expiry highlight (expired_at - now < 30d colored row)
• Derived metrics: KPI cards (total / expiring in 30d / expired); pie chart (auto_cert true/false)

POST /api/guard/certs — Upload certificate

Purpose: upload one PEM cert. The most common integration pitfall is using multipart/form-data; please use JSON.

Authentication: guard.cert.create

Security note: direct integrations still pass cert / key as JSON PEM strings. Do not put private keys in AI chats, tickets, logs, or telemetry. When operating through the Aegeon Cloud conversational assistant, prefer its secure certificate attachment flow: the browser uploads the cert/key to Aegeon and the chat only contains an attachment reference; the private key is not stored in the AI message.

Input parameters (request body CertUploadReq, application/json):

Output fields: returns the new CertVO.

Visualization recommendation: not a chart. The frontend upload component should support both "paste PEM" and "read local file".

Example request:

curl -X POST https://waf.example.com/api/guard/certs \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"prod-2026","cert":"-----BEGIN CERTIFICATE-----\nMII...\n-----END CERTIFICATE-----","key":"-----BEGIN PRIVATE KEY-----\nMII...\n-----END PRIVATE KEY-----"}'

GM / keyless examples:

# GM NTLS: all four materials (signing pair + encryption pair) are mandatory
curl -X POST https://waf.example.com/api/guard/certs \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"gm-2026","certificate_type":2,"sign_cert":"-----BEGIN CERTIFICATE-----\n...","sign_key":"-----BEGIN PRIVATE KEY-----\n...","cert":"-----BEGIN CERTIFICATE-----\n...","key":"-----BEGIN PRIVATE KEY-----\n..."}'

# Keyless: cert plus the keyless server address only
curl -X POST https://waf.example.com/api/guard/certs \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"keyless-2026","certificate_type":3,"cert":"-----BEGIN CERTIFICATE-----\n...","no_key_tls_addr":"10.0.0.9:8443"}'

Common pitfalls:

• Using multipart/form-data to upload files → backend doesn't support it; returns 400
• Type 2 with only sign_cert/sign_key and no encryption pair → 400; all four GM materials are mandatory
• Type 3 without no_key_tls_addr → 400; nodes need it to reach the keyless server
• GM material that is not SM2 (RSA/ECDSA PEM pasted in) → 400. The legacy platform swallows the parse error and stores the record anyway; cloud deliberately rejects it so the problem is caught before deployment
• Passing file paths in cert / key → must be the PEM text content itself
• Pasting private keys into AI chat or logs → use a secure attachment / secret-handling path and let the server decrypt only when calling this API

GET /api/guard/certs/{id} — Cert detail

Purpose: detail page; includes full PEM text.

Authentication: guard.cert.view

Input parameters: path id.

Output fields: CertDetailVO = CertVO + cert + sign_cert (PEM text, useful for download) + no_key_tls_addr + has_ssl_password.

Private key material (key / sign_key) is never returned. no_key_tls_addr is not a secret and comes back so the edit form can pre-fill it.
The passphrase (ssl_password_file) is not echoed either — only the boolean has_ssl_password. It unlocks the private key, so returning it would let any read-only account with guard.cert.view walk away with it. The legacy platform is write-only here too.
Consequently an empty passphrase field on edit means keep the current one; clearing requires explicitly submitting an empty string.

Visualization recommendation: form display. Add a "Download cert" button (frontend assembles PEM into a download).

Keyless package endpoints

These endpoints require guard.cert.download. They return public release
metadata or a release artifact only; they never accept, assemble, or record a
business private key. First deployment does not require a certificate_type=3
certificate: Keyless must be installed first to obtain the HOST:8443
address required by that form.

GET /api/guard/keyless/package returns the version, Linux
architectures, SHA-256 values for the ZIP verification bundle and enclosed
tar.gz, integrity-verification state, and a usage guide. Controlled CI builds
each release from the repository-vendored, source-only KeyServer snapshot,
cross-builds Linux amd64/arm64, and copies it with its SHA-256 checksum files
into the immutable Cloud server image. The backend rechecks package and ZIP
integrity before exposing it;
the release directory defaults to /app/releases/keyless.

POST /api/guard/keyless/package/download

Request body:

{"arch":"amd64"}

The response is a ZIP verification bundle with X-Artifact-SHA256. It contains
the tar.gz, SHA-256, and VERIFY.txt; verify the tar.gz according to VERIFY.txt
before extracting it. The download action is written to the operation audit
log. Any package with a missing or invalid checksum or bundle structure is not
downloadable. The
package includes verify-package.sh, install.sh, provision.sh, restart.sh,
status.sh and verify-transport.sh; the full instructions are in
docs/QUICKSTART.md. First install can run:

sudo ./scripts/install.sh --copy-private-key-file /absolute/path/to/business.key --enable

The recommended one-command installation reads and validates the source key
only on the target Linux host, then copies it to
/etc/keyless/keys/business.key (keyless:keyless, mode 0600). The source
is not modified or uploaded. Advanced users may keep a direct path with
--private-key-file or user.yml, provided the keyless user can read it and
search every parent directory.

Once the service is running and its reachable HOST:8443 is known, create a
Keyless certificate in the platform, paste the matching public fullchain, and
enter that address. KeyServer reads only the unencrypted RSA PEM/DER private
key on the target Linux host and does not load the platform certificate chain.
TLS connectivity does not mean remote signing was verified.

Integrations with an existing Keyless certificate may continue to use the
compatibility endpoints /api/guard/certs/{id}/keyless/package and
/api/guard/certs/{id}/keyless/package/download; new UI and first deployment
should use the certificate-independent endpoints above.

PUT /api/guard/certs/{id} — Update cert

Purpose: replace PEM directly (no need to delete-then-create).

Authentication: guard.cert.edit

Input parameters (request body CertUpdateReq, same fields as upload but all optional): name / certificate_type / cert / key / sign_cert / sign_key / no_key_tls_addr / ssl_password_file.

• An empty string means "leave unchanged" for every field except ssl_password_file, which uses JSON null/omission for "unchanged" and an empty string to clear the passphrase.
• Material you do not submit is carried over from the stored record (e.g. changing only no_key_tls_addr on a keyless cert reuses the stored certificate — no need to re-paste the PEM) — but only while certificate_type stays the same.
• Omitting certificate_type keeps the current type. Switching type rebuilds the whole record and explicitly clears mutually exclusive fields (standard → keyless clears key; GM → standard clears sign_cert/sign_key). Across a type switch the private key, signing pair and keyless address are never carried over and must be resubmitted (the cert itself still carries over).
• Replacing the material still has to cover bound domains: if the new CN/SAN does not cover a bound domain the API returns 400 and you must unbind first.

Output fields: returns the updated CertVO.

DELETE /api/guard/certs/{id} — Delete cert

Authentication: guard.cert.delete

Input parameters: path id.

Output fields: data is null.

Side effect: deletion auto-unbinds the cert from all bound domains.

GET /api/guard/certs/{id}/domains — List domains bound to a cert

Purpose: on the cert detail page, show "which domains is this cert protecting".

Authentication: guard.cert.view

Input parameters: path id.

Output fields (data[] = CertDomainVO[]):

Visualization recommendation: table.

POST /api/guard/certs/{id}/bind — Bind cert to domain

Purpose: bind a specific cert to a domain.

Authentication: guard.cert.edit

Input parameters (request body CertBindReq):

Output fields: data is null.

Visualization recommendation: not a chart.

DELETE /api/guard/certs/{id}/bind/{domainId} — Unbind cert from domain

Purpose: break the binding between a cert and a domain.

Authentication: guard.cert.edit

Input parameters: path id = cert ID; path domainId = domain ID.

Output fields: data is null.

Path: it is DELETE /bind/{domainId}, not POST /unbind.

Certificate Management UX Revamp · Backend Supplement Audit (2026-06-29)

The frontend is redesigning the certificate page (expiry overview + bound domains + SM2/国密 upload). Conclusion: the core capabilities already exist (list / upload incl. SM2 sign_cert·sign_key / detail with PEM / bind·unbind / GET /certs/{id}/domains); the redesign is mostly frontend type-alignment + wiring. Suggested backend supplements / clarifications:

No backend needed: SAN list / fingerprint / serial / key size detail fields can be parsed client-side by the frontend from the cert (full PEM) returned by GET /certs/{id}; no extra backend fields required.
Frontend to align (not a backend item, memo): the frontend CertVO type still uses old field names (cert_type/user_id); the backend actually returns certificate_type/user_name; CertDetailVO.domains[] does not exist on the backend (bound domains go through GET /certs/{id}/domains). The frontend will fix these — no backend work.

5.3 Policies /api/guard/policies

A policy is a rule container: CC / ACL / bwlist all attach to a policy. One domain binds one policy.

GET /api/guard/policies — Policy list

Authentication: guard.policy.list

Input parameters: page / size / keyword.

Output fields (data.list[] = PolicyVO):

switches is returned by the create / detail / list endpoints alike (they share the same VO); the site onboarding wizard uses it to show which protections the selected policy currently has on. Defaults for a newly created policy: waf=GuardMode_3_Enable, cc / acl / ddos / anti_crawler / black_white_list / user_priority = CFGOPTION_2_ENABLE, everything else CFGOPTION_1_DISABLE (geo / acl_rule stay CFGOPTION_0_UNKNOWN).

Visualization recommendation: table + three chips (cc/bwl/acl counts).

POST /api/guard/policies — Create policy

Authentication: guard.policy.create

Input parameters (PolicyCreateReq): name (required) / comment.

Name uniqueness: scoped to the owner (user_id), not global — different users may reuse the same policy name. When the owner already has a policy with that name the request does not fail; the server automatically appends an _01/_02… sequence suffix (same behaviour as the legacy zmod CheckPolicyNameAlready). If the requested name already carries an _0N suffix it is stripped first and the search restarts from _01.

Output fields: returns the new PolicyVO. The persisted name is whatever data.name says; it may differ from the requested name, so echo that value back to the user.

GET /api/guard/policies/{id} — Policy detail

Authentication: guard.policy.view

Input parameters: path id.

Output fields: PolicyVO.

PUT /api/guard/policies/{id} — Update policy

Authentication: guard.policy.edit

Input parameters (PolicyUpdateReq): name / comment.

Name uniqueness: renaming checks for duplicates within the policy owner's own policies (excluding itself), matching the legacy zmod "update guard policy" handler. A collision returns business code 2004 (err.guard.policy.name_exists); unlike creation it is not auto-suffixed.

Output fields: returns the updated PolicyVO.

DELETE /api/guard/policies/{id} — Delete policy

Authentication: guard.policy.delete

Input parameters: path id.

Output fields: data is null. Ensure no domain references this policy before deleting.

POST /api/guard/policies/{id}/copy — Copy policy

Authentication: guard.policy.copy

Input parameters: path id (source policy). All request-body fields optional:

Deep-copies all config blobs of the source policy (fields absent from the UI are preserved verbatim) plus three live rule child tables (WAF precise-rule groups+items, CC rules, ACL rules) with fresh IDs, and rewrites the ID arrays inside the blobs accordingly. The source policy is untouched. Output fields: data is the new policy VO.

GET /api/guard/policies/{id}/geo-config — Get geo blocking config

Auth: guard.policy.view

Friendly view of guard_policies.geo_config: mode (black|white), oversea (block overseas), world_list/prov_list/city_list, custom_list (exempt IP set IDs), stime/etime (active hours, 0-0 = all day), enabled (switches.geo, read-only).

PUT /api/guard/policies/{id}/geo-config — Update geo blocking config

Auth: guard.policy.edit

Input: mode (required, black|white) / oversea / world_list / prov_list / city_list / custom_list / stime / etime (0-23).

Omitting custom_list (exempt IP set IDs) keeps the stored value; it is written only when you pass the array explicitly ([] clears it). The Cloud access-control UI does not expose this field, and zcloud guard policies geo-config update does not send it, so existing IP-set bindings are never overwritten.

Persists without dispatching: changes become pending until POST /policies/{id}/publish. Legacy fields not covered by the request are preserved as-is.

GET /api/guard/policies/{id}/sensitive-config — Get sensitive-data protection config

Auth: guard.policy.view

Returns a passthrough view of guard_policies.sensitive_config: hide_sensitive (masking bitmask enum_sensitive + selected keys enum_sensitives + custom keywords src_str), info_leakage, hide_head (service header to strip), status_codes (abnormal status-code protection), and enabled (the switches.sensitive_protection toggle, read-only).

PUT /api/guard/policies/{id}/sensitive-config — Update sensitive-data protection config

Auth: guard.policy.edit

Input: config (required, whole JSON: hide_sensitive / info_leakage / hide_head / status_codes) / enabled (optional, syncs the sensitive_protection toggle).

config is passed through wholesale: gen-server owns the full schema; cloud only persists and triggers dispatch, preserving fields not present in the request.

GET /api/guard/policies/{id}/crawler-config — Get anti-crawler config

Auth: guard.policy.view

Returns a passthrough view of guard_policies.crawler_config: search_engine/scanner/script_tool/other (four recognition-block toggles), robots (custom robots.txt), limit_often_err_req + limit_often_err_req_cfg (frequent-error-request limiting: default_code/custom_code/limit_rate/limit_rate_time(_unit)/deny_time(_unit)), and enabled (switches.anti_crawler, read-only).

PUT /api/guard/policies/{id}/crawler-config — Update anti-crawler config

Auth: guard.policy.edit

Input: config (required, whole JSON) / enabled (optional, syncs the anti_crawler toggle). Passed through wholesale, absent legacy fields preserved; persists and triggers dispatch.

GET /api/guard/policies/{id}/global-blacklist-config — Get collaborative defense config

Auth: guard.policy.view

Returns a passthrough view of guard_policies.global_blacklist_config: block_time (seconds a malicious IP stays blocked once auto-added to the dynamic blacklist; candidates 100/300/400/500/1000) and enabled (switches.global_blacklist, read-only).

PUT /api/guard/policies/{id}/global-blacklist-config — Update collaborative defense config

Auth: guard.policy.edit

Input: config (required, {block_time}) / enabled (optional, syncs the global_blacklist toggle). Persists and triggers dispatch.

GET /api/guard/policies/{id}/pending-changes — Pending changes

Auth: guard.policy.view

Returns dirty (policy modified after last publish; never-published counts as dirty), last_modified_at, last_apply, and changes[] (cloud-side operations since last publish: action/resource_label/detail field-level diff/oper_name/ctime). Legacy-console edits only surface via dirty.

PUT /api/guard/policies/{id}/features/{featureKey} — Toggle feature

Auth: guard.policy.edit

Input: enabled (bool); with featureKey=waf you may pass mode (disable|log|block; when set, enabled is ignored).

Valid featureKeys: waf / cc / geo / global-blacklist / one-key-close / one-key-lock / tamper / sensitive / brute-force / crawler / web-lock.

5.4 CC Rules /api/guard/policies/{id}/cc/rules

CC = HTTP rate limiting (Connection / Concurrency Control). Lives under a policy and is isolated by policy_id.

GET /api/guard/policies/{id}/cc/rules — CC rule list

Authentication: guard.cc.list

Input parameters: path id = policy_id; query page / size.

Output fields (data.list[] = CcRuleVO):

Visualization recommendation: table + status badge. matches is complex; collapse it under a "Detail" button modal.

POST /api/guard/policies/{id}/cc/rules — Create CC rule

Authentication: guard.cc.create

Input parameters (CcRuleCreateReq):

Complex shapes: list one rule first as a template.

Output fields: returns the new CcRuleVO.

GET /api/guard/policies/{id}/cc/rules/{rid} — CC rule detail

Authentication: guard.cc.view

Input parameters: path id = policy_id, rid = rule_id. The backend verifies that rule_id belongs to the current policy_id; cross-policy reads return NotFound.

Output fields: CcRuleVO.

PUT /api/guard/policies/{id}/cc/rules/{rid} — Update CC rule

Authentication: guard.cc.edit

Input parameters: path id + rid, body same as Create.

Output fields: returns the updated CcRuleVO.

DELETE /api/guard/policies/{id}/cc/rules/{rid} — Delete CC rule

Authentication: guard.cc.delete

Input parameters: path id + rid.

Output fields: data is null.

PUT /api/guard/policies/{id}/cc/rules/{rid}/status — Toggle CC rule status

Purpose: enable/disable a rule from the list page using a switch component.

Authentication: guard.cc.edit

Input parameters (CcRuleStatusReq):

Important: status is an int32 number, not the string "enabled" / "disabled".

Output fields: data is null.

Example request:

curl -X PUT https://waf.example.com/api/guard/policies/p_default/cc/rules/12345/status \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"status":1}'

5.5 ACL Rules /api/guard/policies/{id}/acl/rules

ACL = Access Control List (allow/block by IP / Header / URI). Similar shape to CC rules but no priority field.

GET /api/guard/policies/{id}/acl/rules — ACL rule list

Authentication: guard.acl.list

Input parameters: path id, query page / size.

Output fields (data.list[] = AclRuleVO):

Visualization recommendation: table + status badge + action.type chip color (block red / pass green / page blue).

POST /api/guard/policies/{id}/acl/rules — Create ACL rule

Authentication: guard.acl.create

Input parameters (AclRuleCreateReq): name / describe / matches[] (≥1) / action / stime / etime.

When action.type is block or page, the content field is base64-encoded server-side; the caller passes plaintext.

Output fields: returns the new AclRuleVO.

GET /api/guard/policies/{id}/acl/rules/{rid} — ACL rule detail

Authentication: guard.acl.view

Input parameters: path id + rid.

Output fields: AclRuleVO.

PUT /api/guard/policies/{id}/acl/rules/{rid} — Update ACL rule

Authentication: guard.acl.edit

Input parameters: path id + rid, body same as Create.

Output fields: returns the updated AclRuleVO.

DELETE /api/guard/policies/{id}/acl/rules/{rid} — Delete ACL rule

Authentication: guard.acl.delete

Input parameters: path id + rid.

Output fields: data is null.

PUT /api/guard/policies/{id}/acl/rules/{rid}/status — Toggle ACL rule status

Authentication: guard.acl.edit

Input parameters (AclRuleStatusReq): status int32 (1=enabled 2=disabled, number).

Output fields: data is null.

5.6 BW List /api/guard/bwlist

The bwlist has two layers: a set (logical container, blacklist/whitelist) and IPs (individual entries within a set). Each set carries its own scope: all = applies to every domain of the current user (including domains added later), selected = applies only to the chosen domains. The backend writes the binding into each domain's config and triggers delivery automatically — no per-domain or per-policy switch is needed anymore.

Legacy compatibility: older sets bound via policy_id (reported as scope_type = policy) keep working; editing such a set and picking a new scope migrates it and unbinds policy_id. Grey-black (3) / grey-white (4) sets are deprecated and hidden by default (include_grey=true to list them), kept only for legacy data.

GET /api/guard/bwlist/summary — Account-level list-group counts

Purpose: counts for the verdict-flow nodes / type filter. Kept separate from the list because these numbers do not depend on the search keyword — the UI fetches them once per page visit.

Auth: guard.bwlist.list. Output: {black, white, cdn_white, total}.

Not mounted under /sets (/sets/summary would clash with the /sets/{id} route parameter).

GET /api/guard/bwlist/sets — Set list

Authentication: guard.bwlist.list

Input parameters: page / size / keyword / ip_set_type (1 = blacklist, 2 = whitelist) / policy_id / include_grey (default false, returns black/white sets only).

Output fields (data.list[] = IPSetVO):

Visualization recommendation:

• Recommended chart: table (primary) + KPI cards (blacklist count / whitelist count / enabled %)
• Derived metrics: pie chart (ip_set_type 1/2 split)

Search: keyword is a single box covering name LIKE ∪ describe LIKE ∪ member IP text LIKE ∪ member CIDR containing that IP (searching 1.2.3.4 matches a set holding 1.2.3.0/24, matching zmod's FindIPInIPSet). Containment only kicks in when keyword parses as an IP.

GET /api/guard/bwlist/sets/{id} — Get one set

Permission: guard.bwlist.list (same as the list endpoint)

Input: path id.

Output: a single IPSetVO (fields as in the table above, including scope_type / domain_ids / domain_names).

Used by the console's list detail page to load a set by ID on deep link or refresh. Business-level users can only read sets they own; reading someone else's set returns 404 — "not found" and "not permitted" are deliberately indistinguishable, so IDs cannot be used to probe for other tenants' data. Platform-level users are not restricted.

POST /api/guard/bwlist/sets — Create set

Authentication: guard.bwlist.create

Input parameters (BWListSetCreateReq):

Output fields: returns the new IPSetVO.

With scope_type set, the backend writes the set into each in-scope domain's bwlist config (the domain-side switch is enabled automatically) and triggers delivery; an all-scope set also covers domains created later. Passing both scope_type and policy_id returns 400.

PUT /api/guard/bwlist/sets/{id} — Update set

Authentication: guard.bwlist.edit

Input parameters (BWListSetUpdateReq): name / status / describe / scope_type / domain_ids (all optional).

Output fields: returns the updated IPSetVO.

Updating status syncs domain config and triggers delivery: enabled sets enter black/white lists, disabled sets enter the disabled list (dis_list). Passing scope_type recomputes the scope: narrowing it withdraws the config from removed domains; passing a scope on a legacy policy-bound set unbinds policy_id and migrates it to the scope model.

status is discouraged: set-level enable/disable is an extension of this platform. The legacy platform has no such concept (its set list shows only info / description / IP / created / actions), and the field has never been used in practice. Neither the console nor the zcloud CLI offers it — once a set is disabled, the console shows no reason and provides no way back. For enable/disable, use the per-IP PUT /api/guard/bwlist/ips/{id}/status.
This endpoint still accepts status only to avoid breaking existing integrations; omitting it leaves the stored value untouched, so a status imported from the legacy platform is preserved and delivered as-is.

DELETE /api/guard/bwlist/sets/{id} — Delete set

Authentication: guard.bwlist.delete

Input parameters: path id.

Output fields: data is null. All IPs in the set are deleted as a side effect.

Deleting a set also unbinds it from the bwlist config of every effective domain (and legacy policy) and triggers redelivery for affected domains.

GET /api/guard/bwlist/sets/{id}/ips — List IPs in a set

Authentication: guard.bwlist.ip_list

Input parameters: path id = set ID; query page / size / keyword (fuzzy match on IP/CIDR).

Output fields (data.list[] = IPVO):

| ctime / utime | int64 | Time |

There is no expiry field. List entries have no TTL (matching zmod's IPV2 model): expired_at / expire_at / left_time / timeout / ttl are neither accepted nor returned — passing them has no effect. Delete the entry to lift a temporary block.

Visualization recommendation: table.

POST /api/guard/bwlist/sets/{id}/ips — Add a single IP

Authentication: guard.bwlist.ip_add

Input parameters (BWListIPAddReq):

Output fields: returns the new IPVO.

POST /api/guard/bwlist/sets/{id}/ips/batch — Bulk add IPs

Purpose: import hundreds of IPs in one call (e.g. threat-intel feeds), reducing round trips. Duplicate IPs are skipped (idempotent).

Authentication: guard.bwlist.ip_add

Input parameters (BWListIPBatchAddReq):

Output fields: data is null or the list of new IDs (implementation-defined).

POST /api/guard/bwlist/sets/{id}/ips/batch/delete — Bulk delete IPs

Purpose: delete many IPs in a set at once (e.g. clearing expired bans) in a single atomic transaction, avoiding partial failures and audit-log spam from per-entry deletes.

Authentication: guard.bwlist.ip_delete

Input parameters (BWListIPBatchDeleteReq):

Output fields: data.deleted is the number actually deleted. Returns 404 when nothing in the set matches.

PUT /api/guard/bwlist/ips/{id}/status — Enable/disable a single IP

Authentication: guard.bwlist.ip_add (reuses the write permission)

Input parameters: path id = IP entry ID; body (BWListIPStatusReq):

Output fields: returns the updated IPVO.

DELETE /api/guard/bwlist/ips/{id} — Delete a single IP

Important: the delete path is the top-level DELETE /api/guard/bwlist/ips/{id}, not the nested DELETE /sets/{sid}/ips/{id}.

Authentication: guard.bwlist.ip_delete

Input parameters: path id = IP entry ID.

Output fields: data is null.

5.7 IP Forward /api/guard/forwards

This is TCP/UDP port forwarding (L4), not path forwarding / reverse proxy (L7).

GET /api/guard/forwards — Forward list

Authentication: guard.forward.list

Input parameters:

Output fields (data.list[] = ForwardVO):

Visualization recommendation:

• Recommended chart: table + status / schema dual chips
• Derived metrics: pie chart (TCP/UDP split)

POST /api/guard/forwards — Create forward

Authentication: guard.forward.create

Input parameters (ForwardCreateReq):

Fields source_path / target do not exist.

Output fields: returns the new ForwardVO.

GET /api/guard/forwards/{id} — Forward detail

Authentication: guard.forward.view

Input parameters: path id.

Output fields: ForwardVO.

PUT /api/guard/forwards/{id} — Update forward

Authentication: guard.forward.edit

Input parameters: path id, body same as Create (all fields optional).

Output fields: returns the updated ForwardVO.

PUT /api/guard/forwards/{id}/status — Toggle a forward

Permission: guard.forward.status

Input: path id; the body carries a single field.

How this differs from PUT /api/guard/forwards/{id}: this endpoint writes the status column only and skips
full revalidation of nodes and origins. Rules whose guard nodes were reclaimed, taken offline, or never migrated
into the cloud node inventory (common for zmod-imported data) are rejected by the full update path with
"the selected guard node is unassigned or unavailable", which means such a rule cannot even be stopped —
precisely when stopping it matters most. The legacy zmod endpoint
(PATCH /api/guard/forward/ipfromward/ipfromwards/{id}/status) skips the same checks.

Still enforced: tenant isolation, domain-bound legacy rules cannot be toggled here (convert to standalone first),
and port-conflict checking on the same node when enabling. Config delivery is triggered only when the status
actually changes; an unchanged status returns idempotently without delivery.

Output: the updated ForwardVO (including apply_triggered / apply_message).

DELETE /api/guard/forwards/{id} — Delete forward

Authentication: guard.forward.delete

Input parameters: path id.

Output fields: data is null.

Origin Forwarding UX Overhaul · Backend Supplement Audit (2026-06-30)

The frontend is redesigning the origin-forwarding page (benchmarked against competitors' "non-website / port forwarding": Alibaba Cloud Anti-DDoS port access, Tencent Cloud BGP Anti-DDoS non-website protection). A competitor's single L4 forwarding rule can configure: forwarding protocol (TCP/UDP), forwarding port, origin server port (separate from forwarding port), origin IPs/domains (Alibaba ≤20 comma-separated with auto load-balancing; Tencent ≤20 per rule), weight + load-balancing algorithm, session persistence (toggle + timeout), health check (TCP/UDP probe: interval / response timeout / healthy + unhealthy thresholds / port, auto-eject unhealthy origins), new-connection + read/write timeouts, connection / new-connection rate limits; the list displays per-origin health + real-time connections / bandwidth. Our current state:

Conclusion: ① ② are frontend self-fixes (backend already supports them); ③ is the key blocker — until the backend provides the raw-JSON schema, the "advanced config" (origin port / session persistence / health check / weight) cannot become a structured form, so the frontend will first ship the core loop of protocol + forwarding port + origin IP + description + enable, deferring advanced items to the backend schema. ④ ⑤ are display enhancements, optional.

5.8 DNS Scheduling /api/guard/schedules

This module only covers DNS parsing scheduling (mode switch between SRC/NODE and batch record enable/disable). The legacy cron-driven schedule endpoints have been retired.

⚠️ Asynchronous semantics: every write persists to the compatibility tables guard_db.dns_records + guard_db.dns_affairs, then the cloud DNS worker applies it through the configured DNS provider API. Callers must poll the affairs endpoint to obtain the final status (initial AffairsStatus_Start → AffairsStatus_Succeed / AffairsStatus_Faild).

⚠️ Source of truth: dns_records.group_type is the truth for the current mode, while guard_configs.parsing_state is synced asynchronously; both live in the legacy guard_db and may lag by up to 30s. The VO returns both; render a "syncing" badge whenever they disagree.

5.8.1 Domain Scheduling

GET /api/guard/schedules/domains — List domains

Authentication: guard.schedule.list

Input parameters:

Output fields (data = ScheduleDomainListResp):

POST /api/guard/schedules/domains/{id}/switch-mode — Switch SRC/NODE

Authentication: guard.schedule.switch

Input parameters:

Implementation notes: a single guard_db transaction SELECT FOR UPDATEs the domain's dns_records → updates group_type and switch_state=2 (switching) → inserts a dns_affairs row with status=AffairsStatus_Start. After commit, publishes NSQ Cmd=0.

Output fields: returns the newly created ScheduleAffairVO; the frontend should pin affairs_id for polling.

POST /api/guard/schedules/domains/switch-mode — Switch SRC/NODE for many domains

Authentication: guard.schedule.switch (same permission as the single-domain switch; no new perm key)

Input parameters:

Implementation notes: matches the legacy platform's PATCH /api/guard/schedule/domain/dns/switch
id_list semantics — the whole batch runs in one transaction and any per-domain validation failure
rolls everything back; there is no partial success. Inside the transaction each domain goes through
exactly the same checks as the single-domain switch (FOR UPDATE lock, no in-flight affair, target mode
has restorable records, no enabled locked records). Exactly one dns_affairs row is inserted whose
content is a comma-separated domain_id list — the legacy format, which cloud's LatestByDomainIDs
already splits on commas, so both platforms can read each other's rows. After commit the cloud-owned DNS
worker updates guard_configs.parsing_state for every domain and calls the DNS provider.

Output fields: returns the newly created ScheduleAffairVO (one row for the whole batch).

POST /api/guard/schedules/domains/{id}/init — Initialize parsing

Authentication: guard.schedule.init

Input parameters: path id (domain_id); optional body comment.

Implementation notes: reads source/dispatch settings from guard_domain_settings and node bindings from domain_node_ships, locks existing dns_records, deletes and recreates source/node records, then inserts a dns_affairs row and publishes NSQ Cmd=0 so zdns syncs once.

Output fields: returns the newly created ScheduleAffairVO.

POST /api/guard/schedules/domains/{id}/reset — Reset parsing

Authentication: guard.schedule.reset

Input parameters: path id (domain_id); optional body comment.

Implementation notes: every dns_records.switch_state is restored to 1 and status is rolled back to last_status; an affair is created and NSQ Cmd=0 is published.

Output fields: returns the newly created ScheduleAffairVO.

GET /api/guard/schedules/domains/{id}/records — List DNS records of a domain

Authentication: guard.schedule.records

Input parameters:

Output fields (data = ScheduleRecordsResp):

Read-only query against zdns_db.dns_records; no affair is created.

5.8.2 Record Scheduling

POST /api/guard/schedules/domains/{id}/records — Create a DNS record

Auth: guard.schedule.batch

Input (ScheduleRecordCreateReq):

Semantics: the record is enabled immediately when its group matches the active mode, otherwise created disabled; duplicates on group+type+line+value are rejected; default-line guard — a group serving enabled A records must keep at least one default-line (Line 1) record, or visitors not matching any ISP line cannot resolve (mirrors zmod NoIPv4DefaultLine).

Output: data is the scheduling affair ScheduleAffairVO.

PUT /api/guard/schedules/records/{id} — Update a DNS record

Auth: guard.schedule.batch

Input (ScheduleRecordUpdateReq, all three required):

Semantics: type and group are immutable (recreate to change); locked records (mark=2) refuse edits; the default-line guard runs after the change.

Output: data is the scheduling affair ScheduleAffairVO.

DELETE /api/guard/schedules/records/{id} — Delete a DNS record

Auth: guard.schedule.batch

Semantics: locked records, the last enabled record of the active mode, and deletions violating the default-line guard are rejected.

Output: data is the scheduling affair ScheduleAffairVO.

POST /api/guard/schedules/records/batch-status — Batch enable/disable records

Authentication: guard.schedule.batch

Input parameters (ScheduleBatchStatusReq):

Implementation notes: UPDATE dns_records SET last_status=status, status=? WHERE record_id IN (?); an affair is created and NSQ Cmd=0 is published.

Output fields: returns the newly created ScheduleAffairVO.

5.8.3 Affair Records

GET /api/guard/schedules/affairs — Affair list

Authentication: guard.schedule.affairs

Input parameters:

Output fields (data = ScheduleAffairListResp): see ScheduleAffairVO below.

GET /api/guard/schedules/affairs/{id} — Affair detail

Authentication: guard.schedule.affairs

Input parameters: path id (affairs_id).

Output fields (data = ScheduleAffairVO):

Polling tip: after triggering a write, poll this endpoint every 2-5s until status becomes Succeed or Faild; if it stays at Start for an extended period, the cloud DNS worker is still executing or retrying — render a "syncing" indicator.

DNS Scheduling UX Overhaul · Backend Supplement Audit (2026-07-01)

The frontend will redesign the DNS-scheduling page. Benchmarked against competitors: Alibaba Cloud DNS "Intelligent Resolution / GTM Global Traffic Manager", Tencent DNSPod, Cloudflare Load Balancing, and various WAF CNAME-onboarding + disaster failover flows. Our model = per-domain switching of DNS resolution between origin (SRC=1) ↔ protection nodes (NODE=2) (cloud writes compatibility tables and the cloud DNS worker applies changes through the configured DNS provider API; each write produces an affair transaction that the worker writes back to terminal state). Capabilities competitors have that we lack: health check + auto-failover (node down → auto-switch to origin), weighted load balancing, intelligent lines (ISP/geo), single-record CRUD, TTL editing. Backend supplement audit:

Frontend self-fixes (not backend): DnsRecordVO.mark / .protect_status are declared client-side but the backend DTO never returns them → the frontend will drop them; parsing_state not being on the domain Detail (it comes only from /schedules/domains) is a deliberate split, unchanged.

Conclusion: ① ② should be settled before the redesign (sync-state field + orphaned-endpoint fate), low cost. ③④⑤⑥ are the product decision of "whether to upgrade DNS scheduling from manual origin/node switching into intelligent resolution with health/weight/lines/CRUD", dependent on the final mock's scope — please have the backend assess feasibility on the zdns_db + NSQ side first. The core loop (manual SRC/NODE switch + batch record enable/disable + init/reset + affair polling) is already fully supported, so the redesign can start with pure UX (a domain-centric flow + clearer current-mode/sync-state + a switch-history timeline).

5.8bis Ops: Config Snapshots + Per-Origin Status · Backend Follow-ups (2026-07-01)

Source: the domain-centric holistic review + two ops scenarios (dozens of domains each disabling a specific origin / snapshot before bulk ops and one-click restore afterward). The frontend has shipped a "Config Snapshot UI" first (on the port-forwarding page, localStorage-backed + replay via existing PUT /forwards/:id), to switch to a server-side implementation once the APIs below exist.

Priority: ② per-origin soft-disable is the foundation — relatively cheap and directly solves "how to restore after disabling"; ① server-side snapshots next; ③ product-dependent. ②③ hinge on whether L4 forwarding moves from "whole-rule toggle" to "per-origin granularity" — a product decision; have the backend assess feasibility first.

④ Onboarding closed-loop · Verify access (benchmarking big vendors): the onboarding wizard's completion step now has a "Verify access" button; the frontend interim derives liveness from GET /guard/domains/:id's proxy_switch && !stoping (passive, depends on the backend's async detection). Suggest a backend active probe POST /guard/domains/:id/verify-access: check in real time ① whether DNS already CNAMEs to us ② whether the origin is reachable, returning { dns_ok, origin_ok, resolved_cname, message }, so "Verify access" gives an instant result (matching Aliyun/Tencent/Huawei access checks).

5.8ter Config Delivery Records (Apply) · Backend Follow-ups (2026-07-02)

The frontend redesigned "Config Delivery Records" into a delivery-task monitor (list progress bars + detail node-status grouped-by-cluster + failure clustering + retry/cancel + live polling while delivering). The current model (ApplyVO status/success-fail counts, ApplyNodeStat clustered by node_group_name, ApplyDetailItemVO.apply_err per-node error, retryApplyApi(node_ids)/quitApplyApi) already supports the core. Hardening items (edge cases from the architecture review):

⚠️ Architecture reality (read after checking backend code — determines where each item lives): cloud is a thin front — apply + apply_detail are written in a single-DB ACID transaction to cloud_guard, then pushed via outbox → zRPC cmd=550 → gen-service (the legacy config-generation platform); the one that actually delivers to nodes and writes back apply_status (PENDING1→RUNNING4→SUCCESS2/FAILED3)/effect_status/apply_err is gen-service (cloud does not write these); the outbox already re-pushes after 30s without a writeback. So each item lands differently: ② severity is cloud-side doable (cloud knows what changed at trigger time — just tag it; lowest cost, prioritize); ① generation/rollback, ③ normalized error codes, ④ effect semantics mostly live in gen-service (need the legacy platform, not a cloud-Go tweak); ⑤ timeout/retry is partly covered by cloud's outbox (node-level eventual consistency still in gen-service); ⑥ affair uses zdns/NSQ while apply uses gen-service/outbox — two backends, costly to merge.

Priority: ① (versioning+rollback: out-of-order protection + same line as snapshots) and ② (severity alarm) are highest; ③④⑤ are robustness; ⑥ is long-term architecture.

5.8quater Protection Nodes & Back-to-Origin (Tenant View) · Pending Backend APIs (2026-07-02)

Background: cloud is positioned as the tenant product (users jump in from an upper console). The "Cluster Nodes" management UI (platform ops / node list / groups / ACL / assignment / deploy-upgrade) has been fully removed from the cloud frontend (it belongs to the upper console); the backend /api/node is fully retained (agent self-registration and domain_node_ships are the foundation of scheduling/delivery; the upper console calls these APIs directly). Two new tenant-view APIs are needed (modeled on Aliyun/Tencent WAF back-to-origin IP disclosure + Anti-DDoS line views; the frontend already implements this contract and shows a notice — never fake data — until they are ready).
Frontend consumption (adjusted after the 2026-07-02 review; no standalone page): origin-ip-ranges → the onboarding wizard's completion step ("allow back-to-origin IP ranges" block) + the domain workbench access section's "back-to-origin allowlist" modal (shared component OriginIpRanges.vue); my-nodes → the health badge + line names on the "protection node" in the DNS-scheduling detail flow diagram.

Notes: ① gate with the tenant's existing guard.domain.list (read-only); ② the status health here is the official data source for the scheduling page's "node health" placeholder (prerequisite for auto failover); ③ if back-to-origin egress IPs differ from node management IPs (NAT / dedicated egress), expose the actual egress — never leak management IPs to tenants.

5.9 WAF Rules /api/guard/waf/rules

A WAF rule group is mounted under a policy (policy_id). Each group contains a set of sub-rules (rules[]). The gateway matches a request against the zone / pattern fields, and on hit applies action (block / log / captcha).

⚠️ Status convention: status is unified as 1 = disabled, 2 = enabled (the S-6 fix aligned this with forwards / bwlist / schedules). The POST /status endpoint validates oneof=1 2.

⚠️ Path ID is tag: in PUT/DELETE /api/guard/waf/rules/{id}, {id} is the rule group's tag (uint64 primary key) — NOT rule_id (the business code). The frontend reads tag from the list response.

GET /api/guard/waf/rules — WAF rule group list

Authentication: guard.waf.list

Input parameters:

Output fields (data.list[] = WafGroupVO):

WafRuleVO (sub-rule) fields:

Visualization recommendation:

• Recommended chart: table + action / status dual chips + rules.length count badge
• Derived metric: pie chart of groups grouped by action (block / log / captcha split)

POST /api/guard/waf/rules — Create WAF rule group

Authentication: guard.waf.create

Input parameters (WafGroupCreateReq):

WafRuleReq (sub-rule body):

Example:

curl -X POST https://waf.example.com/api/guard/waf/rules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SQL injection guard",
    "policy_id": "1",
    "describe": "OWASP Top 10 SQLi blacklist",
    "action": 1,
    "status": 2,
    "rules": [
      { "zone": "ARGS", "pattern_type": 2, "pattern": "union\\s+select", "describe": "SQLi: union select" }
    ]
  }'

Output fields: the new WafGroupVO (including the assigned tag and the persisted rules[]).

Fields that do not exist: a boolean enabled (use integer status) / description (use describe) / domains[] (scope is the scope string).

PUT /api/guard/waf/rules/{id} — Update WAF rule group

Authentication: guard.waf.edit

Input parameters (path id = rule group tag; body WafGroupUpdateReq, all fields optional, applied incrementally; rules[] is a full replace):

This endpoint does not update status — use the dedicated PUT /api/guard/waf/rules/{id}/status for enable / disable.

Output fields: the updated WafGroupVO.

DELETE /api/guard/waf/rules/{id} — Delete WAF rule group

Authentication: guard.waf.delete

Input parameters: path id (rule group tag).

Implementation note: cascades to sub-rules (waf_rules.group_id = tag).

Output fields: data is null.

PUT /api/guard/waf/rules/{id}/status — Toggle WAF rule group enable / disable

Authentication: guard.waf.status

Input parameters (path id = rule group tag; body WafStatusReq):

Example:

curl -X PUT https://waf.example.com/api/guard/waf/rules/42/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": 1 }'

Output fields: data is null.

GET /api/guard/waf/rules/export — Export precision rules as a JSON file

Auth: guard.waf.export

Query params:

Output: returns a JSON file stream directly (Content-Disposition: attachment; filename="waf-precision-rules.json", not the {code,data} envelope). File shape:

{
  "version": 1,
  "kind": "waf-precision-rules",
  "rules": [
    {
      "name": "block-injection", "describe": "", "waf_type": 8, "sub_rule_condition": 1,
      "scope": "/api/", "action": 1, "status": 2,
      "rules": [ { "zone": "URL", "sub_field": "", "pattern_type": 1, "pattern": "select", "describe": "", "is_not": false } ]
    }
  ]
}

Each group in rules[] omits id/tag/policy_id/timestamps, so files import into any policy.

POST /api/guard/waf/rules/import — Bulk-import precision rules from JSON

Auth: guard.waf.import

Body (WafRuleImportReq):

Behavior: each group is validated/created independently (append; one failure doesn't block the rest), then a single push is triggered.

Example:

curl -X POST https://waf.example.com/api/guard/waf/rules/import \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "policy_id": "P123", "rules": [ { "name": "block-x", "waf_type": 8, "action": 1, "sub_rule_condition": 1, "rules": [ { "zone": "URL", "pattern_type": 1, "pattern": "select" } ] } ] }'

Output fields: data = { imported, failed, errors[] }.

5.9 WEB Base Protection /api/guard/policies/{id}/waf/*

WEB base protection migrated from zmod, in four parts: base config (custom block page/engine/XML/body size/schema), high-frequency penalty, precision whitelist, and BODY inspection whitelist. Precision rules themselves still go through /api/guard/waf/rules. Everything except the penalty (stored in the dedicated column guard_policies.waf_rate_limit) is inlined in the guard_policies.waf_config JSON. All write endpoints dispatch immediately (ApplyTagWaf) to the policy's bound domains. Enum fields use zmod pb enum name strings (e.g. WAFPageType_1_DEFAULT), passed through by the frontend. Permissions: read guard.waf.view/guard.waf.list, write guard.waf.create/edit/delete.

Precision whitelist entry: { id, name, describe, rule_id(comma string), rule_name, op(str/regex), url, status(CFGOPTION_2_ENABLE/..), zones[{zone,sub_field}] }. "Which checks to skip" is expressed by rule_id (comma-separated built-in rule IDs to bypass); whitelist has no action/waf_type.

BODY whitelist entry: { rule_id, op(prefix/suffix/regex/equal), data(match path), describe, status(bool) }. Note status is a bool (unlike whitelist's CFGOPTION string).

Base config body: { waf_policy{name,policy_id,default_main_rule_version}, waf_custom_err_code{page_type,code,content,redirect_addr}, waf_xml{status,max_depth,...}, req_body_size, engine{version} }.

⚠️ Precision rule (/api/guard/waf/rules) sub-rule pattern/describe are stored base64 in user_rule_v3 (consistent with zmod/gen-server); this migration added the codec with plaintext-compat fallback.

§6 Analytics

📊 Analytics · 18 paths (covering 80+ chart-key single-chart endpoints) · used to build WAF monitoring dashboards, operational reports, closed-loop alert handling
All /api/analytics/* paths are public; fields can only be added, paths cannot be modified or removed.
Each chart-key has a clearly recommended chart in the per-page sections below.

6.0 Common Calling Contract

Most Analytics endpoints are homogeneous chart queries. This chapter uses "common contract + index tables + special endpoint expansions".

Authentication & Permissions

Header: Authorization: Bearer <token> or Authorization: ApiKey zck_..., optionally with Accept-Language: zh-CN / en-US.

Permissions fall into three classes:

When using an API Key, the key's scopes must cover the required permission. For example, calling GET /api/analytics/access/status requires analytics.access.view in scope.

Single-chart GET template

curl -sS 'https://waf.example.com/api/analytics/access/status?window=last_24h&site_id=site-001' \
  -H "Authorization: ApiKey $ZCLOUD_API_KEY" \
  -H 'Accept-Language: en-US'

Returns the unified envelope. Chart data always uses the Chart Unified Contract (docs/specs/chart-contract.md). This is the only public contract for the new system; historical PostgreSQL tables, aggregate tables, and ES indexes are internal data sources only and do not affect request parameters or response shape.

Chart data always contains exactly these 5 fields; series / totals / kpis / points / list are not public top-level fields:

window.granularity is not a request parameter: clients pass window=last_24h; the backend automatically picks the 5m/1h/1d aggregation table based on the window size and echoes the chosen granularity in the response.

Batch template

For POST /api/analytics/batch and POST /api/analytics/<page>/batch.

curl -sS -X POST https://waf.example.com/api/analytics/overview/batch \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
        "time_window": "last_24h",
        "site_id": "",
        "domain_id": "",
        "compare": false,
        "charts": [
          { "key": "kpi" },
          { "key": "bandwidth" }
        ]
      }'

The batch response's data.data is keyed by chart-key; data.meta gives total elapsed, cache hit ratio, failed chart count, and effective window. If a single chart fails, inspect the partial / error fields on its node.

6.1 Glossary

GET /api/analytics/glossary — Statistics glossary

Purpose: returns the analytics glossary; the frontend renders tooltips ("what is QPS / block rate") from this map.

Authentication: authenticated session

Input parameters: none.

Output fields:

Visualization recommendation:

• Recommended chart: not directly charted; the frontend looks up the glossary by chart-key when attaching tooltips

Example response:

{
  "code": 0,
  "data": {
    "terms": {
      "qps": "Queries per second",
      "block_rate": "Block rate"
    }
  }
}

6.2 Cross-page Batch

POST /api/analytics/batch — Cross-page batch query

Purpose: load multiple chart-keys in one round-trip when initializing a dashboard, avoiding N single-chart GETs. The backend runs subqueries in parallel and merges responses.

Authentication: maps to analytics.<page>.view based on the page field.

Input parameters (request body):

logs (Phase 1 access logs) and reports (Phase 4 report center) are independent groups and do not support batch.

Output fields:

Visualization recommendation:

• Recommended chart: this endpoint itself is a data-loading layer, not directly charted; frontend dispatches each chart-key result to its own chart component
• Derived metrics: data.meta.cache_hit_ratio can be displayed as a KPI card in dev mode to monitor dashboard cache efficiency

Example request/response:

// Request
{
  "page": "overview",
  "time_window": "last_24h",
  "compare": false,
  "charts": [
    { "key": "kpi" },
    { "key": "bandwidth" }
  ]
}

// Response
{
  "code": 0,
  "data": {
    "data": {
      "kpi": {
        "chart_key": "overview/kpi",
        "render_hint": "kpi",
        "schema": {
          "dimensions": [],
          "measures": [
            { "name": "domain_count", "type": "integer", "unit": "" },
            { "name": "requests",     "type": "integer", "unit": "requests" },
            { "name": "blocked",      "type": "integer", "unit": "events" },
            { "name": "block_rate",   "type": "percent", "unit": "%" },
            { "name": "qps",          "type": "float",   "unit": "qps" },
            { "name": "ai_detect",    "type": "integer", "unit": "events" }
          ]
        },
        "rows": [
          { "domain_count": 8, "requests": 12345, "blocked": 678, "block_rate": 5.49, "qps": 0.143, "ai_detect": 0 }
        ],
        "meta": { "source": "postgres", "cache": "miss", "latency_ms": 10 }
      },
      "event-type": {
        "chart_key": "overview/event-type",
        "render_hint": "categorical_distribution",
        "schema": {
          "dimensions": [{ "name": "event_type", "type": "string" }],
          "measures": [{ "name": "count", "type": "integer", "unit": "events" }]
        },
        "rows": [
          { "event_type": "sql_injection", "count": 1234 },
          { "event_type": "xss", "count": 567 }
        ],
        "meta": { "source": "elasticsearch", "cache": "miss", "latency_ms": 15, "partial": false }
      }
    },
    "meta": {
      "elapsed_ms": 22,
      "cache_hit_ratio": 0,
      "total_charts": 2,
      "failed_charts": 0,
      "window": { "stime": 1746662400000, "etime": 1746748800000, "granularity": "1h" }
    }
  }
}

Note: in the example above, kpi's measure names requests / blocked are the public contract truth names, aligned with the pkg/chart/contract source-of-truth structs. Underlying database field names are not exposed; the frontend reads values strictly by schema.measures[].name.

POST /api/analytics/{page}/batch — Page-level batch

Purpose: equivalent to POST /api/analytics/batch, but page is fixed by URL (more direct for fixed-page frontends).

Authentication: maps to analytics.<page>.view based on {page}.

Supported pages: