- source-repos/octo-server/README.zh.md（开源源码第一手）
- source-repos/octo-server/main.go + internal/modules.go（开源服务入口）
- source-repos-internal/octo-deployment/docker/docker-compose.yaml（内部版全组件）
- source-repos-internal/octo-deployment/docker/nginx/conf.d/（路由配置）
- source-repos-internal/octo-deployment/helm/octo/values.yaml
- 02-architecture/OCTO全组件服务清单.md v0.1
- 01-product/模块说明/ 各模块v0.3文档（docs/drive/fleet-loop/marketplace/speech/summary/search/我的）
- 01-product/模块说明/模块间联动关系总览.md v0.1
- 00-inbox/product-bot-answers/ 各批次产品管家回答
OCTO 总体架构 v2.0
文档定位
1. 总体分层（含内部版全模块）
┌──────────────────────────────────────────────────────────────────────────┐
│ 客户端层 (Clients) │
│ octo-web(Web/PC-Electron) · octo-android · octo-ios · octo-admin │
│ [Web独有: 文档/网盘/回路/市场/我的/智能总结] │
│ [移动端: 消息/语音输入/语音转写/基础摘要; 无回路/无Drive] │
└────────────────────────────┬─────────────────────────────────────────────┘
│ HTTPS :28443 / HTTP :28080
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ nginx 薄网关层 (容器 :80/:443) │
│ TLS终结 · /ws→WuKongIM(WS) · /admin/→admin · /docs-collab→docs(WS) │
│ /docs-html/→docs-html · /{bucket}/{key}?X-Amz-*→MinIO(presigned直反代) │
│ / → web:80（厚路由层） │
└────────────────────────────┬─────────────────────────────────────────────┘
│
┌──────────────┴──────────────┐
│ 厚应用层 web:80 (nginx) │
│ /api/*,/v1/* → server:8090 │
│ /summary/api/ → summary │
│ /market/api/ → marketplace │
│ /fleet/api/ → fleet │
│ /v1/drive/ → drive │
│ /api/v1/docs/ → docs-backend│
│ /speech-admin/ → speech-adm │
│ / → SPA │
└──────────────┬──────────────┘
│
┌────────────────────────────▼─────────────────────────────────────────────┐
│ 核心后端：octo-server (Go, 单二进制 :8090/:6979) │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ main.go + Gin HTTP 引擎 + gRPC server :6979 │ │
│ │ 全局中间件：accesslog · auth · ratelimit · metrics · CORS · reqid │ │
│ │ 业务模块（modules/，Go init 自注册，进程内直接调用）： │ │
│ │ ┌──────────┬──────────┬────────────┬──────────┬──────────────┐ │ │
│ │ │ IM 核心 │ 文件/附件 │ Bot/Agent │ 管 理 │ 集 成/搜索 │ │ │
│ │ │ message │ file │ bot_api │ user │ webhook │ │ │
│ │ │ group │ sticker │ botidentity│ space │ incoming │ │ │
│ │ │ thread │ category │ botfather │ oidc │ integration │ │ │
│ │ │ channel │ source │ bot_task │ ~~org*~~ │ openapi │ │ │
│ │ │ voice_ │ search │ bot_mention│ backup │ agentmail │ │ │
│ │ │ adapter │ messages_│ bot_provis-│ qrcode │ adapter │ │ │
│ │ │ │ _search │ ion │ report │ voice_adapter│ │ │
│ │ │ │ │ app_bot │ statistics│ card_tmpl_ │ │ │
│ │ │ │ │ ai_team │ notification│ catalog │ │ │
│ │ │ │ │ robot │ usersecret│ cardtrust │ │ │
│ │ └──────────┴──────────┴────────────┴──────────┴──────────────┘ │ │
│ │ internal/ 内核：carddispatch · tokenlifecycle · msgextraseq │ │
│ │ · projectprovision · agent编排 │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ 请求处理 5 步：Authenticate → Authorise → Execute → Fan out → Respond │
└──────┬──────────────┬───────────────┬───────────────┬───────────────────┘
│ │ │ │
┌────▼────┐ ┌─────▼─────┐ ┌──────▼──────┐ ┌─────▼──────────────┐
│WuKongIM │ │ 必选存储 │ │ 旁路微服务 │ │ 搜索基础设施 │
│(必选IM │ │ │ │ (opt-in) │ │ (opt-in, search │
│ 底座) │ │ MySQL 8 │ │ │ │ profile) │
│:5001mgr │ │ Redis 7 │ │ octo-matter │ │ │
│:5100TCP │ │ MinIO/S3 │ │ (任务/Todo) │ │ Kafka 3.8.0 │
│:5200WS │ │ │ │ │ │ (KRaft,事件总线) │
│:5300mon │ │ │ │ summary-api │ │ ↓ │
│gRPC:6979│ │ │ │ summary-wkr │ │ es-indexer │
│(webhook)│ │ │ │ │ │ doc-indexer │
└─────────┘ │ │ │ speech │ │ drive-indexer+Tika │
│ │ │ speech-admin│ │ ↓ │
│ │ │ │ │ OpenSearch 2.17.0 │
│ │ │ docs-backend│ │ (+IK中文分词) │
│ │ │ docs-html │ │ │
│ │ │ │ └────────────────────┘
│ │ │ drive │
│ │ │ │ ┌────────────────────┐
│ │ │ marketplace │ │ Fleet专用存储 │
│ │ │ (默认启动) │ │ (opt-in, fleet) │
│ │ │ │ │ PostgreSQL 16 │
│ │ │ fleet │ │ (Fleet唯一使用PG) │
│ │ │ (+fleet-pg) │ └────────────────────┘
│ │ └─────────────┘
└───────────┘
~~`org*`~~：Q10已确认——源码无organization概念（全仓org_id=0命中），租户边界唯一是Space，代码对应`modules/space/`；不存在独立org模块。
- 最小开源生产集7件套：octo-server + octo-web + octo-admin + WuKongIM + MySQL + Redis + MinIO
- 内部版全量：在7件套基础上按需启用各profile（summary/speech/docs/docs-html/drive/fleet/marketplace/search/doc-index/drive-index）
2. 两层Nginx路由架构
客户端 :28080/:28443
↓
nginx(gateway/thin层 :80/:443) ← TLS终结、WS升级、MinIO直反代
├─ /ws → wukongim:5200 (IM WebSocket长连接)
├─ /admin/ → admin:80 (管理后台)
├─ /docs-collab → docs-backend:1234 (文档协同Hocuspocus WS, 86400s超时)
├─ /docs-html/ → docs-html:8080 (HTML文档服务)
├─ /{bucket}/{key}?X-Amz-* → minio:9000 (presigned URL直传,保SigV4签名)
└─ / → web:80 (厚路由层)
↓
web(thick层nginx :80) ← 所有应用层API路由 + SPA fallback
├─ /api/*, /v1/* → octo-server:8090 (核心REST API)
├─ /summary/api/v1/agent/chat/stream → summary-api:8080 (SSE,proxy_buffering off)
├─ /summary/api/v1/* → summary-api:8080 (摘要API)
├─ /market/api/* → marketplace:8092 (市场API)
├─ /fleet/api/daemon/ws → fleet:8080 (Daemon WebSocket)
├─ /fleet/api/v1/* → fleet:8080 (Fleet REST API)
├─ /fleet/ws → fleet:8080 (Fleet WebSocket)
├─ /fleet/uploads/* → fleet:8080 (Fleet文件上传)
├─ /fleet/auth/* → fleet:8080 (Fleet认证)
├─ /v1/drive/* → drive:8080 (网盘API,用户侧)
├─ /api/v1/docs/*, /docs-api/* → docs-backend:3000 (文档API)
├─ /api/v1/bot/docs/* → docs-backend:3000 (文档Bot侧路径,实际开放待确认)
├─ /speech-admin/ → speech-admin:8781 (语音管理台)
├─ /speech-admin-api/* → speech-admin:8781 (语音管理台API)
└─ / → web本地SPA (React, try_files→index.html)
硬口径：开源版 Bot API 中不存在 /v1/bot/drive/ 路由（全仓 0 命中）。Bot 如需上传/下载文件，只能通过 IM 消息附件通道（chat/前缀 bucket + 预签名 URL）。独立 Drive 网盘模块是高级服务能力，提供用户侧 /v1/drive/* 接口，不对 Bot 暴露。
3. 服务端核心结构
3.1 启动入口（开源事实）
- 单二进制：
main.go 编译为 octo-server，通过 --config ./configs/tsdd.yaml 加载 YAML 配置。
- 依赖注入：使用
octo-lib/module 框架，所有业务模块通过 Go blank import 触发 init() 自注册。
- HTTP 引擎：Gin。全局中间件链（accesslog、auth、ratelimit、metrics、CORS、reqid），再注册各模块路由。
- gRPC 服务：在 6979 端口暴露，用于接收 WuKongIM webhook 回调（消息上行事件），支持 HMAC-SHA256 签名校验。
- 无服务注册发现：没有 Consul/etcd/Nacos；旁路服务地址通过 env 写死，靠 docker-compose/K8s 内置 DNS 解析容器名。
3.2 全局中间件要点
- 令牌桶限流：全局 per-IP 令牌桶。
/v1/ping、/v1/health、/v1/bot/heartbeat、/v1/bot/register 为豁免路径；后两者有各自 per-bot strict 桶兜底。
- Bot 自愈通道设计：heartbeat + register 必须成对豁免，由
main_test.go:TestExcludedBotPathsEachHaveTheirOwnFloor 结构性钉住不变量。
3.3 internal/ 与 modules/ 的边界
| 目录 |
职责 |
是否对外暴露 HTTP 路由 |
modules/ |
业务模块，每个模块是一个自包含单元（API + service + repository + SQL migration） |
是，注册 REST/WebSocket 路由 |
internal/ |
内核装配，在服务启动期被 main.go 调用 |
否（卡片分发、token 生命周期、项目开通、Agent编排等） |
pkg/ |
跨模块共享库（认证、DB、卡片协议、限流、签名、i18n、botevent等） |
否（被 modules/ 引用） |
4. 服务间通信总表（v2.0补全）
- octo-server 是单体，40+ 模块纯 Go 进程内直接调用（代码搜索
eventbus=0 命中）
- 旁路微服务通过 HTTP 调用，地址 env 写死，无注册中心
- WuKongIM 双向协议不同（下行 HTTP、上行 gRPC webhook、客户端直连）
- Kafka 仅供搜索ETL管道（消息/文档/网盘三管道），不做服务间通信
- Redis 承担缓存+限流+bot_task调度队列+幂等+Fleet DB 1
- Summary通过MySQL直读（IM主库只读账号）获取消息，不经过搜索
- 内部服务间回调使用HMAC-SHA256鉴权（共享NOTIFY_INTERNAL_TOKEN）
| 组件A ↔ 组件B |
协议 |
端口 |
用途 |
确认状态 |
| server 内部模块 ↔ 模块 |
Go 直接调用 |
— |
进程内业务 |
✅ |
| server → WuKongIM |
HTTP API |
:5001(容器内)/:25001(宿主) |
下发消息、建频道、管理 |
✅ |
| WuKongIM → server |
gRPC webhook |
:6979 |
消息上行事件回调（HMAC-SHA256签名） |
✅ |
| 客户端 ↔ WuKongIM |
TCP/WS 直连 |
TCP:25100/WS:25200 |
实时长连接（经nginx /ws反代，不经server） |
✅ |
| server → summary-api |
HTTP |
:8080(容器内) |
触发摘要、查询结果 |
✅ |
| summary-worker → MySQL(octo) |
MySQL协议(只读) |
:3306 |
直读IM消息(summary_reader) |
✅ |
| summary-worker → summary-api |
HTTP(HMAC) |
:8081(内部) |
任务完成回调(/internal/task-event) |
✅ |
| summary-api → LLM API |
HTTP |
外部 |
调大模型生成摘要(默认claude-sonnet-4-6) |
✅ |
| server → speech |
HTTP |
:8780 |
语音转写代理(SPEECH_SERVICE_URL) |
✅ |
| server → matter |
HTTP |
:28086 |
matter任务能力（开源版旁路） |
✅ |
| docs-backend → server |
HTTP(内部) |
:8090 |
认证委托(OCTO_IDENTITY_MODE=http) + bot-mentions |
✅ |
| docs-backend ↔ Hocuspocus |
WebSocket(内置) |
:1234 |
Yjs CRDT协同(/docs-collab) |
✅ |
| drive → server |
HTTP(Internal Token) |
:8090 |
认证/集成(DRIVE_OCTO_SERVER_INTERNAL_TOKEN) |
✅ |
| fleet → server |
HTTP |
:8090 |
集成(OCTO_APP_SERVER_URL) |
✅ |
| daemon → fleet |
WebSocket(HMAC) |
:8080 |
Daemon长连接(/fleet/api/daemon/ws) |
⚠️端点职责待确认 |
| marketplace → server |
HTTP(委托认证) |
:8090 |
AUTH_ENABLED + OCTO_API_URL |
✅ |
| server ↔ Redis |
Redis协议 |
:6379 |
缓存/会话/限流/bot_task队列(DB0)/Fleet(DB1) |
✅ |
| server ↔ MySQL |
MySQL协议 |
:3306 |
主数据(octo库) |
✅ |
| summary ↔ MySQL(summary) |
MySQL协议 |
:3306 |
摘要任务/结果(octo_summary库) |
✅ |
| speech ↔ MySQL(speech) |
MySQL协议 |
:3306 |
转写记录(octo_speech库,可选) |
✅ |
| docs ↔ MySQL(docs) |
MySQL协议 |
:3306 |
文档元数据(octo_docs库) |
✅ |
| drive ↔ MySQL(drive) |
MySQL协议 |
:3306 |
网盘元数据(octo_drive库)；有octo_docs读权限 |
✅ |
| marketplace ↔ MySQL(marketplace) |
MySQL协议 |
:3306 |
市场元数据(octo_marketplace库) |
✅ |
| fleet ↔ PostgreSQL |
PG协议 |
:5432 |
Fleet数据(唯一使用PG的模块) |
✅ |
| 各服务 ↔ MinIO |
S3协议 |
:9000 |
对象存储（各模块独立bucket） |
✅ |
| 搜索三层管道 |
|
|
|
|
| server(内置searchetl) → Kafka |
Kafka协议 |
:9092 |
消息变更事件(topic: octo.message.v1) |
✅ |
| docs-backend → Kafka |
Kafka协议 |
:9092 |
文档变更事件(topic: octo.docindex.v1) |
✅(配置存在) |
| drive → Kafka |
Kafka协议 |
:9092 |
网盘文件变更(topic: octo.driveindex.v1) |
✅(配置存在) |
| es-indexer ← Kafka → OpenSearch |
Kafka+HTTP |
:9092/:9200 |
消息索引(octo-message) |
✅ |
| doc-indexer ← Kafka → OpenSearch |
Kafka+HTTP |
:9092/:9200 |
文档索引(octo-doc) |
✅ |
| drive-indexer ← Kafka → Tika → OpenSearch |
Kafka+HTTP |
:9092/:9998/:9200 |
网盘索引(octo-drive，Tika提取文本) |
✅ |
| server → OpenSearch |
HTTP |
:9200 |
搜索查询（直查read alias） |
✅ |
| 服务注册发现 |
无 |
— |
靠env/配置 + compose/K8s内置DNS |
✅ |
5. 请求处理 5 步链路（README原文，开源核心）
客户端 / Bot / Adapter
│
▼
① Authenticate 认证 — token/cookie/DH加密WebSocket帧
│
▼
② Authorise 授权 — Space成员角色+频道ACL + Agent身份闸门
│
▼
③ Execute 执行 — 业务逻辑；必要时spawn/续接Agent会话；
│ 触发搜索producer(TS_KAFKA_ON)；语音转写代理
│
▼
④ Fan out 扩散 — WuKongIM下发IM消息；触发adapter；
│ docs评论@mention→bot_task；drive事件
│
▼
⑤ Respond 响应 — 统一JSON信封/WS帧+tracing/metrics
6. 核心链路详图
6.1 IM消息流全链路（用户A @Bot → Bot回复 → 用户B收到）
客户端A ──WS:25200/TCP:25100──► WuKongIM ──gRPC webhook:6979──► octo-server
│ │ │
│ ① 长连接直连发消息 │ ② 持久化+HMAC签名回调 │ ③ 业务处理(存MySQL/会话/@判定/限流)
│ │ │
│ │ ▼
│ │ ④ bot_task 模块
│ │ │
│ │ ▼ Redis DB0队列（幂等+限流，key=bot_id+msg_id去重）
│ │ │
│ │◄─── HTTP API :25001 ──── ⑥ Bot回消息 ── ⑤ 长轮询 /v1/bot/events (cursor+ACK, at-least-once)
│ │ │
│ │ Bot (openclaw-channel-octo插件)
▼ ▼
客户端B ◄── 长连接推送 ── WuKongIM ⑦ 推送
6.2 Loop/Fleet/Daemon关系图（v2.0新增）
┌─────────────────────────────────────────────────────────────────────┐
│ 用户视角（Web端） │
│ │
│ Web左侧「回路」入口(dmloop.enabled门控) │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ Issue工作流 │ │ 专家/专家团 │ │ 「我的→运行时」(Runtimes) │ │
│ │ (派发/验收) │ │ (AI协作体) │ │ 设备列表/添加电脑 │ │
│ └──────┬──────┘ └──────┬───────┘ └────────────┬─────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Loop 工作流语义层 │ │
│ │ 用户发任务→助理整理Issue→派专家→执行→验收→归档/退回 │ │
│ └──────────────────────────┬───────────────────────────────────┘ │
└─────────────────────────────┼───────────────────────────────────────┘
│ (经nginx /fleet/api/* 路由)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Fleet 服务层（octo-fleet :8080） │
│ PG 16 + Redis DB 1 + JWT + HMAC │
│ │
│ ┌──────────────┐ ┌───────────────┐ ┌────────────────────┐ │
│ │ Daemon注册 │ │ Bot编排/置备 │ │ 运行时清单 │ │
│ │ /心跳管理 │ │ (managed_bots) │ │ (哪个daemon跑哪些 │ │
│ │ /fleet/api/ │ │ │ │ Agent) │ │
│ │ daemon/ws │ │ │ │ │ │
│ └──────┬───────┘ └───────┬───────┘ └─────────┬──────────┘ │
│ │ │ │ │
│ │ ┌─────────────┴────────────────────┘ │
│ │ │ │ │
│ │ │ OCTO_APP_SERVER_URL (与server集成) │
│ │ ▼ │
│ │ octo-server :8090 ← matter协同任务分发 │
│ │ │
└─────────┼───────────────────────────────────────────────────────────┘
│ WebSocket长连接（space-scoped API key / HMAC认证）
│ /fleet/api/daemon/ws
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 用户本地电脑（octo-daemon, npm包） │
│ ~/.octo-daemon/config.json │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 自动检测本地AI Agent CLI: │ │
│ │ Claude Code / Codex / OpenClaw / Hermes │ │
│ │ │ │
│ │ 功能： │ │
│ │ · 上报本地Agent运行时状态 → Web「Runtimes」可见 │ │
│ │ · 作为专家运行时环境，执行回路任务 │ │
│ │ · 支持一键远程升级插件 │ │
│ │ │ │
│ │ ⚠️ 本地能力边界（Shell/文件访问/命令执行）—— │ │
│ │ 取决于daemon配置，待源码验证(FL-05)，不猜测 │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ 安装：私聊BotFather → /daemon → 获取server URL+space-scoped │
│ API key → npm i -g octo-daemon → 配置写入config.json │
└─────────────────────────────────────────────────────────────────────┘
- Loop = 面向用户的项目管理+AI协作工作流层（类似Linear/Jira）
- Fleet = 底层Bot编排+Daemon运行时管理服务（从octo-server拆出的独立Go服务）
- octo-daemon = 用户本地电脑上的运行时载体（npm包），通过WS长连接连到Fleet
- 三层不是独立产品，而是同一能力体系的不同层次：用户在Loop里派任务，Fleet负责调度到具体daemon执行
6.3 搜索三层管道详图（Producer→Kafka→Indexer→OpenSearch）（v2.0新增）
┌─────────────────────────── 数据写入侧（Producers）─────────────────────────────┐
│ │
│ 新消息到达 WuKongIM → gRPC webhook → octo-server │
│ │ │
│ ├─[TS_KAFKA_ON=true]─► octo-server内置searchetl模块 │
│ │ │ │
│ │ │ MySQL分片表维护ETL游标(octo_etl_es_cursor) │
│ │ ▼ │
│ │ Kafka topic: octo.message.v1 (+ .dlq) │
│ │ │
│ 文档变更（创建/编辑/评论）→ docs-backend :3000 │
│ │ │
│ ├─[SEARCH_INDEX_ENABLED/SEARCH_ENABLED]─► │
│ │ │ │
│ │ ▼ │
│ │ Kafka topic: octo.docindex.v1 (+ .retry + .dlq) │
│ │ │
│ 网盘文件变更（上传/更新/删除）→ octo-drive :8080 │
│ │ │
│ ├─[DRIVE_KAFKA_DISABLED=false]─► │
│ │ │ │
│ │ ▼ │
│ │ Kafka topic: octo.driveindex.v1 (+ .retry.v1 + .dlq.v1) │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ search-kafka :9092 (KRaft) │ │
│ │ KAFKA_AUTO_CREATE_TOPICS_ENABLE=false │ │
│ │ Topics由各kafka-init job预创建 │ │
│ └──────────────────────────────┬─────────────────────────────────────┘ │
└─────────────────────────────────┼──────────────────────────────────────────────┘
│
┌─────────────────────────────────┼──────────────────────────────────────────────┐
│ 索引消费侧（Indexers） │
│ ▼ │
│ octo.message.v1 ──► es-indexer (BATCH_SIZE=500) │
│ │ │ │
│ │ └──► DLQ → search-dlq-spill (crash-resumable) │
│ │ │ │
│ ▼ ▼ │
│ octo.docindex.v1 ──► doc-indexer :3100 (v1.1.0) │
│ │ │ │
│ │ └──► retry(3次?) → dlq │
│ │ │ │
│ ▼ ▼ │
│ octo.driveindex.v1 ─► drive-indexer :3200 (v0.1.0) │
│ │ │ │
│ │ ├──► tika :9998 (Apache Tika 文本提取) │
│ │ │ (PDF/Word/Excel/PPT等→纯文本) │
│ │ └──► retry → dlq │
│ │ │ │
│ │ SSRF防护: ALLOWED_DOWNLOAD_HOSTS, SSRF_ALLOW_LOOPBACK=false │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ OpenSearch :9200 (IK中文分词定制版) │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ octo-message │ │ octo-doc │ │ octo-drive │ │ │
│ │ │ alias: │ │ alias: │ │ (alias待确认)│ │ │
│ │ │ wukongim- │ │ octo-doc-read│ │ │ │ │
│ │ │ messages-read│ │ │ │ │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │
│ │ │ │ │ │ │
│ │ ik_max_word索引分词 │ │
│ │ ik_smart查询分词 │ │
│ │ DISABLE_SECURITY_PLUGIN=true(本地简化; 生产需启用🔴) │ │
│ └─────────────────────────┬──────────────────────────────────────────┘ │
└────────────────────────────┼───────────────────────────────────────────────────┘
│
┌────────────────────────────┼───────────────────────────────────────────────────┐
│ 查询侧（Query） │
│ ▼ │
│ octo-server :8090 (统一查询入口) │
│ 直查OpenSearch read alias │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ 权限控制： │ │
│ │ · 消息搜索尊重权限（解散authz校验） │ │
│ │ · 撤回/删除/用户级删除 → MySQL post-filter兜底(fail-closed) │ │
│ │ · Space维度隔离 │ │
│ │ · Bot搜索: POST /v1/botfather/messages/search (OBO模式,权限=主人) │ │
│ │ │ │
│ │ 技术特征： │ │
│ │ · routing=channelId（分片局部性） │ │
│ │ · Highlight 标签, fragment_size=120 │ │
│ │ · search_after+HMAC防篡改cursor翻页, pageSize=20, max=100 │ │
│ │ · 5 QPS/用户限流 │ │
│ │ · sender JOIN user表(LRU cache, 不存OS) │ │
│ └────────┬───────────────────────────────────────────────────────────┘ │
└──────────┼─────────────────────────────────────────────────────────────────────┘
│
▼
Web / iOS / Android
search-cursor-seed（search-tools profile）：将ETL游标种子到MAX(id)，防止producer启动回放全历史search-backfill：一次性历史回填（MySQL→OS直写，绕过Kafka），带reconcile校验search-producer-guard：双向互斥检查，防止内置producer和独立producer双写Kafka- 各kafka-init/ensure job：预创建topics + indexes + read aliases
6.4 文档评论@Mention→Bot链路图（v2.0新增）
用户在文档评论区 @Bot
│
│ 评论事件（docs-backend :3000 / :1234 Hocuspocus协同）
▼
docs-backend :3000
│
│ 内部HTTP调用（OCTO_IDENTITY_MODE=http委托认证）
│ POST /v1/internal/bot-mentions（事件类型: docCommentMentionEventType）
│ 需内部鉴权
▼
octo-server :8090
│
│ 校验权限 + 幂等claim
▼
bot_task 模块
│
▼
Redis DB0 队列（key=bot_id+msg_id 幂等去重）
│
│ BRPOP 长轮询（cursor+ACK, at-least-once投递）
▼
Bot（openclaw-channel-octo 插件）
│
│ 识别 docCommentMentionEventType 事件
│ 隔离会话派发
│
│ 1. 解析文档上下文（文档ID/评论内容/@位置）
│ 2. AI推理生成内容/回复
│ 3. 用 octo-cli（bot自身token）调用文档操作
│ · 编辑文档正文（插入AI生成内容）
│ · 回复评论串
│
│ ⚠️ Bot Token 不能直接调 /api/v1/docs（需登录态）
│ ⚠️ 仅支持 BotFather 创建的 User Bot（不支持 app_bot）
│ ⚠️ Bot必须先被加为文档成员且有权限
│ ⚠️ 灰度门控 gate.Allows(DocID, SpaceID)，MVP阶段
│ ⚠️ PPT评论@Bot同链路（插件v1.5.0+）
▼
docs-backend :3000
│
│ Hocuspocus WS :1234（Yjs CRDT协同同步）
▼
其他在线用户实时看到文档更新 + 评论回复
6.5 Summary MySQL直读+HMAC回调链路图（v2.0新增）
┌─ 触发方式 ─────────────────────────────────────────────────────────┐
│ │
│ ①手动: Web左侧「智能总结」/ ✨一键总结(30条) / iOS-Android底部 │
│ ②定时: summary-worker日/周/月周期（Web v2026.06.13） │
│ ③Agent驱动: PR#850, Agent可触发/引用总结结果 │
└──────────────────────┬─────────────────────────────────────────────┘
│
┌────────────┴────────────┐
│ │
▼ ▼
前端(SUMMARY_API_URL) Worker定时触发
/summary/api/v1/* (cron日/周/月)
│ │
│ 经nginx厚路由 │ WORKER_TRIGGER_URL
▼ ▼
┌─────────────────────────────────────────────────────┐
│ summary-api :8080 (外部API) │
│ │
│ · 接收前端总结请求 │
│ · SSE流式返回(/agent/chat/stream, │
│ proxy_buffering off, 3600s超时) │
│ · 总结CRUD │
│ · 通过WORKER_TRIGGER_URL触发异步任务 │
│ │
│ LLM调用: LLM_API_URL/KEY/MODEL │
│ (默认claude-sonnet-4-6, 可配置) │
│ map-reduce+意图识别处理长会话(v2026.07.06+) │
└───────────┬───────────────────────────┬──────────────┘
│ │
│ 触发worker │ 完成回调(HMAC)
│ POST /internal/ │ POST /internal/task-event
│ worker-trigger │ WORKER_API_CALLBACK_URL
│ (NOTIFY_INTERNAL_TOKEN) │ :8081(内部端口)
▼ │
┌─────────────────────────────────┐ │
│ summary-worker :8082 │ │
│ │ │
│ · 跑定时总结任务(日/周/月) │ │
│ · 异步处理长会话map-reduce │ │
│ · LLM_API_KEY可占位启动 │ │
│ │ │
│ ═══ 关键: 直读IM MySQL ═══ │ │
│ MESSAGE_FETCH_BACKEND=mysql │ │
│ IM_MYSQL_DSN = │ │
│ summary_reader@tcp(mysql)/octo│ │
│ (只读账号! 不依赖搜索服务) │ │
│ │ │
│ MYSQL_DSN = │ │
│ summary@tcp(mysql)/octo_sum- │ │
│ mary (读写摘要任务/结果) │ │
└─────────────────────────────────┘ │
▲ │
│ 结果回传 │
└───────────────────────────┘
│
▼
SSE推送/返回前端
(iOS群聊总结生成后自动发群提醒 v1.0.5+)
- Summary 不依赖搜索服务（MESSAGE_FETCH_BACKEND=mysql，直接读IM主库），可独立于search profile部署
- summary_reader是IM主库的只读账号，精确权限范围待确认(SM-06)
- API↔Worker之间通过NOTIFY_INTERNAL_TOKEN做HMAC-SHA256鉴权
- SSE流式端点（
/agent/chat/stream）用于总结结果流式返回，不是AI对话代理
- Worker可在LLM_API_KEY占位时启动（方便开发/测试）
6.6 文件上传/下载链路（Presigned URL直传）
客户端 octo-server MinIO/S3
│ │ │
│ 1.请求上传(文件名/类型/大小) │ │
├───────────────────────────►│ │
│ │ 2.生成Presigned URL │
│◄───────────────────────────┤ (含X-Amz-Signature) │
│ │ │
│ 3.PUT直传文件(不经server) │ │
├───────────────────────────────────────────────────►│
│ │ │
│ 4.上传完成回调确认 │ │
├───────────────────────────►│ │
│ │ │
│ 5.下载: GET presigned URL │ │
├───────────────────────────►│ │
│◄───────────────────────────┤ │
│ 6.GET直连MinIO下载 │ │
├───────────────────────────────────────────────────►│
6.7 语音ASR链路
用户录音/发送语音消息
│
│ 语音输入: 长按左Shift(Web)/按住说话(移动端)
│ 语音消息: type=4, 含url+duration
▼
octo-server :8090
│ POST /api/v1/voice/transcribe
│ SPEECH_API_KEY鉴权
▼
octo-speech :8780
│
├── 引擎选择(降级链):
│ 本地(localhost:8787) → 后端API → 模型列表fallback
│
├── 4种引擎:
│ · Gemini(默认): gemini-3.1-pro-preview/3-flash/2.5-pro
│ · GPT: gpt-4o-mini-transcribe (仅语音输入append_only)
│ · Qwen: qwen3.5-omni-plus
│ · 本地: localhost:8787
│
├── 处理:
│ · @mention识别
│ · 口语化书面语优化
│ · 情感emoji标注(VOICE_EMOTION_EMOJI=true默认开)
│
└── 限制: max 60s / 3MB / min 1s
│
▼
返回转写文字 → octo-server → wukongim → 客户端展示
│
└──► Bot自动收到转写文字(可直接处理)
Bot语音纠错API: /v1/bot/voice/context
7. 文件存储Bucket映射
| Bucket |
归属模块 |
内容 |
匿名下载 |
chat, file |
IM核心 |
消息图片/文件/视频/语音 |
✅（预设匿名策略） |
avatar |
IM核心 |
用户/群头像 |
✅ |
sticker |
IM核心 |
贴纸包 |
✅ |
moment, report, chatbg |
IM核心 |
动态/报表/聊天背景 |
✅ |
common, download, group |
IM核心 |
公共资源/下载/群共享 |
✅ |
octo-docs-attachments |
Docs |
文档附件 + docs/ HTML正文 |
❌（需签名） |
octo-drive |
Drive |
网盘文件 |
❌（需签名） |
marketplace |
Marketplace |
技能/插件/专家资源包/图标/截图 |
❌（OSS_DOWNLOAD_SIGNED=true） |
8. 数据库/Schema分布
| 数据库 |
服务 |
内容 |
权限 |
MySQL octo |
octo-server |
用户/消息/群组/Thread/Bot/bot_task/核心IM |
RW(server) / RO(summary_reader) |
MySQL octo_summary |
summary-api/worker |
摘要任务/结果 |
RW(summary) |
MySQL octo_speech |
speech |
转写记录/配置（可选） |
RW(speech) |
MySQL octo_docs |
docs-backend + docs-html |
文档/协作者/评论/版本/HTML元数据 |
RW(docs) |
MySQL octo_marketplace |
marketplace |
市场资源/元数据 |
RW(marketplace) |
MySQL octo_drive |
drive |
文件/目录/权限/共享空间 |
RW(drive)；SELECT on octo_docs.doc_meta/doc_member |
PostgreSQL fleet |
fleet |
Daemon/运行时/Bot编排/Loop数据 |
RW(fleet)；唯一使用PG的模块 |
| Redis DB 0 |
server + marketplace |
核心缓存/会话/bot_task队列/分布式锁/marketplace缓存 |
— |
| Redis DB 1 |
fleet |
Fleet专用 |
— |
9. 内部认证/鉴权机制汇总（v2.0补全）
| 认证场景 |
机制 |
密钥/Token |
| 客户端↔WuKongIM |
Token Auth |
wukongim tokenAuthOn（octo-server签发） |
| WuKongIM↔server |
gRPC Manager Token + HMAC-SHA256 |
WUKONGIM_MANAGER_TOKEN / X-Signature-256 |
| server内部回调 |
HMAC-SHA256 |
NOTIFY_INTERNAL_TOKEN / OCTO_NOTIFY_INTERNAL_TOKEN |
| Drive↔server |
Internal Token |
DRIVE_OCTO_SERVER_INTERNAL_TOKEN |
| Summary API↔Worker |
HMAC-SHA256 |
NOTIFY_INTERNAL_TOKEN（回调:8081/internal/task-event） |
| Fleet JWT |
JWT(≥32hex) |
FLEET_JWT_SECRET |
| Fleet Loop凭证 |
HMAC(≥32hex) |
FLEET_LOOP_CREDENTIAL_HMAC_KEY（daemon认证？待确认FL-03） |
| Daemon↔Fleet |
space-scoped API key + WS（HMAC?） |
BotFather /daemon下发API key；具体机制待确认 |
| Marketplace↔server |
委托认证 |
AUTH_ENABLED=true + OCTO_API_URL |
| Speech↔server |
API Key |
SPEECH_API_KEY（推断，无确证） |
| Speech Admin |
独立用户名密码+JWT |
ADMIN_USERNAME/PASSWORD/JWT_SECRET（loopback:28088 SSH隧道） |
| Bot→WuKongIM API |
Manager Token |
WUKONGIM_MANAGER_TOKEN |
| Bot→server |
Bearer bot_token (opaque) |
bf_前缀User Bot / app_前缀App Bot |
| MinIO应用用户 |
IAM(签名URL) |
octo-app用户（所有模块共用） |
| Docs协同 |
JWT(Hocuspocus) |
COLLAB_TOKEN_SECRET(≥32hex) |
| Kafka |
PLAINTEXT（内网） |
无认证（本地简化模式）🔴 |
| OpenSearch |
DISABLE_SECURITY=true |
无认证（本地简化模式）🔴生产需启用 |
| Fleet→私网Webhook |
SSL CA Bundle |
SSL_CERT_FILE（自签证书信任）🔴安全敏感 |
10. Profile依赖关系图（v2.0补全）
┌──────────┐
│ 默认启动 │
│(无profile)│
└─────┬────┘
│
┌──────────┬───────────┼───────────┬──────────┐
▼ ▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌─────────┐
│ 核心IM │ │market- │ │botfather │ │nginx │ │preflight│
│server/web│ │place │ │(一次性) │ │(两层) │ │minio-init│
│admin/mysql││(⚠️helm │ └──────────┘ └────────┘ └─────────┘
│redis/minio││disabled) │
│wukongim │ └──────────┘
└────┬─────┘
│
┌────┴──────────────────────────────────────────────────────┐
│ opt-in profiles │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ summary │ │ speech │ │ docs │ │ drive │ │
│ │(api+ │ │(speech+ │ │(backend │ │(+config │ │
│ │ worker) │ │ admin) │ │ +preflt)│ │+preflt │ │
│ └─────────┘ └─────────┘ └────┬────┘ │+migrate)│ │
│ │ └────┬────┘ │
│ ┌─────────┐ │ │ │
│ │ fleet │ ┌────▼────┐ │ │
│ │(+preflt │ │docs-html│ │ │
│ │+fleet-db│ │(依赖docs)│ │ │
│ │+postgres│ └─────────┘ │ │
│ │ 可选) │ │ │
│ └─────────┘ │ │
│ │ │ │
│ ┌────┴─────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ search (基础设施) │ │
│ │ kafka + opensearch + es-indexer │ │
│ │ +kafka-init + search-ensure + guard │ │
│ └────┬───────────────┬────────────────┘ │
│ │ │ │
│ ┌────▼────┐ ┌────▼─────┐ │
│ │doc-index│ │drive-index│ │
│ │(依赖docs │ │(依赖drive │ │
│ │ +search)│ │ +search) │ │
│ │+doc- │ │+tika │ │
│ │ indexer │ │+drive- │ │
│ │+init/ │ │ indexer │ │
│ │ ensure │ │+init/ │ │
│ └─────────┘ │ ensure │ │
│ └───────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │search-producer│ │ search-tools │ │
│ │(独立producer,│ │(cursor-seed │ │
│ │ K8s用,互斥) │ │ +backfill) │ │
│ └──────────────┘ └──────────────┘ │
└───────────────────────────────────────────────────────────┘
11. 与周边系统的边界
┌───────────────────────────────────────────────────────────────┐
│ OCTO 平台边界（含内部版全模块） │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ 旁路微服 │ │ octo-server │ │ octo-web/admin/ios/ │ │
│ │ summary │◄──┤ (核心锚点) ├──►│ android │ │
│ │ speech │ │ │ │ [Web独有:文档/网盘/ │ │
│ │ matter │ │ │ │ 回路/市场/我的/总结] │ │
│ │ docs- │ │ ┌────────┐ │ └──────────────────────┘ │
│ │ backend │ │ │WuKongIM│ │ ┌──────────────────────┐ │
│ │ docs-html│ │ │(外部IM)│◄├──►│ 客户端长连接(WS/TCP) │ │
│ │ drive │ │ └────────┘ │ └──────────────────────┘ │
│ │ fleet │ │ │ ┌──────────────────────┐ │
│ │ market- │ │ ┌────────┐ │ │ OpenClaw 运行时 │ │
│ │ place │┌──┤► │Adapter │◄├──►│ (Bot/Agent宿主) │ │
│ └──────────┘│ │ │(桥接) │ │ │ openclaw-channel- │ │
│ │ │ └────────┘ │ │ octo 插件 │ │
│ ┌──────────┐│ │ │ └──────────────────────┘ │
│ │搜索基础设││ │ │ ┌──────────────────────┐ │
│ │施Kafka+OS││ │ │ │ octo-daemon(用户本地) │ │
│ │+indexers ├──►│ │◄──►│ npm包,WS连Fleet, │ │
│ └──────────┘│ │ │ │ 执行回路任务 │ │
│ │ └──────────────┘ └──────────────────────┘ │
│ ┌──────────┐│ │
│ │Fleet专用 ││ │
│ │PostgreSQL││ │
│ └──────────┘│ │
└──────────────┼────────────────────────────────────────────────┘
│
┌─────────┴─────────┐
▼ ▼
企业SSO/LDAP 第三方IM/AI渠道
(OIDC模块) (octo-adapters)
底座：MySQL(多库) · Redis(DB0+DB1) · MinIO/S3(13 bucket) ·
可选(Kafka+OpenSearch搜索管道) · 可选(Fleet PostgreSQL)
- WuKongIM是外部独立进程：OCTO不内置IM引擎，WuKongIM是被驱动的底座（薄控制面），可替换。
- OpenClaw在平台外部：Agent（大脑）跑在OpenClaw运行时，通过`openclaw-channel-octo`插件经Bot API接入；但摘要(summary)直接调LLM，不依赖OpenClaw。
- octo-daemon在用户本地：不是服务端组件，是用户电脑上的本地运行时载体，通过WS连Fleet。
- 文档/网盘/回路/市场/语音/摘要/搜索均为可选旁路微服务：通过profile启用，最小生产7件套不含这些。
- Fleet独立使用PostgreSQL：是OCTO内部唯一使用PG而非MySQL的模块，选型原因待确认。
- 搜索Kafka只供ETL：不是通用消息总线，不承担服务间通信。
- Summary直读MySQL：不经过搜索管道，可独立部署。
12. 相关文档
- [01-product/OCTO是什么.md](../01-product/OCTO是什么.md) — 产品定义与核心能力
- [01-product/核心能力概览.md](../01-product/核心能力概览.md) — 10大能力域概览（v2.0）
- [02-architecture/OCTO全组件服务清单.md](OCTO全组件服务清单.md) — 全组件硬事实（端口/镜像/环境变量/路由）
- [02-architecture/OpenClaw-Agent-Bot-OCTO关系说明.md](OpenClaw-Agent-Bot-OCTO关系说明.md) — 四者关系专门文档
- [02-architecture/安全权限与鉴权-v0.1.md](../99-archive/2026-09-22-v0x清零/安全权限与鉴权-v0.1.md) — 安全鉴权
- [01-product/模块说明/](01-product/模块说明/) — 8个内部版模块详细文档
- [01-product/模块说明/模块间联动关系总览.md](../01-product/模块说明/模块间联动关系总览.md) — 模块联动14条链路图
- [03-deployment-ops/OCTO部署形态总览.md](../03-deployment-ops/OCTO部署形态总览.md) — 部署形态
待源码验证项（v2.0更新）
| 编号 |
待确认项 |
优先级 |
安全敏感 |
| AR-01 |
Fleet Bot→daemon完整调度链路：Bot如何通过Fleet调度daemon本地执行任务，链路是否成立 |
P0 |
否 |
| AR-02 |
Daemon本地能力边界(FL-05)：Shell/文件访问/命令执行权限模型🔴 |
P0 |
是 |
| AR-03 |
Fleet DM_OUTBOUND_WEBHOOK_ALLOW_PRIVATE_NETWORKS动机🔴：向谁发？为何允许私网？ |
P0 |
是(SSRF) |
| AR-04 |
搜索延迟数值/NRT profile：消息到可搜索的典型延迟(SR-01) |
P0 |
否 |
| AR-05 |
文档/网盘搜索权限模型(SR-05)：是否同消息搜索一样respect权限🔴 |
P1 |
是(越权) |
| AR-06 |
OpenSearch/Kafka安全配置：生产环境认证/TLS(SR-09)🔴 |
P1 |
是 |
| AR-07 |
Speech数据保留策略(S-05)：语音文件存多久/是否用于训练🔴 |
P0 |
是(隐私) |
| AR-08 |
Speech TTS能力：是否完全无TTS(S-01) |
P1 |
否 |
| AR-09 |
Docs /api/v1/bot/docs/ Bot API实际开放状态(DOC-03) |
P0 |
否 |
| AR-10 |
Drive /v1/bot/drive/ Bot API → 🔴已确认不存在，Bot无Drive API（通过IM附件通道传文件）。原D-05待确认项关闭。 |
P0 |
✅ 已确认不存在（全仓0命中，无此Bot API） |
| AR-11 |
summary_reader只读账号精确权限范围(SM-06)🔴 |
P1 |
是(数据访问) |
| AR-12 |
Marketplace上架权限边界/付费私有市场(M-03/M-04) |
P0 |
否 |
| AR-13 |
Marketplace在helm默认disabled vs compose默认启动(M-07) |
P2 |
否 |
| AR-14 |
octo-server内部Agent调度实现路径：internal/agent/具体路径 |
P2 |
否 |
| AR-15 |
Fleet为何使用PostgreSQL(FL-08) |
P2 |
否 |
| ~~AR-16~~ |
~~组织(org)模块边界~~：Q10已确认=无此模块，租户=Space(modules/space/) |
~~P2~~ |
是（已关闭） |
| AR-17 |
生产HA部署推荐：副本数/MySQL Redis WuKongIM集群/监控方案 |
P2 |
否 |
| AR-18 |
全局跨模块搜索是否存在统一入口(SR-02/L-01) |
P1 |
否 |
| AR-19 |
Tika格式清单/OCR支持(SR-03) |
P1 |
否 |
| AR-20 |
Drive-Index SSRF防护ALLOWED_DOWNLOAD_HOSTS精确范围(SR-10)🔴 |
P1 |
是(SSRF) |
版本记录
| 版本 |
日期 |
主要变更 |
| v1.0 |
2026-09-19 |
初版：基于octo-server开源源码描述核心IM架构（单锚点、5步链路、7件套） |
| v1.1 |
2026-09-20 |
补充两层Nginx路由、Presigned URL直传、基础存储/Bucket映射 |
| v2.0 |
2026-09-21 |
P0扩展阶段二完成：补全内部版8模块架构（Loop/Fleet/daemon层、搜索三层Kafka→Indexer→OpenSearch管道、文档Bot @Mention链路、Summary MySQL直读+HMAC回调、Marketplace委托认证集成、Speech ASR多引擎链路）；通信总表从12行扩至34行含所有内部模块端口/协议/鉴权；新增完整ASCII架构图（含内部版模块）、Profile依赖关系图、平台边界图；待源码验证项从7条扩至20条（标安全敏感）；frontmatter confidence升级medium-high |
来源标注
- octo-server/README.zh.md：单锚点架构、龙虾一等公民、可替换存储与IM、请求5步、模块分层表
- octo-server/main.go + internal/modules.go：启动入口、Gin引擎、中间件、模块注册
- octo-server/modules/ 目录：业务模块清单
- source-repos-internal/octo-deployment/docker/docker-compose.yaml：内部版全组件部署配置（镜像/端口/环境变量/依赖）
- source-repos-internal/octo-deployment/docker/nginx/conf.d/：两层nginx路由配置（octo.conf.template + web/default.conf.template）
- source-repos-internal/octo-deployment/helm/octo/values.yaml：Helm部署配置（profile开关对照）
- source-repos-internal/octo-deployment/docker/scripts/init-extra-dbs.sh：数据库/用户初始化
- 02-architecture/OCTO全组件服务清单.md v0.1：全组件硬事实
- 01-product/模块说明/ 各模块v0.3文档（docs/drive/fleet-loop/marketplace/speech/summary/search/我的）：模块级链路和产品管家确认的功能事实
- 01-product/模块说明/模块间联动关系总览.md v0.1：14条数据流/链路图
- 产品管家各批次回答（2026-09-19至2026-09-21）：Q1-Q6 P0核心问题 + P0扩展阶段二8个模块问题
- octo-server/modules/messages_search/ + docs/messages-search/：开源搜索模块源码和开发文档