文档 DLP 流水线 — 运维参考
当某个 workspace 启用了 DLP 扫描时，每个上传的文档在 ingestion 之后都会经过一次异步的 pg-boss 扫描：
当某个 workspace 启用了 DLP 扫描时，每个上传的文档在 ingestion 之后都会经过一次异步的 pg-boss 扫描：
可选的 Enterprise 功能，按 workspace 启用（workspaces.dlpDocumentScanEnabled，默认 off；启用需先通过 eval gate）。来源：docs/DLP_DOCUMENT_PIPELINE.md（Phase 192, DLP-01..06 — v0.28.1）。来源行：FACT-CENSUS.mdF-DLP-1、F-DLP-2、F-AUDIT-1。
- Detect — 三层检测流水线：管理员可配置的 regex 模式（
dlpPatternService），对固定格式意大利标识符的校验值验证（Codice Fiscale 含 omocodia、P.IVA、IBAN —dlpChecksum），以及经 LLM 的上下文 NER 检测姓名/地址（使用既有 Ollama 客户端）。 - Mask — 检测到的实体变为文档级编号占位符（
[PERSON_1]、[GOV_ID_2]、…）。打码是幂等的（mask∘mask = mask）— 占位符语法永远不可能重新自我匹配。 - 已打码的 re-embed —
document_chunks.chunkText以已打码文本重写，searchVector/searchVectorMulti（FTS）重新计算，向量经 collector 端点/api/ingest/reembed重新嵌入。任何未经脱敏的向量都不会保持可检索。 - 加密原件 — 原始文本与每个实体值都以 AES-256-GCM 密文保存（
encryptionService，ENCRYPTION_KEY 契约）。打码是单向的：加密原件是唯一的干净副本。
管理控制
每个 workspace 的开关（DLP-01）
Settings → Workspaces → DLP document scan 开关（列 workspaces.dlpDocumentScanEnabled，默认 off）。
- 开关保持不可用直至下方的 eval gate 通过 — 关闭操作从不被阻止。
- 状态先乐观翻转，保存失败时回退。
eval gate（DLP-05）
检测质量评估必须先通过才能启用：
- POST /api/system/dlp/eval/run（admin）— 在已提交的意大利 PII 修复数据集语料（
packages/server/src/__tests__/fixtures/dlp-eval/）上运行可重复的评估器。结果持久化到 SystemConfigDLP_EVAL_LAST_RUN（管理员不可编辑）。 - GET /api/system/dlp/eval/result（admin）— 读取最近一次运行；从未运行返回
{ passed: false, noRun: true }— 绝无静默通过。 - 门槛指标： GOV_ID/FINANCIAL 两类上，被校验值抑制的检测给出零误报。PERSON/ADDRESS 的 recall 仅做文档化（nerMode 标记
stubvslive）。
旧语料的 backfill（DLP-06）
POST /api/system/dlp/backfill（admin，UI 中需 AlertDialog 确认）：
- Eval-gated：当最近一次评估缺失或未通过时，以
409 { error, gate: "eval-not-passed" }拒绝。 - 幂等 + 可续跑：标记
dlpScannedAt— 重跑只入队没有标记的文档。 - 限速：队列并发 1（低于实时扫描队列）。
- 收敛由 integration 双身（真实 Postgres）固定验证：已打码 chunk 持久化、tsvector 重新计算、reembed payload 与已打码文本 byte 相等、审计查询 = 零剩余 PII。
四类模式（欧洲/意大利标识符）
| 类别 | 检测什么 |
|---|---|
| GOV_ID | Codice Fiscale（含 omocodia 校验） |
| FINANCIAL | P.IVA、IBAN（含校验值验证） |
| PERSON | 人名（上下文 NER，经 LLM） |
| ADDRESS | 地址（上下文 NER，经 LLM） |
校验值类（GOV_ID/FINANCIAL）是确定性的；上下文类（PERSON/ADDRESS）经 LLM 的 NER — 其 recall 在评估结果中做文档化。
聊天重组（DLP-03）
已打码的占位符会到达 LLM；在流结束时，恰好一次，服务器为在所引文档 workspace 上持有 dlp:unmask 的用户把终端消息中的占位符重组还原。SSE done payload 上的附加字段 content 携带重组文本；widget 访客绝不接收重组文本（服务端强制；对 UI 只是隐藏控件）。
Unmask 预览（DLP-04）
GET /api/documents/:documentId/text 默认提供已打码文本。?unmask=true 只沿门槛阶梯重组：合法 param → workspace 开关 on → resolveWorkspaceRole + dlp:unmask 权限。每一处不满足都返回已打码文本（200）— 该端点绝不是授权判定器。UI 开关只为有权用户在含实体的文档上绘制（DOM 缺席式），按视图存在且从不持久化。
审计矩阵（SC-4）
每条读取路径都被一个行为测试固定（18 行：文本视图、OCR 预览、synthesis、citations、widget RAG、MCP tools、FTS、export、复制 KB、reembed admin）。widget/citations/MCP 携带硬性负固定（已打码，绝不重组）。
本指南介绍文档 DLP 流水线的操作面；工程深潜见孪生博文：
Provenance
| 章节 | 来源 |
|---|---|
| 4 阶段流水线 / detect / mask / reembed / encrypt | docs/DLP_DOCUMENT_PIPELINE.md（Overview — Phase 192 DLP-01..06）— F-DLP-1 |
| 管理控制 / 开关 / eval / backfill | docs/DLP_DOCUMENT_PIPELINE.md（§ Admin controls） |
| 聊天重组 / Unmask 预览 / 审计 | docs/DLP_DOCUMENT_PIPELINE.md（§ DLP-03/04, SC-4）— 审计类见 F-AUDIT-1 |
| “10 PII”计数 | 不引用：该计数在本次工作中不可溯源（F-DLP-2 = UNTRACED-IN-THIS-PASS）— 页面只陈述真实的类别，绝无未溯源的数字 |
---
运维参考 — Simmetric Chat v0.28.1（文档更新于 2026-10-02，普查 SHA `aca5b8ff`）。