首页 产品 为什么选 OCTO 解决方案 文档 关于
文档中心 / 部署运维 / 部署形态总览
← 返回文档中心

部署形态总览

OCTO 文档中心 · 部署运维
  • source-repos/octo-deployment/README.zh.md（OOTB 部署仓库 single source of truth：组件/端口/依赖/形态）
  • source-repos/octo-deployment/docker/README.zh.md（Docker Compose 单机栈：setup.sh/网络/凭据/HTTPS/可选profile/硬ening/故障排查）
  • source-repos/octo-server/README.zh.md（单锚点架构、可替换存储、一键部署指向 octo-deployment）
  • source-repos-internal/octo-deployment/docker/docker-compose.yaml（内部版8个可选模块部署配置）
  • source-repos-internal/octo-deployment/helm/octo/values.yaml（Helm profile开关对照）
  • 00-inbox/product-bot-answers/2026-09-19-第一批核心问题回答.md（产品管家 Q3/Q4：支持私有化开源，但单机/PoC/生产/HA 推荐架构与硬件规格无一手文档，待确认）
  • 02-architecture/OCTO全组件服务清单.md（全组件端口/路由/镜像tag）
  • 03-deployment-ops/基础设施依赖映射.md（MySQL库/MinIO bucket/Kafka topic/OS索引/Volume/端口映射）

OCTO 部署形态总览 v1.1

文档定位

1. 官方部署形态分类

形态 入口 官方定位（README 原文） 适用场景
单机 Docker Compose docker/ + setup.sh "单机评估部署、内部 demo/staging、我就想试试 OCTO 的标准路径" 评估、demo、PoC、小规模内部试用
多节点 Kubernetes kustomize/base/ + overlays/dev,prod（另含 helm/） "多节点 / 生产部署请使用 kustomize/base/ 并自带 DB/缓存/对象存储" 多节点、生产环境

README 明确声明：多节点/生产部署需要自行准备 MySQL、Redis、WuKongIM、S3 对象存储（不随 K8s 栈一起拉起）。

关于"PoC / 高可用 / 离线"形态的口径

  • PoC：官方未给出独立"PoC 形态"定义。从 README 看，单机 Docker Compose 栈可承担"客户现场验证 / 我就想试试"的角色；正式客户 PoC 是否需要额外配置/资源待产品管家确认。
  • 高可用（HA）：K8s overlays/prod 提供多副本生产 overlay，但 HA 拓扑（MySQL 集群/Redis 哨兵/WuKongIM 集群/多可用区）官方未在本仓库给出参考方案；octo-deployment README「待补」列出 Ingress/Gateway 示例、DB 初始化、MinIO+WuKongIM 集群内样板均待补。
  • 离线 / 内网 / air-gapped：官方未给出离线镜像导入文档。源码事实：镜像默认从 docker.io/mininglamposs/* 拉取，搜索 profile 的 OpenSearch IK 插件在构建时从 release.infinilabs.com 下载；LLM 摘要/语音需外部 API key。离线部署具体步骤待产品管家确认。

2. 组件清单（OOTB 官方镜像）

服务 镜像 容器端口 是否默认启动 说明
octo-server mininglamposs/octo-server 8090(HTTP) / 6979(gRPC) ✅ 默认 核心后端（Go 单二进制）
octo-web mininglamposs/octo-web 80 ✅ 默认 Web/PC 客户端（Electron）
octo-admin mininglamposs/octo-admin 80 ✅ 默认 管理后台
octo-matter mininglamposs/octo-matter 8080 ✅ 默认 任务/Todo 微服务
octo-smart-summary-api mininglamposs/octo-smart-summary-api 8080/8081 ⚙️ opt-in（--summary） LLM 摘要 API
octo-smart-summary-worker mininglamposs/octo-smart-summary-worker 8082 ⚙️ opt-in（--summary） 摘要异步 worker
octo-marketplace （随 compose 默认启动） — ✅ 默认 技能/MCP/Bot 市场（技能 ZIP 上传 20 MiB）
nginx nginx:1.27-alpine 80→28080(host) ✅ 默认 前置反向代理（单端口入口）
WuKongIM wukongim/wukongim 多个（见端口表） ✅ 默认（Docker）/ 外部（K8s） IM 长连接底座（≥v2）
MySQL mysql:8 3306→23306(host) ✅ 默认（Docker）/ 外部自备（K8s） 三个库：octo / octo_matter / octo_summary（+ octo_marketplace / octo_docs 可选）
Redis redis:7-alpine 6379→26379(host) ✅ 默认（Docker）/ 外部自备（K8s） 缓存/会话/限流
MinIO / S3 兼容存储 无公开最低版本（OOTB 用 minio/minio） S3 API 29000 / console 29001 Docker 栈内置；生产可替换为腾讯云 COS/阿里云 OSS/AWS S3 等任意 S3 兼容存储（apiURL+app_user+app_password+downloadURL）；downloadURL 必须是客户端可达对外地址；bucket 命名按 S3 兼容规范即可
WuKongIM 无 server 版本对照表（v2 为主，建议锁部署包自带版本） API 25001/TCP 25100/WS 25200/monitor 25300/gRPC webhook 6979 Docker 栈内置 wukongim/wukongim；K8s 部署需自备；数据独立（有自己的 mysqlAddr/redisAddr，不复用 server 的 MySQL/Redis）；需配 TS_WUKONGIM_MANAGERTOKEN；v3 兼容性暂无公开信息，不擅自升级大版本
octo-speech / octo-speech-admin （语音引擎镜像） 28088(admin) ⚙️ opt-in（speech profile） 语音转写（默认 qwen 引擎，支持 gpt/gemini）
octo-docs-backend （协同文档镜像） 3000(REST) / 1234(WS) ⚙️ opt-in（docs profile） Hocuspocus+Yjs 实时协同文档
Kafka（KRaft 单 broker） （wurstmeister/confluent 类） 9092→29092(host) ⚙️ opt-in（search profile） 消息搜索流水线（RF=1 单节点）
OpenSearch（+IK 分词） octo-search-opensearch-ik（本地构建） 9200→29200(host) ⚙️ opt-in（search profile） 全文搜索（JVM 默认 -Xms512m -Xmx512m）
es-indexer mininglamposs/octo-search-indexer — ⚙️ opt-in（search profile） Kafka→OpenSearch 消费者（Go worker）

3. 必选与可选依赖

定性结论（产品管家 2026-09-20 Q1，message_id=2101665052363755520）：OCTO 是「单体 server + 若干可选旁路服务 + 必选基础依赖」的部署形态，不是重微服务拆分。最小生产集 7 件套：octo-server + octo-web + octo-admin + WuKongIM + MySQL + Redis + MinIO。octo-matter/octo-smart-summary/octo-speech/搜索(OpenSearch+Kafka) 都是按需旁路服务，可关。

3.1 必选应用层组件

组件 进程形态 端口（Docker 默认直连） 说明
octo-server 单体 Go 二进制（40+业务模块编译进同一进程） 28081（直连）；对外经 nginx 走 28080 后端本体，聚合消息/群/Thread/文件/Bot/卡片/用户/搜索全部模块
octo-web 前端静态资源（nginx 托管） 28083（直连）；对外经 nginx / 走 28080 Web/PC 前端，必选
octo-admin 前端静态资源（nginx 托管） 28082（直连）；对外经 nginx /admin/ 走 28080 管理后台（空间管理/后台管理），必选

3.2 可选应用层旁路服务

组件 端口（Docker） opt-in 方式 不部署影响
octo-matter 28086 默认启动但可关（具体开关待确认） 不部署则无 matter/Todo 能力
octo-smart-summary（summary-api/worker） 28087 --summary 或 COMPOSE_PROFILES=summary，需配置 LLM_API_URL/KEY 不部署则无智能摘要/群总结
octo-speech 28088（speech-admin） scripts/speech-setup.sh，需语音引擎 key（默认 qwen） 不部署则无语音消息/转写
octo-docs（Hocuspocus+Yjs） — COMPOSE_PROFILES=docs，需 OCTO_DOCS_* 密钥 不部署则无协同文档

3.3 必选外部基础设施（所有部署形态）

组件 版本要求（源码事实） Docker 默认端口 说明
MySQL 8（建议8.x；5.7可用性待研发确认） 23306 Docker 栈内置 mysql:8；K8s 部署需自备，字符集必须 utf8mb4（硬要求）；三个库 octo/octo_matter/octo_summary（+ octo_marketplace/octo_docs 可选）；wait_timeout/max_connections 官方无公开推荐值，按连接池自行调
Redis 6.x/7.x 主流版均可（OOTB 用 redis:7-alpine） 26379 Docker 栈内置；K8s 部署需自备；承担缓存/会话/限流/bot_task 队列+幂等；生产必须设密码（.env redisPass，OOTB 只绑127.0.0.1默认空）；单机即可满足OOTB，HA 自行上主从/Sentinel
WuKongIM ≥ v2 API 25001 / TCP 25100 / WS 25200 / monitor 25300；gRPC webhook 6979 到 octo-server Docker 栈内置；K8s 部署需自备独立部署；IM 长连接底座
S3 兼容对象存储 S3 API 兼容 MinIO API 29000 / console 29001 Docker 栈内置 MinIO；K8s 可对接 AWS S3 / 腾讯 COS / MinIO 等

3.4 可选基础设施（条件可选，开了搜索才必选）

组件 端口（Docker） 默认状态 说明
OpenSearch（含 IK 分词） 29200 默认关闭 OCTO_SEARCH_BACKEND=disabled 全文/消息搜索后端；不开搜索不需要
Kafka 29092 默认关闭 OCTO_SEARCH_PRODUCER_ON=false 仅搜索链路 searchetl-producer 用；不开搜索不需要

重要：搜索基础设施启动后不会自动开始索引，也不会自动切 reader；必须运行 `scripts/search-upgrade.sh` 做零停机升级（6 步，带 G1-G5 闸门）。

3.5 内部版可选模块部署（v1.1新增）

以下模块为 OCTO 内部版独有能力（需明略商业授权），通过 docker-compose `COMPOSE_PROFILES` 或 Helm `values.yaml` 开关启用。所有模块均依赖核心7件套（octo-server/web/admin/WuKongIM/MySQL/Redis/MinIO）正常运行后再逐个启用。

3.5.1 内部版模块Profile总览

模块 docker-compose Profile Helm Key 默认开启 依赖Profile 宿主机端口(默认loopback)
智能摘要 Summary summary summary ❌ — 28087(summary-api)
语音 Speech speech speech ❌ — 28088(speech-admin)
文档协同 Docs docs docsBackend ❌ — —（经nginx路由）
文档HTML渲染 docs-html docs-html docsHtml ❌ docs —（经nginx路由）
企业网盘 Drive drive drive ❌ — —（经nginx路由）
回路/运行时 Fleet fleet(+fleet-db内置PG) fleet ❌ — 25432(fleet-postgres)、28089(fleet)
消息搜索 Search search(+search-producer/search-tools) search ❌ — 29092(kafka)、29200(opensearch)
文档索引 doc-index doc-index docIndexer ❌ docs+search 3100(doc-indexer健康检查)
网盘索引 drive-index drive-index driveIndexer ❌ drive+search 3200(drive-indexer健康检查)、9998(tika)
市场 Marketplace 无profile(docker默认启动) marketplace(helm默认false⚠️) ⚠️ docker默认/helm待确认 — —（经nginx路由）

3.5.2 各模块部署详情

📝 Summary（智能摘要）
项目 值
Profile summary（同步启动summary-api + summary-worker）
依赖 mysql（需先创建octo_summary库+summary/summary_reader用户）
额外基础设施 需外部LLM API（默认claude-sonnet-4-6，可配置LLM_API_URL/KEY/MODEL）；不依赖Kafka/OpenSearch
容器端口 summary-api: 8080(外部API)/8081(内部回调)；summary-worker: 8082
宿主机端口 127.0.0.1:28087（summary-api直连）
数据库 MySQL octo_summary（summary用户RW）+ octo（summary_reader用户RO只读）
Nginx路由 /summary/api/v1/* → summary-api:8080；SSE流/summary/api/v1/agent/chat/stream单独配proxy_buffering off/3600s
启动顺序 mysql → summary-api → summary-worker（worker依赖mysql就绪）
关键配置项 LLM_API_URL/KEY/MODEL（必填；KEY可占位启动但实际调用失败）、MYSQL_DSN、IM_MYSQL_DSN、OCTO_API_URL、NOTIFY_INTERNAL_TOKEN（与server一致）、WORKER_TRIGGER_URL
注意 LLM_API_KEY占位时worker仍可启动（方便测试环境）；summary-worker通过MESSAGE_FETCH_BACKEND=mysql直接读IM消息，不经过搜索服务
🎤 Speech（语音ASR）
项目 值
Profile speech（启动octo-speech + octo-speech-admin）
依赖 mysql（SPEECH_DB_PASSWORD非空时需octo_speech库）
额外基础设施 需语音引擎API Key（默认VOICE_ENGINE=qwen通义千问，需VOICE_QWEN_URL/KEY/MODELS；或Gemini/GPT/本地localhost:8787）
容器端口 octo-speech: 8780(ASR服务)；octo-speech-admin: 8781(管理控制台)
宿主机端口 127.0.0.1:28088（speech-admin，SSH隧道访问）
数据库 MySQL octo_speech（可选；SPEECH_DB_PASSWORD为空时不创建独立库，待确认存储方式）
Nginx路由 octo-server /api/v1/voice/transcribe→SPEECH_SERVICE_URL=http://octo-speech:8780；/speech-admin/→speech-admin:8781（loopback+SSH隧道）
启动顺序 mysql → octo-speech → octo-speech-admin
关键配置项 VOICE_ENGINE（默认qwen/Gemini/GPT/本地四选一）、VOICE_QWEN_URL/KEY/MODELS、VOICE_MAX_DURATION=60s、VOICE_MAX_FILE_SIZE=3MB、VOICE_EMOTION_EMOJI=true、VOICE_LOCAL_ENABLED（本地转写可选）、SPEECH_API_KEY（内部鉴权，待确认）、ADMIN_USERNAME/PASSWORD/JWT_SECRET（speech-admin独立认证）
注意 用户首次使用需opt-in（设置→语音设置）；speech-admin功能范围全部待确认（feature-map未收录）；TTS能力待源码验证(P1)
📄 Docs（文档协同）
项目 值
Profile docs（启动octo-docs-backend + docs-preflight + docs-migrate-entrypoint）
依赖 mysql + redis + minio-init（需octo_docs库+docs用户）
额外基础设施 无（不依赖Kafka/PG；对接doc-index搜索时需search profile）
容器端口 octo-docs-backend: 3000(REST API) / 1234(Hocuspocus协作WebSocket)
数据库 MySQL octo_docs库（docs用户，utf8mb4_general_ci）；Redis prefix: octo-docs
对象存储 MinIO bucket octo-docs-attachments（文档附件，独立bucket）
Nginx路由 /api/v1/docs/→:3000；/docs-collab(WS)→:1234；/api/v1/bot/docs/ rewrite→:3000/v1/bot/docs/；/docs-api/→:3000
启动顺序 mysql/redis/minio-init → docs-preflight → docs-migrate → octo-docs-backend
关键配置项 MYSQL_*、COLLAB_TOKEN_SECRET（≥32hex Hocuspocus JWT，preflight校验）、OCTO_IDENTITY_MODE=http（委托server认证）、ATTACHMENT_DRIVER=s3、SEARCH_INDEX_ENABLED/SEARCH_ENABLED（默认false）、KAFKA_BROKERS+DOCINDEX_KAFKA_TOPIC（对接doc-indexer时启用）
功能门控 docs_on/docs.enabled appconfig flag（Web端门控，未开不显示「文档」入口）
注意 启动时先执行schema.sql+migration再启服务；Bot操作文档走评论@Mention链路而非Bot API直调；docs-html需单独启用
🌐 docs-html（HTML文档渲染，依赖docs）
项目 值
Profile docs-html（必须同时启用docs）
依赖 docs（复用octo_docs库+octo-docs-attachments bucket）、octo-server
额外基础设施 无
容器端口 docs-html: 8080
数据库 MySQL octo_docs（复用docs用户）
Nginx路由 /docs-html/ rewrite→:8080/（sub_filter修正静态资源路径）
启动顺序 docs-backend → docs-html-migrate → docs-html
关键配置项 LOGIN_ENABLED=true、BOT_AUTH_ENABLED=true（Bot创建HTML文档）、OCTO_SERVER_BASE_URL、DOCS_BACKEND_REGISTER_URL（向docs-backend注册）
📁 Drive（企业网盘）
项目 值
Profile drive（启动octo-drive + drive-config + drive-preflight + drive-migrate）
依赖 mysql + minio-init + octo-server（需octo_drive库+drive用户）
额外基础设施 MinIO bucket octo-drive（独立bucket）；需授予drive用户octo_docs.doc_meta/doc_member的SELECT权限（挂载云文档列表）；对接drive-index搜索时需search+Tika
容器端口 octo-drive: 8080(HTTP API)
数据库 MySQL octo_drive库（drive用户，utf8mb4_unicode_ci）
Nginx路由 /v1/drive/→:8080；/v1/bot/drive/→:8080；/v1/user/drive/→:8080
启动顺序 drive-config（渲染config.yaml）→ drive-preflight → drive-migrate → octo-drive → octo-server
关键配置项 DRIVE_MYSQL_PASSWORD、DRIVE_OCTO_SERVER_INTERNAL_TOKEN（=NOTIFY_INTERNAL_TOKEN）、DRIVE_STORAGE_*_KEY（S3凭据）、DRIVE_KAFKA_DISABLED=true（默认，开drive-index时设false）、DRIVE_SEARCH_DISABLED=true（默认）、AWS_CA_BUNDLE（自签S3证书信任）
功能门控 drive_on（默认false）
注意 ⚠️ 仅Web端，iOS/Android未实现；drive v0.5.0 distroless镜像无shell，无liveness probe；storage.endpoint通过drive-config init从模板渲染（不支持env覆盖）；Bot API能力（/v1/bot/drive/）待源码确认
🔄 Fleet/Loop（回路与运行时管理）
项目 值
Profile fleet + fleet-db（内置PG时；用外部PG时只启fleet，设FLEET_DATABASE_URL即可）
依赖 redis + octo-server；fleet-db profile时启动内置postgres:16-alpine
额外基础设施 PostgreSQL 16（OCTO内部唯一使用PG而非MySQL的模块）；Redis DB 1（非默认DB 0）
容器端口 octo-fleet: 8080(HTTP+WS)；fleet-postgres: 5432
宿主机端口 127.0.0.1:25432(fleet-postgres PG直连)；127.0.0.1:28089(fleet直连)
数据库 PostgreSQL fleet库（fleet用户），内置postgres:16-alpine或外部FLEET_DATABASE_URL
存储卷 fleet-postgres-data（PG数据，🔴高重要性）；certs挂载（自签HTTPS webhook信任fullchain.pem）
Nginx路由 /fleet/api/v1/*→:8080（掉v1）；/fleet/api/daemon/ws(WS，无Connection strip)；/fleet/ws(WS)；/fleet/uploads/*；/fleet/auth/*
启动顺序 fleet-postgres(可选)/外部PG → fleet-preflight → octo-fleet（start_period:300s，迁移最长需5分钟）
关键配置项 DATABASE_URL/REDIS_URL、JWT_SECRET（≥32hex）、LOOP_CREDENTIAL_HMAC_KEY（≥32hex）、OCTO_APP_SERVER_URL、ALLOW_SIGNUP=false（默认受控邀请制）、DM_OUTBOUND_WEBHOOK_ALLOW_PRIVATE_NETWORKS=true、SSL_CERT_FILE（自签证书信任）、MULTICA_APP_URL/PUBLIC_URL
功能门控 dmloop.enabled（管理员开启Loop回路入口）
注意 ⚠️ 仅Web端（移动端确认无回路，dmloop_on未实现）；Daemon本地能力边界待源码验证(P0安全项)；Fleet为何用PG选型原因待确认；健康检查start_period=300s（冷启动慢）；certs卷用于自签HTTPS webhook信任
🔍 Search（消息全文搜索基础设施）
项目 值
Profile search（启动search-kafka + search-opensearch + es-indexer + search-kafka-init + search-ensure）+可选search-producer(K8s独立producer)+search-tools(cursor-seed+backfill)
依赖 mysql/redis/octo-server基础就绪；producer与octo-server内置searchetl互斥（search-producer-guard双向fail-closed）
额外基础设施 Kafka(KRaft单节点,3.8.0) + OpenSearch(2.17.0,baked in IK中文分词)；额外存储卷opensearch-data/kafka-data/search-dlq-spill
容器端口 search-kafka: 9092/9093/29092；search-opensearch: 9200；es-indexer: 无独立HTTP端口(消费进程)
宿主机端口 127.0.0.1:29092(kafka)；127.0.0.1:29200(opensearch)
数据库/索引 OpenSearch索引octo-message（alias: wukongim-messages-read）；Kafka topic octo.message.v1+.dlq
启动顺序 search-kafka-init → search-opensearch → search-ensure → es-indexer；首次启动需search-cursor-seed+search-backfill
关键配置项 OCTO_SEARCH_BACKEND=es（默认disabled）、TS_KAFKA_ON=true/octo-server内置producer或search-producer独立部署、KAFKA_AUTO_CREATE_TOPICS_ENABLE=false、ES_INDEXER_ENABLED=true、INDEXER_BATCH_SIZE=500、DISABLE_SECURITY_PLUGIN=true（本地简化模式🔴生产需启用）、OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m
注意 启动后不会自动索引，必须跑scripts/search-upgrade.sh（6步零停机升级G1-G5闸门）；搜索基础设施资源消耗显著（Kafka+OS各~0.5-1GiB）；doc-index/drive-index需额外profile
📑 doc-index（文档索引，依赖docs+search）
项目 值
Profile doc-index（必须同时启用docs+search）
依赖 docs-backend（SEARCH_INDEX_ENABLED/SEARCH_ENABLED需开启）+ search(kafka+opensearch)
额外基础设施 复用search profile的Kafka+OpenSearch
容器端口 doc-indexer: 3100(HTTP/readyz)
索引/Topic OpenSearch索引octo-doc（alias: octo-doc-read）；Kafka topics: octo.docindex.v1/.retry/.dlq
启动顺序 doc-index-kafka-init → doc-index-ensure → doc-indexer
关键配置项 复用search的Kafka/OS连接；doc-indexer镜像octo-doc-indexer:v1.1.0
📎 drive-index（网盘文件索引，依赖drive+search）
项目 值
Profile drive-index（必须同时启用drive+search）
依赖 octo-drive（DRIVE_KAFKA_DISABLED=false+DRIVE_SEARCH_DISABLED=false）+ search(kafka+opensearch)
额外基础设施 Apache Tika 3.3.0.0（文件文本提取:9998）；复用search的Kafka+OpenSearch
容器端口 drive-indexer: 3200；tika: 9998
索引/Topic OpenSearch索引octo-drive；Kafka topics: octo.driveindex.v1/.retry.v1/.dlq.v1
启动顺序 drive-index-kafka-init → tika(等/version就绪) → drive-index-ensure → drive-indexer
关键配置项 TIKA_URL=http://tika:9998；SSRF防护ALLOWED_DOWNLOAD_HOSTS/SSRF_ALLOW_LOOPBACK=false；drive-indexer镜像octo-drive-indexer:v0.1.0
注意 Tika支持格式清单/OCR能力待源码确认(P1)；SSRF_ALLOW_LOOPBACK=false防止索引器访问内网
🏪 Marketplace（市场/技能市场）
项目 值
Profile docker-compose无profile gating，默认启动；helm values.yaml marketplace.enabled=false⚠️（差异待确认）
依赖 mysql + redis + minio-init + octo-server + market-preflight
额外基础设施 无独立基础设施（复用mysql/redis/minio，独立库octo_marketplace）
容器端口 marketplace: 8092
数据库 MySQL octo_marketplace库（marketplace用户）
对象存储 MinIO bucket marketplace（私有，OSS_DOWNLOAD_SIGNED=true签名URL下载）
Nginx路由 /market/api/* rewrite→:8092/api/*；/market/healthz→:8092/healthz
启动顺序 mysql/redis/minio-init → market-preflight(幂等建库建用户) → marketplace
关键配置项 AUTH_ENABLED=true（委托octo-server认证）、OCTO_API_URL、STORAGE_DRIVER=oss(S3)、MAX_UPLOAD_MB=20、OSS_DOWNLOAD_SIGNED=true、REDIS_URL=redis://redis:6379/0
注意 ⚠️ docker-compose与helm默认值差异待确认；不是Bot市场（Bot通过BotFather管理），是技能包+专家+插件的分发市场

3.5.3 内部模块推荐启动顺序

第一批(基础验证)：核心7件套 → smoke-test全通过
第二批(独立旁路)：summary → speech   （各自独立，不依赖其他opt-in模块）
第三批(文档能力)：docs → docs-html    （docs先启，docs-html依赖docs）
第四批(网盘能力)：drive               （独立于docs，但挂载需docs）
第五批(回路能力)：fleet+fleet-db      （独立PG，启动慢300s）
第六批(搜索基础)：search              （Kafka+OS+es-indexer，重资源）
第七批(搜索扩展)：doc-index → drive-index  （依赖search+对应业务模块）

⚠️ Marketplace在docker-compose中默认启动（无profile），不需要单独启用。如果不希望启动marketplace，需手动注释或用COMPOSE_PROFILES精确控制（待确认是否有禁用方式）。

3.5.4 内部模块端口映射补充

宿主机端口 绑定地址 容器端口 服务 Profile
28087 127.0.0.1 8080 summary-api summary
28088 127.0.0.1 8781 speech-admin speech
25432 127.0.0.1 5432 fleet-postgres fleet-db
28089 127.0.0.1 8080 octo-fleet fleet
29092 127.0.0.1 29092/9092 search-kafka search
29200 127.0.0.1 9200 search-opensearch search

正常客户端访问仍只需开放28080(HTTP)或28443(HTTPS)。所有内部模块均经nginx路由对外提供服务，不需要额外开放防火墙端口。

4. 网络端面（单端口承诺）

4.1 对外唯一端口（默认）

端口 bind 说明
TCP 28080（HTTP，可通过 OCTO_HTTP_PORT 调整） 0.0.0.0（nginx） 用户入口——唯一需要在防火墙开放的端口
TCP 28443（HTTPS） 0.0.0.0 TLS 形态占位，默认未启用，需手动配置证书或前置反向代理

4.2 内部端口（默认 loopback，不对外）

服务 主机端口（默认） 说明
octo-server REST 直连 28081 操作员调试（绕过 nginx 限流）
octo-admin SPA 直连 28082 经 nginx /admin/ 对外
octo-web SPA 直连 28083 经 nginx / 对外
octo-matter 直连 28086 经 nginx /matter/ 对外
smart-summary API 直连 28087 经 nginx /summary/ 对外
speech-admin 控制台 28088 语音 profile 启用后，仅限 loopback（SSH 隧道访问）
summary-api 直连 28087 summary profile 启用后，经 nginx /summary/ 对外
Fleet 直连 28089 fleet profile 启用后，仅限 loopback
Fleet PostgreSQL 直连 25432 fleet-db profile 启用后，仅限 loopback
WuKongIM manager API 25001 内部 debug，不挂 nginx；远程访问用 SSH 隧道
WuKongIM TCP 原生传输 25100 仅原生 IM 客户端（手机/桌面 app 直连）时才需放开
WuKongIM WS 直连 25200 同上；浏览器走 nginx /ws 不需要此端口
WuKongIM monitor 25300 可观测性/路由 admin
MinIO API 29000 单端口形态走 nginx bucket-name 路由，不直连
MinIO console 29001 仅管理员，SSH 隧道访问，不通过 nginx 暴露
MySQL 23306 backing service
Redis 26379 backing service（Docker 栈默认无密码，必须 loopback）
OpenSearch（search profile） 29200 loopback
Kafka（search profile） 29092 loopback

4.3 K8s 部署端口（来自 README 组件表）

  • octo-server：8090(HTTP) / 6979(gRPC，WuKongIM webhook 回调)
  • octo-web/octo-admin：80
  • octo-matter：8080
  • octo-smart-summary-api：8080/8081
  • octo-smart-summary-worker：8082
  • 外部依赖（MySQL/Redis/WuKongIM/S3）由部署者自备，网络端面由部署者决定。

5. 部署流程

5.1 单机 Docker Compose 最短路径（官方 TL;DR）

git clone https://github.com/Mininglamp-OSS/octo-deployment.git
cd octo-deployment
./setup.sh                                  # 步骤1：交互式向导（自动探测公网 IP，生成密钥写到 docker/.env）
sudo ./setup.sh --up                        # 步骤2：起栈（start-only，阻塞等 healthy，240s 超时，自动重试一次）
sudo ./setup.sh --smoke-test                # 步骤3：端到端自检（11 步：容器健康→nginx→REST→matter→MinIO→SPA→WS→admin 登录→presign→SigV4 PUT）
  • --up 是 start-only 子命令：docker/.env 不存在时直接 exit 1（不隐式生成密钥）；永远不会改写/重新生成密钥（只会 chown root:600）；从 R8 起代码强制这个契约。
  • --up --force 才会 bootstrap+启栈（会生成新密钥，禁止在已在跑生产的主机上使用）。
  • 等待期间每 5 秒打一个 .；MySQL 冷启动可能 60-90 秒。
  • 非交互模式：./setup.sh --non-interactive --domain octo.example.com --ip 1.2.3.4。
  • 启用可选 profile：--summary、--search（可组合）。

5.2 smoke-test 11 步自检

  • [infra] container + nginx routing (1-7)：容器健康、nginx vhost、octo-server REST、matter、MinIO health、admin SPA、web SPA。FAIL = 平台问题。
  • [user-path] auth + WS + presigned PUT (8-11)：WuKongIM /ws（raw socket 探测，专门捕获容器 Exited(0) 绕过 healthy 检测的场景）、admin 登录（验证 octo-server+MySQL+bcrypt+Redis）、presign 签发、SigV4 PUT（验证 nginx 原样转发+MinIO 签名）。FAIL = 契约问题。

5.3 K8s 部署最短路径（README 原文）

kubectl create namespace octo
cd kustomize/base
for f in *-secret.example.yaml; do cp "$f" "${f/.example/}"; done
$EDITOR octo-*-secret.yaml                   # 替换 CHANGE_ME_* 占位符
kubectl apply -n octo \
  -f octo-server-secret.yaml \
  -f octo-matter-secret.yaml \
  -f octo-smart-summary-secret.yaml
kubectl apply -n octo -k .
# 差异化部署：
kubectl apply -n octo-dev  -k kustomize/overlays/dev
kubectl apply -n octo-prod -k kustomize/overlays/prod
  • octo-server-secret：DM_MYSQL_DSN、DM_REDIS_ADDR、WUKONGIM_MANAGER_TOKEN、OCTO_ADMIN_PASSWORD、OCTO_MASTER_KEY、NOTIFY_INTERNAL_TOKEN、OCTO_INTERNAL_HMAC_SECRET、OCTO_JWT_SECRET（启用 OIDC/COS/SMTP/APNS 时加对应字段）
  • octo-matter-secret：MYSQL_DSN、LLM_API_KEY、NOTIFY_INTERNAL_TOKEN（必须与 server 侧一致）
  • octo-smart-summary-secret：MYSQL_DSN、IM_MYSQL_DSN、LLM_API_URL、LLM_API_KEY

5.4 卸载/重置（三档）

  1. Full uninstall：停容器 + 删 named volume（数据全丢，需打 `YES` 确认）
  2. Data-only reset：只删 named volume
  3. Containers only：停+删容器，保留 volume

6. WuKongIM 三对齐（所有部署形态必做）

WuKongIM 配置 octo-server 对应配置
managerToken wukongIM.managerToken（YAML）/ WUKONGIM_MANAGER_TOKEN（env/Secret）
webhook.grpcAddr（WuKongIM 回调地址） :6979（让 IM 消息事件回到 OCTO）
external.ip / external.wsAddr / external.wssAddr（WuKongIM 对客户端暴露地址） 与终端客户端经 ingress/LB 访问 WuKongIM 的实际地址一致

7. HTTPS / TLS

  • 路径 A：Cloudflare Tunnel（推荐快速 HTTPS）：零入站端口、自动 HTTPS、cloudflared 出站隧道反代到 localhost:28080，请求体上限 Free 100MB / Pro 200MB / Business 500MB
  • 路径 B：host nginx + certbot（最常见自托管）：--nginx 插件签证书+自动续期；关键是 WebSocket 需 map $http_upgrade $connection_upgrade，不能写死 Connection "upgrade"（会打断 REST keepalive）
  • 路径 C：Caddy（最少零件）：单 binary 自动 LE 签续，默认讲 HTTP/2+HTTP/3，自动转发 WS 头
MINIO_SERVER_URL=https://[:port]
TS_MINIO_DOWNLOADURL=https://[:port]
TS_EXTERNAL_BASEURL=https://[:port]
OCTO_WK_WSS_ADDR=wss://[:port]/ws

8. 首位 admin 启动

  • 推荐（选项 A）：docker/.env 设 OCTO_ADMIN_PWD=<强密码>，octo-server 第一次启动时检测到 account.adminUID（默认 "admin"）用户行不存在且 adminPwd 非空，自动插入 superAdmin（username=superAdmin，bcrypt 密码）。该钩子是 one-shot，行存在后 restart no-op，留着值安全。登录后从 admin UI 改密码并从 .env 删掉该值。
  • 手动（选项 B）：生成 bcrypt hash（htpasswd 或 python bcrypt），手动 INSERT user 行（role 必须是字符串 'superAdmin'，不是 int enum）。

9. 安全要点（来自 Hardening checklist 源码事实）

  1. Redis Docker 栈默认无密码——必须留在 loopback 或加 `--requirepass`。
  2. MinIO octo-app 用户是 scope-limited IAM：只授予白名单 bucket（file/chat/moment/sticker/report/chatbg/common/download/group/avatar）的 Get/Put/Delete/multipart+ListBucket，不给 CreateBucket/mc admin/console/IAM 权限。root 凭据只在 minio-init 一次性 job 中使用。
  3. 内容 bucket 匿名可读（chat/file/moment/sticker/chatbg/common/avatar = `download`；report/group/download = private 必须签名）。这是 OCTO web `` 模型需要（SPA 直接用未签名 downloadURL，CDN 风格），但意味着图片 URL 一旦签发就永久全网可读（key 是高熵 UUID 无法枚举，s3:ListBucket deny）。
  4. Preflight 容器纵深防御：`preflight` 和 `minio-init` 一次性服务拒绝任何 `CHANGE_ME_*`/`CHG_ME*` 占位凭据，OOTB 栈在 placeholder 没换的情况下不可能到达 healthy。
  5. 全局限流豁免不变量：`/v1/bot/heartbeat` 和 `/v1/bot/register` 必须成对豁免（避免「能发现掉线但爬不起来」死锁），由 `main_test.go:TestExcludedBotPathsEachHaveTheirOwnFloor` 结构性钉住。

10. 资源规格与 HA（待产品管家确认）

  • CPU/内存/磁盘最低配置：docker README 仅给出单机试用 ≥4 GiB RAM、≥10 GiB 空闲磁盘（这是 OOTB 单机评估前置条件，不是生产推荐规格）。生产资源规格待产品管家/交付侧确认。
  • search profile 额外资源：README 给出单节点轻载占用参考（OpenSearch ~1 GiB JVM、Kafka ~0.5-1 GiB、es-indexer ~50-100 MiB），这是 idle 到轻载数据点，不是容量规划。
  • K8s 副本数 / HPA / PodDisruptionBudget：overlays/prod 存在但具体副本数、反亲和、HA 策略待确认。
  • MySQL/Redis/WuKongIM 高可用拓扑：主从/集群/哨兵/多可用区方案待确认（README「待补」列出 MinIO+WuKongIM 集群内样板）。
  • 备份/恢复方案：modules/backup 模块存在，但策略、RPO/RTO、脚本待确认。
  • 版本兼容矩阵：各端/插件/服务端版本对照表待确认（OOTB 默认 latest，生产需 pin release tag）。
  • 离线/air-gapped 部署步骤：镜像离线导入、IK 插件离线构建、LLM/语音服务内网对接方案待确认。
  • PoC 与生产的功能/配置/资源差异：官方未给出独立 PoC 形态定义，待交付侧确认。

11. 相关文档

  • [02-architecture/OCTO总体架构.md](../02-architecture/OCTO总体架构.md) — 总体架构分层与请求链路（含 WuKongIM/OpenClaw/外部系统边界）
  • [02-architecture/OpenClaw-Agent-Bot-OCTO关系说明.md](../02-architecture/OpenClaw-Agent-Bot-OCTO关系说明.md)
  • [代码仓库解读/仓库总览.md](../代码仓库解读/仓库总览.md) — 9 个官方仓库清单（含 octo-deployment）
  • 待补：03-deployment-ops/ 下后续可建备份恢复、监控告警、升级回滚、故障排查 SOP 子文档（P1+阶段）

版本记录

  • v1.0（2026-09-20）：首版，基于开源版octo-deployment README+docker/kustomize配置+产品管家P0三批12问
  • v1.1（2026-09-21）：P0扩展补漏——新增§3.5「内部版可选模块部署」章节，覆盖8个内部模块（summary/speech/docs/docs-html/drive/fleet/search/doc-index/drive-index/marketplace）的profile开关/依赖/端口/数据库/启动顺序/关键配置；补充内部模块端口映射表和推荐启动顺序；更新frontmatter（source增加内部部署仓库+全组件服务清单+基础设施依赖映射，confidence升到medium-high）

待产品管家确认项

  1. 生产资源规格：单机/PoC/生产/HA 各形态的官方 CPU/内存/磁盘推荐值、并发支撑能力、容量规划模型。
  2. HA 参考架构：K8s 多副本生产 overlay 的具体副本数、反亲和策略；MySQL/Redis/WuKongIM/MinIO 集群方案；是否有官方 Helm values（`helm/octo/` 存在但 README 未给出生产 values 示例）。
  3. PoC 正式定义：官方是否有独立 PoC 形态配置（功能裁剪、数据保留策略、验收标准）还是直接用单机 Compose 栈。
  4. 离线/内网部署：镜像离线导入流程、air-gapped 下 LLM/语音服务对接方案、IK 插件离线构建方式。
  5. 版本矩阵：octo-server/web/admin/matter/summary 各组件版本兼容对照表；生产环境 pin tag 策略。
  6. 备份恢复：modules/backup 的使用方式、RPO/RTO、MySQL 全量+增量备份方案、MinIO 备份策略。
  7. 监控告警：是否有官方 Prometheus metrics 清单、Grafana dashboard、告警规则。
  8. 语音（speech profile）qwen/gpt/gemini 引擎的具体要求：模型端点、配额、是否可本地化部署。
  9. docs profile 协同文档的生产形态：是否推荐在生产启用、Hocuspocus 多实例部署策略。

来源标注

  • octo-deployment/README.zh.md：OOTB 组件/端口表、必选/可选依赖、WuKongIM 三对齐、Docker/K8s 双形态、搜索 opt-in
  • octo-deployment/docker/README.zh.md：setup.sh 三步流程、start-only 契约、smoke-test 11 步、单端口网络端面表、所有端口/bind 默认值、反向代理三条 HTTPS 路径、必填 Secret、COMPOSE_PROJECT_NAME 隔离事故（INCIDENT-2026-05-16）、Preflight 凭据校验、MinIO IAM 策略、首位 admin bootstrap 两种路径、Redis 无密码警告、ufw+iptables 陷阱、search-upgrade 6 步 G1-G5 闸门、搜索 profile 拆除风险（不能用项目级 down -v）、speech/docs/marketplace profile
  • octo-server/README.zh.md：单锚点架构、可替换存储/IM、一键部署指向 octo-deployment
  • 产品管家 2026-09-19 Q3/Q4：支持私有化开源、单机/PoC/生产/HA/硬件规格/Helm 要求无一手文档证据
  • 00-inbox/product-bot-answers/2026-09-20-P0-部署架构-Q4回答.md（产品管家 Q4：镜像 tag 快照，2026-09-20）

附录 A：OOTB 镜像 tag 参考（来自 octo-deployment，截至 2026-09-20）

来源：产品管家 2026-09-20 Q4 核对 `octo-deployment`（helm values.yaml + docker-compose.yml）实际 pin 值。具体版本以交付部署包为准，下表为仓库快照。

组件 镜像 OOTB 默认 tag 备注
octo-server mininglamp/octo-server v1.18.0 核心后端，helm chart appVersion 标注此版本
octo-web mininglamp/octo-web 2026.09.14 Web/PC 前端
octo-admin mininglamp/octo-admin latest 建议客户生产锁具体 tag，部署包内会带版本号
WuKongIM mininglamp/wukongim wukongim-v3 具体 patch 版本以部署包为准；OOTB 默认 v3 协议
MySQL mysql 8.0 必选，三库 octo/octo_matter/octo_summary
Redis redis 7-alpine 必选，缓存/限流/bot_task 队列+幂等
MinIO minio/minio latest（RELEASE.2024-xx） 必选，S3 兼容对象存储
OpenSearch（可选） opensearchproject/opensearch 2.x 搜索 profile opt-in，配合 IK 分词
matter（可选） mininglamp/octo-matter 与 server 版本配套 任务/Todo 微服务
summary（可选） mininglamp/octo-smart-summary 与 server 版本配套 LLM 摘要
  • helm chart 的 appVersion 标注的是 octo-server 版本，旁路服务（matter/summary/speech）版本与 server 配套发布，不要跨大版本混搭。
  • latest tag 不建议生产直接用，交付时必须锁到部署包内具体版本号。
  • WuKongIM 镜像独立发版（tag 前缀 wukongim-），与 octo-server 无强绑定版本号，但 OOTB 部署包中默认 tag 已对齐测试。
← 返回文档中心