API 与端点

端点复制链接

以下路径位于 Web 端口（PORT，默认 3000），仅 ROLE=app、all 提供。

/api/*、/rpc/*、/downloads/*、/install.sh、/healthz 下未匹配的请求返回 404 与 {"error":"not found"}，不回退到 Web UI。

公开 API复制链接

/api/v1 与 /rpc 由 packages/contract 中的同一份 oRPC 契约生成。OpenAPI 文档位于 /api/v1/openapi.json，其 servers 为 <EDGEWEIR_PUBLIC_URL>/api/v1；系统设置 的「OpenAPI」链接到该文档。

curl -fsS https://cdn-admin.example.com/api/v1/openapi.json

认证复制链接

• 请求头 x-api-key: <key>：AccessKey（ewk_ 开头）或服务账号 key（ews_ 开头）。
• AccessKey 以运营者（初始化向导创建的唯一账户）身份调用，可调用的过程由其权限范围决定，见 AccessKey。服务账号 key 只能调用服务账号中列出的过程。
• 密钥无效、已吊销或缺失：401。
• 每个 AccessKey 连续最多 600 次请求：距上一次请求超过 60 秒时计数清零。超出返回 429 API_KEY_RATE_LIMITED，data.retryAfterSeconds 为需等待的秒数。持续轮询用服务账号 key，服务账号 key 不计数。
• 无需密钥的过程（OpenAPI 中 security: []）：GET /system/status、POST /system/setup。
• GET /me 返回调用方：{ user: { id, name, email, twoFactorEnabled }, serviceAccount }；使用 AccessKey 时 serviceAccount 为 null。

AccessKey复制链接

在 个人设置 → AccessKey（用户菜单）中管理；也可在已登录的会话中经 /rpc 调用 accessKeys.*。

未设置权限范围的密钥按读写处理。创建与吊销写入审计日志（api_key.create、api_key.revoke）；经 AccessKey 执行的操作在审计日志中的操作者类型为 api_key。better-auth 的 /api/auth/api-key/* 端点不开放，返回 404。

服务账号复制链接

服务账号是供集成调用 /api/v1 的机器身份。它不能登录：没有密码、passkey 或会话，只有 key。在 系统设置 → 服务账号 中管理。

以上变更写入审计日志（service_account.create、service_account.update、service_account.delete、service_account.key_create、service_account.key_revoke）；服务账号执行的操作在审计日志中的操作者类型为 service_account。服务账号 key 只在 /api/v1 生效。

服务账号只能调用下表列出的过程，每个过程需要对应的 scope：

GET /me 对服务账号返回 serviceAccount: { id, name, scopes }，user 为服务账号的 id 与名称（email 为空，twoFactorEnabled 为 false）。scope 只用于服务账号；AccessKey 使用只读 / 读写权限范围。

幂等键复制链接

/api/v1 的 POST、PUT、PATCH 接受请求头 Idempotency-Key：1–255 个可打印 ASCII 字符，可写成 RFC 8941 字符串（"key"）或原样。

• key 按调用方区分：全部 AccessKey 共用一份，每个服务账号单独一份。
• 保存 24 小时，每小时清理过期记录。
• 5xx 响应不保存，调用方可以用同一个 key 重试；401 与 429（未进入过程）也不保存。4xx 响应保存，重放返回同一错误。
• 执行中的记录 10 分钟后视为中断（控制台实例崩溃），下一个请求接管并重新执行。
• GET 与 DELETE 忽略该请求头。

乐观并发复制链接

以下写操作接受可选的 expectedUpdatedAt（ISO 8601，调用方读取时的 updatedAt）。值不一致时返回 409 UPDATED_AT_MISMATCH，data.updatedAt 为当前值。

网站或 L4 应用已经是请求的启停状态时，sites.setEnabled、l4Apps.setEnabled 直接返回当前状态，不比较 expectedUpdatedAt。

站点启停复制链接

PUT /sites/{id}/enabled（过程 sites.setEnabled），请求体 {"enabled":false}。运营者（会话或读写 AccessKey）与 sites:write 服务账号可以调用。

• 停用的网站不下发到节点，节点对其域名的 HTTP 请求返回 503（X-Edgeweir-Error: site-disabled），HTTPS 请求在 TLS 握手时失败；DNS 记录保留；证书续期继续，HTTP-01 挑战照常应答。
• 状态有变化时生成新的配置版本（原因码 site_enabled、site_disabled）并写审计（site.enable、site.disable）；没有变化时返回当前状态，不生成版本、不写审计。
• 对停用的网站清缓存或预热：409 SITE_DISABLED。
• 响应为 { site, revision }；site.enabled 为当前状态。

网站生效与上线检查复制链接

网站（sites.list、sites.get 与各写操作返回的 site）带 delivery：

新建网站（POST /sites）时 name 可省略，默认为第一个域名（超过 100 字符时截断）。

GET /sites/{id}/launch（过程 sites.launch）当场解析网站的每个域名，耗时可达数秒：

节点能力复制链接

修改后的配置需要集群中某个活动节点缺少的能力（节点在 supportedFeatures 中上报，如 challenge-v1、modsecurity-v1）时：

控制台的自动任务发布配置时与服务账号受同样的限制。升级节点见节点升级。

封禁复制链接

服务账号不能调用这些过程（403 SERVICE_ACCOUNT_FORBIDDEN）；只读 AccessKey 只能调用 GET。范围 scope：site 针对一个网站，platform 针对全部网站（界面显示为「全局」）。

列表响应 { items, total }，只含有效的封禁（未到期、未解封），按创建时间倒序。封禁字段：

• 同一范围、网站与地址已有有效的手动封禁时，create 更新 reason 与到期时间并返回同一 id，审计 ban.update；否则审计 ban.create。delete 解除任一有效封禁（手动或自动），审计 ban.delete。
• maxTotal 是有效手动封禁的上限，网站与全局封禁合计；续期不计入新增。shareAutoBans 决定自动封禁是否下发到同一集群的其他节点。setBans 审计 system.bans_update。
• 节点的封禁状态：GET /nodes/{id} 的 banStatus（appliedSequence、entries、capacity、unappliedIds、unapplied、kernelEntries、autoEvicted、reportedAt），节点未上报时为 null；节点能力见 supportedFeatures（bans-v1、kernel-ban-v1）。

curl -fsS -X POST -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"scope":"platform","cidr":"203.0.113.0/24","reason":"attack","durationSeconds":86400}' \
  https://cdn-admin.example.com/api/v1/bans

行为见 封禁。

挑战与 CC 防护复制链接

服务账号不能调用这些过程（403 SERVICE_ACCOUNT_FORBIDDEN）；只读 AccessKey 只能调用 GET。挑战类型与 CC 级别取值：cookie302、js、pow、captcha（级别另有 normal）。

响应：

• 修改发布网站所在集群的配置版本（原因 site_protection_updated），审计 site.protection_update；全局 Under Attack 变化时发布所有集群（platform_protection_updated），审计 system.protection_update；修改 CC 模板发布有网站跟随模板的集群（cc_template_updated），审计 system.cc_template_update。挑战密钥每日轮换发布 challenge_keys_rotated。
• 挑战、Under Attack 与 CC 需要节点能力 challenge-v1，logJa4 另需 ja4-v1；集群有活动节点缺少时见节点能力。

curl -fsS -X PATCH -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"underAttack":true,"underAttackChallenge":"pow","cc":{"enabled":true,"followTemplate":true}}' \
  https://cdn-admin.example.com/api/v1/sites/<网站 ID>/protection

行为见 挑战与 CC 防护。

压缩与 OWASP CRS复制链接

服务账号不能调用这些过程（403 SERVICE_ACCOUNT_FORBIDDEN）；只读 AccessKey 只能调用 GET。

响应：

• https.update 发布网站所在集群（原因 certificate_updated），审计 site.https_update；waf.update 发布（site_waf_updated），审计 site.waf_update。
• POST /certificates/request 的 bindSiteId：证书签发后绑定到该网站（forceHttps 等其他设置不变），发布网站所在集群，审计 site.https_update（操作者 system）；names 须覆盖网站全部域名（400 CERTIFICATE_DOMAIN_MISMATCH），每个网站同时只有一个这样的申请（409 CERTIFICATE_BUSY）。证书的 bindSiteId 在签发前为该网站 ID，签发后为 null。
• available 为 false 时仍可经 API 开启，见节点能力。
• 网站不存在：404 SITE_NOT_FOUND。

curl -fsS -X PATCH -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"mode":"block","paranoiaLevel":1,"excludedRuleIds":[920350]}' \
  https://cdn-admin.example.com/api/v1/sites/<网站 ID>/waf
curl -fsS -H "x-api-key: $EDGEWEIR_API_KEY" \
  'https://cdn-admin.example.com/api/v1/sites/<网站 ID>/waf/rules?range=1h'

行为见 HTTPS 与证书 与 OWASP CRS 托管规则。

清缓存、预热、源站与错误页复制链接

服务账号不能调用这些过程（403 SERVICE_ACCOUNT_FORBIDDEN）；只读 AccessKey 只能调用 GET。

响应：

• errorPages.update 发布网站所在集群（原因 site_error_pages_updated），审计 site.error_pages_update；settings.setErrorPages 发布所有集群（error_pages_updated），审计 system.error_pages_update。

curl -fsS -X POST -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"type":"tag","siteIds":["<网站 ID>"],"tags":["product-42"]}' \
  https://cdn-admin.example.com/api/v1/cache-tasks
curl -fsS -X POST -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"type":"sitemap","urls":["https://www.example.com/sitemap.xml"],"maxUrls":2000,"variants":["desktop","mobile"]}' \
  https://cdn-admin.example.com/api/v1/cache-tasks

行为见 源站与缓存 与 错误页。

缓存区、PURGE 方法、内容设置与维护模式复制链接

服务账号不能调用这些过程（403 SERVICE_ACCOUNT_FORBIDDEN）；只读 AccessKey 只能调用 GET。

响应：

用到新字段的配置需要节点能力 site-content-v1（节点自己的缓存容量需要 cache-zone-v1），见节点能力。行为见源站与缓存与错误页。

规则与批量重定向复制链接

服务账号不能调用这些过程（403 SERVICE_ACCOUNT_FORBIDDEN）；只读 AccessKey 只能调用 GET 与 POST /rules/validate。

响应：

• rules.save 发布网站所在集群（原因 rules_updated），审计 site.rules_update；platformRules.save 发布所有集群，审计 platform.rules_update；bulkRedirects.save 发布网站所在集群（rules_updated），审计 site.bulk_redirects_update（条目数）。
• 用到函数、新字段、值表达式、查询参数编辑、origin 或 compression 动作、config 阶段的新字段、gzip: true、非构建器形状的缓存规则条件、browserTtlSeconds、批量重定向或非默认源站组的配置要求节点能力 rules-v2。
• 用到 rules-v3 字段（http.request.cookies[…]、http.request.uri.args[…]、http.referer、http.user_agent、http.request.version、http.request.scheme、http.request.id、http.request.timestamp.sec、edge.server_port、ip.geoip.as_name、http.response.cache_status）、函数（url_encode、base64_encode、base64_decode、md5、sha1、sha256、substring、to_string）、wildcard / strict wildcard、报头或查询参数的 expression、append、statusCode: 303，或错误页模板含 {{time}}、{{path}} 的配置要求节点能力 rules-v3。批量重定向的 statusCode 仍为 301、302、307、308。
• rules.validate 的 code 增加 cookie_name、argument_name、integer_argument（params 为 min、max）。

curl -fsS -X PUT -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"redirects":[{"source":"/old","target":"/new","statusCode":301,"preserveQuery":true}]}' \
  https://cdn-admin.example.com/api/v1/sites/<网站 ID>/bulk-redirects
curl -fsS -X POST -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"expression":"regex_replace(http.request.uri.path, \"^/old/\", \"/new/\")","phase":"redirect","kind":"value"}' \
  https://cdn-admin.example.com/api/v1/rules/validate

行为见 规则、IP 名单与 GeoIP 与 源站与缓存。

用量复制链接

每个网站、每个 UTC 5 分钟窗口 [windowStart, windowEnd) 一条记录，数值为该窗口内全部节点上报的分钟统计之和。

记录字段：

• usage.list 按（窗口，网站）排序，响应 { items, nextCursor, completeUntil }；nextCursor 为 null 时没有下一页。from、to 未对齐或 to 不晚于 from：400 USAGE_RANGE_INVALID；游标无效：400 USAGE_CURSOR_INVALID。
• usage.changes 按 seq 返回 afterSeq 之后创建或修订的记录，响应 { items, lastSeq, completeUntil }；下次以 lastSeq 作为 afterSeq。被修订的记录会再次出现。
• 没有流量的窗口没有记录。
• 窗口结束后每分钟重算一次；迟到数据改变数值时 revision 加 1 并分配新的 seq，数值不变时两者都不变。同一统计批次重复上报不改变结果。
• 保留期默认 100 天，系统设置 → 用量 可调（35–400 天）。

completeUntil（ISO 8601 或 null）：结束时间不晚于它的窗口，已包含当时所有活动节点的数据。

集群与概览复制链接

clusters:read 服务账号可以调用 clusters.list、clusters.get；其他过程服务账号不能调用（403 SERVICE_ACCOUNT_FORBIDDEN）。都是 GET，只读 AccessKey 可以调用。

行为见集群与系统与接入节点。

节点通道地址复制链接

服务账号不能调用（403 SERVICE_ACCOUNT_FORBIDDEN）；只读 AccessKey 只能调用 settings.nodeChannel。已注册的节点继续使用注册时的地址，见 节点通道地址与证书。

节点升级复制链接

服务账号不能调用这些过程（403 SERVICE_ACCOUNT_FORBIDDEN）；只读 AccessKey 只能调用 GET。

前提、状态与节点侧校验见节点升级。

区域探针、调度地址与智能调度复制链接

服务账号不能调用这些过程（403 SERVICE_ACCOUNT_FORBIDDEN）；只读 AccessKey 只能调用 GET。POST /probe-tokens 不接受 Idempotency-Key（见幂等键）。

DNS 绑定与记录的新增字段：

行为见区域探针与智能调度与DNS 调度与告警。

监听端口与访客 IP复制链接

服务账号不能调用这些过程（403 SERVICE_ACCOUNT_FORBIDDEN）；只读 AccessKey 只能调用 GET。

网站的端口经 PATCH /sites/{id} 的 ports（{ http, https }）修改，POST /sites 可选同一字段（省略为 80 与 443）；网站响应带 ports。错误码：SITE_PORT_UNAVAILABLE、SITE_PORTS_EMPTY、SITE_HTTPS_PORT_NEEDS_CERTIFICATE。PUT /sites/{id}/https 的设置新增 redirectStatus（301、302、303、307、308，默认 301）、redirectPort（443 或网站的 HTTPS 端口，默认 443，HTTPS_REDIRECT_PORT_INVALID）与 redirectExcludedDomains（网站的域名，最多 50 个，HTTPS_REDIRECT_DOMAIN_INVALID）。GET /sites/{id}/features 新增 edgePorts、clientIp；GET /clusters 的集群新增 clientIpMode。

端口池与 L4 应用复制链接

服务账号不能调用这些过程（403 SERVICE_ACCOUNT_FORBIDDEN）；只读 AccessKey 只能调用 GET。

• create、update 发布集群的配置版本（原因 l4_app_created、l4_app_updated），审计 l4_app.create、l4_app.update；setEnabled 状态变化时发布（l4_app_updated），审计 l4_app.enable、l4_app.disable，状态不变时返回最新版本，不发布、不写审计；delete 发布（l4_app_deleted），审计 l4_app.delete。setPortPools 审计 cluster.port_pools_update。
• 配置中有启用的应用时要求节点能力 l4-v1，见节点能力。

curl -fsS -X PUT -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"pools":[{"protocol":"both","from":20000,"to":20100}]}' \
  https://cdn-admin.example.com/api/v1/clusters/<集群 ID>/port-pools
curl -fsS -X POST -H "x-api-key: $EDGEWEIR_API_KEY" -H 'content-type: application/json' \
  -d '{"clusterId":"<集群 ID>","name":"game","protocol":"tcp","port":20000,"origins":[{"address":"game-origin.example.com","port":7000}],"proxyProtocolVersion":2}' \
  https://cdn-admin.example.com/api/v1/l4-apps

行为见四层转发。

示例复制链接

列出网站（过程 sites.list，GET /api/v1/sites）：

curl -fsS -H "x-api-key: $EDGEWEIR_API_KEY" \
  "https://cdn-admin.example.com/api/v1/sites?page=1&pageSize=20"

响应：{"items":[…],"total":<总数>}。

错误格式复制链接

{
  "defined": false,
  "code": "ACCESS_KEY_READ_ONLY",
  "status": 403,
  "message": "access key is read only",
  "data": {}
}

认证与输入校验失败使用 oRPC 通用代码：UNAUTHORIZED（401）、BAD_REQUEST（400）。

Web UI 接口复制链接

/rpc/* 使用 oRPC RPC 协议，供 Web UI 调用，路径为过程路径，例如 POST /rpc/sites/list。

第三方集成使用 /api/v1。

认证端点复制链接

/api/auth/* 由 better-auth 处理，只放行下表中的路径与方法。匹配为精确匹配（不接受前缀、编码变体或结尾斜杠），其余请求返回 404。请求中的 x-api-key 被剥离；客户端 IP 按 EDGEWEIR_TRUSTED_PROXIES 解析后传入。控制台不开放注册，唯一的账户由初始化向导创建；AccessKey 经 accessKeys.* 管理。NODE_ENV=production 时启用限速，计数存于 PostgreSQL。

健康检查复制链接

GET /healthz 返回 200：

{ "status": "ok", "version": "20260929-a1b2c3d" }

HTTP 服务监听即返回，不检查数据库。容器健康检查见命令行。

安装脚本与发布镜像复制链接

GET /install.sh 返回节点安装脚本（text/x-shellscript，cache-control: no-store），脚本中的控制台地址替换为 EDGEWEIR_PUBLIC_URL。选项见命令行。

GET、HEAD /downloads/* 从 EDGEWEIR_DOWNLOADS_DIR 提供文件，URL 路径与目录中的相对路径相同：

<项目> 为 edgeweir-node 或 cosign；edgeweir-openresty、edgeweir-openresty-modsecurity 软件包放在 edgeweir-node 的同一版本目录。其他路径、不存在的文件、指向目录外的符号链接返回 404。目录准备见接入节点。

节点通道复制链接