From 2f076141a3cf026a8d341b71adc719dbde456231 Mon Sep 17 00:00:00 2001 From: leietal Date: Sun, 1 Nov 2026 20:43:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E8=A1=A5=E5=85=85=20MeshSafe?= =?UTF-8?q?=20=E6=96=87=E4=BB=B6=E5=AE=89=E5=85=A8=E6=A3=80=E6=B5=8B?= =?UTF-8?q?=E5=AF=B9=E6=8E=A5=E9=85=8D=E7=BD=AE=E8=AF=B4=E6=98=8E(?= =?UTF-8?q?=E6=80=BB=E5=BC=80=E5=85=B3/=E5=8F=82=E6=95=B0=E8=A1=A8/?= =?UTF-8?q?=E6=95=B0=E6=8D=AE=E5=BA=93=E8=84=9A=E6=9C=AC/MeshSafe=E4=BE=A7?= =?UTF-8?q?=E5=87=AD=E8=AF=81/=E5=89=8D=E7=AB=AF=E8=87=AA=E5=8A=A8?= =?UTF-8?q?=E6=84=9F=E7=9F=A5/=E9=83=A8=E7=BD=B2=E6=A3=80=E6=9F=A5?= =?UTF-8?q?=E6=B8=85=E5=8D=95)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7ccfb8b..98d4447 100644 --- a/README.md +++ b/README.md @@ -19,10 +19,67 @@ cd backend && mvn spring-boot:run cd frontend && bun install && bun dev ``` -## 文件安全检测（MeshSafe） +--- -独立检测服务，上传/传输接收解包后自动送检，检测不通过的文件禁止分享与传输（文件夹可确认跳过，仅传通过内容）；支持人工复核与重新检测。 +## 文件安全检测（MeshSafe 对接配置） + +对接独立检测服务 MeshSafe（`code.senmesh.com/zhaolei/MeshSate`）：文件**上传**与跨网传输**接收解包**后自动送检（HMAC-SHA256 签名 + 响应验签），结论回写 `x_file_security` 表并标记在文件上。 + +**核心行为**： + +- 检测不通过的文件**禁止分享与跨网传输**（下载/预览不受限）；文件夹内部分文件不通过时，分享/传输弹窗列出清单，用户确认后**仅传输通过的内容**（`onlyPassed=true`） +- 检测中 → 禁止分享/传输；检测失败 → 默认放行（仅标记，可重新检测） +- 管理员可**人工复核**改判（必填说明，留痕并回写 MeshSafe）、**重新检测** +- 列表"安全检测"列展示状态徽章 + 结论摘要，悬停浮窗显示全信息；检测中的文件列表每 2 秒自动轮询刷新 + +### 1. 后端配置（`backend` 的 application.yml） + +```yaml +meshsafe: + enabled: true # 总开关：false 时整体关闭——不送检/不拦截/预检返回空/前端隐藏检测列 + base-url: https://meshsafe.internal # MeshSafe 服务地址 + client-id: s-file # MeshSafe 分配的调用方标识 + secret: "***" # MeshSafe 分配的密钥(勿泄露，建议环境变量注入) + channel: default # 业务通道标识(仅用于 MeshSafe 日志追溯) + timeout-seconds: 120 # 单次请求超时 + fail-open: true # 检测服务异常时降级：true-放行(仅标记检测失败) / false-同样禁止分享传输 + poll-timeout-minutes: 60 # "检测中"超过该时长仍无结论则标记检测失败(防死轮询) + review-sync-to-meshsafe: true # 人工复核是否回写 MeshSafe(失败仅告警，不影响本地生效) + poll: + cron: "0 */30 * * * ?" # 轮询未完成检测任务的定时任务(默认30秒) +``` + +| 配置项 | 说明 | +|---|---| +| `enabled` | **总开关**。关闭场景（无需 MeshSafe 的部署）：后端上传/解包不送检、分享传输不拦截、`/file_security/share_check` 预检返回空、复核与重新检测接口报"文件安全检测未开启" | +| `fail-open` | 安全优先的部署建议 `false`（检测服务异常时宁可阻断）；可用性优先用 `true` | +| 其余 | 一般保持默认即可 | + +### 2. 数据库 + +执行 `backend/db/upgrade-20261101-meshsafe-file-security.sql`（新增 `x_file_security` 检测记录表，MySQL/DM8 与 PostgreSQL 双节；全新环境直接执行 init 脚本已包含）。同一文件允许多条检测记录（复核/重检均新增），业务取最新一条。 + +### 3. MeshSafe 侧配置 + +- 向管理员申请调用方凭证，并将 `client_id:secret` 加入 MeshSafe 的 `MESHSAFE_API_CLIENTS` 环境变量白名单； +- MeshSafe 策略 `config/policy.yaml` 的 `engine_failure_mode` 生产必须为 `fail_closed`（引擎异常宁可拒绝），注意不要为了"服务没起来也能用"改成 `fail_open` 后带上生产； +- 建议监控 `GET /api/v1/health`（重点 `clamav.available` 与签名库更新时间）。 + +### 4. 前端（无需配置） + +前端通过 `GET /file_security/enabled` 自动感知总开关：开启时展示"安全检测"列与复核/重新检测入口，关闭时相关 UI 完全隐藏，无需前端发版。 + +### 5. 部署检查清单 + +1. 执行数据库升级脚本（`x_file_security`）； +2. 后端配置 `meshsafe:` 段并确认 `enabled: true`； +3. MeshSafe 侧将后端凭证加入白名单，确认 `/api/v1/health` 健康； +4. 重启后端，上传一个测试文件验证：列表出现"检测中"→ 数秒内变为"检测通过/不通过"； +5. 用测试样本验证拦截链路（分享/传输被拒、文件夹确认跳过、复核改判后放行）。 + +### 6. 相关文档与代码 -- 后端配置：`backend/docker-test/application.yml` 的 `meshsafe:` 段（`enabled` 总开关） - 接口文档：`backend/docs/接口文档-文件安全检测.md` -- 数据库脚本：`backend/db/`（init 全量 + upgrade 增量，双写 MySQL/PG） +- 客户端实现：`backend/src/main/java/com/senmesh/sfile/client/MeshSafeClient.java`（HKDF 密钥派生、请求签名、multipart 手工构造、响应验签） +- 检测记录表：`x_file_security`（实体 `FileSecurity`，取最新一条生效） +- 送检触发点：网盘上传（`NormalUserFileServiceImpl`）、传输接收解包（`TransferFileMonitorServiceImpl`）、手动重检（`/file_security/rescan`）