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

部署 FAQ

OCTO 文档中心 · 部署运维
  • 03-deployment-ops/OCTO部署形态总览.md v1.1（基于octo-deployment README + docker/kustomize配置 + 内部版模块部署）
  • source-repos/octo-deployment/README.zh.md
  • source-repos/octo-deployment/docker/README.zh.md（nginx反代/location/端口/首位admin bootstrap）
  • source-repos-internal/octo-deployment/docker/docker-compose.yaml（内部模块配置）
  • 02-architecture/OCTO全组件服务清单.md
  • 03-deployment-ops/基础设施依赖映射.md
  • 01-product/模块说明/各模块v0.3文档
  • 00-inbox/product-bot-answers/2026-09-20-P0-版本与命名-回答.md（产品管家2026-09-20，server v1.18.0/锁版本规则）
  • 07-faq-troubleshooting/README.md v0.1（已收录3条运维FAQ）

部署 FAQ v0.2（私有化部署常见问题）

状态：`draft` / v0.1。confidence:medium。

本文收集 OCTO 私有化部署最常被售前/交付/运维问到的问题。能答的基于源码和产品管家权威口径回答（标来源）；当前证据不足的明确标"待产品管家 deployment-architecture 回答后补"，不编造。

与 `07-faq-troubleshooting/README.md` 的区别：那篇是面向三类读者的通用 FAQ 入口，本文专门深挖部署/运维侧问题。

一、端口与访问

Q1：OCTO 默认 HTTP/HTTPS 端口是多少？

  • Docker Compose 单机部署默认：HTTP 28080、HTTPS 28443。
  • K8s 通过 Ingress/LB 暴露，端口由部署者配置（通常走 80/443）。
  • 栈内 nginx（OOTB 自带）location 反代规则：
  • / → octo-web 前端静态资源；
  • /admin/ → octo-admin 管理后台静态资源；
  • /v1/、/api/、/api/v1/ → octo-server 后端。
  • gRPC（WuKongIM webhook 回调）端口：6979（用于 WuKongIM 把消息投递回 octo-server）。
  • Prometheus metrics 端口：默认不开，需设 DM_METRICS_ENABLED=true 后监听 :9090（DM_METRICS_ADDR 可覆盖）。

Q2：前置反向代理（nginx/Caddy/Cloudflare Tunnel）怎么配？为什么图片裂/文件下载403？

  • HTTPS 部署必须同步配置 4 个对外地址，否则会出 mixed-content / SigV4 签名错误：
  • MINIO_SERVER_URL
  • TS_MINIO_DOWNLOADURL
  • TS_EXTERNAL_BASEURL
  • OCTO_WK_WSS_ADDR（WebSocket 地址，必须是 wss://）
  • 前置反代把 HTTPS 流量回源到 127.0.0.1:28080 时，必须设 OCTO_NGINX_BIND=127.0.0.1，避免栈内 nginx 对公网暴露。
  • MinIO bucket 鉴权策略差异：
  • chat/file/avatar 等"内容"bucket 默认匿名可读，图片链接直接 渲染；
  • report/group/download 等 bucket 需要预签名 URL 访问，配置不对就会 403。
  • 排查顺序：F12 Network 看是 403 还是 mixed-content → 检查上面4个环境变量是否都是 HTTPS → 反代头是否正确。

二、版本与镜像

Q3：生产部署应该锁什么镜像 tag？能不能用 latest？

  • 后端锁 octo-server 具体 release tag（当前最新 GitHub Latest = v1.18.0，2026-09-07）；
  • Web 锁对外日期版本（当前 2026.09.14）；
  • 移动端锁各端 SemVer（iOS 1.0.5 / Android 1.4.0）；
  • 插件锁 openclaw-channel-octo SemVer（当前 1.5.0）；
  • WuKongIM/admin/matter/smart-summary 暂无官方对照，建议部署时记录实际 pin 版本，后续找研发补兼容矩阵。

⚠️ 关键坑：`docs/changelog.md` 节标题维护滞后（停在 v1.1.2-2026-03-05），不能以 changelog.md 节标题判断最新 tag，必须查 GitHub Releases（releases/latest）。

Q4：OCTO 有没有官方跨组件版本兼容矩阵？

  • 默认推荐用同期最新发布组合；
  • 客户明确要最小兼容组合时，单独找研发确认；
  • openclaw-channel-octo 插件有明确的 OpenClaw SDK 版本硬约束（例如 1.4.1 要求 OpenClaw 2026.8+），可用 create-openclaw-octo doctor 校验兼容性——这是目前唯一已知硬性版本约束点。

三、必选/可选依赖

Q5：最小部署必须装哪些中间件？Kafka/OpenSearch 是必需的吗？

  • octo-server（Go 后端单二进制，核心，聚合 40+ 模块）；
  • octo-web（Web/PC 前端，nginx 托管静态资源）；
  • octo-admin（管理后台，必选，nginx /admin/ 托管）；
  • WuKongIM（IM 长连接底座，独立进程；四端口：API 25001内/5001容器、TCP 25100、WS 25200、monitor 25300、gRPC webhook 6979；数据独立，有自己的 mysqlAddr/redisAddr，不复用 server 的 MySQL/Redis；必须配 TS_WUKONGIM_MANAGERTOKEN）；
  • MySQL（推荐 8.x，字符集必须 utf8mb4 硬要求；Docker 端口 23306；matter/summary 各有独立 DB_PASSWORD/独立库；wait_timeout/max_connections 无官方推荐值，按连接池调）；
  • Redis（6.x/7.x 主流版均可；Docker 端口 26379；承担缓存/会话/限流/bot_task 队列+幂等；生产必须设密码 .env redisPass，OOTB 只绑 127.0.0.1 默认空；单机即可满足 OOTB，HA 自行上主从/Sentinel，无强制要求）；
  • S3 兼容对象存储（MinIO API 29000/console 29001；生产可替换为腾讯云 COS/阿里云 OSS/AWS S3；downloadURL 必须指向客户端可达对外地址）。
  • Kafka + OpenSearch：消息全文搜索；默认 SEARCH_BACKEND=disabled/SEARCH_PRODUCER_ON=false，不开搜索就完全不需要；Kafka 只在独立 searchetl-producer 容器里，server 主进程 kafka=0 命中；
  • octo-matter：Todo/任务（独立旁路 28086，独立 DB，可关）；
  • octo-smart-summary：LLM 会话摘要（独立旁路 28087，需 LLM_API_URL/KEY，可关）；
  • octo-speech / voice_adapter：语音消息与转写（按需部署，有 speech-setup 脚本）；
  • octo-docs（Hocuspocus+Yjs）：协同文档。

⚠️ 版本基线提醒（产品管家 2026-09-20 Q3 口径）：OCTO 目前暂无官方外部依赖最低版本兼容基线文档，OOTB 镜像用同期主流稳定版；售前承诺以交付部署包 pin 的版本为准。以下几项暂无公开信息不臆断：MySQL 5.7 可用性、WuKongIM v2/v3 兼容、OpenSearch/ES 兼容+IK 分词、Kafka 复用集群，需研发补正式基线。

Q6：OCTO 默认自带 OpenClaw 运行时吗？

  • 纯 IM/文件/群组/文档协作场景可以不装 OpenClaw；
  • 需要 AI Agent（产品管家、知识库助手）则需要单独部署 OpenClaw 并安装 openclaw-channel-octo 插件。

四、安全与配置

Q7：首位管理员怎么创建？公开注册开着吗？

  • OCTO OSS 默认关闭公开注册（register.off: true）。
  • 首位 superAdmin 由部署时 out-of-band 创建：设 OCTO_ADMIN_PWD 环境变量自动 bootstrap，或手动 SQL seed。
  • 普通用户由管理员在管理后台创建/邀请，或配 SSO（OIDC）登录。具体 SSO 配置待确认。

Q8：全局限流阈值是多少？为什么我 429 了？

  • 全局 per-IP 令牌桶默认 500 rps / burst 1000（可通过 DM_API_RATELIMIT_RPS / DM_API_RATELIMIT_BURST 环境变量覆盖）。
  • 4 条豁免路径（不进全局桶，但各自有严格桶兜底）：/v1/ping、/v1/health、/v1/bot/heartbeat、/v1/bot/register——这是 2026-08-05 事故（同 IP 多 Bot 互饿死锁）的修复方案。
  • Bot 级限流（business/heartbeat/register 三条通道）默认关闭，由 modules/common system_setting 热加载启用，参数可动态调整。
  • 常见 429 原因：同 IP 部署多个 Bot 抢配额（被邻居挤掉）→ heartbeat 漏 → Bot 离线。

Q9：CORS 怎么配？为什么浏览器报跨域？

  • 未配置 DM_CORS_ALLOWED_ORIGINS：等价于禁用跨域（剥离所有 CORS 响应头，只允许同源调用）；
  • 配置了就按配置的 origin 白名单响应。

五、运维与排障

Q10：怎么看服务是否健康？

  • 存活探针：/v1/ping、/v1/health（限流豁免）；
  • 就绪探针：/v1/ready（不参与 accesslog，ingorePaths 列表可见）；
  • gRPC :6979 通 = WuKongIM 能回调成功；
  • 版本号/ldflags 注入字段具体暴露端点（/version？/metrics？）待确认；
  • Prometheus metrics（开 DM_METRICS_ENABLED=true 后）暴露在 :9090/metrics，包含 HTTP per-route 延迟/状态码、DB/Redis 连接池、Bot 限流、卡片渲染、头像缓存、session rollout 等指标。

Q11：数据库 migration 怎么跑？升级要手动吗？

  • 跨 MINOR/MAJOR 的强制升级顺序（先升 server 还是先升 web）待确认（无官方 SOP）；
  • 字段 rolling expand 设计（如 joined_at 采用新字段可空、旧二进制可省略、读侧 COALESCE）暗示支持新旧二进制共存短暂窗口，但正式回滚 SOP 待确认。

Q12：备份怎么做？有官方备份方案吗？

  • 源码存在 modules/backup（source-repos/octo-server/modules/backup/），包含 /data/wukongim 数据目录处理、wukongim-YYYYMMDD-HHMMSS.tar.gz 打包逻辑；
  • 具体使用方式、RPO/RTO、MySQL+MinIO 完整备份方案（特别是 MinIO bucket 一致性快照）待产品管家/运维确认（知识地图 P0-13 已列入待确认清单）。

⚠️ 待产品管家 `deployment-architecture` Q3 回答后补外部依赖完整备份方案。

七、内部版可选模块部署FAQ（v0.2新增）

Q13：如何开启文档协同（docs）功能？

  1. docker-compose：`COMPOSE_PROFILES=docs ./setup.sh --up`，或在.env中添加 `COMPOSE_PROFILES=docs`
  2. Helm：设 `docsBackend.enabled=true`
  3. 同时需要配置 docs 必需密钥：`OCTO_DOCS_DB_PASSWORD`（非空）、`COLLAB_TOKEN_SECRET`（≥32hex随机字符串，preflight校验）、attachment secret（≥32hex）
  4. docs-backend启动时自动执行schema.sql+migration
  5. 管理员需在appconfig中开启`docs_on`/`docs.enabled`，Web端左侧才显示「文档」入口
  6. 如需HTML文档能力，同时启用`docs-html` profile（依赖docs）

Q14：如何开启企业网盘（drive）功能？

  1. docker-compose：`COMPOSE_PROFILES=drive ./setup.sh --up`
  2. Helm：设 `drive.enabled=true`
  3. 配置 `OCTO_DRIVE_DB_PASSWORD`（非空，合法字符集[A-Za-z0-9._-]）
  4. drive-preflight自动创建`octo_drive`库+drive用户+授予octo_docs读权限
  5. drive-config从模板渲染config.yaml（替换storage.endpoint为实际S3端点），drive-migrate执行SQL迁移
  6. 管理员需开启`drive_on`（默认false）

Q15：Fleet（回路/运行时）为什么用PostgreSQL而不是MySQL？

  • 使用内置PG时启用fleet-db profile自动拉起postgres:16-alpine
  • 使用外部PG时设FLEET_DATABASE_URL即可，不需要fleet-db profile
  • Fleet使用Redis DB 1（核心模块使用DB 0，互不干扰）
  • 可能原因（推测，不构成定论）：Fleet是从octo-server拆出的独立Go服务，可能使用了PG特有的功能（如JSONB、LISTEN/NOTIFY、特定扩展），或与daemon长连接状态管理有关

Q16：Search（全文搜索）"near-real-time"（近实时）是什么意思？

  • 新消息经WuKongIM webhook到octo-server后，searchetl producer将变更事件写入Kafka
  • es-indexer批量消费Kafka消息（BATCH_SIZE=500），写入OpenSearch
  • OpenSearch默认refresh_interval为1秒（索引变更从内存buffer刷新到可查询段）
  • 全链路典型延迟预计在数秒级别，不是毫秒级强实时
  • 允许秒级延迟换取更高吞吐（批量消费）
  • DLQ死信队列保证消息不丢（消费失败进DLQ）
  • cursor-seed保证producer重启不回放全量历史
  • backfill支持历史数据回填
  • read alias模式支持零停机reindex/alias swap

Q17：语音（speech）模块需要什么模型配置？

引擎 默认模型 配置项 适用场景
Gemini（默认） gemini-3.1-pro-preview/3-flash-preview/2.5-pro VOICE_ENGINE=gemini 通用转写
GPT gpt-4o-mini-transcribe VOICE_ENGINE=gpt 仅语音输入append_only模式
Qwen qwen3.5-omni-plus VOICE_ENGINE=qwen 通用转写（独立配置VOICE_QWEN_URL/KEY）
本地ASR（可选） localhost:8787 VOICE_LOCAL_ENABLED=true（默认false） 本地部署转写
Qwen（通义千问） qwen3.5-omni-plus VOICE_ENGINE=qwen + VOICE_QWEN_URL/KEY/MODELS 通用转写
本地 localhost:8787 VOICE_LOCAL_ENABLED=true 本地部署转写
  1. 启用`speech` profile
  2. 配VOICE_ENGINE和对应引擎的URL/KEY/MODELS
  3. 可选配SPEECH_DB_PASSWORD（非空时创建octo_speech库）
  4. speech-admin（:8781）有独立ADMIN_USERNAME/PASSWORD/JWT_SECRET，仅loopback+SSH隧道访问

Q18：智能摘要（summary）必须配LLM Key吗？

  1. 启动阶段：LLM_API_KEY可以用占位值（容器不会因为KEY无效或为空而启动失败），方便开发/测试环境拉起栈验证部署
  2. 实际使用阶段：用户触发总结时summary-api/worker需调LLM API生成摘要，如果KEY无效/占位会导致摘要请求失败
  3. 必须配置：
  • LLM_API_URL：LLM API端点（默认指向https://api.example.com/v1，需替换为实际地址）
  • LLM_API_KEY：对应LLM的API Key
  • LLM_MODEL：默认claude-sonnet-4-6，可改
  1. Summary不依赖搜索服务（MESSAGE_FETCH_BACKEND=mysql直接读IM MySQL），可以独立于search profile部署
  2. summary-worker用summary_reader账号只读访问octo主库读取消息

Q19：内部模块应该按什么顺序启用？

  1. 第一批（基础）：核心7件套，smoke-test全通过
  2. 第二批（独立旁路）：summary → speech（各自独立，互不依赖）
  3. 第三批（文档）：docs → docs-html（docs-html依赖docs）
  4. 第四批（网盘）：drive（独立于docs，但挂载云文档需docs已启）
  5. 第五批（回路）：fleet + fleet-db（独立PG，冷启动start_period=300s）
  6. 第六批（搜索基础）：search（Kafka+OpenSearch+es-indexer，重资源~2-3GiB额外内存）
  7. 第七批（搜索扩展）：doc-index → drive-index（依赖search+对应业务模块）
  • search启用后必须跑scripts/search-upgrade.sh做零停机升级
  • fleet冷启动慢（DB迁移最长5分钟），healthcheck start_period=300s
  • 开启doc-index/drive-index前需确认docs/drive的SEARCH_ENABLED/DRIVE_KAFKA_DISABLED已正确设置

Q20：开启内部模块需要额外开放防火墙端口吗？

八、版本记录

  • v0.1（2026-09-20）：首版，覆盖端口/反代/版本/必选依赖/限流/CORS/migration/备份等12个FAQ
  • v0.2（2026-09-21）：P0扩展补漏——新增§七「内部版可选模块部署FAQ」8个问题（Q13-Q20）：开启docs/drive方法、Fleet为何用PG、搜索NRT含义、语音模型配置、summary LLM Key、模块启用顺序、防火墙端口；更新frontmatter增加内部部署仓库+模块文档来源，confidence升到medium-high

六、待产品管家回答后回填项（topic: deployment-architecture）

# 待回填项 对应Q
D1 后端微服务完整清单（matter/summary/speech/docs 是否独立进程） Q1
D2 哪些组件是私有化必选、哪些 opt-in（特别是 matter/summary/admin） Q1
D3 服务间通信方式（HTTP/gRPC/MQ？服务注册发现？Bot 任务调度？） Q2
D4 外部依赖 MySQL/Redis/MinIO/Kafka/OpenSearch 的推荐版本范围 Q3
D5 WuKongIM 是独立进程/是否内置、元数据存在哪里、v2 最低版本/v3 兼容计划 Q4
D6 K8s 生产高可用方案（副本数/反亲和/MySQL-Redis-WuKongIM-MinIO 集群拓扑） P0-9（后续 topic）
D7 Helm chart 默认 tag/锁版本方式/values 参考 P0-21（后续 topic）

相关文档

  • [03-deployment-ops/OCTO部署形态总览.md](OCTO部署形态总览.md) v1.0 — 端口/组件/必选可选/HTTPS/SigV4
  • [09-version-change/OCTO版本口径.md](../09-version-change/OCTO版本口径.md) v1.1 — 版本号/锁版本规则
  • [07-faq-troubleshooting/README.md](../07-faq-troubleshooting/README.md) v0.1 — 通用FAQ（含3条运维FAQ）
  • [06-api-integration/OCTO-Bot-API接入快速上手指南-v0.1.md](../04-api-integration/OCTO-Bot-API接入快速上手指南-v0.1.md) — apiBase/反代/CORS 调试
  • [代码仓库解读/octo-server启动流程.md](../代码仓库解读/octo-server启动流程.md) v0.1 — 中间件/限流/metrics 启动顺序

v0.1 边界说明

  • 端口/反代/锁版本/必选依赖/限流/CORS/migration 有源码或产品管家直接证据，confidence:high；
  • HA/备份恢复/Helm/WuKongIM版本/MatterSummary 进程形态待产品管家回答，标"待补"，不编造；
  • 本文不替代官方部署手册；后续配合 03-deployment-ops/ 单机部署 / K8s 部署 / 备份恢复 等子页形成完整部署手册。
← 返回文档中心