apisix/ssl_manager/TEST_README.md

SSL 证书自动申请测试脚本使用说明

功能

test_ssl_auto.py 是一个完整的测试脚本，用于测试从路由创建到 SSL 证书申请的整个流程。

测试步骤

脚本会依次执行以下步骤，每个步骤都会显示成功或失败：

1. 检查系统依赖 - 检查 certbot、Python 模块等
2. 检查 APISIX 服务 - 验证 APISIX Admin API 是否可访问
3. 检查 Webroot 目录 - 检查验证文件目录是否存在
4. 检查/创建 Webroot 路由 - 检查或创建验证路由
5. 测试验证路径 - 测试验证路径是否可访问
6. 创建测试路由 - 创建测试域名路由
7. 申请 SSL 证书 - 使用 Let's Encrypt 申请证书
8. 同步证书到 APISIX - 将证书上传到 APISIX
9. 验证证书信息 - 验证证书是否有效

使用方法

基本用法

# 使用自动生成的测试域名（测试完成后自动清理）
python3 test_ssl_auto.py

# 指定测试域名
python3 test_ssl_auto.py --domain test.example.com

# 指定配置文件
python3 test_ssl_auto.py --config config.json --domain test.example.com

选项说明

• --domain, -d: 指定测试域名（不指定则自动生成）
• --config, -c: 指定配置文件路径（默认使用环境变量或默认配置）
• --cleanup: 测试完成后清理测试数据（路由和 SSL 配置）
• --no-cleanup: 测试完成后不清理测试数据

示例

# 示例1: 快速测试（自动生成域名，自动清理）
python3 test_ssl_auto.py

# 示例2: 测试指定域名（保留测试数据）
python3 test_ssl_auto.py --domain test.jingrowtools.cn --no-cleanup

# 示例3: 使用配置文件，测试完成后清理
python3 test_ssl_auto.py --config config.json --domain test.jingrowtools.cn --cleanup

输出说明

成功输出示例

✅ 检查系统依赖 - 成功
✅ 检查 APISIX 服务 - 成功
✅ 检查 Webroot 目录 - 成功
...

失败输出示例

❌ 检查系统依赖 - 失败
❌ 检查 APISIX 服务 - 异常: Connection refused
...

注意事项

1. 域名解析: 测试域名必须 DNS 解析到当前服务器，否则证书申请会失败
2. Staging 模式: 默认使用 staging 模式（测试环境），不会消耗生产环境配额
3. 权限要求: 某些操作需要 root 权限（如创建证书文件）
4. 清理数据: 使用自动生成的域名时，默认会清理测试数据；指定域名时，默认保留数据

测试流程

开始测试
  ↓
检查依赖 → 失败 → 结束
  ↓ 成功
检查 APISIX → 失败 → 结束
  ↓ 成功
检查 Webroot → 失败 → 结束
  ↓ 成功
检查/创建路由 → 失败 → 结束
  ↓ 成功
测试验证路径 → 失败 → 结束
  ↓ 成功
创建测试路由 → 失败 → 结束
  ↓ 成功
申请证书 → 失败 → 结束
  ↓ 成功
同步证书 → 失败 → 结束
  ↓ 成功
验证证书 → 完成
  ↓
清理数据（可选）
  ↓
显示测试总结

故障排查

1. Certbot 未安装

sudo apt-get install certbot

2. APISIX 服务不可访问

# 检查 APISIX 是否运行
docker ps | grep apisix

# 检查端口
netstat -tlnp | grep 9180

3. Webroot 目录不存在

sudo mkdir -p /var/www/certbot/.well-known/acme-challenge
sudo chown -R www-data:www-data /var/www/certbot

4. 验证路径不可访问

• 检查 webroot 路由是否正确配置
• 检查路由 priority 是否足够高
• 检查路由 host 是否匹配

完整测试示例

# 1. 准备测试域名（确保 DNS 已解析）
export TEST_DOMAIN="test-$(date +%s).jingrowtools.cn"

# 2. 运行测试
python3 test_ssl_auto.py --domain $TEST_DOMAIN --no-cleanup

# 3. 检查结果
curl -v https://$TEST_DOMAIN

# 4. 清理（如果需要）
python3 ssl_manager.py sync --domain $TEST_DOMAIN  # 先同步证书
# 然后手动删除路由和 SSL 配置

与生产环境集成

测试通过后，可以：

1. 修改 config.json 设置 letsencrypt_staging: false
2. 使用 ssl_manager.py 申请生产证书
3. 配置自动续期

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

# 启用自动续期
sudo systemctl enable apisix-ssl-renew.timer
sudo systemctl start apisix-ssl-renew.timer