Files
trade-message-center/.trellis/tasks/09-07-onetalk-summary-internal-network/prd.md
T

5.4 KiB
Raw Blame History

Center 摘要内部网络入口

Goal

用同一 Docker daemon 中受限成员的私有网络,替代 Center 摘要历史读取的 Bearer、共享 token 与 Mind authorize-summary 回调。Mind 只经 Center 的内部 7777 监听器读取摘要;既有面向扩展和页面的 7878 服务保持不变。

已确认事实

  • 已归档任务 09-07-onetalk-summary-read-authorization 为摘要 history GET 增加了 Bearer、X-Mind-PurposeX-Mind-Workspace-IdTRADE_MESSAGE_CENTER_SUMMARY_READ_TOKEN 与 Center→Mind POST /internal/bright/onetalk/authorize-summary;这些仅是摘要专用机制。
  • 当前 startServer 只调用一次 app.listen({ host: config.host, port: config.port })createApp 将 public HTTP、WebSocket、页面/插件授权和 summary route 装配为同一 Fastify app。
  • 当前 release workflow 只以 docker run --publish 7878:7878 运行 Center,未创建或加入供 Mind 共用的命名网络。
  • 用户已确认:Mind 与 Center 将运行在同一个 Docker daemon;摘要读取的权限边界改为该私有网络的成员资格。该边界不提供 workspace/conversation 级授权,具备该网络或 Docker daemon 管理权限的主体均可访问摘要接口。

Requirements

  • R1:保留 public 7878 listener、Cookie 页面授权、扩展 WebSocket、普通读取、发送、health 和现有发布端口;不得以改写唯一 PORT 的方式把整个 Bright 服务迁至 7777。
  • R2:新增独立 7777 internal listener,只暴露摘要 history GETpublic listener 的既有 health check 保持不变。internal handler 直接选择 summary read,继续使用既有固定 [fromSentAtMs,toSentAtMs)、opaque cursor、history_incomplete 和只读 service 语义。
  • R3internal listener 不读取或校验 summary Bearer、X-Mind-PurposeX-Mind-Workspace-Id,也不回调 Mind 归属服务。摘要响应只返回会话、消息与分页数据,不得伪造或回显 workspace/mind user/bindingMind 自己持有调用的 workspace 上下文。
  • R4:删除仅由摘要互信引入的 Center contract、credential/config、callback client、diagnostic、测试、示例环境变量和 release secret 注入。保留供 public 页面与插件使用的通用 Mind authorization reader、其 MIND_AUTH_BASE_URL 配置与 WebSocket 授权。
  • R5:发布在一个仅含 Mind 与 Center 的命名 Docker internal 网络上提供 7777;Center 先加入仅供其自身 egress/public port 的命名 bridge network,再挂载该 internal network,不能留在 Docker 默认 bridge。Center 仍发布 7878,绝不 --publish/Compose ports 映射 7777。内部监听必须绑定 0.0.0.0:7777,以供对等容器访问;镜像 EXPOSE 不得被误当作访问控制。
  • R6:网络成员资格是唯一摘要访问控制。不得添加 token、Cookie fallback、IP allowlist、workspace header 或从 Center 数据行反推 workspace 的替代机制;也不得将无鉴权摘要路由注册到 public listener。
  • R7:交付给 Mind 的对接文档,固定内部 URL、无认证请求形状、网络名称/加入方式、不可用边界、部署验收命令和明确的 Docker-daemon 前提;不在本仓库修改 Mind 代码或其部署。

Acceptance Criteria

  • Mind 容器在 trade-message-center-summary 网络中,能不带 Bearer 和 Mind workspace/purpose header 访问 Center :7777 的摘要 history;固定时间窗、分页、history_incomplete 和数据库只读行为保持既有契约。
  • 同一无鉴权请求通过 public :7878 不会获得摘要消息;public listener 的 Cookie 授权、CORS、列表/详情/消息、WebSocket、发送和 health 回归通过。
  • Center 运行时源码、配置、示例 env、CI/release 和活跃测试不再引用 summary token、authorize-summary 或摘要 callback;通用 Mind authorization 和页面/插件授权仍可用。
  • 发布脚本创建/复用受限命名网络、将 Center 接入它,并且只发布 7878。部署验收用 docker network inspectdocker port 和真实 Mind→Center internal HTTP 请求证明网络可达与 7777 未对宿主机发布。
  • Mind 对接文档可让其所有者在同一 Docker daemon 将 Mind 容器加入私有网络、改用内部 7777 URL,且明确此网络成员可读取任意摘要 account/conversation,不应保留 Bearer/workspace/purpose header。
  • 目标单测、typecheck、build、格式检查和 diff review 通过;真实双容器部署验证若当前环境不可得,必须以外部未验证项报告,不能用单机 mock 代替。

Out of Scope

  • 在本仓库修改 Mind 的业务读取逻辑、数据库 schema 或其部署仓库;Mind 将请求内部 URL 并加入命名网络的改动由其所有者交付。
  • workspace、账号或会话级授权;它们与“网络成员即授权”的已确认边界冲突。
  • 7777 暴露给宿主机、互联网、跨 Docker daemon、Kubernetes 或 Docker Swarm 网络;若 Mind 与 Center 不在同一 Docker daemon,本设计不适用。
  • 数据库迁移、消息投影、历史 cursor/排序语义、通用 Mind authorization 的重构。

Delivery Boundary

Center 的 release workflow 负责创建/复用私有网络并把 Center 接入其中。Mind 所有者依据本任务交付的文档,将其容器接入同一网络并改用 internal URL;该外部操作是端到端部署验收的前置条件,不是本仓库的代码变更。