346 lines
8.3 KiB
Markdown
346 lines
8.3 KiB
Markdown
# 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） |
|