laser-data-hub/docs/操作手册.md

激光材料数据平台操作手册

适用平台版本：1.3.0　文档更新日期：2026-07-26

0. 老用户请先强制刷新一次

如果你以前访问过本系统的旧版本，浏览器很可能仍在使用缓存里的旧页面文件。表现是：录入页能看到“成品图片”这一段标题，但下面没有“选择图片”按钮，或者按钮点了没反应。

这不是故障，强制刷新一次即可，且只需做这一次：

设备	操作
Windows 电脑	打开页面后按 Ctrl + F5（或 Ctrl + Shift + R）
Mac 电脑	按 Command + Shift + R
安卓手机	浏览器菜单 →「设置」→「隐私」→ 清除缓存，然后重新打开页面
iPhone	Safari：「设置」→「Safari 浏览器」→「清除历史记录与网站数据」；微信内置浏览器请改用 Safari 打开

刷新后仍看不到按钮，请按第 10 节反馈，并附上你使用的设备和浏览器。

1. 部署前准备

生产环境建议至少 2 核 CPU、4 GB 内存、20 GB 可用磁盘，安装 Docker Engine 24+ 与 Docker Compose v2+。应准备域名、HTTPS 证书和一处异机备份存储。服务器只需对外开放反向代理的 80/443 端口；PostgreSQL 不应直接暴露到公网。

复制环境变量文件：

cp .env.example .env

至少修改以下内容：

APP_SECRET=使用密码生成器创建的32位以上随机字符串
ADMIN_USERNAME=admin
ADMIN_PASSWORD=首次登录使用的高强度密码
POSTGRES_PASSWORD=数据库高强度密码
BACKUP_KEEP_DAYS=30

.env 不得提交到 Git，也不要通过聊天或邮件发送。

2. 启动、升级与停止

首次启动：

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 尝试限速。

更新代码后：

docker compose up -d --build

停止但保留数据库：

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 信息。
• 图片是逐张依次上传的，缩略图右上角的 × 可以移除，失败的会显示原因并提供“重试”。上传未完成时提交会被拦下，请等所有缩略图不再显示进度条。
• 单张图片压缩后仍超过 8 MB 会被拒收（正常手机照片远达不到）。若提示“上传超时”，多为现场网络不稳，点“重试”即可，不必重填表单。
• 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 天。

建议用宿主机定时任务每日执行：

docker compose exec -T web python scripts/db_backup.py

项目内 backups/ 只是第一份副本。应每天同步到另一台服务器或对象存储，并至少每季度做一次恢复演练。

成品图片保存在数据库中，上面两种备份都已包含图片，不需要单独备份图片目录，恢复后也不会出现“数据在、图片丢”。代价是备份体积会随图片增长：按每条记录 3 张、单张 300 KB 估算，每 1000 条记录约多出 0.9 GB，且 JPEG 几乎无法再压缩。请据此核算 backups/ 所在磁盘容量，必要时调小 BACKUP_KEEP_DAYS 或缩短异机副本的保留周期。

恢复必须安排维护窗口：停止 Web 写入，确认备份摘要及时间，再执行：

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 未被浏览器禁止。
• 录入页看不到“选择图片”按钮：多为浏览器缓存了旧版页面文件，按第 0 节强制刷新一次即可。若强刷后仍不显示，按 F12 打开控制台查看是否有报错，并确认 /static/image-upload.js 与 /static/entry.js 都返回 200 或 304。
• 保存返回 422：按提示检查必填、数值范围和日期格式。
• 备份失败：确认容器内 pg_dump 可用、磁盘空间充足、数据库连接正常。

11. 上线安全清单

• 已修改 APP_SECRET、管理员密码和数据库密码。
• 已启用 HTTPS，HTTP 自动跳转 HTTPS。
• 数据库端口未暴露公网。
• .env 权限受限且未进入版本库。
• 已创建个人账号并停用不必要账号。
• 已为需要快速录入的用户单独设置 Key，且未使用弱组合。
• 已确认成品图片可以公开；如属内部资料，已收紧 GET /api/images/{id} 权限。
• 已按预期图片量核算备份磁盘容量。
• 每日自动备份已配置，异机副本和恢复演练已完成。
• 服务器与容器镜像有定期补丁计划。