Aether/docs/operations/security-hardening-compatibility-review.md

# 安全加固兼容性复核（2026-09-07）

后续扩展到全仓的检查范围、新发现、逐文件清单及限制见 `security-hardening-full-audit.md` 和 `security-hardening-audit-manifest.tsv`。

## 范围

本轮针对 `579f2c7cc`（2026-09-04）及其后续修复进行复核。该提交涉及 1019 个文件，混合了安全边界、订阅计费、数据持久化和运行时变更，不适合整体 revert。

本轮重点检查管理端脱敏与编辑往返、Provider OAuth 默认配置、已有 DNS/代理兼容性修复、管理员错误诊断、SMTP/LDAP/OAuth 配置、导入导出及请求大小限制。以下是已确认的问题及处理，不代表对全部文件逐行审计或对生产环境的完整验证。

## 新增：管理员按需查看规则原值

- 端点管理的请求/响应规则工具栏增加“查看原值”。只读弹窗展示服务端已保存的请求头、请求体和响应头规则，不覆盖未保存的草稿。
- 新接口：`GET /api/admin/endpoints/{endpoint_id}/rules/reveal`。
- 仅管理员可访问；管理令牌需要 `admin:endpoints_manage:admin`，只读和普通写权限不足。
- 返回 `Cache-Control: no-store`、`Pragma: no-cache`，记录 `admin_endpoint_rules_revealed` 审计事件。响应仅包含三组规则，不附带端点的其他配置或凭据。
- 关闭弹窗、切换端点或卸载组件时取消请求并清除明文；旧请求的迟到结果不会重新显示。

## 本轮修复的六类误伤

| 问题 | 影响 | 处理 |
| --- | --- | --- |
| 普通协议头也全部脱敏 | `Content-Type`、`User-Agent`、版本/客户端信息及相应条件无法正常查看；配置导出也受影响 | 恢复明确的常用非凭据头的显示；认证头、Cookie 和未知自定义头继续默认隐藏。旧版本返回的保留标记仍可正常保存 |
| 重复规则无法恢复原值 | 同一头或路径配置多条条件规则后，保存或重排可能将原值变成 `***` | 在相同操作和目标范围内按可区分的规则结构匹配；未修改的重复规则保留原顺序与原值。无法唯一定位的脱敏编辑明确报错，禁止静默写入占位符 |
| 嵌套条件组丢失原值 | 多层 `all`/`any` 在修改其他条件或重排后，内部脱敏值无法恢复 | 增加递归条件组匹配、未修改条件组往返保留和保留值校验 |
| URL 类型判断过宽 | `image_url` 等对象/数组被变成 `null`，内嵌 `data:` 图片 URL 也受影响，继续编辑可能破坏请求规则 | 保留结构化 URL 和内嵌数据；递归处理网络 URL，继续隐藏并在保存时恢复网络凭据 |
| 保存后的编辑状态没有同步 | 后台返回脱敏数据后，界面仍保留提交前明文，持续显示“未保存” | 使用保存响应重新建立编辑基准；保存期间的新编辑不被覆盖，关闭后清除草稿，忽略跨弹窗的旧响应 |
| Gemini CLI 默认 OAuth 被误移除 | 未额外配置环境变量时，原有默认客户端不能授权或刷新 | 恢复加固前内置 native-app 客户端的配套默认值；显式配置优先，自定义客户端 ID 仍必须提供自己的凭据，调试输出继续脱敏 |

明确可直接显示的头包括 `Accept`/编码/语言、`Content-Type`/编码、`Cache-Control`、`User-Agent`、Anthropic/OpenAI 协议版本与 beta 标记，以及明确列出的 `x-stainless-*` 客户端运行时字段；不是按前缀放行任意自定义头。

## 补充修复：显式 `full` 请求记录被禁用

原则：安全处理应约束未授权访问、未配置时的默认行为和真实凭据泄露，不应静默覆盖管理员明确启用的功能。

本次确认不是单纯的前端隐藏，而是同一链路上的多重清空：

- `request_record_level=full` 在运行时被强制解析为 `basic`。
- 独立 HTTP 审计存储的输入投影清除了所有请求头、正文、正文引用和采集状态。
- 内存仓库每次更新都丢弃正文与引用；PostgreSQL 的单条写入把正文 blob 同步改成删除，并拒绝 HTTP 审计内容。

处理：恢复显式 `full`（含旧配置名 `request_log_level`）的采集与独立存储，保留当前配置名优先；恢复请求、上游请求、上游响应和客户端响应各方向已有的采集内容，流转状态更新不再无条件删除它们。PostgreSQL 正文仍写入原有压缩 blob 表，HTTP 头与引用仍写入独立审计表，不重新塞回计费主表。

保留：缺失、无效配置和读取配置失败时默认 `basic`；`basic` 不记录正文；OAuth 令牌交换等内部凭据请求不采集正文；认证头及未知自定义头继续脱敏；正文引用仍校验所属请求和字段；管理端权限、审计及无缓存策略不变。普通同格式非流式响应仍只保存一份原有响应体，前端沿用回退显示，不制造重复的客户端副本。

新增回归覆盖配置解析、内存生命周期、流式/非流式管理端正文读取、旧正文大小配置不覆盖 `full`、PostgreSQL 单条/批量写入与正文读回、前端按需加载与无正文时的展示。真实数据库测试使用本机临时隔离 PostgreSQL，不访问现有业务数据库。

此修复只能恢复之后新采集的记录；此前未采集或已删除的正文无法由代码补回。运行时沿用原有的 30 秒采集策略缓存，刚切换记录级别时需等待缓存刷新。

扩大执行原有、默认忽略的 PostgreSQL 测试时，另发现 5 个旧用例的测试数据/类型与当前 schema 不兼容：4 个使用超过 `varchar(36)` 限制的 Provider Key ID，1 个直接按 `f64` 解码 `NUMERIC` 列。它们并非本次正文修复引入，也不作为本次已通过项；未修改相关业务逻辑或测试夹具。

## 继续复核：视频任务链路的四类回归

继续沿“业务字段被当作诊断数据清空”“读取投影与更新条件不一致”检查，另确认以下四类问题，均可定位到本次加固新增的清空或校验条件，不是用户配置错误：

| 问题 | 实际影响 | 本轮修复 |
| --- | --- | --- |
| 任务业务信息被清空 | 提示词、用户名和客户端 Key 名称丢失，管理页显示空白或 `Unknown`；提示词被写成 `NULL` 还与 PostgreSQL 的非空约束冲突，可能直接阻止任务入库 | 保留这些明确用于任务展示的业务字段，不再作为敏感诊断一律删除 |
| 下载地址被清空或破坏签名 | OpenAI 任务的 `video_url` 被无条件丢弃；Gemini 地址仅保留 `alt=media`，使下载签名、有效期等参数失效 | 保留 HTTP(S) 产物地址及完整查询串，不重排重复参数、不重编码签名；继续拒绝非法协议和 URL userinfo，移除 fragment |
| Gemini 完成结果和重载丢失 | 完成轮询直接清空元数据；数据库重建与加密文件加载再次清空结果 URI，出现任务已完成但无法取得视频 | 仅保留下载所需的最小结果 URI，不保留上游完整响应；从数据库的业务字段重建必要的提示词、尺寸信息和结果 URI，保证再次保存不会丢失 |
| PostgreSQL 轮询更新条件自相矛盾 | 领取任务时不读出时长、分辨率、宽高比和尺寸，而加固后的更新要求这些不可变字段逐项相等，导致正常轮询更新被拒绝、任务停留在处理中 | 领取时读回必要业务字段，保留原有归属/身份校验和并发领取锁，不靠放宽更新条件绕过问题 |

保留原有播放/下载接口与鉴权语义：签名产物链接是有权限用户访问任务结果所需的业务数据，不等同于可随意删除的调试凭据。OpenAI 直接下载不附带 Provider 认证头；Gemini 仍通过网关文件接口访问，并校验上游地址同源后才附加 Provider Key。私网/保留地址拦截、跨域凭据隔离、任务归属校验及管理操作审计不撤销。

任务数据库仍不保存完整请求体、原始错误消息或含认证头的传输快照；本地文件仍使用原有认证加密格式，调试输出继续脱敏。回归覆盖任务保存后重读、签名参数顺序与编码、加密文件重载、管理列表/详情、带审计的下载，以及轮询前后提示词和尺寸不丢失。

真实 PostgreSQL 回归使用临时 Unix socket 实例，并从正式迁移后的 schema 复制会话隔离的任务表。OpenAI/Gemini 两种任务均验证了入库、领取、正常完成更新、拒绝不匹配的尺寸更新和重新查询签名地址；不连接现有业务数据库。

这四类是本轮已经确认的新增回归，不代表对混合提交全部 1019 个文件给出“零遗漏”保证。原有用户策略字段停用早于本次加固，不据此回退；后台任务和缓存中的裁剪未发现足以确认本次功能回归的调用链，不做猜测性恢复。数据库仍保存的历史值可以重新读取；已经写空、未入库或已过期的资源不能凭本次源码修复重建。

## 已存在的后续修复：保留，不重复撤销

- `522b97905`：已移除普通 Provider 代理的 DNS 地址过滤和相关白名单设置。
- `696273122`：已恢复 Antigravity 默认 native-app OAuth 配套凭据；本轮将同类遗漏补到 Gemini CLI。
- `a26680f46`：已恢复旧 SMTP 密码迁移。
- `062e111c0`：已恢复管理员查看上游错误诊断的能力，同时保留普通用户侧脱敏。
- `14f96c9fa` 等：已修复脱敏后的密钥健康状态摘要，不将其退回旧实现。

## 保留的安全边界

- 管理员/普通用户与管理令牌的权限隔离；凭据查看接口的审计和无缓存要求。
- 凭据加密存储及凭据与目标/身份绑定；未知头和真实敏感字段的默认脱敏。
- 登录 OAuth、支付、隧道中继等独立网络边界，TLS 校验和隧道防重放。
- 有界请求/响应缓冲、备份恢复模式、导入校验、计费与配额一致性；本轮没有因“安全加固”标签撤回这些功能。

## 回归覆盖与使用限制

回归用例覆盖规则投影/恢复、重复与嵌套规则、占位符拒绝、结构化 URL、保存期间的并发编辑、弹窗关闭/切换时的迟到响应、接口权限/审计/无缓存，以及 Gemini CLI 和 Antigravity 的默认配置与显式覆盖。

早期兼容性修复的阶段性验证记录（最终全量结果见 `security-hardening-full-audit.md`）：

- 视频数据契约 12 项、视频核心 33 项（含加密文件重载）、内存视频仓库 11 项、PostgreSQL 视频仓库 9 项、Provider 视频传输 9 项均通过。
- 新增的真实 PostgreSQL 回归单独执行通过，同时覆盖 OpenAI 和 Gemini；临时数据库实例已停止并清理。
- 网关 `video` 101 项、`async_task::` 20 项、`usage` 302 项、端点规则原值查看 3 项、管理令牌权限 28 项均通过；筛选结果可能重叠，不合计为独立用例总数。
- 前端 199 个测试文件、1411 项测试通过；补齐保存测试的类型夹具后，该文件 4 项测试及 ESLint 再次通过；Rust 格式检查和 `git diff --check` 通过。
- 阶段性检查曾发现 461 条既有类型诊断，与未修改 HEAD 的同依赖基线一致。2026-09-07 的“全部修复”续轮已修正这些诊断，并将 `npm run type-check` 接入 `vue-tsc -b --force --pretty false`；当前真实全量类型检查为 0 错误。最新全量测试、构建及剩余验证边界以 `security-hardening-full-audit.md` 为准，未关闭严格模式或排除测试。

上述修复与回归不涉及生产服务器部署或现有业务数据库更改；源码提交、推送不代表生产环境已经部署或完成验证。若历史版本已经把真实值覆盖为字面量 `***`，查看接口不能重建丢失的原值，需重新填写或从可靠备份恢复。