- 内部部署仓库 docker-compose.yaml / Helm values.yaml / nginx 路由配置 / init-extra-dbs.sh（2026-09-21 解析）
- OCTO知识库建设组父群 / 2026-09-21 12:21 GMT+8 / Octo产品管家回答（message_id: 2101889478749491200）
- 00-inbox/product-bot-answers/2026-09-21-P0扩展-文档模块回答.md
- 02-architecture/OCTO全组件服务清单.md（第七节 octo-docs-backend / 第八节 docs-html）
- 00-inbox/product-bot-answers/2026-09-22-P1-round1-Q4-Docs文档协同深度回答.md（源码确认级：octo-deployment/kustomize/docs + octo-auth/hocuspocus + octo-cli/skills/octo-docs + octo-server/bot_mention + octo-cli/cmd/docs_excalidraw_export）
文档协同Docs模块说明 v0.3
文档协同（Docs）是 OCTO 内部版独有的实时多人协同模块，后端为 octo-docs-backend（Node.js，统一协同服务）+ octo-docs-html（Go，HTML文档后端），通过 Web 左侧导航「文档」独立空间访问。包含 5种独立文档载体（富文本doc/表格sheet/白板board/PPT演示html_ppt/HTML文档html），各载体有独立实现而非"类Notion通用文档"；实时协同基于 Hocuspocus+Yjs CRDT（WebSocket `/docs-ws/`），支持评论分级、版本历史（非破坏性回滚）；Bot通过评论区@Mention独立事件链路（doc_comment_mention）操作文档并写回评论线程，个人空间文档同链路不依赖群。
一、模块定位（一句话口径）
文档协同 = Octo 内置实时多人协同模块，5种文档载体各有独立实现：`docs`/`docs-html` profile 开关门控（docs-html 依赖 docs）。协同后端 octo-docs-backend（Node.js）内置 Hocuspocus WebSocket 服务，基于 Yjs CRDT 实现实时冲突自动合并；5类载体（富文本doc/Tiptap、表格sheet、白板board/自建Excalidraw、PPT演示html_ppt/内建、HTML文档html/immutable独立服务docs-html）各有独立实现，不是"类Notion通用文档"。存储使用 MySQL `octo_docs` + Redis + MinIO `octo-docs-attachments`；鉴权通过 Hocuspocus onAuthenticate 短期JWT(HS256)+permission_epoch撤权+document_name绑定防重放。Bot 通过文档评论@Mention独立事件链路（`doc_comment_mention`，非群聊消息）写回评论线程，个人空间文档同链路。版本历史支持非破坏性回滚（先存安全快照可撤销）。Markdown/Word/PDF导入导出及格式保留、版本留存天数/策略位于私有仓 octo-docs-backend，待确认。
二、部署与基础设施硬事实
2.1 主服务 octo-docs-backend（docs profile）
| 项目 |
事实 |
来源 |
| 服务镜像 |
mininglamposs/octo-docs-backend:0.8.0（pin版，Node.js） |
docker-compose / Helm |
| 容器端口 |
3000（REST API）、1234（Hocuspocus 协作 WebSocket） |
docker-compose |
| Profile |
docs |
docker-compose profiles / Helm values |
| 数据库 |
MySQL octo_docs 库，用户 docs；Redis（prefix: octo-docs） |
docker-compose / init-extra-dbs.sh |
| 对象存储 |
MinIO bucket octo-docs-attachments（文档附件独立bucket，不与drive混用） |
docker-compose / minio-init |
| S3 附件驱动 |
ATTACHMENT_DRIVER=s3（环境变量配置） |
docker-compose env |
| 认证模式 |
OCTO_IDENTITY_MODE=http（委托 octo-server 认证） |
docker-compose env |
| 协同鉴权 |
Hocuspocus onAuthenticate：短期JWT(HS256)，secret取自COLLAB_TOKEN_SECRET（≥32hex）；permission_epoch支持即时撤权；document_name绑定防跨文档重放攻击 |
docker-compose env / octo-auth/hocuspocus 源码 / Q4 |
| 启动流程 |
docs-migrate-entrypoint.sh 先执行 schema.sql + migration 再启服务 |
docker-compose entrypoint |
| 搜索开关 |
SEARCH_INDEX_ENABLED / SEARCH_ENABLED（默认 false，对接doc-indexer时启用） |
docker-compose env |
| Kafka 对接 |
KAFKA_BROKERS + DOCINDEX_KAFKA_TOPIC（对接 doc-indexer 实现文档搜索） |
docker-compose env |
| 存储卷 |
无额外持久化卷（元数据存MySQL，附件存S3，协同状态存Redis） |
docker-compose |
| 依赖服务 |
docs-preflight / mysql / redis / minio-init |
docker-compose depends_on |
| nginx REST 路由 |
/api/v1/docs/→:3000；/docs-api/ rewrite→:3000/；/api/v1/bot/docs/ rewrite→:3000/v1/bot/docs/ |
nginx web default.conf.template / octo.conf.template |
| nginx WS 路由 |
/docs-ws/(WebSocket upgrade)→:1234（Hocuspocus协同通道，厚路由层；薄网关层路径/docs-collab经内部路由最终到达同一服务） |
nginx octo-shared.inc.template / Q4源码确认 |
| 同步协议 |
WebSocket（❌不是WebRTC） |
Q4源码确认 |
| 功能开关 |
docs_on / docs.enabled appconfig flag（Web端门控，未开启不显示「文档」入口） |
产品管家Q1.5 |
| 客户端 |
Web 端（左侧导航「文档」入口，应用内路由 /docs，独立分享页 /d/:docId）；iOS/Android 支持情况待确认 |
产品管家Q1.5 |
2.2 初始化/一次性服务（docs profile）
| 服务 |
功能 |
来源 |
| docs-preflight |
启动前检查 docs 必需密钥：DB 密码非空、COLLAB_TOKEN_SECRET ≥32hex、attachment secret ≥32hex，防止弱口令上线 |
docker-compose / init脚本 |
| docs-migrate（内置entrypoint） |
docs-migrate-entrypoint.sh 执行 schema.sql + SQL migration 文件，完成数据库schema初始化/升级 |
docker-compose entrypoint |
注：`octo_docs` 数据库和 `docs` 用户由公共初始化脚本 `init-extra-dbs.sh` 创建（mysql 容器首启动时执行），不是 docs 独立preflight。
2.3 主服务 octo-docs-html（docs-html profile，依赖 docs）
| 项目 |
事实 |
来源 |
| 服务镜像 |
hub2.intra.mlamp.cn/octo/octo-docs-html:v0.4.0（pin版，内网registry；Go二进制） |
docker-compose / Helm |
| 容器端口 |
8080 |
docker-compose |
| Profile |
docs-html（需同时启用 docs profile） |
docker-compose profiles |
| 数据库 |
MySQL octo_docs 库（复用 docs 用户，非独立库） |
docker-compose env |
| 对象存储 |
MinIO bucket octo-docs-attachments，路径 docs/ 存HTML正文 |
docker-compose / minio-init |
| 登录鉴权 |
LOGIN_ENABLED=true（环境变量） |
docker-compose env |
| Bot鉴权 |
BOT_AUTH_ENABLED=true（开启Bot对HTML文档服务的鉴权访问，用于Bot创建HTML文档） |
docker-compose env / 产品管家Q3.3 |
| 上游注册 |
DOCS_BACKEND_REGISTER_URL（向 octo-docs-backend 注册自身为HTML文档后端） |
docker-compose env |
| 依赖 |
octo-server（OCTO_SERVER_BASE_URL） |
docker-compose env / depends_on |
| nginx 路由 |
/docs-html/ rewrite→:8080/（sub_filter 修正根路径静态资源链接） |
nginx web default.conf.template |
| 访问路径 |
独立分享页 /d/:docId、/v1/、/me 等（经 /docs-html/ 反代） |
产品管家Q1.4 |
| 存储卷 |
无额外持久化卷（正文存S3，元数据存MySQL） |
docker-compose |
| 功能定位 |
独立immutable HTML文档服务（非"发布只读页"、非嵌入HTML、非通用HTML编辑器），具备完整文档生命周期：immutable versions/drafts/assets/comments/元素编辑/发布/分享/权限 |
Q4源码确认 |
2.4 docs-html-migrate（一次性，docs-html profile）
| 服务 |
功能 |
来源 |
| docs-html-migrate |
执行 migrate 命令完成 docs-html 数据库 schema 迁移（复用 octo_docs 库） |
docker-compose |
2.5 doc-indexer 关联组件（doc-index profile 附加，依赖 docs + search）
⚠️ 以下为部署配置中存在的组件（硬事实），用于文档全文搜索索引；是否对用户开放、索引链路是否完整启用需源码/部署验证。部署配置存在 ≠ 功能一定可用。
| 服务 |
端口 |
功能（部署配置描述） |
来源 |
| doc-indexer |
3100（HTTP/readyz） |
Kafka消费者（topic由 DOCINDEX_KAFKA_TOPIC 指定），消费docs-backend写入的文档事件 → 写入 OpenSearch 文档索引，实现文档全文搜索 |
docker-compose / Helm（镜像 octo-doc-indexer:v1.1.0） |
三、已确认能力（产品管家代码验证）
3.1 实时协同内核 ✅确认（Q4源码级）
- 协同后端：octo-docs-backend（Node.js），内嵌 Hocuspocus WebSocket服务
- 同步协议：WebSocket（端口1234，nginx upgrade代理，路径
/docs-ws/），❌不是WebRTC
- 协同数据模型：Yjs CRDT（Conflict-free Replicated Data Type）
- 冲突合并策略：
- 富文本/表格/PPT等Yjs原生类型：Yjs CRDT自动合并，无需人工解决冲突
- 白板（Excalidraw）元素：Yjs CRDT基础上额外使用
version 字段做 CAS（Compare-And-Swap），高version胜出版本获胜
- 协同鉴权链（Hocuspocus
onAuthenticate）：
- 客户端连接时携带短期 JWT（HS256签名）
- 服务端校验JWT有效性 + `permission_epoch`（权限版本号，支持即时撤权——撤销权限后旧epoch立即失效）
- JWT绑定 `document_name`，防止跨文档重放攻击（A文档的token不能用于B文档）
- 存储层：Yjs文档状态持久化到 MySQL
octo_docs 库 + Redis缓存；附件存 MinIO octo-docs-attachments
- 富文本编辑内核：基于 Tiptap（Block-based 富文本框架），存储格式为Tiptap JSON（非纯Markdown）
3.2 文档表面类型（doc_type）——5种载体各有独立实现 ✅确认（Q4源码级）
🔴 P0纠偏：文档协同不是"类Notion通用文档"。5种载体各有独立实现，不是单一通用编辑器套不同皮肤。
| doc_type |
后端服务 |
载体性质 |
核心能力 |
确认级别 |
doc（富文本） |
docs-backend |
Tiptap Block-based 富文本文档 |
标题/段落/列表/表格/代码块/图片等富文本元素，Yjs CRDT实时协同 |
✅源码确认 |
sheet（表格） |
docs-backend |
独立表格载体 |
区域保护、行高拖拽、查找替换、行列增删；Yjs CRDT协同 |
✅源码确认 |
board（白板） |
docs-backend |
自建Excalidraw白板（自建于Y.Doc之上，❌非第三方托管白板服务） |
Excalidraw手绘风格图形；元素级version CAS冲突解决（高version胜） |
✅Q4源码确认 |
html_ppt（PPT演示） |
docs-backend |
内建PPT载体（❌未见PPTGenJS，非第三方PPT库） |
slides管理、评论、版本历史、HTML导出 |
✅Q4源码确认 |
html（HTML文档） |
docs-html（Go独立服务） |
独立immutable HTML文档（❌非嵌入HTML片段、❌非通用HTML编辑器） |
immutable versions（不可变版本）、drafts（草稿）、assets（资产）、comments（评论）、可检索、元素编辑、发布/分享/权限 |
✅Q4源码确认 |
3.3 版本历史与回滚 ✅确认（Q4源码级）
- 全5类doc_type均支持版本管理，统一API：
versions list：列出版本versions create：创建快照versions state：预览版本内容versions rename：重命名版本versions delete：删除版本versions restore：回滚到指定版本- versionId =
docVersionSeq（整型递增序列号）
- 快照类型：manual（手动快照）+ auto（自动快照）
- restore非破坏性回滚：执行restore前，系统自动保存当前状态为一个安全快照，因此回滚操作本身可撤销（"可再撤销"）
- ⚠️ 版本保留天数/留存策略：源码中未找到证据（位于私有仓octo-docs-backend，待确认）
3.4 评论与@Bot链路 ✅确认（Q4源码级）
reader：仅可查看commenter+：可发表评论writer+：可 resolve/reopen 评论线程
用户在文档评论区 @Bot
↓
docs-backend 存储评论
↓
docs-backend 调用 octo-server POST /v1/internal/bot-mentions
↓
octo-server 生成独立事件 doc_comment_mention
↓（非群聊消息、不走群消息通道）
↓（进 bot event 队列）
↓（携带字段：doc_id / comment_id / from_uid / bot_uid / url / space_id）
openclaw-channel-octo 插件接收事件，隔离会话派发
↓
Bot 执行（读取文档内容 + octo-cli 操作）
↓
Bot 回复经 docs comments add --parentId 写回原评论线程
- ✅ 事件类型为独立的
doc_comment_mention，不是群聊消息，不进群聊通道
- ✅ 事件携带完整上下文：doc_id、comment_id、from_uid、bot_uid、url、space_id
- ✅ Bot回复写回方式：octo-cli
docs comments add --parentId，挂在原评论下形成线程
- ✅ 个人空间文档同链路、不依赖群——文档评论@Bot不需要文档属于某个群
- ✅ PPT（html_ppt）评论@Bot同链路（插件v1.5.0+）
- ✅ 能编辑文档正文
- ✅ 能插入 AI 生成内容
- ✅ 能回复评论串（
docs comments add --parentId）
- ✅ PPT/HTML文档评论@Bot同链路
- ❌ Bot Token 不能直接调
/v1/bot/docs 类接口（octo-server bot_api 路由无此注册）
- ❌
/api/v1/docs 需登录态，Bot Token 调不了
- ⚠️ 仅支持 BotFather 创建的 User Bot（不支持 app_bot）
- ⚠️ Bot 必须先被加为该文档成员且有权限
- ⚠️ 有灰度门控
gate.Allows(DocID, SpaceID)，属 MVP 阶段
3.5 前端入口 ✅确认
- Web 左侧导航栏「文档」图标，独立空间
- 应用内路由
/docs
- 独立分享页
/d/:docId
- 受
docs_on / docs.enabled appconfig flag 门控，未开启不显示入口
- 不是群内嵌
- iOS/Android 移动端文档入口是否已实现（Drive明确仅Web，Docs客户端范围待确认）
3.6 权限模型
- 文档权限自治，不继承群/Space权限
- 协同鉴权：JWT(HS256)+permission_epoch即时撤权+document_name绑定防重放
- 评论权限分级：reader / commenter / writer
- 版本快照：writer+ 创建，admin 可恢复
- Bot操作文档需先被加为文档成员且拥有相应权限
- 完整的文档成员角色枚举（所有者/编辑/评论/查看的准确分级与权限矩阵）
- 文档分享链接的权限设置（是否支持组织外访问、密码保护、有效期）
- 文档空间（个人/团队）层级结构
3.7 导入导出 ⚠️私有仓部分确认
- ✅ 已确认导出：
- HTML文档（html类型）：HTML导出
- PPT（html_ppt类型）：HTML导出
- 白板（board类型）：Excalidraw场景导出
- 🔴 私有仓未可见（octo-docs-backend）：
- Markdown 导入/导出
- Word（docx）导入/导出
- PDF 导入/导出
- "导入保留格式"的具体实现与支持范围
- ⚠️ v0.2中提到的"docx和Markdown双向导入导出（PR #752）"来自P0产品管家回答，但Q4源码级确认时octo-docs-backend为私有仓不可验证，此项降为待确认，需私有仓源码验证
四、Bot/API 能力与模块联动
4.1 docs-html 的 Bot 能力
BOT_AUTH_ENABLED=true 开启 Bot 对 HTML 文档服务的鉴权访问- 典型场景：机器人创建 HTML 文档并转发到聊天（Bot 生成 HTML 报告类内容）
- Web v2026.07.27 起支持 Bot 创建 HTML 文档
- Web v2026.08.17 起用户/机器人均可直接创建 HTML 文档
4.2 事件推送
- 文档评论@Bot →
doc_comment_mention 独立事件 → bot event队列 → 插件派发
- 该事件不依赖群聊，个人空间文档同样触发
- 普通文档"创建/编辑"事件是否也 webhook 推给 Bot（非评论 mention 场景）——代码未见明确注册，待产品管家确认
4.3 nginx 路由中存在的 `/api/v1/bot/docs/`
⚠️ nginx 路由存在 `/api/v1/bot/docs/` rewrite→docs-backend `:3000/v1/bot/docs/`，但产品管家明确表示 octo-server bot_api 路由无此注册，Bot Token 直接调用目前不行。该路由可能是 docs-backend 预留接口或内部使用，不能凭路径存在就断言Bot API可用。
行动项：需查 docs-backend `/v1/bot/docs/` handler 源码 + octo-server bot_api 路由注册，确认实际开放状态。
五、私有仓边界声明
| 边界项 |
说明 |
| Markdown/Word/PDF导入导出 |
是否支持、支持范围、格式保留程度 |
| 版本保留天数/留存策略 |
versions是否有自动清理、保留天数配置 |
| 完整权限矩阵 |
所有者/编辑/评论/查看的精确权限边界 |
六、待确认项汇总（知识库行动项）
| 编号 |
待确认项 |
确认方式 |
优先级 |
| DOC-01 |
Markdown/Word(dockx)/PDF导入导出是否支持、格式保留程度 |
私有仓octo-docs-backend源码 / 产品管家 |
P0（影响售前口径和集成方案） |
| DOC-02 |
版本保留天数/留存策略配置（versions是否自动清理） |
私有仓octo-docs-backend源码 / 产品管家 |
P1 |
| DOC-03 |
非评论场景的文档创建/编辑事件是否webhook推Bot |
查 octo-server bot_mention/事件路由源码 |
P1 |
| DOC-04 |
/api/v1/bot/docs/ Bot API 实际是否开放、暴露哪些能力 |
查 docs-backend /v1/bot/docs/ handler + octo-server bot_api 路由注册 |
P0 |
| DOC-05 |
完整文档成员角色枚举与权限矩阵（所有者/编辑/评论/查看） |
私有仓 / 查 docs-backend 权限模块源码 |
P1 |
| DOC-06 |
文档分享链接能力（组织外访问/密码保护/有效期/下载权限） |
查 docs 分享模块源码 + Web前端 |
P2 |
| DOC-07 |
iOS/Android 移动端文档入口是否已实现 |
查移动端代码 + 产品管家确认 |
P1 |
| DOC-08 |
文档空间层级结构（个人空间/团队空间如何组织） |
查 docs-backend API + Web前端 |
P2 |
| DOC-09 |
doc-indexer（Kafka+OpenSearch文档搜索）与Web端文档搜索功能的对应关系；SEARCH_ENABLED默认false时用户是否能搜索文档 |
查部署配置 + docs-backend 搜索模块源码 |
P2 |
| DOC-10 |
文档附件是否支持引用 Drive 文件（还是只能走docs自己的octo-docs-attachments bucket） |
查 docs-backend 附件模块源码 |
P2 |
| DOC-11 |
光标同步具体表现（Yjs CRDT标配awareness但未单独验证） |
查 Hocuspocus awareness配置 + 前端协同组件 |
P3 |
七、与其他模块的关系
| 模块 |
关系 |
状态 |
| Drive（网盘） |
两个独立模块/空间，不是"文档是网盘里的一种文件"；支持云文档挂载到网盘目录（listMountedDocs API），文档本体仍归docs管；Drive有octo_docs.doc_meta/doc_member的SELECT读权限用于挂载列表 |
✅ 已确认 |
| 聊天/IM |
Bot通过评论区doc_comment_mention独立事件链路联动（不依赖群聊）；Bot创建HTML文档可转发到聊天；普通文档创建/编辑事件推送待确认（DOC-03） |
✅ 评论链路已确认（个人空间同链路）；⚠️ 事件推送待确认 |
| octo-server |
认证委托（OCTO_IDENTITY_MODE=http）；评论@Mention事件路由（POST /v1/internal/bot-mentions，事件类型doc_comment_mention）；Bot鉴权与事件派发 |
✅ Q4源码确认 |
| MinIO |
文档附件存储后端，octo-docs-attachments bucket（HTML正文存 docs/ 路径） |
✅ 部署事实 |
| MySQL |
元数据+Yjs文档持久化存储，octo_docs 库（docs-backend和docs-html共用） |
✅ 部署事实 |
| Redis |
Yjs协同状态/缓存，prefix octo-docs |
✅ 部署事实 |
| Hocuspocus |
Yjs CRDT 实时协同WebSocket服务（内置在docs-backend :1234，路径/docs-ws/）；onAuthenticate JWT+permission_epoch+document_name绑定鉴权 |
✅ Q4源码确认 |
| Yjs |
CRDT数据模型，自动冲突合并；白板Excalidraw元素额外version CAS |
✅ Q4源码确认 |
| doc-indexer |
文档全文搜索索引管道（Kafka→OpenSearch），doc-index profile 附加，默认 SEARCH_ENABLED=false |
⚠️ 部署配置存在，功能开放待确认（DOC-09） |
| OpenSearch |
文档搜索索引后端（doc-indexer写入） |
⚠️ 同 DOC-09 |
| Kafka |
文档事件→doc-indexer 消息队列 |
⚠️ 同 DOC-09 |
| openclaw-channel-octo 插件 |
接收doc_comment_mention事件，隔离会话派发Bot执行 |
✅ Q4源码确认 |
| octo-cli |
Bot通过 docs comments add --parentId 写回评论线程；skills/octo-docs提供文档操作技能 |
✅ Q4源码确认 |
八、版本记录
- v0.1（2026-09-21）：基于产品管家 Q1-Q3 回答初版草稿
- v0.2（2026-09-21）：合并 OCTO全组件服务清单.md 第七/八节部署硬事实；严格区分「部署配置存在」与「功能对用户开放」；补充5类文档表面能力表、Bot@Mention触发链路、docs-html定位、与Drive关系
- v0.3（2026-09-22）：Q4源码确认级回填——
- 🔴P0纠偏：明确5种载体各有独立实现，删除"类Notion通用文档"表述
- 白板=自建Excalidraw（非第三方托管），元素级version CAS冲突解决
- PPT=内建html_ppt（非PPTGenJS，支持slides/comments/versions/HTML导出）
- HTML=独立immutable文档（非嵌入HTML/通用HTML编辑器）
- 协同内核补充：Hocuspocus+Yjs CRDT完整鉴权链（JWT HS256+permission_epoch撤权+document_name绑定防重放）
- WS路径确认为
/docs-ws/（厚路由层），说明与 /docs-collab（薄网关层）的关系
- 同步协议确认为WebSocket（❌非WebRTC）
- 评论@Bot链路补充：独立事件
doc_comment_mention、携带字段明细、个人空间同链路不依赖群、Bot回复方式docs comments add --parentId
- 版本历史补充：全类型支持6个API（list/create/state/rename/delete/restore）、versionId=docVersionSeq整型、manual/auto快照、restore非破坏性（先存安全快照可撤销）
- 导入导出降级：Markdown/Word/PDF降为私有仓待确认，仅确认HTML(PPT/HTML)+Excalidraw导出
- 新增私有仓边界声明章节
- confidence升至high（核心机制源码确认级），status维持draft（导入导出/版本保留期待私有仓确认后升review）
- 待确认项表更新：DOC-01改为导入导出（P0），新增DOC-11光标同步