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