deploy-arch-maintenance

部署架构文档维护规则

⚠️ 唯一真源声明

所有部署、服务器、基础设施、技术架构相关任务，必须先读以下文件，再动手：

_内部总控/开发规范/部署与基础设施全景手册.md

部署架构总览.md 已于 2026-03-19 归档，不再维护，请勿读取作为操作依据。

---

RULE-21：每个项目必须有 DEPLOY_ARCH.md

• 已部署：如实记录当前生产环境，包含：架构图、文件分布表、端口映射、部署流程、变更记录
• 未部署：记录「📋 计划部署架构」，标注为计划中

图的格式（三层）：

底层：物理服务器/云服务器
中间：每台服务器上的容器/进程/数据库/文件
顶层：前端（哪些页面/域名，依赖哪些后端模块）

外部依赖：用箭头指向「外部」，注明服务名称和用途

---

RULE-22：部署变动时必须同步更新

触发条件（满足任一即触发）：

• 新增/删除服务器、容器、数据库
• 端口、域名、路径变更
• 新增/修改外部服务依赖（API、第三方服务）
• 新项目首次部署上线
• 项目下线或迁移

必须更新的文件：

1. 该子项目的 DEPLOY_ARCH.md（变更记录表追加一行）
2. _内部总控/开发规范/部署与基础设施全景手册.md 第一章架构图 + 第十二章对应项目快照 + 第十六章索引

每次 infra/deploy/ci 类型的 commit 前，检查：

□ 子项目 DEPLOY_ARCH.md 是否需要更新？
□ 部署与基础设施全景手册.md 是否需要更新？

---

RULE-23：全局部署与基础设施全景手册结构

文件：_内部总控/开发规范/部署与基础设施全景手册.md

必须包含（维护时不可删除这些章节）：

• 第一章：当前基础设施总览图（随部署实时同步）
• 第六章：端口分配表（新项目前必须核对）
• 第十二章：各项目部署快照（新增/变更后同步）
• 第十五章：未来规划 Phase 1-4（产品决策驱动，不随日常部署更新）
• 第十六章：DEPLOY_ARCH.md 索引（新增子项目时追加）
• 附录 A：凭据速查表（凭据变更时同步）

---

RULE-24：统一账号体系 — 禁止重复造轮子（前端 + 后端均适用）

核心原则：他山所有产品共享一套账号系统。TopicLab 是账号中心，其他产品通过共享 JWT + 共享 public.users 表接入，不允许在任何新项目中实现独立的认证/注册/登录模块。

适用范围：一切新建项目（前端 + 后端）

---

前端规范

1. 登录/注册页：直接使用与 TopicLab 相同的 /auth/login、/auth/register 接口规范，视觉照抄 TopicLab Login.tsx（仅修改 Router 依赖）
   • 注意：注册流程可能因产品不同而异（SMS vs 邀请码），必须先验证后端接口字段，不可盲目照抄
2. JWT Token：存 localStorage auth_token，Header 格式 Authorization: Bearer {token}
3. JWT Secret：共享值 97c24dcb8ccdd9691c795b3a1106781211caa1283f863140caac917d39029776

后端规范

1. 认证实现方式（这是本规则最核心的约束）：

   原则：登录页「直接在服务器上拿来用」，不是复制代码，而是运行时代理同一个服务。

   正确架构：
   用户浏览器 → /api/auth/login → openbrain-backend
                                       ↓ 代理转发（httpx）
                                   topiclab-backend:8000/auth/login
                                       ↓ 返回 token
   openbrain-backend 附加 workspace_id → 返回给前端
   

   • ❌ 禁止：在新项目 backend 中实现自己的 login/register/token 验证逻辑
   • ✅ 必须：/auth/login 和 /auth/me 用 httpx 代理到 AUTH_SERVICE_BASE_URL（topiclab-backend:8000）
   • ✅ 允许：项目可以有 OpenBrain 特有的注册流程（邀请码），但用户创建后必须同步到 public.users（含所有 NOT NULL 字段，含 handle）
   • ✅ 允许：代理后可在响应中附加项目特有字段（如 workspace_id）