Openship域名与SSL排障：DNS解析、证书续期与action required处理指南-平芜编程栈

Openship域名与SSL排障：DNS解析、证书续期与action required处理指南

【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship

本文是 Openship 自托管部署平台的域名与 SSL 排障指南，面向新手覆盖三大高频问题：DNS 解析验证失败、证书卡在 Provisioning 无法续期、以及部署出现action required（需要人工处理）状态时的处理方法，帮助你在不阅读源码的情况下快速定位并修复 HTTPS 相关故障。

一、先搞懂 Openship 域名与证书的工作机制

在排查之前，先理解 Openship 的域名/SSL 流程，能帮你快速判断问题卡在哪一环：

DNS 记录：每个自定义域名需要两条记录——一条路由记录（自托管用A记录指向服务器公网 IP，Cloud 用CNAME指向 Cloud 目标），一条归属证明记录（主机名为_openship-challenge的TXT记录，内容是 Openship 给出的密钥串）。
验证（Verify）：Openship 会分别查询这两条记录，哪条不匹配就会明确告诉你具体是哪条、期望值是什么。
证书签发：验证通过后，由管理端 OpenResty 边缘上的Certbot走 ACME 协议（默认 Let's Encrypt）签发证书，并自动重写现有路由加上 TLS。
自动续期：ssl:renew定时任务会扫描临期证书（约到期前两周窗口内）批量续期；签发过程带按域名的锁，避免并发 ACME 请求烧掉 Let's Encrypt 配额。

💡 域名状态字段sslStatus的取值含义：none（无证书）→provisioning（签发中）→active（正常）或error（失败）。看懂这个状态机，排障就成功了一半。

二、DNS 解析验证失败的快速修复

症状：点击 Verify 一直不通过

"Verification failed" 提示会精确指出失败记录，常见三种：

看到的提示	哪条记录出问题	原因
`A record not pointing to server for …`	路由`A`记录（自托管）	缺失，或指向的 IP 与服务器公网 IP 不一致
`CNAME record not found for …`	路由`CNAME`记录（Cloud）	缺失或指向错误目标
`TXT record _openship-challenge.… must equal "…"`	归属`TXT`记录	缺失或密钥串复制不完整

最快修复步骤

打开项目的Domains页签，重新打开该域名的DNS Records面板，对照注册商处的实际记录。
从 Openship 面板直接复制记录值，不要手动输入——多一个空格都会验证失败。
先删除同名旧记录（残留的旧A/CNAME是常见元凶），再保存新值。
等待生效后点击Verify。

⚠️ 自托管特别提醒：A记录必须解析到"外部世界实际看到的"公网 IP。如果服务器在 NAT 或代理之后改变了地址，指向内网 IP 会永远验证失败。

三、DNS 尚未生效（传播延迟）怎么办

记录看起来填对了，但 Verify 仍提示记录不存在？这是 DNS 传播延迟，不是 Openship 的问题。

面板本身也会提示："DNS 变更最多需要 48 小时才能在全球生效"，通常几分钟即可。
可以用dig A app.example.com或dig TXT _openship-challenge.app.example.com自查：如果公网查不到新值，Openship 同样查不到。
不用干等：Openship 默认开启Domain DNS verification后台任务，每 13 分钟运行一次，对创建满 10 分钟的待验证域名自动重试验证和证书签发；手动点Verify只是更快的显式重试。

四、证书卡在 Provisioning 与续期排障

症状：域名已 Verified，SSL 徽章却停在 Provisioning

Provisioning表示签发仍在进行、结果未观测到、或首次尝试失败。处理顺序：

等一小会，点域名⋯菜单的Recheck SSL——这是只读检查（不重新签发、不消耗限流配额），证书就位后状态立即翻成Active。
若提示 "No valid certificate found… give Let's Encrypt a moment, then recheck"，说明证书确实还没签发完，稍后再 Recheck。
想要立即重试就点Renew SSL：真实失败原因（DNS 未就绪、端口被封、Let's Encrypt 限流、ACME 故障）都会在这个动作里明确报出。

关于自动续期，你需要知道的

证书Active后通常完全不用管：临期证书由续期任务自动处理。
手动上传的证书（BYO）不会被 certbot 续期，到期前需自行更换。
若提示Domain must be verified before SSL can be managed，说明域名还没通过验证——先完成上面的 DNS 修复。
正常情况下Verify 后不需要重新部署：证书提供者会把已有路由重新注册为 TLS。如果只有重新部署后 HTTPS 才生效，说明存在边缘/路由对账问题，需保留部署日志与验证日志排查。

五、action required 状态是什么、怎么处理

Openship 把"系统自己修不了、必须有人动手"的问题统一标记为action required（区别于纯failed和普通告警）。你可以在两个地方看到它：

Issues 统一问题面板：合并了容器故障、部署阻塞、路由未同步、未验证域名、证书错误等所有检查项，按严重度排序（outage>action_required>advisory）。关键点是：每条问题都带resolveWith字段——可以直接调用的修复动作（已替你把参数填好），照着执行即可。
部署详情：部署失败若属于阻塞类错误（如路由冲突），状态会是action_required而非failed，意味着"部署被挂起等待你的决定"。它带pendingPrompt与expiresAt——在超时前用build/respond（或面板上的待决操作）回复该 action id，部署会继续；超时则自动中止。

🎯 排障黄金路径：先打开 Issues 面板看整体计数（outage / actionRequired / advisory），再按resolveWith给的调用或面板按钮逐项处理，而不是在单个项目里盲目翻日志。

六、特殊场景：外部 Ingress（你的边缘自己终结 TLS）

如果应用已经挂在 Cloudflare Tunnel、负载均衡器或 Traefik/Caddy 之后由你自己的边缘处理 HTTPS，而 Openship 仍在要求 A/CNAME 记录并尝试签发证书——请在添加域名时打开External ingress & TLS开关：

只需添加_openship-challenge的TXT记录做归属验证，无需路由记录；
验证成功后 SSL 状态显示External TLS，这是正确且最终的状态——Openship 不会为其运行 certbot；
只有当你的边缘确实终结 TLS 时才开启此开关，否则域名会验证通过但只有裸 HTTP。

七、进阶：更换证书颁发机构（ACME CA）

Openship 默认使用 Let's Encrypt 生产环境，也可通过环境变量切换为ZeroSSL、Let's Encrypt staging（测试用）或step-ca 私有 CA，支持 EAB（外部账户绑定）凭据与ec256/rsa2048等密钥类型。要点：

更换 CA 后，旧证书无法跨 CA 续期——Openship 会在下次续期时为该域名在新 CA 下一次性重新签发，期间旧证书继续服务，不中断流量。
详细配置项与环境变量说明见官方文档apps/web/content/docs/中的 ACME 说明（docs/acme.md），以及私有 CA 信任根挂载方式。

八、关键文件速查

内容	文件路径
域名 SSL 签发/续期/验证核心逻辑	`apps/api/src/lib/domain-ssl.ts`
SSL 自动续期定时任务	`apps/api/src/lib/ssl-scheduler.ts`
签发并发锁（防限流/端口冲突）	`apps/api/src/lib/provision-lock.ts`
action required 状态判定	`apps/api/src/modules/deployments/blocking-errors.ts`
统一 Issues 面板与严重度定义	`apps/api/src/modules/issues/issues.service.ts`
域名数据模型（sslStatus 等字段）	`packages/db/src/schema/domain.ts`
官方排障文档（域名/DNS/SSL）	`apps/web/content/docs/troubleshooting/domains-ssl.mdx`
自定义域名完整指南	`apps/web/content/docs/guides/custom-domains.mdx`
ACME CA 配置文档	`docs/acme.md`