broccoliandClaude Fable 5
edfb216561
公开数据看板、四位 Key 录入面板、管理后台与三级权限、动态字段配置、 PostgreSQL/SQLite 双支持、数据库备份，以及本版新增的成品图上传与预览。 图片相关： - 录入表单支持相册选图与手机端直接拍照，每条记录最多 6 张 - 浏览器内压缩到最长边 1600 并剥离 EXIF，入库统一为 JPG/PNG - 二进制直接入库，现有备份自动覆盖图片，部署无需新增卷 - 详情页缩略图宫格与全屏 lightbox，公开看板同样可见 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
198 lines
12 KiB
Markdown
198 lines
12 KiB
Markdown
# 激光材料数据平台操作手册
|
||
|
||
版本：1.0 更新日期：2026-07-17
|
||
|
||
## 1. 部署前准备
|
||
|
||
生产环境建议至少 2 核 CPU、4 GB 内存、20 GB 可用磁盘，安装 Docker Engine 24+ 与 Docker Compose v2+。应准备域名、HTTPS 证书和一处异机备份存储。服务器只需对外开放反向代理的 80/443 端口；PostgreSQL 不应直接暴露到公网。
|
||
|
||
复制环境变量文件：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
至少修改以下内容：
|
||
|
||
```dotenv
|
||
APP_SECRET=使用密码生成器创建的32位以上随机字符串
|
||
ADMIN_USERNAME=admin
|
||
ADMIN_PASSWORD=首次登录使用的高强度密码
|
||
POSTGRES_PASSWORD=数据库高强度密码
|
||
BACKUP_KEEP_DAYS=30
|
||
```
|
||
|
||
`.env` 不得提交到 Git，也不要通过聊天或邮件发送。
|
||
|
||
## 2. 启动、升级与停止
|
||
|
||
首次启动：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
docker compose ps
|
||
docker compose logs --tail=100 web
|
||
```
|
||
|
||
当 `web` 和 `db` 均为运行状态后，访问 `http://服务器IP:5980`。端口由 `.env` 的 `APP_PORT` 控制。生产环境应在前方配置 Nginx/Caddy HTTPS 反向代理。只有在明确限制受信代理 IP 后才应启用转发头解析，不能无条件信任公网请求提供的 `X-Forwarded-For`，否则会削弱 Key 尝试限速。
|
||
|
||
更新代码后：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
停止但保留数据库：
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
不要执行 `docker compose down -v`，该命令会删除 PostgreSQL 数据卷。
|
||
|
||
## 3. 首次登录
|
||
|
||
1. 打开登录页，输入 `.env` 中的管理员账号和密码。
|
||
2. 首次登录后点击“立即修改”，设置至少 10 位且同时含字母和数字的新密码。
|
||
3. 在“用户与权限”中为实际使用人员创建独立账号。禁止多人共用管理员账号，否则审计日志无法追溯到个人。
|
||
|
||
登录会话默认 12 小时。退出时点击左下角退出按钮。连续失败登录会记入审计日志；生产环境还应在反向代理层启用限速。
|
||
|
||
## 4. 手动录入实验数据
|
||
|
||
系统提供两种手动录入入口：登录管理后台后点击左侧“手动录入”，或访问 `/entry` 使用四位录入 Key。两者使用相同的字段校验和数据库事务。
|
||
|
||
### 4.1 设置四位录入 Key
|
||
|
||
管理员或数据录入员登录 `/admin` 后点击右上角“录入 Key”，输入两次四位数字和当前登录密码。只读用户不能设置或使用录入 Key。Key 在所有用户中必须唯一，数据库只保存带应用密钥的摘要，不保存原值。更换或停用 Key 会立即撤销已签发的录入会话。
|
||
|
||
四位数字只有 10,000 种组合，因此该入口采用以下限制：同一 IP 在 15 分钟内最多失败 5 次；验证成功后授权仅持续 30 分钟；提交时必须再次输入 Key 所属账号的准确用户名。不要把 Key 设置成易猜的生日、年份或连续数字，也不要公开传播。
|
||
|
||
访问 `/entry`，输入 Key 后进入专用录入面板。数据填写完成后点击“检查并提交”，在弹窗中输入登录用户名（不是显示名称）再次确认。用户名或 Key 会话不匹配时，数据不会写入。
|
||
|
||
### 4.2 字段填写
|
||
|
||
表单分为五组：
|
||
|
||
1. 实验与材料：实验 ID、测试日期、材料大类、名称/型号、厚度。
|
||
2. 材料物理特性：原 Excel 红色表头对应的 10 项字段，全部可选。
|
||
3. 激光雕刻参数：功率、电流、速度、频率、脉宽、离焦、线间距、填充方式和加工尺寸。
|
||
4. 实验结果：切透、碳化边宽度、蚀刻深度、起火/阴燃、两项评分、成品图文件名和备注。
|
||
5. 成品图片：可选，最多 6 张，详见 4.3。
|
||
|
||
带 `*` 的项目必须填写。实验 ID 在整个系统内唯一；百分比必须位于 0–100，评分必须位于 0–10，是否类字段通过下拉框选择。点击“保存实验数据”后，后端会再次校验；任何字段错误都不会产生半条记录。
|
||
|
||
建议实验 ID 采用固定规则，例如 `LAS-2026-0001`。“成品图文件名”记录图片在单位文件服务器或对象存储中的归档名；上传第一张图片后系统会自动填入该字段（手机拍照没有有意义的文件名时，用实验 ID 补齐），需要时可以手动改写。
|
||
|
||
### 4.3 上传成品图片
|
||
|
||
在录入表单第 5 段“成品图片”里，点击 **选择图片** 从相册或文件中挑选（支持一次多选），手机和平板上还会多出一个 **拍照** 按钮，点击即调起系统相机直接拍摄。电脑上也可以把图片文件直接拖进虚线框。
|
||
|
||
要点：
|
||
|
||
- 每条记录最多 6 张。可以选择 JPG、PNG、WebP、HEIC 照片，浏览器会统一转成 JPG 或 PNG 再上传；出于安全考虑不接受 SVG、GIF 及任何伪装成图片的文件。
|
||
- 图片在浏览器里就会被压缩到最长边 1600 像素再上传，一般每张 200–400 KB，用手机流量提交也不慢。压缩过程顺带**清除了照片中的 GPS 定位等 EXIF 信息**。
|
||
- 图片是逐张依次上传的，缩略图右上角的 × 可以移除，失败的会显示原因并提供“重试”。**上传未完成时提交会被拦下**，请等所有缩略图不再显示进度条。
|
||
- iPhone 若拍出 HEIC 格式且浏览器无法转换，页面会提示到「设置 → 相机 → 格式」选「兼容性最佳」后重拍。
|
||
- 上传后未提交的图片属于临时状态，只有上传者本人能看到，2 小时后自动清理。所以**填完表单要及时提交**。
|
||
- 图片二进制保存在数据库中，日常数据库备份已经包含图片，不需要单独备份图片目录。
|
||
|
||
在管理后台编辑已有记录时，原有图片会显示在同一位置，可以删除或继续追加，保存后生效。只读账号只能查看，不能增删。
|
||
|
||
### 4.4 管理扩展数据字段
|
||
|
||
管理员进入 `/admin`，选择“数据字段配置”，可添加固定 32 项之外的数据种类。支持以下填写形式：
|
||
|
||
| 填写形式 | 用途 |
|
||
|---|---|
|
||
| 单行文本 | 型号、方法、短说明 |
|
||
| 多行文本 | 较长实验描述 |
|
||
| 数字 | 可含小数的测量值 |
|
||
| 整数 | 次数、等级编号 |
|
||
| 日期 | ISO 日期 |
|
||
| 是 / 否 | 二元状态 |
|
||
| 下拉选项 | 由管理员维护的固定选项 |
|
||
|
||
每个字段还可设置名称、单位、排序值、必填/可选、是否在公开看板显示以及启用/停用状态。排序值越小越靠前。
|
||
|
||
系统不允许从页面物理删除字段。字段名称、类型、选项或启用状态改变时，`custom_field_values` 中的原始值不被改写：
|
||
|
||
- 新增必填字段不会伪造旧记录的值；旧记录显示为未填写，后续编辑时需要补充。
|
||
- 类型改变后，能转换的历史值按新类型显示。
|
||
- 无法转换的值显示原文并标记“历史格式”；编辑其他字段时留空不会清除该原值，主动填写符合新类型的新值才会替换。
|
||
- 停用字段不再出现在新录入表单，但已有值仍在管理详情中显示；若字段允许公开，公开详情也会标记为历史字段。
|
||
- 调整下拉选项不会删除已不在新选项列表中的旧值。
|
||
|
||
## 5. 公开数据面板
|
||
|
||
访问 `/` 无需登录。页面显示总记录数、材料分类数、近 30 天新增、平均清晰度，并支持按实验 ID、材料名称和材料分类筛选。点击记录可查看成品图片、材料物性、激光参数和实验结果。详情弹窗顶部是成品图缩略图，点击任意一张即可全屏放大，支持左右方向键、手机左右滑动切换，按 Esc 或点击空白处关闭。
|
||
|
||
公开接口不会返回录入用户、备注、成品图文件名、审计日志或账号信息。**但成品图片本身是公开的**：任何人都能在公开看板看到并直接访问图片地址。请提醒录入人员不要拍进白板、工牌、屏幕等含内部信息的画面；若图片属于内部资料，应在正式上线前收紧 `GET /api/images/{id}` 的权限。扩展字段只有在管理员启用“公开看板显示”后才会公开。若某些科学参数也属于内部敏感数据，应在正式上线前调整公开字段白名单。
|
||
|
||
## 6. 查询、编辑与删除
|
||
|
||
“数据中心”支持按实验 ID、材料名称模糊搜索，或按材料大类精确筛选。
|
||
|
||
- 管理员：可查看、编辑、删除。
|
||
- 录入员：可查看、编辑，不能删除。
|
||
- 只读用户：只能查看。
|
||
|
||
点击“编辑”会将完整数据载入表单。删除前系统要求二次确认，删除动作不可从页面撤销，但会写入审计日志；如需找回，应通过数据库备份恢复到临时实例后导出目标记录，不建议直接覆盖生产库。
|
||
|
||
## 7. 用户和权限管理
|
||
|
||
管理员进入“用户与权限”后可创建账号、修改角色、停用账号或重置密码。被重置密码的用户下次登录会收到改密提示。系统阻止停用当前登录账号，并保证至少保留一名启用的管理员。
|
||
|
||
人员离职时应立即停用而不是复用账号。每季度检查一次管理员列表和长期未使用账号。
|
||
|
||
## 8. 审计日志
|
||
|
||
审计日志记录登录成功/失败、退出、密码修改、记录新增/修改/删除、用户管理及备份创建，包含操作者、资源、时间、IP 和摘要。只有管理员可查看。审计表应纳入数据库备份，日常不得手工修改。
|
||
|
||
## 9. 备份与恢复
|
||
|
||
管理员可在“备份管理”点击“立即备份”。生产 PostgreSQL 使用 `pg_dump --format=custom` 创建一致性备份；开发 SQLite 使用在线备份 API。每个备份记录大小和 SHA-256 摘要，默认保留 30 天。
|
||
|
||
建议用宿主机定时任务每日执行：
|
||
|
||
```bash
|
||
docker compose exec -T web python scripts/db_backup.py
|
||
```
|
||
|
||
项目内 `backups/` 只是第一份副本。应每天同步到另一台服务器或对象存储，并至少每季度做一次恢复演练。
|
||
|
||
成品图片保存在数据库中，上面两种备份都已包含图片，不需要单独备份图片目录，恢复后也不会出现“数据在、图片丢”。代价是备份体积会随图片增长：按每条记录 3 张、单张 300 KB 估算，每 1000 条记录约多出 0.9 GB，且 JPEG 几乎无法再压缩。请据此核算 `backups/` 所在磁盘容量，必要时调小 `BACKUP_KEEP_DAYS` 或缩短异机副本的保留周期。
|
||
|
||
恢复必须安排维护窗口：停止 Web 写入，确认备份摘要及时间，再执行：
|
||
|
||
```bash
|
||
docker compose stop web
|
||
docker compose run --rm web python scripts/db_restore.py database-YYYYMMDD-HHMMSS.dump --confirm
|
||
docker compose up -d web
|
||
```
|
||
|
||
恢复会覆盖当前数据库。生产恢复前先额外备份当前状态，并优先在临时数据库验证备份可用性。
|
||
|
||
## 10. 日常检查与故障处理
|
||
|
||
- 健康检查：访问 `/health`，应返回 `status: ok`。
|
||
- 服务日志：`docker compose logs --tail=200 web`。
|
||
- 数据库日志：`docker compose logs --tail=200 db`。
|
||
- 磁盘检查：关注 PostgreSQL 数据卷、`backups/` 和 Docker 日志空间。
|
||
- 无法登录：确认账号未停用、系统时间正确、Cookie 未被浏览器禁止。
|
||
- 保存返回 422：按提示检查必填、数值范围和日期格式。
|
||
- 备份失败：确认容器内 `pg_dump` 可用、磁盘空间充足、数据库连接正常。
|
||
|
||
## 11. 上线安全清单
|
||
|
||
- 已修改 `APP_SECRET`、管理员密码和数据库密码。
|
||
- 已启用 HTTPS，HTTP 自动跳转 HTTPS。
|
||
- 数据库端口未暴露公网。
|
||
- `.env` 权限受限且未进入版本库。
|
||
- 已创建个人账号并停用不必要账号。
|
||
- 已为需要快速录入的用户单独设置 Key，且未使用弱组合。
|
||
- 已确认成品图片可以公开；如属内部资料，已收紧 `GET /api/images/{id}` 权限。
|
||
- 已按预期图片量核算备份磁盘容量。
|
||
- 每日自动备份已配置，异机副本和恢复演练已完成。
|
||
- 服务器与容器镜像有定期补丁计划。
|