# 快速开始指南

## 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
```

## 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

# 续期证书
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`