125 lines
5.2 KiB
Markdown
125 lines
5.2 KiB
Markdown
# 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 上传、文件列表、下载、辨识反馈和容积请求流程。 |