GuangYu/certificate-system
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b6be8b45933258a3d2ea423fbfee6bd68e7440c0
certificate-system/docs/阿里云正式部署详细操作手册.md
Nelson 1e9404cc7d 新增PDF生成并发设置
2026-06-23 12:54:14 +08:00

15 KiB
Raw Blame History

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

本文档用于把“培训结业证书管理与查询系统”部署到阿里云正式环境。当前日期：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 来统一管理多服务部署。

参考：

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

本地验证版

路径：

local_app/

启动方式：

start-local.bat

访问地址：

http://127.0.0.1:8000/admin/login

用途：

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

正式部署版

路径：

backend/
frontend/
docker-compose.yml
deploy/

技术：

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

正式部署时不要运行：

local_app/server.py

正式部署要运行：

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. 域名和备案

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

https://cert.example.com

你需要：

  1. 购买域名。
  2. 如果服务器在中国大陆，通常需要完成 ICP 备案。
  3. 在域名 DNS 里添加解析：
类型：A
主机记录：cert
记录值：你的 ECS 公网 IP

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

http://ECS公网IP:8080

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

5. ECS 初始化

下面以 Ubuntu 22.04 为例。

5.1 登录服务器

在本地终端执行：

ssh root@你的ECS公网IP

5.2 更新系统

apt update
apt upgrade -y

5.3 安装常用工具

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

5.4 安装 Docker

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

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 创建数据目录

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 拉代码

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

方式 B：本地打包上传

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

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

服务器上解压：

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

7. 配置环境变量

在服务器项目目录下：

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

7.1 自建 MySQL 方案的 .env

如果用 Docker Compose 里的 MySQL：

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 一致：

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

7.2 RDS MySQL 方案的 .env

如果用阿里云 RDS：

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 里提前创建数据库：
certificate_system

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

8. 首次启动

在项目目录执行：

docker compose up -d --build

查看容器状态：

docker compose ps

查看后端日志：

docker compose logs -f backend

查看前端日志：

docker compose logs -f frontend

9. 初始化数据库

首次部署需要执行：

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

这个命令会：

  • 执行数据库迁移。
  • 创建基础角色。
  • 创建默认管理员。
  • 初始化默认项目配置。
  • 初始化系统设置，PDF 生成并发限制 默认值为 2。

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

docker compose exec backend alembic upgrade head

10. 访问系统

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

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

如果已经配置域名和 HTTPS：

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

公开查询页：

https://你的域名/query

证书直达链接类似：

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

二维码核验链接类似：

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

11. 安全组设置

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

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

不建议公网开放：

3306 MySQL
8000 后端接口

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

12. HTTPS 和 Nginx

12.1 临时上线

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

http://ECS公网IP:8080

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

12.2 正式上线

推荐：

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

项目里有参考配置：

deploy/nginx.prod.conf

需要修改：

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

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

Nginx 重新加载：

nginx -t
systemctl reload nginx

13. 正式上线前检查

13.1 后台登录

打开：

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

确认：

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

13.2 项目管理

确认：

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

13.3 学员管理

确认：

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

13.4 证书管理

确认：

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

13.5 Excel 导入

确认模板字段只有：

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

确认：

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

13.6 公开查询

确认：

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

13.7 操作日志

确认：

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

14. 数据备份

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

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

后台备份文件保存在：

/data/certificate-system/db-backups

14.1 如果使用 RDS

建议：

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

14.2 如果使用 ECS 自建 MySQL

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

创建备份目录：

mkdir -p /data/backups/mysql

手动备份：

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

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

也可以写定时任务：

crontab -e

加入：

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 天前备份的任务：

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

14.3 文件数据备份

需要备份：

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

不需要长期备份：

/data/certificate-system/pdf-cache

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

15. 日志保留策略

当前系统建议：

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

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

16. 日常运维命令

查看容器：

docker compose ps

查看后端日志：

docker compose logs -f backend

查看前端日志：

docker compose logs -f frontend

重启后端：

docker compose restart backend

重启全部服务：

docker compose restart

更新代码后重新构建：

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

停止服务：

docker compose down

不要随便执行：

docker compose down -v

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

17. 常见问题

17.1 页面打不开

检查：

docker compose ps
docker compose logs -f frontend

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

17.2 后台接口 502

检查后端：

docker compose logs -f backend

检查数据库连接：

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

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

17.3 PDF 中文乱码或字体不对

后端 Dockerfile 已安装：

fonts-noto-cjk

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

17.4 公开链接域名不对

检查 .env：

PUBLIC_BASE_URL=https://你的域名

修改后重启后端：

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. 一期推荐选择

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

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

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

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

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

Reference in New Issue View Git Blame Copy Permalink