update server

2026-07-30 11:12:31 +08:00
commit 4312cb878c
99 changed files with 24034 additions and 0 deletions
@@ -0,0 +1,125 @@
+# ReinLoop Express Server
+
+该服务将原微信云函数中的文件中转、配置发布、辨识反馈和容积配置请求迁移到服务器。
+请求体继续使用原来的 `type` 字段，因此 ReinLoop 和 ControlPanel 只需更换服务 URL。
+
+## 本地运行
+
+要求 Node.js 20 或更高版本。
+
+```powershell
+cd server
+npm install
+$env:B_ADMIN_TOKEN="your-admin-token"
+npm start
+```
+
+默认监听：
+
+- 业务接口：`http://127.0.0.1:3000`（同时兼容原有 `/api` 路径）
+- 健康检查：`http://127.0.0.1:3000/health`
+
+ControlPanel 本地联调：
+
+```powershell
+$env:REINLOOP_API_URL="http://127.0.0.1:3000"
+$env:B_ADMIN_TOKEN="your-admin-token"
+$env:REINLOOP_DEVICE_ID="local-test-device"
+cd ControlPanel
+npm run gui
+```
+
+ReinLoop 无 GUI 核心联调：
+
+```powershell
+$env:REINLOOP_SERVER_URL="http://127.0.0.1:3000"
+$env:REINLOOP_API_URL="http://127.0.0.1:3000"
+$env:REINLOOP_DEVICE_ID="local-test-device"
+```
+
+如果 ReinLoop 或 ControlPanel 运行在其他设备上，不可使用 `127.0.0.1`，
+应改为服务器的局域网 IP 或 HTTPS 域名。
+
+业务请求可直接发送到域名根路径，也继续兼容 `/api`。反向代理需要将根路径完整转发到
+Node 服务，例如 Nginx：
+
+```nginx
+location / {
+  proxy_pass http://127.0.0.1:3000;
+  proxy_set_header Host $host;
+  proxy_set_header X-Forwarded-Proto $scheme;
+  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+```
+
+外部访问返回 `502 Bad Gateway` 表示请求尚未到达 Express，通常是 Node 服务未运行、
+代理的端口不一致或代理无法连接上游。先在服务器执行
+`curl http://127.0.0.1:3000/health`，确认返回 `success: true`，再检查代理配置和服务日志。
+
+## 数据与上传
+
+- 开发和单元测试时，元数据保存在 `data/database.json`。全新生产部署必须设置
+  `NODE_ENV=production` 和 `DATABASE_URL`；已有 `database.json` 的旧生产实例可继续启动，
+  但会输出迁移警告。PostgreSQL 启动时会执行可重复的规范化表迁移。
+- 模型文件保存在 `data/models/<公司编码>/<产线编码>/`。
+- 模型上传可通过 `modelName` 重命名；数据库同时保存 `originalFileName`，供 Panel
+  显示和识别本地来源名称。未传 `modelName` 时保持原名。
+- 其他上传文件保存在 `data/files/ReinLoop_GUI/`。
+- ReinLoop 上传到 `<设备 ID>/ind_data` 的 CSV/JSON 会进入 Panel 消息队列；
+  Panel 处理并确认后，server 将其标记为已处理并保留，默认 30 天后自动清理。
+- B 端可通过 `listIdentificationFiles` 查看暂存历史，通过
+  `getIdentificationFileDownload` 获取短期签名 URL 下载原始文件，也可通过
+  `deleteIdentificationFile` 显式删除。
+- 除模型外，`/files/:fileID` 必须携带服务端签发且绑定文件与过期时间的下载 token；
+  直接拼接文件地址会返回 `403`。
+- `uploadDataFile` 仍返回 `uploadMetadata`，现有 Python 与 ControlPanel 的 multipart
+  两步上传代码可以继续使用。
+- 可通过 `DATA_DIR` 将数据目录放到独立磁盘。
+- 单文件默认上限为 100 MB。
+
+## API 参考
+
+完整的业务功能、接口字段、权限边界、上传协议和流程说明见
+[features.md](features.md)。
+
+## PostgreSQL 与密钥
+
+生产环境需要以下变量：
+
+- `DATABASE_URL`：PostgreSQL 连接串。
+- `B_ADMIN_TOKEN`：高熵管理令牌。
+- `LICENSE_PUBLIC_KEY_PATH`：只读 RSA 公钥 PEM 路径，用于验证 Panel 已签名许可证。
+- `PUBLIC_BASE_URL`：外部 HTTPS 根地址。
+- `DATA_DIR`：文件存储目录；文件二进制仍保存在该目录的 `files/` 下。
+- `IDENTIFICATION_RETENTION_MS`：已处理辨识 CSV/JSON 的保留时长，默认 30 天。
+- `IDENTIFICATION_PURGE_INTERVAL_MS`：过期清理周期，默认 1 小时。
+- `DOWNLOAD_TOKEN_TTL_MS`：非模型文件短期下载 URL 有效期，默认 5 分钟。
+- `HOST`、`PORT`：监听地址和端口。
+
+迁移可单独执行，且可重复运行：
+
+```sh
+DATABASE_URL=postgres://... npm run migrate
+```
+
+数据库保存文件元数据，文件本体目前需要共享卷或单实例部署；多实例部署前应改为对象存储。
+不得上传、保存或提交 RSA 私钥。通过 HTTPS 部署，定期备份 PostgreSQL 与 `DATA_DIR`，
+密钥轮换时先部署新公钥并验证新许可证，再废止旧签发私钥；恢复时先恢复数据库，再恢复同一
+时间点的文件卷。
+
+## 生产部署注意事项
+
+1. 设置强随机 `B_ADMIN_TOKEN`，不要使用默认开发令牌。
+2. 设置 `HOST=0.0.0.0` 并通过 Nginx/Caddy 提供 HTTPS，或由容器平台映射端口。
+3. 设置 `PUBLIC_BASE_URL` 为外部 HTTPS 根地址，否则下载和上传 URL 会按请求 Host 生成。
+4. 微信小程序后台需要把 HTTPS 域名加入 request、uploadFile 和 downloadFile 合法域名。
+5. 定期备份 PostgreSQL 与整个 `DATA_DIR`；生产环境不可回退到 JSON 存储。
+
+## 验证
+
+```powershell
+npm run check
+npm test
+```
+
+测试会在随机本地端口验证健康检查、multipart 上传、文件列表、下载、辨识反馈和容积请求流程。