yovinchen/RAG
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
RAG/docs/adr/0004-secretless-web-ingress.md
YoVinchen c3bad0f186
Some checks failed
verify / verify (push) Has been cancelled
Details
Make the offline RAG chain observable without widening credential access 
Expose the verified synthetic retrieval path through a typed React client and a non-root Nginx edge while keeping database credentials and data-network reachability out of the browser tier. A fixed-origin gateway preserves request boundaries and now closes upstream streams even when downstream disconnects before body iteration. The deployment ADR and runbooks record the four-network topology and its accepted Web edge-egress risk.

Constraint: The previously exposed Bailian key must be revoked and no live provider credential may enter Git, images, logs, or the browser.
Rejected: Connect Web directly to the data network | expands lateral reach to PostgreSQL.
Rejected: Publish the database-aware API on the edge network | gives a credential-bearing process a public default route.
Rejected: Buffer streaming responses in either proxy | prevents incremental chat delivery in the future.
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Do not mark Stage 1 or Stage 2 complete until the rotated-key live smoke and remaining stage gates pass.
Tested: make verify; 65 backend tests; 14 frontend tests; Docker image build; container health and isolation probes; real HTTP demo/status/search/docs/OpenAPI checks.
Not-tested: Live Bailian models, real document ingestion, business chat SSE generation, and final browser screenshot automation because the browser skill runtime was unavailable.
2026-07-12 17:38:57 +08:00

3.4 KiB
Raw Permalink Blame History

ADR-0004：使用无 Secret 的分层 Web 入口

  • 状态： accepted
  • 日期： 2026-07-12

背景

系统需要同时满足三个约束：浏览器只能访问一个本机 Web 端口；数据库感知 API 不能获得公网出口；React/Nginx 不能因反向代理而加入数据库所在网络。仅把 API 同时接入普通 edge 和内部 data 网络会获得公网出口；仅把 API 接入 internal 网络时，Docker Desktop 又不会可靠发布宿主机端口。

决策

采用四层单机拓扑：

browser
  -> web (Nginx + React; edge + ingress)
  -> gateway (fixed-origin HTTP proxy; ingress + data)
  -> api (FastAPI; data only)
  -> PostgreSQL/pgvector (data only)
  • edge 是普通 bridge，只连接无 Secret 的 web，用于宿主机回环端口发布。
  • ingress 是 internal 网络，只连接 web 和 gateway。
  • data 是 internal 网络，只连接 gateway、api、迁移和数据库等内部组件。
  • 命名的 egress 只供显式云模型工具使用；web、gateway、api 均不连接该网络。普通 edge bridge 仍会给 Web 一个技术上的默认公网出口，不能把网络名称当作防火墙。
  • 只有 web 发布 127.0.0.1:8000；gateway、API 和数据库不发布端口。
  • web 与 gateway 不挂载数据库或百炼 Secret；gateway 固定上游为 http://api:8000，执行请求体上限、头白名单、SSRF 防护和脱敏 502 映射。
  • API 只挂载 app 数据库 Secret，以非 root、只读根文件系统运行，并通过真实 socket 探测证明无公网出口。

取舍

多一层 gateway 会增加一个容器和一次本机网络转发，但当前查询耗时主要来自数据库和模型，额外开销相对可忽略。保留应用层 gateway 可以让固定上游、请求大小和错误脱敏形成可单测契约；Nginx 专注静态资源、SPA fallback、安全响应头和 SSE 代理。

在当前 Docker Desktop 上，edge 必须保持普通 bridge 才能可靠发布宿主机回环端口；实测 Web 可以从该网络建立公网 TCP 连接。当前接受这一残余风险，因为 Web 无 Secret、无数据网络、无挂载，且 Nginx 只代理固定 gateway。需要入口容器零出网的部署必须额外使用主机防火墙或受控出口策略，重新验收后再收紧本 ADR。

被否决方案

  1. API 直接加入 edge 并发布端口： 实测仍可访问公网，不满足数据库感知进程无 egress 的要求。
  2. web 直接加入 data 并代理 API： web 会获得到数据库网络的横向连通性，扩大入口层受攻陷后的范围。
  3. 只发布 internal 网络中的 API 端口： 在当前 Docker Desktop 上没有形成可访问的宿主机端口。
  4. 只使用 Nginx、删除 gateway： 可以减少一跳，但会丢失已经测试的固定上游、请求头白名单和脱敏错误契约；本阶段优先保持安全边界可验证。

验证要求

  • Compose 合同测试锁定网络成员、唯一发布端口和 Secret 挂载。
  • API 与 gateway 容器公网 TCP 探测必须失败；Web 的 edge 出口能力必须被显式记录，web/gateway 镜像历史和环境不得出现 Key、数据库密码或内部 DSN。
  • 浏览器从 Web 入口访问 SPA、/api、健康检查与 SSE 时保持同源。
  • 每次改变该拓扑都必须更新本 ADR、部署文档并重新执行容器级验收。
Reference in New Issue View Git Blame Copy Permalink