5.8 KiB
5.8 KiB
部署与使用手册
本文档用于一期本地验收和正式部署交接。
本地验收版
适合在没有 Docker、npm 环境时先完整跑通业务流程。
cd /d C:\Users\nelso\Documents\projects\certificate-system
start-local.bat
访问地址：
后台：http://127.0.0.1:8000/admin/login
公开查询：http://127.0.0.1:8000/query
默认账号：
admin / Admin123!
本地数据保存在：
local_app/data/local.db
清空本地验收数据：
reset-local-data.bat
后台使用流程
- 登录
/admin/login。 - 进入“项目管理”，维护
DBY、QSX等项目代码。项目支持搜索、修改、启用和停用。 - 进入“学员管理”，手动新增、查询、修改或删除学员。
- 进入“证书管理”，手动新增证书，支持单张预览、PDF 下载、作废、重置直达链接、按条件筛选、勾选后批量预生成 PDF 和导出。
- 进入“Excel 导入”，下载模板、上传 Excel、查看校验结果，确认后正式导入。模板只需要填写姓名、手机号、项目代码、发证日期；证书名称、课程名称、阶段名称、发证单位从项目配置自动带出。 “确认导入”表示把已校验通过的临时数据正式写入学员和证书表。导入记录支持下载原文件、下载错误报告和删除；删除导入记录只删除上传文件、错误报告和批次记录，不删除已经生成的学员和证书。 确认导入后，可以在该批次行点击“预生成PDF”，系统会提前为这一批有效证书生成 PDF，并在弹窗里显示总数、已完成、新生成、已缓存、跳过和失败数量。
- 进入“系统设置”，确认
PDF 生成并发限制。2 核 4G 服务器建议保持默认值2。 - 进入“操作日志”，查看关键后台操作。日志动作已转成中文显示。
公开查询流程
- 用户进入
/query。 - 选择查询方式：
- 证书编号查询：输入证书编号 + 姓名 + 图形验证码。
- 短信验证码查询：输入手机号 + 获取并输入短信验证码。
- 查询成功后展示证书状态和证书信息；短信验证码查询可能返回多张证书。
- 有效证书可下载 PDF。
- 作废证书只展示作废状态，不提供正常 PDF 下载。
PDF 下载说明
PDF 由服务端按需生成，并使用 30 天缓存。这样可以保证模板、二维码、作废状态和审计逻辑统一。
后台 PDF 下载不能用简单的 window.location 直接跳转，因为后台接口需要登录态。如果直接打开下载地址，浏览器不会自动带上前端保存的 Authorization token，容易出现下载失败。当前后台已改为通过带 token 的请求下载 blob 文件，再在浏览器里保存。
首次生成 PDF 会占用 CPU。后台“系统设置”里的 PDF 生成并发限制 默认是 2，用于防止多人同时首次下载 PDF 时把 2 核 4G 服务器打满。前端下载和预览时会显示“当前查询人数较多，请稍后。。。”，避免用户误以为页面卡死。
如果一次性导入大量毕业学员，建议管理员先做批量预生成：
- 进入“Excel 导入”，找到已确认导入的批次，点击“预生成PDF”。
- 或进入“证书管理”，按导入批次、PDF 状态、项目或关键词筛选，勾选需要提前生成的人，再点击“预生成所选PDF”。
- 批量预生成会继续遵守
PDF 生成并发限制，不会绕过系统并发保护。 - 预生成任务只在当前后端进程内记录进度；如果服务重启，已生成的 PDF 缓存仍然保留，但任务进度弹窗不会恢复。
正式部署准备
- Linux 服务器，建议 2 核 4G 起步。
- 域名和 HTTPS 证书。
- Docker 和 Docker Compose。
- MySQL 8，可以使用 Compose 内置 MySQL 或云数据库。
默认数据目录：
/data/certificate-system
建议子目录：
uploads
error-reports
exports
pdf-cache
pdf-cache 是 30 天缓存，不需要作为长期档案备份。
环境变量
复制 .env.example 为 .env，至少修改：
APP_ENV=production
DATABASE_URL=mysql+pymysql://certificate:password@mysql:3306/certificate_system
SECRET_KEY=change-me
PUBLIC_BASE_URL=https://your-domain.com
CERTIFICATE_NO_SECRET=change-me
PDF_CACHE_DAYS=30
DATA_ROOT=/data/certificate-system
Docker 部署
docker compose up -d --build
首次初始化：
docker compose exec backend python -m app.cli init-db --admin-username admin --admin-password "请替换为强密码"
单独执行数据库迁移：
docker compose exec backend alembic upgrade head
后端测试：
docker compose exec backend pytest
当前已实现
- 后台登录。
- 后台概览统计。
- 项目新增、搜索、修改、启用、停用。
- 学员手动新增、查询、修改、删除。
- 证书新增、查询、后台预览、后台下载、作废、重置直达链接。
- 证书按导入批次筛选、按 PDF 状态筛选、批量预生成 PDF。
- Excel 模板下载、上传校验、错误报告下载、确认导入。导入模板字段为姓名、手机号、项目代码、发证日期。
- 导入批次原文件下载和导入批次删除。
- 导入后自动生成证书编号、直达链接 token、二维码 token。
- 证书导出，包含证书编号和对外直达链接。
- 公开查询：证书编号 + 姓名 + 图形验证码，或手机号 + 姓名 + 图形验证码。
- 证书直达页和二维码核验页。
- PDF 服务端按需生成，缓存 30 天。
- 关键操作日志写入和中文展示。
后续上线前确认
- 生产域名、HTTPS 和 Nginx 限流参数。
- PDF 正式模板、Logo、公章和证书文案。
- 生产管理员账号和强密码。
- 服务器部署后的联调和验收数据导入演练。