# SSL 证书自动续期指南

## 概述

XNode 支持 SSL 证书的自动续期功能，通过 cron 定时任务定期检查证书到期时间，在证书到期前自动续期。

## 功能特性

- ✅ 自动检查证书到期时间
- ✅ 到期前自动续期（默认提前 30 天）
- ✅ 续期后自动重启 xnode 服务
- ✅ 详细的日志记录
- ✅ 支持自定义续期时间

## 快速开始

### 1. 安装自动续期定时任务

```bash
# 使用默认时间（每天 03:00）
chmod +x install-cron.sh
sudo ./install-cron.sh --install

# 或指定执行时间（例如：每天 02:30）
sudo ./install-cron.sh --install --time 02:30
```

### 2. 检查定时任务状态

```bash
sudo ./install-cron.sh --check
```

### 3. 查看续期日志

```bash
# 实时查看日志
tail -f cert-renew.log

# 查看最近 50 行日志
tail -n 50 cert-renew.log
```

## 配置说明

### 续期天数配置

在 `cert-config.json` 中配置续期天数：

```json
{
  "cert": {
    "renew_days": 30,
    "email": "admin@example.com"
  }
}
```

- `renew_days`: 证书到期前多少天开始续期（默认: 30 天）
- 建议设置为 30 天，确保有足够时间处理续期失败的情况

### Cron 执行时间配置

默认执行时间：每天 03:00（凌晨 3 点）

**推荐时间：**
- `02:00` - 凌晨 2 点（低峰期）
- `03:00` - 凌晨 3 点（默认）
- `04:00` - 凌晨 4 点

**修改执行时间：**

```bash
# 卸载旧任务
sudo ./install-cron.sh --uninstall

# 安装新任务（指定时间）
sudo ./install-cron.sh --install --time 02:00
```

## 手动续期

如果需要手动续期证书：

```bash
# 续期所有证书
./cert-manager.sh

# 续期单个证书
./cert-manager.sh --renew-only domain.com:aliyun
```

## 定时任务管理

### 查看定时任务

```bash
# 查看所有定时任务
crontab -l

# 查看续期相关任务
crontab -l | grep cert-renew
```

### 卸载定时任务

```bash
sudo ./install-cron.sh --uninstall
```

### 手动编辑定时任务

```bash
# 编辑 crontab
crontab -e

# 添加或修改续期任务
# 格式: 分钟 小时 * * * /path/to/cert-renew.sh >> /path/to/cert-renew.log 2>&1
```

## 日志说明

续期日志保存在 `cert-renew.log` 文件中，包含：

- 续期检查时间
- 证书到期时间
- 续期结果（成功/失败）
- 服务重启状态
- 错误信息（如果有）

**日志示例：**

```
[2024-01-15 03:00:01] ==========================================
[2024-01-15 03:00:01] XNode SSL Certificate Auto Renewal
[2024-01-15 03:00:01] ==========================================
[2024-01-15 03:00:01] 续期检查天数: 30 天
[2024-01-15 03:00:01] 证书目录: /opt/xnode/certs
[2024-01-15 03:00:01] 域名数量: 2
[2024-01-15 03:00:02] 检查证书: example.com
[2024-01-15 03:00:02] 证书将在 25 天后过期，开始续期...
[2024-01-15 03:00:02] 开始续期证书: example.com
[2024-01-15 03:00:15] 证书续期成功: example.com
[2024-01-15 03:00:15] 重启 xnode 服务以加载新证书...
[2024-01-15 03:00:16] xnode 服务已重启
[2024-01-15 03:00:16] ==========================================
[2024-01-15 03:00:16] 续期完成
[2024-01-15 03:00:16] 续期: 1
[2024-01-15 03:00:16] 跳过: 1
[2024-01-15 03:00:16] 失败: 0
[2024-01-15 03:00:16] ==========================================
```

## 故障排查

### 问题：定时任务未执行

**检查清单：**
1. 确认 cron 服务正在运行
   ```bash
   systemctl status crond  # CentOS/RHEL
   systemctl status cron   # Debian/Ubuntu
   ```

2. 检查定时任务是否存在
   ```bash
   crontab -l | grep cert-renew
   ```

3. 检查脚本权限
   ```bash
   ls -l cert-renew.sh
   chmod +x cert-renew.sh
   ```

4. 检查日志文件权限
   ```bash
   touch cert-renew.log
   chmod 666 cert-renew.log
   ```

### 问题：证书续期失败

**可能原因：**
1. DNS API 凭证错误或过期
2. 网络连接问题
3. Let's Encrypt 速率限制

**解决方案：**
1. 检查 DNS API 凭证
   ```bash
   # 检查 .env 文件或环境变量
   cat .env | grep -E "(ALIYUN_|CF_)"
   ```

2. 手动测试续期
   ```bash
   ./cert-manager.sh --renew-only domain.com:aliyun
   ```

3. 查看详细错误日志
   ```bash
   tail -n 100 cert-renew.log
   ```

### 问题：服务未重启

**检查：**
```bash
# 检查服务状态
systemctl status xnode

# 手动重启服务
systemctl restart xnode
```

## 安全建议

1. **保护配置文件**
   ```bash
   chmod 600 cert-config.json .env
   ```

2. **定期检查日志**
   ```bash
   # 设置日志轮转
   logrotate -d /etc/logrotate.d/cert-renew
   ```

3. **监控续期状态**
   - 定期检查日志文件
   - 设置邮件通知（可选）
   - 监控证书到期时间

## 完整示例

### 示例 1：完整安装流程

```bash
# 1. 配置证书（如果还未配置）
export CERT_EMAIL="admin@example.com"
export CERT_DOMAINS="example.com:aliyun"
export ALIYUN_KEY="xxx" ALIYUN_SECRET="xxx"
sudo ./auto-install.sh

# 2. 申请证书
./cert-manager.sh

# 3. 安装自动续期
sudo ./install-cron.sh --install --time 03:00

# 4. 检查状态
sudo ./install-cron.sh --check
```

### 示例 2：使用配置文件

```bash
# 1. 配置 .env 文件
cp env.example .env
nano .env

# 2. 安装自动续期（自动读取 .env）
sudo ./install-cron.sh --install
```

## 相关文档

- [主文档](README.md) - 快速开始指南
- [证书管理文档](README-CERT.md) - SSL 证书申请和管理
- [完全自动化安装](README-AUTO.md) - 完全自动化安装指南
- [服务管理文档](README-SERVICE.md) - 服务安装和管理
- [多域名配置](README-MULTI-DOMAIN.md) - 多域名配置指南
- [配置说明文档](README-CONFIG.md) - 配置文件详细说明

