使用指南
HTTPS 与证书
证书的上传、ACME 申请与续期，以及网站的 HTTPS、TLS、HTTP/2、HTTP/3 和压缩设置。
概念
| 术语 | 定义 |
|---|---|
| 证书 | 证书链与私钥。覆盖网站全部域名的证书可被该网站选用。 |
| ACME 证书 | 控制台向 Let's Encrypt 或 ZeroSSL 申请、自动续期的证书。 |
| DNS 凭据 | DNS 服务商凭据，供 DNS-01 验证写入 TXT 记录。与 DNS 调度的服务商凭据相互独立。 |
| HTTPS 设置 | 网站「HTTPS」页签中的证书选择、跳转、HSTS、TLS、HTTP/2 与 HTTP/3 选项；压缩在「缓存」页签的「压缩」卡片中设置。 |
| 监听端口 | 节点接收 HTTP / HTTPS 流量的端口：80、443 与集群的附加端口；网站在「端口」卡片中选择其中一部分。 |
上传证书
- 打开 证书，点击「上传证书」。
- 填写「名称」。
- 在「证书链（PEM）」中选择文件或粘贴内容，叶证书在前，中间证书依次在后。
- 在「私钥（PEM）」中选择文件或粘贴内容。
- 点击「上传证书」。
- 验证：证书卡片状态为「可用」，显示「到期时间 … · 剩余 … 天」。
| 要求 | 值 |
|---|---|
| 证书链 | 1–10 张证书，最大 128 KiB；每张由下一张签发；只能包含证书，合并了私钥的 PEM 被拒绝（「证书链只能包含证书，私钥请填到私钥栏」） |
| 叶证书 | 不是 CA 证书，含 DNS 类型的 SAN，当前处于有效期内 |
| 密钥类型 | 叶证书的密钥为 RSA（2048 位及以上）或 ECDSA P-256、P-384、P-521；其他曲线（secp256k1、Brainpool、SM2、P-224）、Ed25519、Ed448、ML-DSA、RSA-PSS、DSA 被拒绝 |
| 私钥 | 与叶证书匹配，最大 32 KiB |
| EC 密钥 | 证书与私钥都须使用命名曲线（曲线 OID），不接受显式曲线参数 |
保存的只有重新编码的证书与 PKCS #8 私钥，粘贴内容里的其他文字不保存。上传的证书不自动续期（「未开启自动续期」）；到期前上传新证书并在网站中改选。过期的证书卡片状态为「已过期」，显示「已于 … 过期」。
此前上传、使用显式曲线参数的证书节点同样无法加载，引用它的配置版本在该集群的所有节点上都不应用。后台任务每次启动时检查已上传的证书：这类证书卡片状态为「不可用」并显示原因，审计日志记录「证书标记为节点无法加载」和使用它的网站。网站不能再选用它；已选用它的网站不会被自动改动：上传命名曲线的证书（见故障排查），在这些网站的「HTTPS」页签改选并保存，或改为「仅 HTTP」，再删除旧证书。
添加 DNS 凭据
DNS-01 验证需要先添加凭据。
- 打开 证书，点击「添加 DNS 凭据」。
- 填写「名称」，选择「DNS 服务商」，按表单填写凭据字段。
- 能列出区域的服务商：点击「列出区域」并选择「区域」；其他服务商直接填写「区域」。
- 点击「测试连接」，确认显示「连接正常」。
- 点击「创建」。保存前先执行与「测试连接」相同的测试；失败时对话框显示错误，按钮变为「仍然保存」。
- 验证：凭据出现在「DNS 凭据」卡片中，显示其区域与服务商。
各服务商的凭据字段与所需的最小权限见服务商与凭据，与 DNS 调度使用同一份服务商目录。凭据使用主密钥信封加密后保存，只写不读；「编辑」可改名，或打开「重新填写凭据」轮换密钥，新凭据保存前同样先测试；只改名时不测试，测试失败后修改任一字段，下次保存重新测试。轮换后，使用该凭据且处于「签发失败」的证书和待清理的 TXT 记录立即重试。
申请 ACME 证书
前提：
- HTTP-01：每个证书域名都是某个网站的域名（不能是泛域名），已解析到节点，节点 80 端口可从公网访问；服务这些域名的集群有在线节点，在线节点都支持
http01-v1。 - DNS-01：已添加区域覆盖全部证书域名的 DNS 凭据；证书域名不必已加入网站。
- 打开 证书，点击「申请证书」。
- 填写「名称」「域名」「账户邮箱」。
- 选择「证书颁发机构」和「验证方式」。选择 DNS-01 时选择「DNS 凭据」；选择 ZeroSSL 时填写「EAB 密钥 ID」和「EAB HMAC 密钥」。
- 点击「申请证书」。
- 验证：证书卡片状态依次变为「等待签发」「签发中」「可用」，并显示「已开启自动续期」和「下次续期：…」。
申请字段
| 字段 | 取值 | 默认值 | 作用 |
|---|---|---|---|
| 名称 | 1–100 字符 | 无 | 证书在控制台中的名称 |
| 域名 | 1–100 个域名，逗号或空格分隔，不重复；可含 *. 泛域名 | 无 | 证书 SAN |
| 账户邮箱 | 邮箱地址 | 无 | ACME 账户联系邮箱 |
| 证书颁发机构 | Let's Encrypt / ZeroSSL | Let's Encrypt | ACME 目录；设置了 EDGEWEIR_ACME_DIRECTORY 时改为只读的「ACME 目录（EDGEWEIR_ACME_DIRECTORY）」 |
| 验证方式 | HTTP-01 / DNS-01 | HTTP-01 | 域名控制验证方式；泛域名必须使用 DNS-01，选择 HTTP-01 时表单在「域名」下提示「泛域名需要 DNS-01 验证」 |
| DNS 凭据 | 已添加的 DNS 凭据 | 第一个凭据 | DNS-01 写入 TXT 所用的账户；每张证书一个区域 |
| 跳过解析检查 | 开 / 关 | 关 | 仅 HTTP-01：不检查域名是否解析到节点（申请时与每次签发前），例如节点前面还有负载均衡 |
| EAB 密钥 ID / EAB HMAC 密钥 | ZeroSSL 提供的 EAB 凭据 | 无 | ZeroSSL 必填，加密保存 |
同一证书颁发机构、EAB 密钥 ID 与账户邮箱的证书共用一个 ACME 账户：CA 限制每个 IP 新注册的账户数（Let's Encrypt 为 3 小时 10 个）。
验证方式
| 方式 | 行为 |
|---|---|
| HTTP-01 | 每个名称都必须是某个网站的非泛域名，否则申请被拒绝（「证书域名与网站或 DNS 区域不匹配」）：挑战只由服务该名称的集群应答。控制台把一张证书的全部挑战一次发布到这些集群（每个集群一个版本，网站已停用时同样发布），集群内所有在线节点须支持 http01-v1 并在 40 秒内应用后才请求 CA 验证，同时验证 4 个名称。申请时和每次签发前，控制台用系统 DNS 解析各名称（每次 3 秒、最多 2 次）：名称没有 A/AAAA 记录，或解析结果中有不属于该集群活动节点的地址（节点配置的调度地址或上报的公网地址）时，申请被拒绝（「以下名称未解析到节点：…」），签发不联系 CA 直接失败（「有域名未解析到节点」）；解析超时或节点没有已知公网地址时不拦截。挑战在 80 端口应答，不跳转、不缓存，10 分钟后或签发结束后失效（其他 HTTP-01 token 转给源站，源站可自行签发证书，这类请求不缓存、不挑战）；挑战版本不计入保留的配置版本数 |
| DNS-01 | 每个名称都必须在 DNS 凭据的区域内（区域本身或其下的子域名），否则申请被拒绝。在 _acme-challenge.<域名> 写入 TXT，最长等待 3 分钟传播。签发结束、超时或进程中断后删除本次写入的 TXT 值；删除失败时按 1 分钟起、每次加倍、最长 6 小时的间隔重试，服务商已没有该区域时视为已删除 |
续期
| 项目 | 行为 |
|---|---|
| 自动续期 | 控制台申请的证书默认开启 |
| 续期时间 | CA 提供 ARI（ACME Renewal Information）窗口时按窗口；否则在证书有效期过去三分之二时；最晚为到期前 1 分钟。卡片显示「下次续期：…」 |
| 窗口变化 | 签发后按 CA 的建议间隔（1–24 小时，默认 6 小时）重新查询 ARI；窗口提前到下次续期时间之前（例如 CA 将提前吊销证书）时，续期改到新窗口内，写审计 certificate.renewal_rescheduled |
| 检查周期 | 后台任务每分钟检查到期的证书，每次最多 10 张，新申请与「立即续期」优先，其余按续期时间先后，同时签发 3 张；需要 ROLE=worker 或 ROLE=all 的控制台进程 |
| 续期域名 | HTTP-01 证书续期时去掉已没有网站使用的名称，只要至少还剩一个名称；使用该证书的网站的域名都会保留，网站仍被覆盖。续期成功后证书的域名列表随之更新。网站新增的域名见添加域名 |
| 生效 | 签发或续期成功后，为引用该证书的网站所在集群发布新版本 |
| 失败 | 状态变为「签发失败」，卡片显示原因，保留当前证书；重试间隔为证书剩余有效期的十分之一（10 分钟到 12 小时），首次签发 1 小时后重试，见故障排查。因名称未解析到节点而失败（「有域名未解析到节点」）的 HTTP-01 证书，后台每 5 分钟重新解析，名称都解析到节点后立即重试 |
| 过期 | 续期失败直到证书过期时，状态显示「已过期」，卡片仍显示失败原因；重试期间状态为「等待签发」或「签发中」，卡片显示「已于 … 过期」 |
| 手动 | ACME 证书可点击「立即续期」，在下一次检查时执行；「签发中」时不可用 |
| 中断 | 「签发中」超过 10 分钟视为中断，下一次检查重新执行；单次签发最长 8 分钟 |
删除
证书被网站引用时，删除返回「证书仍被网站使用：…」（列出最多 5 个网站）；处于「签发中」时返回「证书正在处理中」。仍有 DNS-01 TXT 记录待清理时照常删除，不再清理这些记录：审计 certificate.delete 的 leftDnsRecords 列出记录，需在 DNS 服务商处手动删除。DNS 凭据被任一证书引用时不能删除（「DNS 凭据仍被证书使用：…」）。
一键启用 HTTPS
网站还没有可用证书时，「HTTPS」页签只有「启用 HTTPS」。
- 打开 网站，选择网站，进入「HTTPS」页签。
- 控制台先检查能否签发，有阻碍时逐条列出且按钮不可用；修正后点击「重新检查」。
- 点击「启用 HTTPS」。
- 验证：页签显示「正在申请证书」；签发后切换为 HTTPS 设置，「证书」为新证书。「强制 HTTPS」保持关闭，需要时在 HTTPS 设置中打开。
| 项目 | 取值 |
|---|---|
| 证书名称、域名 | 网站名称、网站的全部域名 |
| 验证方式 | HTTP-01；网站有泛域名时用 DNS-01 和第一个区域覆盖全部域名的 DNS 凭据 |
| 账户邮箱 | 最近一个 ACME 账户或申请的邮箱，否则为控制台账户的邮箱；可在「自定义」中修改 |
| 证书颁发机构 | Let's Encrypt；可在「自定义」中改为 ZeroSSL（需要 EAB 凭据） |
| 签发后 | 证书绑定到网站（「强制 HTTPS」等其他设置不变），发布网站所在集群，写审计 site.https_update（操作者 system）；申请后网站新增的域名随即重新签发。网站此时已有其他可用证书时不改动 |
| 检查提示 | 原因 |
|---|---|
| 「集群 … 没有在线节点」 | HTTP-01：网站所在集群没有在线的活动节点 |
| 「以下节点需要升级才能应答 HTTP-01：…」 | HTTP-01：在线节点缺少 http01-v1 |
| 「… 还没有解析记录」「… 未解析到节点」 | HTTP-01：名称没有 A/AAAA 记录，或解析到不属于该集群节点的地址；解析超时或节点没有已知地址时不提示。控制台看到的解析与 CA 不同（内外网分离解析、前面另有代理）时，在「自定义」中打开「跳过解析检查」，这两条不再阻止申请，签发前也不再检查 |
| 「泛域名需要区域覆盖 … 的 DNS 凭据」 | DNS-01：没有这样的 DNS 凭据，点击「添加 DNS 凭据」 |
| 「DNS 凭据 …：…」 | DNS-01：凭据的连接测试失败 |
| 「… 的 CAA 记录不允许 … 签发」 | 名称或其上级域名的 CAA 记录不允许所选 CA（Let's Encrypt：letsencrypt.org；ZeroSSL：sectigo.com、trust-provider.com、usertrust.com），含 issuewild 与 validationmethods；设置了 EDGEWEIR_ACME_DIRECTORY 时不检查 |
签发中页签每 3 秒刷新状态。签发失败时显示分类后的原因（与证书卡片相同），可「重试」或「取消」（删除这张证书）。已有覆盖网站全部域名的可用证书时，页签列出「已有证书」，点击「使用」直接选用。网站使用的 ACME 证书重新签发或签发失败时，HTTPS 设置上方显示同样的状态。
配置网站 HTTPS
-
打开 网站，选择网站，进入「HTTPS」页签（网站还没有证书时见一键启用 HTTPS）。
-
在「证书」中选择证书。列表包含全部已签发、未过期且节点能加载的证书；「仅 HTTP」表示不启用 HTTPS。
-
设置「最低 TLS 版本」「密码套件」「HSTS 有效期（秒）」和各开关。
-
点击「保存」。控制台提示「已保存」，并发布新的配置版本。
-
验证：节点应用该版本后：
curl -sI --resolve www.example.com:443:<节点 IP> https://www.example.com/返回
HTTP/2 200（开启 HTTP/2 时）；开启 HSTS 时含strict-transport-security；开启 HTTP/3 时含alt-svc: h3=":443"; ma=86400。
节点报告已应用该版本，才表示配置在该节点生效。
HTTPS 跳转选项
打开「强制 HTTPS」后，设置下方出现跳转选项：
| 字段 | 取值 | 默认值 | 作用 |
|---|---|---|---|
| 跳转状态码 | 301、302、303、307、308 | 301 | 跳转响应的状态码 |
| 跳转端口 | 443 或网站绑定的 HTTPS 端口 | 443 | 跳转目标 URL 的端口；443 时 URL 不带端口（「跳转端口 {port} 不是网站的 HTTPS 端口」） |
| 不跳转的域名 | 网站的域名，最多 50 个 | 无 | 这些域名不因「强制 HTTPS」跳转；泛域名写作 *.example.com，网站同时有的精确域名不受它影响 |
配置规则的 forceHttps 照旧按请求打开或关闭跳转：规则打开时也使用这里的状态码与端口，不跳转的域名同样跳转。网站去掉跳转端口所在的 HTTPS 端口时，保存被拒绝；改为不使用证书时跳转端口恢复为 443，删除网站的域名时它也从不跳转的域名中去掉。用到非默认值的配置需要 edge-ports-v1。
验证：
curl -sI -H 'Host: www.example.com' http://<节点 IP>:8081/a返回所选状态码，location: https://www.example.com:9443/a（跳转端口为 9443 时）。
为 HTTPS 网站添加域名
在网站的「域名」页签保存新的域名时：
| 网站的证书 | 行为 |
|---|---|
已覆盖新域名（含上一级的泛域名 *.example.com） | 直接保存 |
| 控制台申请且开启自动续期的证书 | 保存，证书的域名列表加入新域名并立即重新签发（提示「证书 … 正在为新域名重新签发」，写审计 certificate.names_extended）。签发完成前新域名先走 HTTP：不接受 TLS 握手、不跳转 HTTPS、没有 HSTS，其他域名照常使用当前证书；新证书签发后新域名改为 HTTPS。集群有活动节点缺少 tls-pending-domains-v1 时，新域名在新证书签发后才生效。HTTP-01 挑战在此期间照常应答。证书正在签发时，本次签发结束后立即再签发一次 |
| 上传的证书，或未开启自动续期的证书 | 拒绝，返回「证书域名与网站或 DNS 区域不匹配：…」，列出未覆盖的域名 |
HTTP-01 证书不能扩展到泛域名，DNS-01 证书只能扩展到其 DNS 凭据区域内的名称；一张证书最多 100 个名称。
HTTPS 字段
| 字段 | 取值 | 默认值 | 作用 |
|---|---|---|---|
| 证书 | 未过期的证书 / 仅 HTTP | 仅 HTTP | 证书须覆盖网站全部域名；网站的泛域名 *.example.com 要求证书含相同的 *.example.com。之后为网站添加的域名见添加域名 |
| 最低 TLS 版本 | TLS 1.2 / TLS 1.3 | TLS 1.2 | 握手接受的最低版本 |
| 密码套件 | 现代 / 兼容 | 现代 | TLS 1.2 密码套件档位，见下表 |
| HSTS 有效期（秒） | 0–63072000 | 0 | 大于 0 时在 HTTPS 响应中发送 Strict-Transport-Security；需要证书 |
| 强制 HTTPS | 开 / 关 | 关 | HTTP 请求 301 跳转到 https://<Host><请求 URI>（443 端口）；需要证书；ACME 挑战路径不跳转 |
| HTTP/2 | 开 / 关 | 开 | 该网站的 HTTPS 连接协商 HTTP/2 |
| HTTP/3 | 开 / 关 | 关 | 在 UDP 443 提供 QUIC，并发送 Alt-Svc: h3=":443"; ma=86400 |
| HSTS 包含子域名 | 开 / 关 | 关 | HSTS 附加 includeSubDomains |
| HSTS 预加载 | 开 / 关 | 关 | HSTS 附加 preload |
| OCSP 装订 | 开 / 关 | 关 | 在握手中附带 OCSP 响应 |
选择「仅 HTTP」时，「强制 HTTPS」关闭、HSTS 有效期归零。
| 密码套件 | TLS 1.2 套件 |
|---|---|
| 现代 | ECDHE-ECDSA-AES128-GCM-SHA256、ECDHE-RSA-AES128-GCM-SHA256、ECDHE-ECDSA-CHACHA20-POLY1305、ECDHE-RSA-CHACHA20-POLY1305 |
| 兼容 | 现代档位加 ECDHE-ECDSA-AES256-GCM-SHA384、ECDHE-RSA-AES256-GCM-SHA384 |
TLS 会话复用未启用：节点不保存会话缓存（TLS 1.2），也不发会话票据（TLS 1.2 与 TLS 1.3），每个连接都完整握手。
压缩
网站「缓存」页签的「压缩」卡片中，Zstandard、Brotli、Gzip 各有一组设置，单独保存（不影响「HTTPS」页签未保存的修改）：
| 字段 | 取值 | 默认值 | 作用 |
|---|---|---|---|
| 开启 | 开 / 关 | Gzip 开，Brotli、Zstandard 关 | 按该算法压缩响应 |
| 压缩级别 | Brotli 1–11，Zstandard 1–19，Gzip 1–9 | Brotli 6，Zstandard 3，Gzip 空（节点默认 1） | 级别越高压缩率越高、CPU 开销越大；Gzip 级别不是默认值时需要节点能力 site-content-v1 |
| 最小压缩大小（字节） | 1–1048576 | 256 | 小于该长度的响应不压缩 |
| 压缩内容类型 | MIME 类型，逗号或空格分隔，最多 32 个 | text/html、text/plain、text/css、application/javascript、application/json、image/svg+xml | 压缩的响应类型；text/html 始终压缩 |
| 最大压缩长度（字节） | 不小于 0，三种算法共用 | 空（不限） | Content-Length 超过该值的响应不压缩；长度未知（分块）的响应照常压缩。需要 site-content-v1 |
| 行为 | 说明 |
|---|---|
| 协商 | 按请求 Accept-Encoding 的 q 值选择一种已开启的算法；q 值相同时顺序为 zstd > br > gzip，q=0 表示不接受。每个响应只由一种算法压缩 |
Vary | 压缩的响应带 Vary: Accept-Encoding |
| 不重复压缩 | 响应已有 Content-Encoding（如源站已压缩）时原样返回 |
| 缓存 | 缓存保存未压缩或源站原样的内容，每次响应时按请求压缩；缓存命中后编码同样按请求协商 |
| 规则 | 覆盖设置可按请求关闭或重新允许某种算法，压缩规则可限定本次响应的算法与 q 值相同时的顺序；只在已开启的算法中选择，不绕过缓存，见规则 |
| 能力 | 开启 Brotli 需要集群全部活动节点支持 brotli-v1，Zstandard 需要 zstd-v1。有节点不支持时开关不可用，并显示「所在集群有节点不支持，暂时无法开启」；已开启的算法仍可关闭 |
验证（节点应用该版本后）：
curl -s -o /dev/null -D - -H 'Accept-Encoding: zstd' --resolve www.example.com:443:<节点 IP> https://www.example.com/
curl -s -o /dev/null -D - -H 'Accept-Encoding: br' --resolve www.example.com:443:<节点 IP> https://www.example.com/分别返回 content-encoding: zstd 与 content-encoding: br，并带 vary: Accept-Encoding。
监听端口
| 端口 | 协议 | 条件 |
|---|---|---|
| 80/TCP | HTTP、HTTP-01 挑战 | 始终监听；HTTP-01 挑战始终在 80 应答，与网站选择的端口无关 |
| 443/TCP | HTTPS（HTTP/1.1、HTTP/2） | 集群中有选择了证书的已启用网站绑定 443 |
| 集群的附加 HTTP 端口 | HTTP | 始终监听，见监听端口设置 |
| 集群的附加 HTTPS 端口 | HTTPS（HTTP/1.1、HTTP/2） | 始终监听 |
| HTTPS 端口的同号 UDP | HTTP/3（QUIC） | 该端口上有开启 HTTP/3 的网站 |
HTTPS 请求的 SNI 必须与 Host 一致，否则返回 421。Alt-Svc 的端口取请求的 Host 中的端口（没有端口时为 443）。增删端口是结构性变更：节点重新渲染 nginx.conf 并 reload，已有连接由旧 worker 继续服务。
集群的监听端口
- 打开 集群与节点，选择集群，切换到「网络」页签（
/clusters?tab=network）。 - 在「监听端口」卡片的「附加 HTTP 端口」「附加 HTTPS 端口」中填写端口，逗号或空格分隔。
- 点击「保存」。控制台提示「已保存」，并发布新的配置版本。
- 在节点主机的防火墙与云安全组中放行这些端口（HTTPS 端口有 HTTP/3 网站时同时放行 UDP），见端口与防火墙。
| 项目 | 规则 |
|---|---|
| 端口 | 1–65535，不含 80、443；附加 HTTP、附加 HTTPS 端口各最多 16 个；同一端口不能同时是 HTTP 和 HTTPS（「端口 {port} 不能同时用于 HTTP 和 HTTPS」） |
| 端口池 | 不能落在集群的 L4 端口池内（「端口 {port} 在端口池内：…」）；端口池也不能包含监听端口 |
| 移除 | 仍有网站绑定的端口不能移除（「端口 {port} 仍被网站使用：…」） |
| 审计 | cluster.listen_ports_update，元数据为修改前后的端口 |
| 节点能力 | 有附加端口的配置需要 edge-ports-v1；集群有活动节点缺少它时卡片显示「所在集群有节点不支持，暂时无法开启」，只能移除端口 |
网站端口
网站「域名」页签的「端口」卡片选择网站在哪些端口提供服务：HTTP 为 80 与集群的附加 HTTP 端口，HTTPS 为 443 与集群的附加 HTTPS 端口。默认 80 与 443。
| 项目 | 规则 |
|---|---|
| 至少一个 | 网站至少要在一个可用端口上提供服务（「网站至少需要一个可用端口」）；没有证书时 HTTPS 端口不可用 |
| HTTPS 端口 | 需要证书：没有证书时只能保留默认的 443（「HTTPS 端口 {port} 需要证书」）；去掉证书时网站必须还有 HTTP 端口 |
| 未绑定的端口 | 请求到达网站未绑定的端口时按未知域名处理：HTTP 返回 404 平台页（X-Edgeweir-Error: unknown-host），HTTPS 中止 TLS 握手 |
| ACME | HTTP-01 挑战始终在 80 应答；源站自己的 HTTP-01 token 在 80 仍转给源站 |
| 缓存 | 缓存键不含端口：同一网站各端口共用缓存对象 |
| 集群没有附加端口 | 网站保持默认端口时配置与之前逐字节相同，不需要 edge-ports-v1 |
OCSP 装订
| 项目 | 行为 |
|---|---|
| 响应校验 | 只接受签名、证书身份和有效期都通过验证且状态为 good 的响应；签发者证书须在证书链中 |
| 出站限制 | 拒绝私网等特殊用途地址和跳转；连接 5 秒、单次请求 8 秒，响应最大 1 MiB |
| 刷新 | 每 5 分钟及每次应用配置时检查，剩余有效期少于 1 小时时刷新 |
| 无 OCSP 地址 | 证书没有 OCSP 服务地址时不装订 |
节点上的证书
| 项目 | 行为 |
|---|---|
| 下发 | 节点通过 mTLS 单独获取证书材料；只有集群当前目标配置引用的证书 ID 与指纹获准下发 |
| 校验 | 节点检查指纹、私钥匹配和域名覆盖（等待新证书、先走 HTTP 的域名除外）；有一张证书无法加载时整个配置版本不应用，节点继续使用上一份配置，每次同步重试 |
| 存储 | 节点状态目录的 certificates.json（0600）；节点上的私钥不加密，主机管理员可读取 |
| 热更新 | 证书内容与最低 TLS 版本变化不重载 nginx |
| 重载 | HTTP/2、HTTP/3、压缩、密码套件、是否有证书、域名列表或网站集合变化时，先执行配置测试再重载；失败时恢复原配置 |
| 应用成功 | 配置持久化成功后才报告已应用；当前与上一份 last-known-good 配置引用的密钥都保留 |
| 回滚 | 配置回滚使用仍可用的当前证书材料；证书已删除、过期、节点无法加载或不覆盖目标域名时拒绝回滚 |
密钥处理
ACME 账户私钥、证书私钥和 DNS 凭据分别使用绑定记录 ID 的主密钥信封加密。证书助手 edgeweir-certd 由后台任务启动，凭据只经 stdin/stdout 传递，不出现在命令行、日志或节点配置中。
节点能力
| 能力 | 需要的场景 |
|---|---|
tls-v1 | 网站保存过「HTTPS」页签 |
http01-v1 | HTTP-01 验证 |
http3-v1 | 任一网站开启 HTTP/3 |
brotli-v1 | 任一网站开启 Brotli |
zstd-v1 | 任一网站开启 Zstandard |
tls-pending-domains-v1 | HTTPS 网站新增的域名在证书覆盖前先走 HTTP；缺少时这些域名在新证书签发前不生效，不阻止发布 |
edge-ports-v1 | 集群有附加监听端口、网站绑定了非默认端口，或 HTTPS 跳转用了非默认的状态码、端口或不跳转的域名 |
在控制台或用 AccessKey 保存的改动，即使需要集群中部分活动节点缺少的能力也会发布；缺少能力的节点保留 last-known-good 配置，集群与节点 中显示「需要升级」，见节点升级。服务账号与后台任务发布的配置引入活动节点缺少的能力时被拒绝（NODE_CAPABILITY_REQUIRED），原配置不变。
限制
| 项目 | 说明 |
|---|---|
| 证书颁发机构 | 界面只提供 Let's Encrypt 和 ZeroSSL。EDGEWEIR_ACME_DIRECTORY 和 EDGEWEIR_ACME_CA_FILE 可把全部证书改到私有或测试 ACME 目录，此时「申请证书」显示该目录而不是 CA 与 EAB 字段，见环境变量 |
| TLS 版本 | 不支持 TLS 1.0 和 1.1 |
| 密码套件 | 只有「现代」「兼容」两档，不能写入任意 nginx 配置 |
| 压缩 | Gzip、Brotli、Zstandard |
| 节点软件包 | 节点使用为 Edgeweir 构建的 OpenResty 1.31.1.1（edgeweir-openresty），含 HTTP/2、HTTP/3、Brotli 与 Zstandard，见接入节点 |
| 失败原因 | 卡片显示分类后的原因：CA 的问题类型（RFC 8555）、DNS 服务商错误或控制台一侧的原因。CA 或 DNS 服务商返回的原文不保存、不记录；控制台日志的 certificate operation failed 记录证书 ID、code 与控制台一侧的原因 |
故障排查
| 现象 | 原因 | 处理 |
|---|---|---|
| 「证书链须包含 1–10 张可读取的 PEM 证书」 | 证书链为空、超过 10 张或内容损坏 | 重新导出 PEM 格式的证书链 |
| 「无法读取私钥；不支持加密的私钥」 | 私钥损坏或带口令 | openssl pkey -in key.pem -out plain.pem 去掉口令后上传 |
| 「私钥与证书不匹配」 | 私钥属于另一张证书 | 上传与叶证书配对的私钥 |
| 「EC 私钥使用显式曲线参数，请转换为命名曲线」 | 私钥写出了完整曲线参数而不是曲线名称，节点无法加载；保存网站 HTTPS 时出现表示所选证书是此前上传的这类证书。macOS 自带的 LibreSSL 用 openssl req -newkey ec 或 openssl genpkey 生成时默认如此 | 用 OpenSSL 3 转换后上传：openssl pkey -in key.pem -ec_param_enc named_curve -out key-named.pem（LibreSSL 不能转换）；以后生成私钥时加 -pkeyopt ec_param_enc:named_curve |
| 「证书的 EC 公钥使用显式曲线参数，请用命名曲线私钥重新签发」 | 证书本身的公钥使用显式曲线参数，例如 LibreSSL 生成的自签名证书；保存网站 HTTPS 时出现表示所选证书是此前上传的这类证书 | 用转换后的私钥重新签发，或重新生成：openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -pkeyopt ec_param_enc:named_curve … |
| 证书状态「不可用」，原因「节点无法加载：证书的 EC 公钥使用显式曲线参数」或「节点无法加载：EC 私钥使用显式曲线参数」 | 此前上传的证书使用显式曲线参数 | 按上面两行转换或重新签发后上传，在使用它的网站中改选，再删除旧证书 |
节点「应用失败」，原因含 invalid certificate material（如 x509: invalid ECDSA parameters、unknown elliptic curve） | 集群的配置引用了节点无法加载的证书，整个版本不应用 | 在证书列表中找到「不可用」的证书，按上一行处理；改选后发布的新版本即可应用 |
| 「证书链顺序错误：叶证书在前，签发者依次在后」 | 中间证书排在叶证书前，或某张证书不是下一张签发的 | 按叶证书、中间证书的顺序重新组织 PEM |
| 「证书当前不在有效期内（… 至 …）」 | 证书未生效或已过期（时间为 UTC） | 核对服务器时间，或换用有效的证书 |
| 「证书没有 DNS 类型的 SAN」 | 证书只有 IP 地址或只有 CN | 换用含 DNS SAN 的证书 |
| 「不支持该证书的密钥类型；请使用 RSA（2048 位及以上）或 ECDSA P-256、P-384、P-521」 | 叶证书的密钥节点无法加载（secp256k1、Brainpool、SM2 等曲线，Ed448、RSA-PSS、DSA，或公钥指数大于 2³¹−1 的 RSA），或者浏览器无法使用（P-224、Ed25519、ML-DSA、小于 2048 位的 RSA）；节点加载失败会让集群所有节点的版本应用失败 | openssl x509 -in cert.pem -noout -text 的「Public Key Algorithm」一段显示密钥类型与位数；用 RSA 2048 位或 ECDSA P-256 私钥重新签发，例如 openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -pkeyopt ec_param_enc:named_curve -out key.pem |
| 「证书尚未签发或已过期」 | 网站选择的证书还在等待签发，或已过期 | 等待签发完成，或续期后再选择 |
| 「以下名称未解析到节点：…」 | HTTP-01 名称没有解析记录，或解析到源站、其他代理等不属于该集群节点的地址 | 把名称解析到节点；节点前面另有负载均衡或解析在变更中时，打开「跳过解析检查」 |
| 「集群 … 没有在线节点应答 HTTP-01」 | 服务这些名称的集群没有在线的活动节点 | 检查节点状态，或改用 DNS-01 |
| 「节点尚不支持：http01-v1（…）」 | 列出的在线节点缺少 http01-v1 | 升级这些节点，见节点升级 |
| 「证书域名与网站或 DNS 区域不匹配：…」 | 列出的名称：HTTP-01 申请的名称不是任何网站的域名；DNS 凭据的区域不覆盖；所选证书不覆盖网站的这些域名；为网站添加的域名不在上传的证书中，或 HTTP-01 证书无法签发的泛域名、DNS-01 证书凭据区域外的域名 | 先把域名加入网站，或改用 DNS-01；改用匹配的 DNS 凭据或证书 |
| 证书状态「签发失败」 | 卡片上的原因，见下面几行 | 修正后点击「立即续期」；否则按重试间隔自动重试 |
| 「CA 未通过域名验证」「CA 收到的挑战应答不正确」「CA 无法连接到该域名」 | HTTP-01：域名未解析到节点、80 端口不通，或前面还有其他代理；DNS-01：TXT 记录写到了别的区域 | 核对 DNS 解析与 80 端口 |
| 「CA 无法解析该域名」 | 域名没有解析记录，或权威 DNS 不可用 | 添加解析记录 |
| 「CAA 记录不允许该 CA 签发」 | 域名的 CAA 记录未列出所选 CA | 在 CAA 中加入 letsencrypt.org 或 sectigo.com（ZeroSSL），或删除 CAA |
| 「触发 CA 频率限制」 | 同一域名或账户短时间内申请过多 | 等待 CA 的限制窗口结束 |
| 「CA 要求 EAB 凭据」 | ZeroSSL 等 CA 需要 EAB | 填写 EAB 密钥 ID 与 HMAC 密钥后重新申请 |
| 「TXT 记录 3 分钟内未生效」 | DNS 服务商同步慢，或凭据区域不是域名的权威区域 | 稍后重试；核对凭据区域 |
| 「服务商认证失败」等 DNS 服务商原因 | DNS-01 写入 TXT 时服务商返回错误 | 编辑 DNS 凭据，重新填写凭据后会立即重试 |
| 「没有能应答 HTTP-01（http01-v1）的在线节点」「节点未在 40 秒内应用挑战」 | 服务该域名的集群没有在线节点、节点缺少 http01-v1 或应用配置过慢 | 检查集群节点状态，必要时升级节点 |
| 「有域名不属于任何网站」 | 证书的名称都已不是网站的域名 | 把域名加入网站，或改用 DNS-01 |
| 「有域名未解析到节点」 | 签发前的解析检查发现名称未解析到集群的节点，没有联系 CA | 修正解析；5 分钟内自动重试，或点击「立即续期」 |
| 「签发失败，详见控制台日志」 | 未分类的错误 | 在运行后台任务的控制台进程日志中查找 certificate operation failed，按 reason 处理 |
| 证书长期停在「等待签发」 | 没有运行后台任务的控制台进程 | 确认存在 ROLE=worker 或 ROLE=all 的进程 |
| 「证书正在处理中」 | 证书处于「签发中」；或网站已有一个等待绑定的申请 | 等待签发结束；在网站的「HTTPS」页签重试或取消该申请 |
| 「证书仍被网站使用：…」 | 列出的网站选择了该证书 | 先在这些网站的「HTTPS」页签改选证书 |
| 「DNS 凭据仍被证书使用：…」 | 列出的证书使用该凭据做 DNS-01 验证 | 先删除这些证书 |
| 节点显示「需要升级」 | 节点缺少配置所需能力（如 http3-v1），保留 last-known-good 配置 | 升级节点，见节点升级 |
404，X-Edgeweir-Error: unknown-host（网站已配置） | 请求到达网站未绑定的端口 | 在「域名」页签的「端口」卡片绑定该端口，或改用网站的端口 |
| 附加 HTTPS 端口上 TLS 握手失败 | 网站没有绑定该端口，或网站没有证书 | 绑定端口并选择证书 |
| 附加端口连接超时 | 节点防火墙或安全组未放行；容器节点未发布端口 | 按端口与防火墙放行 |
421，X-Edgeweir-Error: sni-host-mismatch | TLS SNI 与 Host 不一致，例如客户端复用了其他域名的连接 | 客户端按请求的域名建立连接 |
| 浏览器不使用 HTTP/3 | 网站所在 HTTPS 端口的 UDP 未放通（如 UDP 443、UDP 9443）；节点缺少 http3-v1；客户端首次访问后才读取 Alt-Svc | 放通 UDP 443，检查节点能力 |
| 响应未压缩 | 内容类型不在列表中；响应小于最小压缩大小；客户端未发送 Accept-Encoding；源站响应已带 Content-Encoding | 检查「缓存」页签的「压缩」设置 |
| 拿到 gzip 而不是 br / zstd | 客户端的 Accept-Encoding 不含该算法或 q 值更低；该算法未开启 | 检查请求头与「压缩」设置 |
| Brotli / Zstandard 开关不可用 | 集群中有活动节点不支持 brotli-v1 / zstd-v1 | 升级节点 |