jingrow
8ff3bf27ab
- 在 QUICKSTART.md 中添加多域名申请的详细说明和示例 - 修复多域名申请时只为所有域名创建 webroot 路由的问题 - 支持使用 --additional-domains 参数申请包含多个域名的证书
257 lines
6.8 KiB
Markdown
257 lines
6.8 KiB
Markdown
# 快速开始指南
|
||
|
||
## 1. 安装依赖
|
||
|
||
```bash
|
||
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`：
|
||
|
||
```python
|
||
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 目录
|
||
|
||
```bash
|
||
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 配置中添加：
|
||
|
||
```nginx
|
||
location /.well-known/acme-challenge/ {
|
||
root /var/www/certbot;
|
||
}
|
||
```
|
||
|
||
### 方法二：在 APISIX 中创建路由
|
||
|
||
使用 APISIX Admin API 创建路由：
|
||
|
||
```bash
|
||
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 环境）
|
||
|
||
### 单域名申请
|
||
|
||
```bash
|
||
# 测试申请证书
|
||
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` 参数**
|
||
|
||
```bash
|
||
# 申请包含多个域名的证书
|
||
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` 参数（如果支持）**
|
||
|
||
```bash
|
||
# 注意：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`
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# 为 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（推荐）
|
||
|
||
```bash
|
||
# 安装 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 续期配置，添加部署钩子：
|
||
|
||
```bash
|
||
sudo nano /etc/letsencrypt/renewal/your-domain.com.conf
|
||
```
|
||
|
||
在 `[renewalparams]` 部分添加：
|
||
|
||
```ini
|
||
deploy_hook = /home/jingrow/apisix/ssl_manager/certbot_deploy_hook.sh
|
||
```
|
||
|
||
## 7. 启动路由监听服务（可选）
|
||
|
||
自动监听新路由并申请证书：
|
||
|
||
```bash
|
||
# 使用 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`：
|
||
|
||
```python
|
||
DEFAULT_CONFIG = {
|
||
# ... 其他配置 ...
|
||
'letsencrypt_staging': False, # 改为 False 使用生产环境
|
||
# ... 其他配置 ...
|
||
}
|
||
```
|
||
|
||
然后重新申请证书：
|
||
|
||
```bash
|
||
# 删除测试证书
|
||
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
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 申请单域名证书
|
||
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
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
### 证书申请失败
|
||
|
||
1. 检查域名 DNS 解析：`nslookup your-domain.com`
|
||
2. 检查 80 端口是否可访问：`curl http://your-domain.com/.well-known/acme-challenge/test`
|
||
3. 查看 Certbot 日志：`sudo tail -f /var/log/letsencrypt/letsencrypt.log`
|
||
4. 使用 staging 模式测试：`letsencrypt_staging: true`
|
||
|
||
### 证书无法同步到 APISIX
|
||
|
||
1. 检查 APISIX Admin API：`curl http://localhost:9180/apisix/admin/routes -H 'X-API-KEY: your-key'`
|
||
2. 检查 Admin Key 是否正确
|
||
3. 查看 SSL 管理器日志：`tail -f /var/log/apisix-ssl-manager.log`
|
||
|
||
### 自动续期不工作
|
||
|
||
1. 检查 systemd timer：`sudo systemctl status apisix-ssl-renew.timer`
|
||
2. 手动测试续期：`sudo certbot renew --dry-run`
|
||
3. 检查部署钩子权限：`ls -l certbot_deploy_hook.sh`
|