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记录指向服务器公网 IPCloud 用CNAME指向 Cloud 目标一条归属证明记录主机名为_openship-challenge的TXT记录内容是 Openship 给出的密钥串。验证VerifyOpenship 会分别查询这两条记录哪条不匹配就会明确告诉你具体是哪条、期望值是什么。证书签发验证通过后由管理端 OpenResty 边缘上的Certbot走 ACME 协议默认 Lets Encrypt签发证书并自动重写现有路由加上 TLS。自动续期ssl:renew定时任务会扫描临期证书约到期前两周窗口内批量续期签发过程带按域名的锁避免并发 ACME 请求烧掉 Lets 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 与续期排障症状域名已 VerifiedSSL 徽章却停在 ProvisioningProvisioning表示签发仍在进行、结果未观测到、或首次尝试失败。处理顺序等一小会点域名⋯菜单的Recheck SSL——这是只读检查不重新签发、不消耗限流配额证书就位后状态立即翻成Active。若提示 No valid certificate found… give Lets Encrypt a moment, then recheck说明证书确实还没签发完稍后再 Recheck。想要立即重试就点Renew SSL真实失败原因DNS 未就绪、端口被封、Lets 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 统一问题面板合并了容器故障、部署阻塞、路由未同步、未验证域名、证书错误等所有检查项按严重度排序outageaction_requiredadvisory。关键点是每条问题都带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 CAOpenship 默认使用 Lets Encrypt 生产环境也可通过环境变量切换为ZeroSSL、Lets 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.tsSSL 自动续期定时任务apps/api/src/lib/ssl-scheduler.ts签发并发锁防限流/端口冲突apps/api/src/lib/provision-lock.tsaction 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/SSLapps/web/content/docs/troubleshooting/domains-ssl.mdx自定义域名完整指南apps/web/content/docs/guides/custom-domains.mdxACME CA 配置文档docs/acme.md九、排障清单30 秒自检✅ A/CNAME 路由记录指向的 IP/目标与面板一致吗复制而非手输✅_openship-challengeTXT 记录的值与面板密钥串完全一致吗✅ 用dig在公网能查到新值吗查不到就等传播。✅ 域名是 Verified 了吗SSL 操作的前提条件。✅ Provisioning 卡住时先 Recheck SSL免费再 Renew SSL看真实报错。✅ 看到 action required打开 Issues 面板按resolveWith执行别猜 id。✅ TLS 由你自己的边缘终结开启 External ingress TLS只做 TXT 验证。按以上顺序排查绝大多数 Openship 域名与 SSL 问题都能在不重启、不重新部署的情况下解决。【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考