lua/apisix

jingrow 8ff3bf27ab feat: 支持多域名证书申请（SAN证书）

- 在 QUICKSTART.md 中添加多域名申请的详细说明和示例
- 修复多域名申请时只为所有域名创建 webroot 路由的问题
- 支持使用 --additional-domains 参数申请包含多个域名的证书

2026-01-03 22:13:58 +08:00

6.8 KiB

Raw Blame History

快速开始指南

1. 安装依赖

cd /home/jingrow/apisix/ssl_manager

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

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

# 运行安装脚本（可选，会自动设置权限和 systemd 服务）
sudo bash install.sh

2. 配置

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

修改配置：

编辑 ssl_manager.py 中的 DEFAULT_CONFIG：

DEFAULT_CONFIG = {
    'apisix_admin_url': 'http://localhost:9180',
    'apisix_admin_key': '8206e6e42b6b53243c52a767cc633137',
    'letsencrypt_email': 'your-email@example.com',  # 修改为你的邮箱
    'letsencrypt_staging': True,  # 首次使用建议 True（测试环境）
    # ... 其他配置 ...
}

首次使用建议设置 letsencrypt_staging: True 进行测试！

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

3. 创建 Webroot 目录

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

4. 配置 APISIX 支持 HTTP-01 验证

Let's Encrypt 需要通过 HTTP-01 验证域名所有权。需要确保 /.well-known/acme-challenge/ 路径可以访问。

方法一：使用 Nginx（如果 APISIX 前面有 Nginx）

在 Nginx 配置中添加：

location /.well-known/acme-challenge/ {
    root /var/www/certbot;
}

方法二：在 APISIX 中创建路由

使用 APISIX Admin API 创建路由：

curl -X PUT 'http://localhost:9180/apisix/admin/routes/certbot-webroot' \
  -H 'X-API-KEY: 8206e6e42b6b53243c52a767cc633137' \
  -H 'Content-Type: application/json' \
  -d '{
    "uri": "/.well-known/acme-challenge/*",
    "name": "certbot-webroot",
    "plugins": {
      "serverless-pre-function": {
        "phase": "rewrite",
        "functions": [
          "return function(conf, ctx) local file = io.open(\"/var/www/certbot\" .. ctx.var.uri, \"r\"); if file then local content = file:read(\"*all\"); file:close(); ngx.header.content_type = \"text/plain\"; ngx.say(content); end end"
        ]
      }
    }
  }'

或者使用静态文件服务插件（如果可用）。

5. 测试申请证书（Staging 环境）

单域名申请

# 测试申请证书
python3 ssl_manager.py request --domain your-domain.com

# 检查证书
python3 ssl_manager.py check --domain your-domain.com

多域名申请（SAN 证书）

一个证书可以包含多个域名（Subject Alternative Names），适用于：

主域名和 www 子域名
多个相关域名
通配符域名的替代方案

方法一：使用 --additional-domains 参数

# 申请包含多个域名的证书
python3 ssl_manager.py request --domain jingrowtools.com --additional-domains www.jingrowtools.com

# 或者使用简写 -a
python3 ssl_manager.py request -d example.com -a www.example.com api.example.com

方法二：多次使用 -d 参数（如果支持）

# 注意：certbot 会自动将所有 -d 参数中的域名包含在一个证书中
python3 ssl_manager.py request --domain example.com --additional-domains www.example.com

说明：

主域名（--domain）将作为证书名称
所有域名（主域名 + 额外域名）都会被包含在证书的 SAN（Subject Alternative Names）中
证书申请成功后，会自动同步到 APISIX，所有域名都可以使用同一个证书
续期时只需要使用主域名：python3 ssl_manager.py renew --domain example.com

示例：

# 为 example.com 和 www.example.com 申请证书
python3 ssl_manager.py request --domain example.com --additional-domains www.example.com

# 为多个子域名申请证书
python3 ssl_manager.py request --domain api.example.com --additional-domains api2.example.com api3.example.com

# 检查证书（使用主域名）
python3 ssl_manager.py check --domain example.com

6. 配置自动续期

使用 systemd timer（推荐）

# 安装 systemd 服务
sudo cp systemd/apisix-ssl-renew.* /etc/systemd/system/
sudo systemctl daemon-reload

# 启用并启动定时器
sudo systemctl enable apisix-ssl-renew.timer
sudo systemctl start apisix-ssl-renew.timer

# 查看状态
sudo systemctl status apisix-ssl-renew.timer

或使用 Certbot 自动续期

编辑 Certbot 续期配置，添加部署钩子：

sudo nano /etc/letsencrypt/renewal/your-domain.com.conf

在 [renewalparams] 部分添加：

deploy_hook = /home/jingrow/apisix/ssl_manager/certbot_deploy_hook.sh

7. 启动路由监听服务（可选）

自动监听新路由并申请证书：

# 使用 systemd
sudo cp systemd/apisix-route-watcher.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable apisix-route-watcher.service
sudo systemctl start apisix-route-watcher.service

# 或手动运行
python3 route_watcher.py

8. 切换到生产环境

测试通过后，修改 ssl_manager.py 中的 DEFAULT_CONFIG：

DEFAULT_CONFIG = {
    # ... 其他配置 ...
    'letsencrypt_staging': False,  # 改为 False 使用生产环境
    # ... 其他配置 ...
}

然后重新申请证书：

# 删除测试证书
sudo rm -rf /etc/letsencrypt/live/your-domain.com
sudo rm -rf /etc/letsencrypt/archive/your-domain.com
sudo rm -rf /etc/letsencrypt/renewal/your-domain.com.conf

# 申请生产证书
python3 ssl_manager.py request --domain your-domain.com

常用命令

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

# 申请多域名证书（SAN 证书）
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

# 查看日志
tail -f /var/log/apisix-ssl-manager.log
tail -f /var/log/apisix-route-watcher.log

故障排查

证书申请失败

检查域名 DNS 解析：nslookup your-domain.com
检查 80 端口是否可访问：curl http://your-domain.com/.well-known/acme-challenge/test
查看 Certbot 日志：sudo tail -f /var/log/letsencrypt/letsencrypt.log
使用 staging 模式测试：letsencrypt_staging: true

证书无法同步到 APISIX

检查 APISIX Admin API：curl http://localhost:9180/apisix/admin/routes -H 'X-API-KEY: your-key'
检查 Admin Key 是否正确
查看 SSL 管理器日志：tail -f /var/log/apisix-ssl-manager.log

自动续期不工作

检查 systemd timer：sudo systemctl status apisix-ssl-renew.timer
手动测试续期：sudo certbot renew --dry-run
检查部署钩子权限：ls -l certbot_deploy_hook.sh

6.8 KiB Raw Blame History Unescape Escape