ssl_manager/
├── ssl_manager.py          # SSL 证书管理主脚本
├── route_watcher.py        # 路由监听服务
├── certbot_deploy_hook.sh  # Certbot 部署钩子
├── config.json            # 配置文件
├── requirements.txt       # Python 依赖
└── README.md             # 说明文档

安装步骤

1. 安装 Certbot

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install certbot

# CentOS/RHEL
sudo yum install certbot

2. 安装 Python 依赖

cd /home/jingrow/apisix/ssl_manager

# 方法一：使用 uv（推荐，更快）
uv pip install --system -r requirements.txt

# 方法二：使用 pip3
pip3 install -r requirements.txt

3. 配置

配置已直接定义在 Python 文件中，不需要 config.json。

方式一：直接修改 Python 文件（推荐）

编辑 ssl_manager.py 中的 DEFAULT_CONFIG：

DEFAULT_CONFIG = {
    'apisix_admin_url': 'http://localhost:9180',
    'apisix_admin_key': '你的APISIX管理密钥',  # 修改这里
    'letsencrypt_email': 'your-email@example.com',  # 修改这里
    'letsencrypt_staging': False,  # 生产环境改为 False
    # ... 其他配置 ...
}

方式二：使用环境变量

export APISIX_ADMIN_KEY="your-admin-key"
export LETSENCRYPT_EMAIL="your-email@example.com"
export LETSENCRYPT_STAGING="false"

详细配置说明请查看 CONFIG.md

4. 创建 Webroot 目录

Certbot 需要 webroot 目录用于验证：

sudo mkdir -p /var/www/certbot
sudo chown -R www-data:www-data /var/www/certbot

5. 配置 APISIX 支持 Webroot 验证

需要在 APISIX 中配置一个路由，将 /.well-known/acme-challenge/ 请求转发到 webroot 目录。

使用方法

手动申请证书

# 申请单个域名证书
python3 ssl_manager.py request --domain example.com

# 申请多域名证书
python3 ssl_manager.py request --domain example.com --additional-domains www.example.com api.example.com

手动续期证书

# 续期单个域名
python3 ssl_manager.py renew --domain example.com

# 续期所有证书
python3 ssl_manager.py renew-all

同步现有证书到 APISIX

python3 ssl_manager.py sync --domain example.com

检查证书过期时间

python3 ssl_manager.py check --domain example.com

启动路由监听服务

# 持续监听（每 60 秒检查一次）
python3 route_watcher.py

# 只执行一次
python3 route_watcher.py --once

# 自定义检查间隔
python3 route_watcher.py --interval 30

自动续期配置

方法一：使用 Certbot 自动续期 + 部署钩子

配置 Certbot 自动续期：

# 编辑 Certbot 续期配置
sudo nano /etc/letsencrypt/renewal/example.com.conf

在配置文件中添加部署钩子：

[renewalparams]
deploy_hook = /home/jingrow/apisix/ssl_manager/certbot_deploy_hook.sh

测试续期：

sudo certbot renew --dry-run

设置 systemd timer（推荐）：

创建 /etc/systemd/system/certbot-renew.timer：

[Unit]
Description=Certbot Renewal Timer

[Timer]
OnCalendar=daily
RandomizedDelaySec=3600
Persistent=true

[Install]
WantedBy=timers.target

创建 /etc/systemd/system/certbot-renew.service：

[Unit]
Description=Certbot Renewal Service
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/bin/certbot renew --quiet --deploy-hook /home/jingrow/apisix/ssl_manager/certbot_deploy_hook.sh

启用定时器：

sudo systemctl enable certbot-renew.timer
sudo systemctl start certbot-renew.timer

方法二：使用自定义脚本 + systemd timer

创建 /etc/systemd/system/apisix-ssl-renew.service：

[Unit]
Description=APISIX SSL Certificate Renewal
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/bin/python3 /home/jingrow/apisix/ssl_manager/ssl_manager.py renew-all
User=root

创建 /etc/systemd/system/apisix-ssl-renew.timer：

[Unit]
Description=APISIX SSL Certificate Renewal Timer

[Timer]
OnCalendar=weekly
RandomizedDelaySec=3600
Persistent=true

[Install]
WantedBy=timers.target

启用：

sudo systemctl enable apisix-ssl-renew.timer
sudo systemctl start apisix-ssl-renew.timer

路由监听服务

路由监听服务会自动检测新创建的路由，并为其中的域名申请证书。

启动服务

# 使用 systemd（推荐）
sudo systemctl start apisix-route-watcher.service

# 或使用 screen/tmux
screen -S route-watcher
python3 route_watcher.py

创建 systemd 服务

创建 /etc/systemd/system/apisix-route-watcher.service：

[Unit]
Description=APISIX Route Watcher Service
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/python3 /home/jingrow/apisix/ssl_manager/route_watcher.py
Restart=always
RestartSec=10
User=root

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl enable apisix-route-watcher.service
sudo systemctl start apisix-route-watcher.service

环境变量配置

也可以通过环境变量配置：

export APISIX_ADMIN_URL="http://localhost:9180"
export APISIX_ADMIN_KEY="your-admin-key"
export LETSENCRYPT_EMAIL="your-email@example.com"
export LETSENCRYPT_STAGING="false"
export WEBROOT_PATH="/var/www/certbot"

注意事项

首次使用建议使用 staging 模式测试：
```
"letsencrypt_staging": true
```
确保 80 端口可访问：Let's Encrypt 需要验证域名所有权，通常使用 HTTP-01 验证方式。
DNS 验证：如果无法使用 HTTP-01 验证，可以配置 DNS-01 验证（需要修改脚本）。
证书存储：证书存储在 /etc/letsencrypt/live/ 目录，请确保有备份。
日志位置：
- SSL 管理器日志：/var/log/apisix-ssl-manager.log
- 路由监听日志：/var/log/apisix-route-watcher.log
- Certbot 部署钩子日志：/var/log/apisix-certbot-deploy.log

故障排查

证书申请失败

检查域名 DNS 解析是否正确
检查 80 端口是否可访问
检查 webroot 目录权限
查看 Certbot 日志：/var/log/letsencrypt/letsencrypt.log

证书无法同步到 APISIX

检查 APISIX Admin API 是否可访问
检查 Admin Key 是否正确
查看 SSL 管理器日志

自动续期不工作

检查 systemd timer 状态：systemctl status certbot-renew.timer
手动测试续期：certbot renew --dry-run
检查部署钩子脚本权限：chmod +x certbot_deploy_hook.sh

测试

测试环境（staging）

"letsencrypt_staging": true

Staging 环境有更高的申请频率限制，适合测试。

生产环境

测试通过后，设置：

"letsencrypt_staging": false

许可证

Apache License 2.0

README.md Unescape Escape

APISIX SSL 证书自动管理

功能特性

目录结构