adep-ops

adep 自建部署的边缘侧运维 CLI：给任意第三方域名 / 自定义 CNAME 签发证书、建 vhost、登记 1panel， 并与平台库对账自动接入。面向 1panel + openresty 终结 TLS 的部署形态。

npm i -g adep-ops
adep-ops doctor          # 先体检
adep-ops install         # 装上两条 cron，之后新域名自动接入

它解决什么问题

用户在控制台绑定了一个不属于平台区域的域名（shop.example.com）并 CNAME 过来之后：

• 平台侧已经就绪 —— 网关能按 Host 路由（project_domains.status='verified'）
• 边缘侧没动 —— 443 上没有属于它的证书，SNI 落到 default_server 拿到平台泛域名证书 ⇒ 浏览器报「证书不安全」

泛域名证书只吃一层（*.a.com 覆盖不到 x.y.a.com，更覆盖不到别人的域名）， 所以第三方域名只能一域名一证书 + 一 vhost。签发走 HTTP-01（webroot）， 域名解析到本机即可，不需要用户提供 DNS API 凭据。

命令

| 命令 | 作用 | 需要 root | | --- | --- | --- | | adep-ops preflight <domain> | DNS + HTTP-01 通道前置检查（只读） | | | adep-ops add <domain> [--staging] | 接入：签发 + vhost + 登记 1panel + 重载 + 自验证 | ✓ | | adep-ops list | 列出托管域名与到期时间 | | | adep-ops renew | 续期全部托管域名（cron 每天 03:17） | ✓ | | adep-ops remove <domain> | 下线（删 vhost 与 1panel 记录，保留证书） | ✓ | | adep-ops sync [--dry-run] | 与平台库对账，自动接入已验证域名（cron 每 5 分钟） | ✓ | | adep-ops check-dns [domain] | 控制台「校验解析」失败的现场自检 | | | adep-ops install / uninstall | 写入 / 撤掉 /etc/cron.d/adep-ops | ✓ | | adep-ops doctor | 部署体检（有不合格项退出码 1） | |

所有命令幂等：任何一步都能单独重跑，这是 cron 能安全调度它的前提。

add 做的事

1. DNS 前置检查（DoH 查 A，必须指向本机；ADEP_ALLOW_PROXIED_DNS=1 放行 CDN 回源）
2. acme.sh HTTP-01（webroot）签发，镜像顺序回退下载 acme.sh
3. --install-cert 落盘到 <panel>/www/sites/<domain>/ssl/ 并登记 reload 命令
4. 生成 vhost <panel>/www/conf.d/<domain>.conf + proxy/root.conf
5. 从其它 vhost 的 server_name 摘除该域名（否则 nginx 只认先定义的，新 vhost 被静默忽略）
6. 登记 1panel（website_ssls / websites / website_domains），先备份 agent.db
7. nginx -t + reload，然后真实 TLS 握手自验证（证书不被信任就报错）

装机

adep-ops install

写入 /etc/cron.d/adep-ops：

17 3   * * *  root <bin> renew >> /var/log/adep-ops-renew.log 2>&1
*/5    * * *  root <bin> sync  >> /var/log/adep-ops-sync.log  2>&1

<bin> 会落成「绝对路径 node + 绝对路径入口」，绕开 cron 的极简 PATH。 重跑 install 会整体覆盖；不再需要就 uninstall。

配置（环境变量）

默认值即生产现状，本机直接跑即可；换机器用环境变量覆盖。

| 变量 | 默认 | 说明 | | --- | --- | --- | | ADEP_OPS_DIR | /opt/adep/ops | 状态根目录（托管清单 / acme / 备份） | | ADEP_OPS_PANEL_ROOT | /opt/1panel | 1panel 根目录（DB / conf / 站点都在它下面） | | ADEP_SERVER_IP | 47.119.137.242 | 本机公网 IP（判定「DNS 是否指向本机」） | | ADEP_APP_UPSTREAM | http://47.119.137.242:3000 | vhost 反代目标 | | ADEP_ALLOW_PROXIED_DNS | 0 | 置 1：域名解析到 CDN 回源而非本机时也继续 | | ADEP_SYNC_RETRY_HOURS | 6 | 接入失败后的冷却小时数 | | ADEP_OPS_VOLUME | adep_app-data | 平台库所在的 docker 命名卷 | | ADEP_OPS_APP_CONTAINER | adep-app | 平台应用容器（check-dns 在里面复现解析） | | ADEP_OPS_CRON_FILE | /etc/cron.d/adep-ops | cron 落盘位置 |

三个容易踩的坑

1. 中国大陆节点 + 未备案域名 = 网络层拦死

与 nginx / 证书配置无关，80 按 Host、443 按 SNI 都会拦（阿里云返回 Server: Beaver + Non-compliance ICP Filing）。判定：

curl -i -H 'Host: <domain>' http://<本机IP>/

本机回环自测永远通过，所以 preflight 通过 ≠ 外网可达。

2. 控制台「校验解析」失败，多半不是配错了

平台走的是容器内 node:dns/promises，与宿主 dig 不是同一条链。递归解析器对新记录有 几十秒~数分钟的不可见窗口，而每次 NODATA 都会刷新负缓存 ⇒ 连点按钮只会越等越久。

adep-ops check-dns <domain>     # 走与平台相同的解析路径逐层判定

处置：加完记录等 1~5 分钟，自检报「通过」后再点一次。

3. 域名别同时挂在两个站上

website_domains 里同一域名两行 ⇒ nginx 只认先定义的那份（日志里只有一句 conflicting server name ... ignored，没有任何报错）。doctor 会查这一项。

依赖的外部命令

sqlite3、openssl、docker、（可选）curl。doctor 会逐项检查。

License

MIT