# 阿里云正式部署详细操作手册

本文档用于把“培训结业证书管理与查询系统”部署到阿里云正式环境。当前日期：2026-06-05。

## 1. 先回答：数据库要不要单独买

可以有两种方案。

### 方案 A：数据库和应用都放在同一台 ECS 上

做法：一台阿里云 ECS 上运行 Docker Compose，里面同时跑：

- MySQL
- 后端 FastAPI
- 前端 Nginx/Vue

优点：

- 成本低。
- 部署简单。
- 一期快速上线足够用。

缺点：

- ECS 故障时，应用和数据库一起受影响。
- 数据库备份、恢复、监控需要自己认真配置。
- 后期迁移到 RDS 时需要再做一次数据库迁移。

适合：

- 一期快速上线。
- 访问量不大。
- 预算有限。
- 可以接受自己维护数据库备份。

### 方案 B：ECS 跑应用，阿里云 RDS MySQL 跑数据库

做法：

- ECS 只跑前端和后端。
- MySQL 使用阿里云 RDS MySQL。

优点：

- 数据库更稳定。
- 阿里云 RDS 提供备份、恢复、监控、容灾等能力。
- 后期维护成本低。
- 更接近正式生产系统。

缺点：

- 成本更高。
- 需要配置 RDS 白名单、账号、数据库连接串。

适合：

- 正式长期使用。
- 证书数据比较重要。
- 不希望自己维护 MySQL 备份和恢复。

### 我的建议

如果你现在要尽快上线，一期可以先用方案 A：一台 ECS + Docker Compose 自带 MySQL。

如果这个系统会长期对外使用，证书数据又比较重要，建议正式上线直接用方案 B：ECS + RDS MySQL。证书系统的数据价值主要在学员、证书、导入记录、操作日志，这些数据丢了很麻烦，所以 RDS 更稳。

阿里云官方文档里，RDS 是托管型关系型数据库服务，支持 MySQL，并提供备份、恢复、监控、容灾等能力。ECS 上也可以安装 Docker 和 Docker Compose 来统一管理多服务部署。

参考：

- 阿里云 RDS MySQL 文档：https://help.aliyun.com/zh/rds/apsaradb-rds-for-mysql/product-overview/
- 阿里云 ECS 安装 Docker 文档：https://help.aliyun.com/zh/ecs/use-cases/install-and-use-docker/
- Docker Compose 官方文档：https://docs.docker.com/compose/

## 2. 正式版和本地版的区别

### 本地验证版

路径：

```text
local_app/
```

启动方式：

```bat
start-local.bat
```

访问地址：

```text
http://127.0.0.1:8000/admin/login
```

用途：

- 本地快速验收。
- 不依赖 MySQL、Node、Docker。
- 用 SQLite 存测试数据。
- 不建议正式部署使用。

### 正式部署版

路径：

```text
backend/
frontend/
docker-compose.yml
deploy/
```

技术：

- 后端：FastAPI
- 前端：Vue 3 + Element Plus
- 数据库：MySQL 8
- 部署：Docker Compose

正式部署时不要运行：

```text
local_app/server.py
```

正式部署要运行：

```bash
docker compose up -d --build
```

## 3. 阿里云购买建议

### ECS 建议

一期建议：

- 地域：选择主要用户所在地区，例如华东、华南。
- 系统：Ubuntu 22.04 LTS 或 Alibaba Cloud Linux 3。
- 配置：2 核 4G 起步。
- 磁盘：系统盘 40G 起步，建议额外挂一块数据盘 50G 或以上。
- 带宽：按量或固定 3M 起步，后面看访问量调整。

如果要把 MySQL 也放 ECS 上，建议：

- 2 核 4G 是最低可用。
- 更稳一点用 2 核 8G。
- 数据盘独立挂载到 `/data`。

### RDS 建议

如果买 RDS MySQL：

- 数据库版本：MySQL 8.0。
- 网络：和 ECS 同地域、同 VPC。
- 规格：小规格起步即可，后期扩容。
- 存储：20G 起步。
- 备份：开启自动备份。
- 白名单：只允许 ECS 内网 IP 访问，不要开放公网访问。

## 4. 域名和备案

如果要通过正式域名访问，例如：

```text
https://cert.example.com
```

你需要：

1. 购买域名。
2. 如果服务器在中国大陆，通常需要完成 ICP 备案。
3. 在域名 DNS 里添加解析：

```text
类型：A
主机记录：cert
记录值：你的 ECS 公网 IP
```

如果暂时没有域名，也可以先用：

```text
http://ECS公网IP:8080
```

但正式对外建议使用域名和 HTTPS。

## 5. ECS 初始化

下面以 Ubuntu 22.04 为例。

### 5.1 登录服务器

在本地终端执行：

```bash
ssh root@你的ECS公网IP
```

### 5.2 更新系统

```bash
apt update
apt upgrade -y
```

### 5.3 安装常用工具

```bash
apt install -y git curl vim unzip ca-certificates gnupg lsb-release
```

### 5.4 安装 Docker

可以按阿里云 ECS Docker 文档安装。Ubuntu 常用命令如下：

```bash
apt install -y docker.io docker-compose-plugin
systemctl enable docker
systemctl start docker
docker --version
docker compose version
```

如果 `docker compose version` 能显示版本号，说明 Compose 可用。

### 5.5 创建数据目录

```bash
mkdir -p /data/certificate-system
mkdir -p /data/certificate-system/uploads
mkdir -p /data/certificate-system/error-reports
mkdir -p /data/certificate-system/exports
mkdir -p /data/certificate-system/pdf-cache
```

## 6. 上传项目代码

你可以用 Git，也可以用压缩包。

### 方式 A：Git 拉代码

```bash
cd /opt
git clone 你的代码仓库地址 certificate-system
cd /opt/certificate-system
```

### 方式 B：本地打包上传

在本地把项目压缩后上传到服务器：

```bash
scp certificate-system.zip root@你的ECS公网IP:/opt/
```

服务器上解压：

```bash
cd /opt
unzip certificate-system.zip
cd /opt/certificate-system
```

## 7. 配置环境变量

在服务器项目目录下：

```bash
cd /opt/certificate-system
cp .env.example .env
vim .env
```

### 7.1 自建 MySQL 方案的 `.env`

如果用 Docker Compose 里的 MySQL：

```env
APP_ENV=production
DATABASE_URL=mysql+pymysql://certificate:请改成强密码@mysql:3306/certificate_system
SECRET_KEY=请改成一串很长的随机字符串
PUBLIC_BASE_URL=https://你的域名
CERTIFICATE_NO_SECRET=请改成另一串很长的随机字符串
PDF_CACHE_DAYS=30
DATA_ROOT=/data/certificate-system
CORS_ORIGINS=https://你的域名
```

同时要修改 `docker-compose.yml` 里的 MySQL 密码，保证和 `DATABASE_URL` 一致：

```yaml
MYSQL_ROOT_PASSWORD: 请改成root强密码
MYSQL_DATABASE: certificate_system
MYSQL_USER: certificate
MYSQL_PASSWORD: 请改成强密码
```

### 7.2 RDS MySQL 方案的 `.env`

如果用阿里云 RDS：

```env
APP_ENV=production
DATABASE_URL=mysql+pymysql://RDS账号:RDS密码@RDS内网地址:3306/certificate_system
SECRET_KEY=请改成一串很长的随机字符串
PUBLIC_BASE_URL=https://你的域名
CERTIFICATE_NO_SECRET=请改成另一串很长的随机字符串
PDF_CACHE_DAYS=30
DATA_ROOT=/data/certificate-system
CORS_ORIGINS=https://你的域名
```

RDS 注意事项：

1. ECS 和 RDS 要在同一个 VPC。
2. RDS 白名单里加入 ECS 的内网 IP。
3. 不建议开放 RDS 公网访问。
4. RDS 里提前创建数据库：

```text
certificate_system
```

如果使用 RDS，建议把 `docker-compose.yml` 里的 `mysql` 服务去掉，或者保留但不启动。最简单的做法是先保留 compose 文件，但后端 `DATABASE_URL` 指向 RDS，实际业务不会用 compose 里的 MySQL。

## 8. 首次启动

在项目目录执行：

```bash
docker compose up -d --build
```

查看容器状态：

```bash
docker compose ps
```

查看后端日志：

```bash
docker compose logs -f backend
```

查看前端日志：

```bash
docker compose logs -f frontend
```

## 9. 初始化数据库

首次部署需要执行：

```bash
docker compose exec backend python -m app.cli init-db --admin-username admin --admin-password "请换成强密码"
```

这个命令会：

- 执行数据库迁移。
- 创建基础角色。
- 创建默认管理员。
- 初始化默认项目配置。

如果后续只是升级代码，一般执行：

```bash
docker compose exec backend alembic upgrade head
```

## 10. 访问系统

如果还没有配置域名，可以访问：

```text
http://ECS公网IP:8080/admin/login
```

如果已经配置域名和 HTTPS：

```text
https://你的域名/admin/login
```

公开查询页：

```text
https://你的域名/query
```

证书直达链接类似：

```text
https://你的域名/cert/xxxx
```

二维码核验链接类似：

```text
https://你的域名/verify/xxxx
```

## 11. 安全组设置

在阿里云 ECS 安全组里建议开放：

```text
22    SSH，仅允许你的办公 IP 更安全
80    HTTP
443   HTTPS
8080  如果临时不用 Nginx/HTTPS，可以开放；正式建议关闭
```

不建议公网开放：

```text
3306 MySQL
8000 后端接口
```

正式情况下，后端只让前端 Nginx 或内网访问。

## 12. HTTPS 和 Nginx

### 12.1 临时上线

可以先用前端容器暴露的 8080：

```text
http://ECS公网IP:8080
```

但这不适合长期正式使用。

### 12.2 正式上线

推荐：

- ECS 上安装 Nginx。
- Nginx 监听 80/443。
- 443 配 HTTPS 证书。
- Nginx 反向代理到前端容器 8080。

项目里有参考配置：

```text
deploy/nginx.prod.conf
```

需要修改：

```nginx
server_name example.com;
ssl_certificate /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;
```

改成你的域名和证书路径。

Nginx 重新加载：

```bash
nginx -t
systemctl reload nginx
```

## 13. 正式上线前检查

### 13.1 后台登录

打开：

```text
https://你的域名/admin/login
```

确认：

- 可以登录。
- 默认密码已经改成强密码。

### 13.2 项目管理

确认：

- 能新增项目。
- 能修改项目。
- 能停用/启用项目。
- 能搜索项目。

### 13.3 学员管理

确认：

- 能新增学员。
- 能修改学员。
- 能删除学员。
- 手机号查询正常。

### 13.4 证书管理

确认：

- 能新增证书。
- 证书编号自动生成。
- 证书名称使用项目名称。
- 能预览证书。
- 能下载 PDF。
- 证书日期、课程标题、导师、二维码显示正常。
- 能作废证书。
- 作废证书不能下载正常 PDF。

### 13.5 Excel 导入

确认模板字段只有：

```text
姓名
手机号
项目代码
发证日期
```

确认：

- 能上传 Excel。
- 能下载原文件。
- 能删除导入批次。
- 能确认导入。
- 确认导入后状态变成已导入。
- 不能重复确认导入。

### 13.6 公开查询

确认：

- 证书编号 + 姓名 + 验证码可以查。
- 手机号 + 姓名 + 验证码可以查。
- 查询结果可以预览和下载。
- 公开查询和公开下载会进入操作日志。

### 13.7 操作日志

确认：

- 日志中文显示。
- 风险等级显示。
- 支持筛选。
- 支持分页，每页 20 条。
- 页码右对齐。
- 上方和下方都有分页。
- 页码多时有省略号。
- 支持导出日志。
- 支持清理过期日志。

## 14. 数据备份

正式后台提供「备份管理」页面，日常优先使用后台：

- 查看本地已有数据库备份。
- 点击「立即备份」生成当前数据库备份。
- 选择某个备份点并输入确认语后回滚。
- 回滚前系统会自动再备份一次当前数据库。

后台备份文件保存在：

```text
/data/certificate-system/db-backups
```

### 14.1 如果使用 RDS

建议：

- 开启自动备份。
- 开启日志备份。
- 定期测试恢复。
- RDS 白名单只允许 ECS 内网 IP。

### 14.2 如果使用 ECS 自建 MySQL

至少每天备份一次数据库。后台「备份管理」可以完成手动备份和回滚；下面命令只作为后台不可用时的服务器兜底方案。

创建备份目录：

```bash
mkdir -p /data/backups/mysql
```

手动备份：

```bash
docker compose exec mysql mysqldump -ucertificate -p certificate_system > /data/backups/mysql/certificate_system_$(date +%F).sql
```

注意：这个命令会提示输入 MySQL 密码。

也可以写定时任务：

```bash
crontab -e
```

加入：

```cron
30 2 * * * cd /opt/certificate-system && docker compose exec -T mysql mysqldump -ucertificate -p你的密码 certificate_system > /data/backups/mysql/certificate_system_$(date +\%F).sql
```

建议再加一个删除 30 天前备份的任务：

```cron
10 3 * * * find /data/backups/mysql -name "certificate_system_*.sql" -mtime +30 -delete
```

### 14.3 文件数据备份

需要备份：

```text
/data/certificate-system/uploads
/data/certificate-system/error-reports
/data/certificate-system/exports
```

不需要长期备份：

```text
/data/certificate-system/pdf-cache
```

PDF 可以重新生成，缓存目录不是核心数据。

## 15. 日志保留策略

当前系统建议：

- 普通后台操作日志保留 180 天。
- 公开查询和公开下载日志保留 180 天。
- 高风险后台操作日志保留 365 天。

后台提供“清理过期日志”，只清理超过保留周期的日志。

## 16. 日常运维命令

查看容器：

```bash
docker compose ps
```

查看后端日志：

```bash
docker compose logs -f backend
```

查看前端日志：

```bash
docker compose logs -f frontend
```

重启后端：

```bash
docker compose restart backend
```

重启全部服务：

```bash
docker compose restart
```

更新代码后重新构建：

```bash
docker compose up -d --build
docker compose exec backend alembic upgrade head
```

停止服务：

```bash
docker compose down
```

不要随便执行：

```bash
docker compose down -v
```

`-v` 会删除 Docker volume，可能导致数据库数据丢失。

## 17. 常见问题

### 17.1 页面打不开

检查：

```bash
docker compose ps
docker compose logs -f frontend
```

确认安全组是否开放 8080、80 或 443。

### 17.2 后台接口 502

检查后端：

```bash
docker compose logs -f backend
```

检查数据库连接：

```bash
docker compose exec backend python -m app.cli init-db --admin-username admin --admin-password "临时测试密码"
```

如果数据库连不上，这个命令会报错。

### 17.3 PDF 中文乱码或字体不对

后端 Dockerfile 已安装：

```text
fonts-noto-cjk
```

如果换系统或自定义镜像，要确认 CJK 字体存在。

### 17.4 公开链接域名不对

检查 `.env`：

```env
PUBLIC_BASE_URL=https://你的域名
```

修改后重启后端：

```bash
docker compose restart backend
```

### 17.5 数据库密码改了但服务连不上

确认三处一致：

1. `.env` 里的 `DATABASE_URL`
2. `docker-compose.yml` 里的 `MYSQL_PASSWORD`
3. MySQL 实际用户密码

如果已经初始化过 MySQL volume，再改 `MYSQL_PASSWORD` 不一定会自动改数据库里的旧密码。需要进入 MySQL 手动改密码，或者在未上线前清空 volume 重新初始化。

## 18. 推荐上线顺序

1. 购买 ECS。
2. 决定数据库方案：先 ECS 自建 MySQL，或直接 RDS。
3. 配置域名解析。
4. 安装 Docker 和 Compose。
5. 上传项目代码。
6. 修改 `.env`。
7. 如果用 RDS，配置 RDS 数据库、账号、白名单。
8. 执行 `docker compose up -d --build`。
9. 执行 `python -m app.cli init-db`。
10. 登录后台。
11. 配置项目。
12. 新增测试学员和测试证书。
13. 验证公开查询和 PDF 下载。
14. 配置 Nginx 和 HTTPS。
15. 配置备份。
16. 正式导入业务数据。

## 19. 一期推荐选择

如果你希望明天就能上线验证：

```text
一台 2核4G 或 2核8G ECS
Docker Compose 自带 MySQL
域名 + HTTPS
每天 mysqldump 备份
```

如果你希望正式长期稳定：

```text
一台 ECS 跑前后端
阿里云 RDS MySQL 跑数据库
RDS 自动备份
域名 + HTTPS
```

我的最终建议：如果预算允许，正式生产用 RDS；如果先快速上线，ECS 自建 MySQL 也可以，但一定要配置每日备份。