# Certd 部署指南

SSL 证书自动化管理工具，支持自动申请、部署和续期 Let's Encrypt / 各种商用证书。

## 功能特性

- 自动申请 Let's Encrypt 免费 SSL 证书
- 支持阿里云、腾讯云、Cloudflare 等多种 DNS 提供商
- 自动部署证书到 Nginx、CDN、OSS 等
- 到期自动续期，无需人工干预
- Web 管理界面，可视化操作

## 技术栈

| 组件 | 版本 | 说明 |
|------|------|------|
| Certd | latest | SSL 证书自动化工具 |
| SQLite | 内置 | 轻量数据库，无需额外部署 |
| Nginx | 系统包 | 反向代理 + HTTPS 接入 |
| Docker | 最新版 | 容器运行环境 |

## 前置条件

1. 一台 Linux 服务器（Ubuntu 22.04/24.04 推荐）
2. 一个已解析到服务器的域名（如 `cert.example.com`）
3. 服务器 80/443 端口可从外网访问

## 目录结构

```
certd/
├── docker-compose.yml    # 容器编排
├── .env.example          # 配置模板
├── deploy.sh             # 一键部署脚本
├── backup.sh             # 备份脚本
├── uninstall.sh          # 完全卸载脚本
├── nginx/
│   └── certd.conf        # Nginx 反向代理配置
└── README.md             # 本文件
```

服务器上的数据目录：

```
/data/certd/              # Certd 数据（SQLite + 证书文件）
/var/backups/certd/       # 备份文件
```

## 快速部署

### 第一步：上传文件到服务器

```bash
# 在本地执行，上传 certd 目录
scp -r certd/ root@<服务器IP>:/opt/certd

# 如果服务器上还没有部署过 base（首台服务或全新服务器），还需上传 base
scp -r base/ root@<服务器IP>:/opt/base
```

### 第二步：登录服务器执行部署

```bash
ssh root@<服务器IP>

# 如果是全新服务器，先安装基础环境
cd /opt/base
cp .env.example .env
# 可选：编辑 .env 配置 Docker 镜像加速
bash setup.sh

# 部署 Certd
cd /opt/certd
bash deploy.sh
# 首次运行会生成 .env，按提示修改配置后重新运行
vi .env
bash deploy.sh
```

### 第三步：配置域名解析

在域名服务商（如阿里云 DNS）添加 A 记录：

| 记录类型 | 主机记录 | 记录值 |
|----------|----------|--------|
| A | cert | `<服务器公网IP>` |

### 第四步：登录管理后台

1. 浏览器访问 `https://cert.yourdomain.com`
2. 默认账号: `admin`
3. 默认密码: `123456`

> **⚠️ 安全提醒：请立即修改默认密码！**

## 配置说明

### .env 配置项

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `CERTD_DOMAIN` | 访问域名 | 必填 |
| `CERTBOT_EMAIL` | Let's Encrypt 邮箱 | 必填 |
| `CERTD_IMAGE` | Docker 镜像 | 阿里云镜像 |
| `CERTD_DATA_DIR` | 数据目录 | `/data/certd` |
| `BACKUP_DIR` | 备份目录 | `/var/backups/certd` |
| `RESET_ADMIN_PASSWD` | 重置管理员密码 | `false` |

### 重置管理员密码

如果忘记管理员密码：

```bash
cd /opt/certd

# 1. 修改 .env，设置 RESET_ADMIN_PASSWD=true
vi .env

# 2. 重新创建容器（restart 不会重新读取 .env，必须用 up -d）
docker compose up -d

# 3. 查看日志确认重置完成（出现"重置1号管理员用户密码完成"即可）
docker logs -f --tail 100 certd

# 4. 用默认密码 123456 登录（用户名为原管理员账号，如修改过请查看上一步日志）

# 5. 改回 RESET_ADMIN_PASSWD=false 并重新创建容器
vi .env
docker compose up -d
```

## 日常运维

### 查看日志

```bash
cd /opt/certd
docker compose logs -f
docker compose logs --tail 100
```

### 备份

```bash
cd /opt/certd
bash backup.sh
```

备份内容包括：
- SQLite 数据库 + 证书文件（`/data/certd`）
- 部署配置（`docker-compose.yml` + `.env` + `nginx/`）

备份文件保存在 `/var/backups/certd/`，自动清理 30 天前的旧备份。

> **提示**：Certd 还内置了自动备份流水线功能，可在管理界面中配置定时备份和失败通知，详见「安全加固建议」章节。

### 恢复备份

```bash
# 查看可用备份
ls /var/backups/certd/

# 停止服务
cd /opt/certd && docker compose down

# 恢复数据
tar xzf /var/backups/certd/<日期>/certd-data.tar.gz -C /data/

# 重启服务
cd /opt/certd && docker compose up -d
```

### 升级

```bash
cd /opt/certd

# 1. 备份当前数据
bash backup.sh

# 2. 拉取新镜像
docker compose pull

# 3. 停止旧容器并启动新容器
docker compose down
docker compose up -d

# 4. 检查运行状态
docker compose ps
docker compose logs --tail 20
```

### 停止 / 启动

```bash
cd /opt/certd
docker compose down      # 停止
docker compose up -d     # 启动
docker compose restart   # 重启
```

## 完全卸载

如果需要从服务器上完全移除 Certd，使用卸载脚本：

```bash
cd /opt/certd
bash uninstall.sh
```

脚本会**交互式确认**每个危险操作，按顺序执行：

| 步骤 | 操作 | 确认方式 |
|------|------|----------|
| 0 | 卸载前备份（可选） | y/N |
| 1 | 停止并删除 Certd 容器 | 输入 YES |
| 2 | 删除 Docker 镜像 | 自动 |
| 3 | 删除 Nginx 站点配置并重载 | 自动 |
| 4 | 删除 Let's Encrypt SSL 证书 | 自动 |
| 5 | 清理 Certbot 定时任务（仅当无其他证书时） | 自动 |
| 6 | 删除数据目录 | 输入 DELETE |
| 7 | 删除部署目录 `/opt/certd` | y/N |

**备份目录 `/var/backups/certd/` 始终保留**，不会被删除。

> 卸载后如需恢复，参考上方「恢复备份」章节。

<details>
<summary>手动卸载步骤（不使用脚本）</summary>

```bash
cd /opt/certd

# 1. 建议先备份
bash backup.sh

# 2. 停止并删除容器
docker compose down -v

# 3. 删除 Docker 镜像（可选）
docker image rm registry.cn-shenzhen.aliyuncs.com/handsfree/certd:latest

# 4. 删除 Nginx 配置
rm -f /etc/nginx/sites-enabled/certd /etc/nginx/sites-available/certd
nginx -t && systemctl reload nginx

# 5. 删除 SSL 证书
certbot delete --cert-name 你的域名

# 6. 删除数据目录（⚠ 不可恢复）
rm -rf /data/certd

# 7. 删除部署目录（可选）
rm -rf /opt/certd

# 备份目录保留在 /var/backups/certd/
```

</details>

## 使用 Certd 管理证书

### 添加 DNS 授权

1. 登录 Certd 管理后台
2. 进入「授权管理」→「新增」
3. 选择 DNS 提供商（如阿里云）
4. 填入 AccessKey ID / Secret

### 创建证书流水线

1. 进入「证书管理」→「新增流水线」
2. 选择「Let's Encrypt」证书颁发机构
3. 填写要申请的域名（如 `*.example.com`）
4. 选择 DNS 授权方式
5. 配置部署目标（Nginx、CDN 等）
6. 点击「运行」

### 自动续期

Certd 会自动检查证书过期时间，在到期前自动续期并部署。默认检查间隔为每天一次。

## 安全加固建议

### 1. 修改管理员用户名

官方强烈建议修改默认的 `admin` 用户名。登录后前往「系统管理」→「用户管理」修改管理员账号的用户名，并建议注册一个名为 `admin` 的普通用户并设为禁用，防止被暴力破解。

### 2. 开启站点隐藏

Certd 设置好后日常很少需要访问，建议平时关闭站点访问入口，减少被攻击风险。前往「系统管理」→「系统设置」→「安全设置」→ 开启站点隐藏。

### 3. 启用 2FA 双重验证

Certd 支持 2FA 双重认证登录，建议在「个人设置」中开启。

### 4. 配置自动备份流水线

Certd 内置数据库自动备份功能。在管理界面中创建一个备份流水线，选择「数据库备份」任务，配置定时执行和失败通知，确保数据安全。详见[官方备份文档](https://certd.docmirror.cn/guide/use/backup/)。

## 故障排查

### 容器无法启动

```bash
# 查看容器状态
docker compose ps

# 查看详细日志
docker compose logs --tail 50
```

### SSL 证书申请失败

```bash
# 检查域名解析是否正确
dig cert.yourdomain.com

# 检查 80 端口是否可访问
curl -I http://cert.yourdomain.com

# 查看 Certbot 日志
cat /var/log/letsencrypt/letsencrypt.log
```

### 访问返回 502

```bash
# 检查 Certd 容器是否运行
docker compose ps

# 检查 7001 端口
curl -I http://127.0.0.1:7001

# 检查 Nginx 配置
nginx -t
```

## 端口说明

| 端口 | 协议 | 说明 |
|------|------|------|
| 80 | TCP | HTTP → HTTPS 重定向 |
| 443 | TCP | HTTPS（Nginx 反向代理） |
| 7001 | TCP | Certd HTTP（仅监听 127.0.0.1） |