0908

acme/README.md

@@ -0,0 +1,98 @@
+# 证书管理服务（acme.sh）
+
+用宿主机上的 [acme.sh](https://github.com/acmesh-official/acme.sh) 管理 Let's Encrypt 证书：
+纯 Shell 实现，不依赖 Python / snap / Docker 容器。
+
+## 为什么换成 acme.sh
+
+之前用 certbot 容器时有个绕不开的别扭点：certbot 的 `--deploy-hook` 在**容器内**执行，
+而我们要 reload 的 nginx 是**宿主机上的容器**，只能在容器里挂 `docker.sock`（等于把宿主机
+root 交给容器），或者退而求其次每天无条件发一次 HUP。
+
+acme.sh 直接跑在宿主机，`--reloadcmd` 天然在宿主机执行，**只在证书真正更新时才 reload**，
+顺带把 certbot 容器、Dockerfile、docker.sock、compose PATH 问题全部消掉。
+
+## 架构
+
+```
+宿主机                                     容器
+─────────────────────────────────────    ──────────────────────────
+acme.sh（~/.acme.sh，自带 cron）
+  ├─ 写挑战文件 ──▶ /var/www/certbot   ──bind mount(ro)──▶ nginx-proxy
+  ├─ 写证书     ──▶ /etc/letsencrypt    ──bind mount(ro)──▶ nginx-proxy
+  └─ 续签后执行 reloadcmd: docker kill -s HUP nginx-proxy
+
+用户 ─▶ frps(80/443) ─▶ frpc ─▶ nginx-proxy(80/8443)
+```
+
+## 目录约定
+
+| 宿主机路径 | 用途 |
+|---|---|
+| `/var/www/certbot` | ACME HTTP-01 挑战文件 |
+| `/etc/letsencrypt/live/<CERT_NAME>/` | 证书（默认 CERT_NAME=stonelan.cn） |
+| `nginx/ssl.d/` | HTTPS server 块，证书就绪后由 `enable-ssl.sh` 写入 |
+
+5 个域名合成**一张 SAN 证书**，放在同一个目录，nginx 的 5 个 server 块都引用它。
+
+## 使用方法
+
+### 1. 安装
+
+```bash
+cd common-server-public/acme
+chmod +x install.sh issue.sh renew.sh check-cert.sh
+./install.sh
+```
+
+### 2. 申请证书（一键引导）
+
+```bash
+sudo ./issue.sh
+```
+
+依次完成：建目录 → 起 nginx（此时无 HTTPS 配置）→ 申请证书 → 安装证书 →
+写入 `ssl.d/` 并重载 nginx。
+
+可用环境变量覆盖：
+
+```bash
+EMAIL=you@example.com \
+CERT_NAME=stonelan.cn \
+DOMAINS="fastgpt.stonelan.cn gitea.stonelan.cn image.stonelan.cn registry.stonelan.cn www.stonelan.cn" \
+sudo -E ./issue.sh
+```
+
+### 3. 自动续签
+
+`install.sh` 已让 acme.sh 自己写入 cron，**无需额外配置**。
+
+建议再加一条兜底告警（`crontab.example`）：
+
+```cron
+0 8 * * * bash <绝对路径>/check-cert.sh >> /var/log/acme-check.log 2>&1
+```
+
+## 故障排查
+
+```bash
+acme.sh --list                       # 已申请的证书
+acme.sh --cron --debug 2             # 带调试跑一次续签
+./check-cert.sh                      # 剩余天数
+
+# 确认 nginx 只加载了 HTTP 配置（冷启动时属正常）
+docker exec nginx-proxy nginx -T | grep -c "listen 8443"
+
+# ACME 路径可达性
+echo probe | sudo tee /var/www/certbot/.well-known/acme-challenge/test
+curl -i http://fastgpt.stonelan.cn/.well-known/acme-challenge/test
+```
+
+## 注意事项
+
+1. 需要 root（或 sudo）运行：要写 `/etc/letsencrypt` 和 `/var/www`
+2. nginx 容器 bind mount 的是**宿主机路径**，宿主机上这两个目录必须存在，
+   否则 docker 会自动创建成 root 所有的空目录
+3. 挑战文件需要让容器内 nginx 可读，目录保持 755（`issue.sh` 已处理）
+4. CA 已显式固定为 Let's Encrypt（acme.sh 3.x 默认是 ZeroSSL）
+5. 证书有效期 90 天，acme.sh 默认在剩余 30 天内续签