89fe54cc07
docs(multi-tenant): 加入汇总索引、跨文档一致性修订、Postgres 切换前移到 Stage 0
...
* 新增 README.zh-CN.md 汇总索引：ADR 状态表 + Stage 0-4 业务目标 / 技术路径 /
验证方式 + Stage↔ADR 对照矩阵 + 不可逆决策一览 + 用语映射 + FAQ + 阅读路径
* 新增 workspace-schema-design.zh-CN.md（Stage 0 schema 锁定版）一并入库
* 7 份 ADR 顶部加"代码命名"映射行（tenant_id ↔ workspace_id）
* ADR-002 §1 加分期落地提示，明确 K8s 推迟到 Stage 3
* ADR-005 §5"第 1/2 阶段"补出与 rollout Stage 2/3 的映射
* ADR-007 §4 加 /api/v1/ 反向链接；§8 加 tid → wid 字段名映射
* headless-api §0/§7 把"SaaS + on-prem 双主线"改为"SaaS 主线、schema 兼容 on-prem"
* phased-rollout 去除重复的"Go/No-Go 进入 Stage 2"段
Postgres 切换从 Stage 1 提前到 Stage 0：Stage 0 已要 ALTER 4 张表加
workspace_id，先 SQLite 再 PG 是纯返工；Stage 0 没有生产数据，迁移阻力最小。
同步调整 phased-rollout / headless-api / phase-0-plan / workspace-schema-design /
README 中的时间盒（Stage 0: 3-4→4-5 周；Stage 1: 10-15→8-13 周）、不可逆决策
清单、PR 顺序、轨道前置依赖。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-10 21:39:58 +08:00
ecc9339ede
docs(multi-tenant): 加入 Headless API 改造轨道（Pattern A/B）+ Stage 1 双轨修订
...
新增 headless-api-track 文档，把 DeerFlow 作为后端服务的两种集成
pattern 全部纳入设计：
- Pattern A（业务 backend 代理）：业务系统 backend 用 API key 调，
浏览器走他们的 backend。覆盖 IM channels + server-to-server 集成。
- Pattern B（自研 web 浏览器直连）：业务 backend 调
/api/v1/auth/exchange-token 换 5-15 min 短期 JWT → 浏览器拿 JWT 直连
含 SSE。核心 4 件事：exchange-token endpoint、ServiceTokenAuthBackend
（AuthMiddleware 第三条路径）、workspaces.allowed_origins + CORS
中间件、SSE 跨域验证。
- 不做 widget / iframe（纯 API）。
数据模型：service_accounts / api_keys / external_users 表（schema 在
Stage 0 末加上不阻塞）；身份模式三态（collapsed / external_passthrough
/ both）按 endpoint 分支。
Stage 1 改为三轨并行：付费 SaaS / Pattern A / Pattern B；时间盒从
6-10 周延到 10-15 周。Pattern B 依赖 Pattern A 完成，建议 Stage 1
末 1-2 周做。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-09 23:29:46 +08:00
fd8d0d637d
docs(multi-tenant): 加入 Stage 0 代码地图
...
把 Stage 0 必做项落到具体文件 + 行号，覆盖 7 个子系统：
auth、user 数据模型、thread 入口路由、ThreadDataMiddleware + 路径系统、
仓储访问模式、setup / 注册流程、CSRF + ContextVar 注入。
文档结构：每节有【关键文件 + 行号】、【关键函数 / 类】、【当前数据流】、
【Stage 0 改动锚点】；外加改动影响面总览（每条 Stage 0 必做项映射到
具体代码位置）、不可逆决策落点、推荐阅读顺序（11 个文件，1.5-2.5h
粗读）。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-09 23:29:27 +08:00
35ae97d0a6
docs(multi-tenant): Stage 2 加入 per-user skill 覆盖与 config 设计
...
补充团队 workspace 内不同成员的 skill 区分模型：
- 启用状态：workspace 级默认 + per-user 覆盖
(final_enabled = user_override ?? workspace_default)
- skill 私有配置（API key 等）：per-user 强制隔离 + KMS 加密
- 上传权限：仅 owner / admin，成员只能 enable/disable + 填自己 config
PR 顺序新增第 8 步，依赖 RBAC + KMS 已就位。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-09 22:47:05 +08:00
e78ed687a6
docs(multi-tenant): 加入按规模分期的落地方案（02-rollout）
...
基于已收敛的目标客户画像（个人用户为主 + 小团队 / 中心化 SaaS /
freemium）把 7 份 ADR 拆成 5 期落地：
- Stage 0：workspace 模型立起来 + auth 收紧（不可逆决策集中在此）
- Stage 1：Postgres + Quota 必落（freemium 不上 quota = 信用卡递给攻击者）
- Stage 2：DeerFlow 表 RLS、KMS、ObjectStorage S3、付费分层
- Stage 3：K8s sandbox + BYO key + audit DB 拆分
- Stage 4：SSO / custom domain / per-tenant DB（按 enterprise 客户合同驱动）
关键取舍：① Stage 0 末就把 workspace_id 列加到 SQLite，避免 Stage 1
切 Postgres 时再补；② Quota 比 ADR-003 原稿提前一档到 Stage 1；③ K8s
sandbox 推到 Stage 3，AioSandbox + 出网白名单 + 资源限额撑到几千用户。
时间盒：最小可付费 4 个月（Stage 0+1）/ 风险可控增长 8 个月（+Stage 2）
/ 全功能 14 个月（+Stage 3）。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-09 22:28:55 +08:00
8bdd308ea0
docs(multi-tenant): 据审计对齐 ADR-002/003/004/005 与 phase-0 计划
...
非 spike 驱动的对齐改动：
- ADR-002/004/005：头部加现状提示 + 链接审计报告（沙箱出网/资源缺位、
token_version 已存在 MembershipCache 全新建、ObjectStorage/7 表/KMS
全部从 0 起）
- ADR-003 LLM 计费：修正 TokenUsageMiddleware 当前只 log 不持久化的描述；
补充 create_chat_model sync→async 改造的连带影响说明
- phase-0 计划：新增 §3.5 底座先行（Postgres 测试夹具 / ObjectStorage
Protocol / KMS 抽象 3 件并行做），时间盒 2 → 3 周；ADR-006/007 摘要
对齐；DoD 加底座骨架检查项
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-09 21:03:32 +08:00
27c4f14233
docs(multi-tenant): 加入 ADR 审计 + spike，并据其修订 ADR-001/006/007
...
新增两份评审产出物：
- adr-vs-code-audit：7 份 ADR 与现状代码的差异核对，标注每条假设是否成立
- adr-spike-langgraph-postgres：实测 langgraph-checkpoint-postgres==3.0.5
注入能力，确认不存在 connection_factory 参数，且 psycopg_pool 自带的
configure callback 不是 per-acquire hook
据 spike 与审计修订三份 ADR：
- ADR-001 数据隔离：LangGraph 表改为应用层强校验 + threads_meta unique
约束兜底（不再挂 RLS、不 ALTER 表）；hook 点从 AssistantsCompat 修正
为 threads.py + thread_runs.py
- ADR-006 运行时与渠道：§2.1 完全重写为应用层强校验；MCP OAuth token
从"无持久化进程内存"直接做加密 DB；channel store binding 改为新建
channel_bindings 表
- ADR-007 路由与前端：删除 Better Auth 假设（前端实际无此依赖），改为
扩展现有 auth/jwt.py TokenPayload 加 tid/role 字段
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com >
2026-05-09 21:03:16 +08:00
dce5e9598b
docs(multi-tenant): add ADRs and phase-0 plan for multi-tenant redesign
...
Add 7 ADRs and a phase-0 plan covering the multi-tenant redesign of
DeerFlow, plus an architecture-overview snapshot of the current state.
ADRs:
- 001 data isolation: row-level tenant_id + Postgres RLS, including
LangGraph-owned checkpoint tables (subquery RLS or column upgrade path).
- 002 sandbox isolation: K8s namespace + gVisor + NetworkPolicy default-
deny, threat model and pod spec defaults.
- 003 LLM key & billing: hybrid platform/BYO with pessimistic reservation
to handle the "ghost token" overflow on the last call, plus a usage
category split for memory/title/summarization charges.
- 004 RBAC: two-level (owner/admin/member), JWT-with-role + 30s LRU
cache for reads, strict DB lookup for sensitive writes, token_version
bump as the single revocation path.
- 005 storage topology: Postgres (structured) + S3-compatible object
store (large objects) + emptyDir (ephemeral); explicit treatment of
the extensions_config.json migration's downstream effects.
- 006 runtime & channel tenancy: per-tenant MCP cache, dual-track skills
loader, sandbox provider routing by namespace, internal LLM call
billing, IM channel-to-tenant binding model.
- 007 routing & frontend: path-slug URL form, JWT-only API auth,
TenantProvider, hard-reload tenant switch, Better Auth integration.
These docs are decision records; no code changes are included.
2026-05-08 23:45:33 +08:00
1445043649