#配置数据脱敏

Alauda Hyperflux 可以在敏感值——内部 IP、令牌、密码——离开服务或被持久化之前对其进行脱敏。脱敏是按需启用的，并包含三部分：

• 值规则（queryRedactionFilters）：将正则规则应用于用户的问题和附件，以及 Agent 工具结果，在文本发送到 LLM 之前以及写入会话历史 之前进行处理。
• 键名脱敏（toolArgRedactKeys）：如果工具调用参数的键名看起来像凭证（password、token、api_key 等），则会在审批卡片和审批审计记录中将其掩码。
• 脱敏审计：每次命中规则都会被记录（规则名称和命中次数——绝不会记录值本身），平台管理员可以对其进行查询。

注意： 脱敏是输入侧过滤，其精度取决于你的正则规则。若某个值没有被任何规则匹配到，它仍然会传递给 LLM，并可能出现在回答中。不要将其视为有保证的输出过滤器。

这两个设置不在安装表单中。它们通过补丁插件配置（ModuleInfo）来应用，并在 Pod 重启后生效（平台会在补丁后自动滚动重启）。

#值规则（queryRedactionFilters）

每条规则都是一个对象：

示例规则集：

[
  {
    "name": "internal_ip",
    "pattern": "\\b(?:10|127)\\.(?:\\d{1,3}\\.){2}\\d{1,3}\\b",
    "replace_with": "[REDACTED_IP]",
    "applies_to": ["query"]
  },
  {
    "name": "jwt",
    "pattern": "eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+",
    "replace_with": "[REDACTED_JWT]",
    "applies_to": ["query", "tool_result"]
  }
]

应用它（值为 字符串 形式的 JSON 数组）：

MI=$(kubectl get moduleinfo -o jsonpath='{.items[?(@.spec.module=="alauda-hyperflux")].metadata.name}')
kubectl patch moduleinfo "$MI" --type=merge -p '{
  "spec": {"config": {"smartdoc": {
    "queryRedactionFilters": "[{\"name\":\"internal_ip\",\"pattern\":\"\\\\b(?:10|127)\\\\.(?:\\\\d{1,3}\\\\.){2}\\\\d{1,3}\\\\b\",\"replace_with\":\"[REDACTED_IP]\",\"applies_to\":[\"query\"]}]"
  }}}
}'

校验是严格的：格式错误的 JSON 字符串会导致部署渲染失败；单条规则无效（缺少 name/pattern、mode 或 applies_to 未知、正则无法编译）会阻止服务启动。脱敏本身是 fail-closed 的——如果在请求上应用规则时出错，则会中止该轮对话，而不是让原始文本透传出去。

编写规则时应注意：

• 规则会在每个请求上按列表顺序依次执行；前一条规则的替换文本对后续规则可见。将范围较宽的规则放在后面。
• 保持模式精确并带锚点。正则语法会在启动时校验，但不会检测灾难性回溯——请避免嵌套量词。
• 规则过于宽泛会悄然降低回答质量（LLM 看到的是 [REDACTED_...]，而不是真实值），这也是该功能默认为空的原因。

#键名脱敏（toolArgRedactKeys）

与值规则无关，当工具调用参数在审批卡片中显示以及存储到审批审计中时，如果参数的键名包含配置的任一子字符串（不区分大小写），就会被掩码。工具本身仍然会接收到真实值。

未设置时，默认会应用一组内置安全集合：

password, passwd, secret, token, api_key, apikey, api-key,
authorization, credential, private_key, access_key, secret_key

设置 toolArgRedactKeys（以逗号分隔的子字符串）会替换这组集合——请包含你想保留的默认值。将其设置为空字符串不会禁用该功能；默认集合会重新生效。

#脱敏审计

只要配置了上面的任一设置，每次规则命中都会记录到会话历史数据库的 redaction_audit 表中：请求 ID、会话、用户名、作用面（query / attachment / tool_result / tool_args）、规则名称、模式和命中次数。匹配到的值绝不会被存储。

平台管理员（见安装表单中的 Admin Users）可以查询这些记录：

GET https://<platform-address>/smart-doc/api/admin/redaction_audit

支持的查询参数（均为可选，且按 AND 组合）：username、session_id、request_id、surface、rule_name、from、to，以及 limit（默认 100，最大 1000）和 offset。非管理员调用会返回 403。

两个运维说明：

• 审计写入尽力而为：写入失败只会被记录并丢弃，绝不会导致用户请求失败。不要将该表视为完全可靠、完整的合规账本。
• redaction_audit 没有自动保留/清理机制——如果你的部署处理大量数据，请在外部进行清理。

#验证

发送一个包含规则可匹配值的问题，然后检查日志：

kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep 'redaction hits'

预期结果（仅显示规则名称和次数，绝不显示值）：

query redaction hits: {'internal_ip': 2}
tool-result redaction hits: {'jwt': 1}

然后以管理员身份查询审计：

curl -sk "https://<platform-address>/smart-doc/api/admin/redaction_audit?rule_name=internal_ip" \
  -H "Authorization: Bearer <admin-acp-token>"