807 lines
15 KiB
Markdown
807 lines
15 KiB
Markdown
# 阿里云正式部署详细操作手册
|
||
|
||
本文档用于把“培训结业证书管理与查询系统”部署到阿里云正式环境。当前日期：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 "请换成强密码"
|
||
```
|
||
|
||
这个命令会：
|
||
|
||
- 执行数据库迁移。
|
||
- 创建基础角色。
|
||
- 创建默认管理员。
|
||
- 初始化默认项目配置。
|
||
- 初始化系统设置，`PDF 生成并发限制` 默认值为 `2`。
|
||
|
||
如果后续只是升级代码，一般执行：
|
||
|
||
```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 也可以，但一定要配置每日备份。
|