Initial certificate system

2026-06-06 19:32:24 +08:00
commit ce4ed6213b
105 changed files with 9133 additions and 0 deletions
--- a/docs/阿里云正式部署详细操作手册.md
+++ b/docs/阿里云正式部署详细操作手册.md
@@ -0,0 +1,792 @@
+# 阿里云正式部署详细操作手册
+
+本文档用于把“培训结业证书管理与查询系统”部署到阿里云正式环境。当前日期：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. 数据备份
+
+### 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 也可以，但一定要配置每日备份。