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

单机 Docker 部署

OCTO 文档中心 · 部署运维
  • source-repos-internal/octo-deployment/docker/docker-compose.yaml
  • source-repos-internal/octo-deployment/docker/docker-compose-setup.sh
  • source-repos-internal/octo-deployment/docker/README.md
  • source-repos-internal/octo-deployment/docker/scripts/
  • 02-architecture/OCTO全组件服务清单.md
  • 03-deployment-ops/基础设施依赖映射.md
  • 03-deployment-ops/OCTO部署形态总览.md

单机 Docker Compose 部署 SOP v1.0

本文档面向单机评估/PoC/内部试用场景，提供从裸机到可用的全流程。生产多节点部署请参考 K8s Helm SOP。

所有命令、端口、路径、环境变量均来自 `docker-compose.yaml` 和 `docker-compose-setup.sh`，不确定处标注待验证。

一、前置要求

1.1 操作系统

  • Linux x86_64（推荐 Ubuntu 22.04 / Debian 12 / CentOS 8+）
  • kernel ≥ 4.18（支持 OverlayFS）
  • macOS（Docker Desktop 4.x，注意文件系统性能）
  • 不推荐 Windows/WSL2（文件权限和挂载路径易踩坑）

1.2 软件版本

软件 最低版本 推荐版本 验证命令
Docker Engine ≥ 24.0 26.x+ docker --version
Docker Compose (v2 plugin) ≥ 2.20 2.24+ docker compose version
openssl ≥ 1.1.1 3.x openssl version

⚠️ 必须使用 Docker Compose v2（`docker compose` 命令，无连字符），不支持 `docker-compose` v1 Python 版本。

1.3 硬件最低配置

场景 CPU 内存 磁盘
核心7件套（最小评估） 2核 ≥4 GiB ≥10 GiB 空闲
+summary/speech/docs/drive 4核 ≥8 GiB ≥30 GiB
+全套（含search/fleet所有模块） 8核 ≥16 GiB ≥50 GiB SSD

⚠️ 以上为单机评估参考值，来自 docker/README.md 说明（≥4 GiB/≥10 GiB）。生产资源规格待产品管家确认。

1.4 网络与域名

  • 对外唯一端口：HTTP 28080（默认）或 HTTPS 28443（默认），仅需在防火墙开放这一个端口
  • 内部服务端口全部绑定 127.0.0.1，不对外暴露
  • 域名/IP：准备一个可被客户端访问的域名（如 octo.example.com）或 IP 地址（如 192.168.1.100）
  • 证书：自签名证书由 docker-compose-setup.sh 自动生成；生产环境请使用可信 CA 证书（Let's Encrypt 等）
  • Docker 网络：compose 自动创建 octo-net 网桥（默认子网 172.28.0.0/24）

二、步骤0：克隆部署仓库

# 内部部署仓库（根据实际地址替换）
git clone  octo-deployment
cd octo-deployment/docker

仓库路径：`source-repos-internal/octo-deployment/`，实际部署时替换为客户侧部署包路径。

三、步骤1：环境准备

3.1 自动方式（推荐）：运行 docker-compose-setup.sh

cd octo-deployment/docker

# 最简用法：一个参数指定域名/IP
./docker-compose-setup.sh octo.example.com

# 指定内网镜像仓库 + LLM 网关（内网部署示例）
./docker-compose-setup.sh 192.168.216.98 \
  --registry hub2.intra.mlamp.cn/octo \
  --llm-url https://llm-gateway.mlamp.cn \
  --llm-key sk-****

# 指定 HTTPS 端口（默认 28443）
OCTO_HTTPS_PORT=443 ./docker-compose-setup.sh octo.example.com

# 自定义启用哪些模块（默认全启）
COMPOSE_PROFILES=summary,speech,docs,drive ./docker-compose-setup.sh octo.example.com

# 强制重新生成证书和 .env（⚠️ 会覆盖已有密钥，已运行的生产禁用）
FORCE=true ./docker-compose-setup.sh octo.example.com
  • 证书生成在 certs/fullchain.pem（公开证书/信任锚）和 certs/privkey.pem（私钥，chmod 600）
  • .env 生成在当前目录（chmod 600）
  • nginx 443 server block 被自动启用

3.2 手动方式：从 .env.example 开始（不推荐）

cp .env.example .env   # 如果存在 .env.example
# 或者直接创建空 .env，逐项填入以下必填项
环境变量 用途 生成命令 长度要求
OCTO_DOMAIN 对外访问域名/IP 手动填写 —
MYSQL_ROOT_PASSWORD MySQL root 密码 openssl rand -hex 16 仅允许 [A-Za-z0-9._-]
MINIO_ROOT_PASSWORD MinIO root 密码 openssl rand -hex 16 ≥8 字符
OCTO_MINIO_APP_PASSWORD MinIO 应用用户 octo-app 密码 openssl rand -hex 24 仅允许 [A-Za-z0-9._-]
OCTO_MASTER_KEY OCTO 主加密密钥（32字节） openssl rand -hex 16 必须恰好 32 hex 字符
OCTO_NOTIFY_INTERNAL_TOKEN 服务间 HMAC 鉴权令牌 openssl rand -hex 32 ≥32 hex；禁止 CHANGE_ME 占位
OCTO_WUKONGIM_MANAGER_TOKEN WuKongIM Manager API 令牌 openssl rand -hex 32 ≥32 hex；禁止 CHANGE_ME 占位
OCTO_ADMIN_PWD 首次创建的超管密码 openssl rand -base64 18 非空即生效
OCTO_MARKETPLACE_DB_PASSWORD Marketplace DB 密码 openssl rand -hex 16 不能是字面默认 "marketplace"
模块 变量 生成命令
summary OCTO_SUMMARY_DB_PASSWORD, OCTO_SUMMARY_READER_PASSWORD openssl rand -hex 16 (各一个)
summary LLM_API_URL, LLM_API_KEY, LLM_MODEL（默认 claude-sonnet-4-6） 手动填写 LLM 网关信息
speech SPEECH_DB_PASSWORD, SPEECH_ADMIN_PASSWORD, SPEECH_ADMIN_JWT_SECRET hex 16/16/32
speech VOICE_QWEN_URL, VOICE_QWEN_KEY（默认 qwen 引擎） 手动填写语音 API
docs OCTO_DOCS_DB_PASSWORD, OCTO_DOCS_COLLAB_SECRET, OCTO_DOCS_ATTACHMENT_SECRET hex 16/32/32
drive OCTO_DRIVE_DB_PASSWORD openssl rand -hex 16
fleet FLEET_POSTGRES_PASSWORD, FLEET_JWT_SECRET, FLEET_LOOP_CREDENTIAL_HMAC_KEY hex 16/32/32

3.3 TLS 证书手动准备（如不用 setup.sh）

mkdir -p certs
# 将你的证书文件放到 certs/ 目录下：
#   certs/fullchain.pem — 完整证书链（含 CA）
#   certs/privkey.pem   — 私钥
chmod 600 certs/privkey.pem
# 同时需手动取消 nginx 443 端口、certs 挂载、drive AWS_CA_BUNDLE 的注释

四、步骤2：核心服务启动

2.1 启动核心基础服务（无 profile）

cd octo-deployment/docker

# 启动核心服务（mysql/redis/minio/wukongim/nginx/octo-server/web/admin/marketplace + 所有 init 容器）
docker compose up -d

# 等待所有服务 healthy（--wait 阻塞等待）
docker compose up -d --wait
  1. `preflight` — 检查密钥非空、非 CHANGE_ME 占位符
  2. `mysql` — 冷启动 30-90s，首次启动运行 `init-extra-dbs.sh` 创建各模块 DB
  3. `minio` + `minio-init` — 创建 IAM 用户 octo-app + 13 个 bucket + 匿名下载策略
  4. `wukongim` — 启动 IM 长连接服务
  5. `market-preflight` — 幂等创建 octo_marketplace 库和用户
  6. `octo-server` — 核心后端启动（start_period 60s）
  7. `botfather-robot` — 设置 botfather 用户 robot=1
  8. `nginx` + `web` + `admin` + `marketplace` — 前端和网关

2.2 查看启动状态

# 查看所有容器状态
docker compose ps

# 查看实时日志
docker compose logs -f

# 查看特定服务日志
docker compose logs -f octo-server

五、步骤3：健康检查

# 服务 健康检查 URL/命令 预期输出 常见失败原因
1 nginx curl -s http://localhost:28080/_nginx_up 200 ok nginx 配置错误/证书缺失
2 mysql docker compose exec mysql mysqladmin ping -h 127.0.0.1 -u root -p"$MYSQL_ROOT_PASSWORD" --silent mysqld is alive 首次启动 init 脚本错误；密码含特殊字符
3 redis docker compose exec redis redis-cli ping PONG —
4 minio curl -s http://localhost:29000/minio/health/live 200 MINIO_ROOT_PASSWORD < 8 字符
5 wukongim curl -s -H "token: $OCTO_WUKONGIM_MANAGER_TOKEN" http://localhost:25001/health 200 token 不对；start_period 内还在初始化
6 octo-server curl -s http://localhost:28081/v1/ping pong（或类似文本） 依赖服务未就绪；OCTO_MASTER_KEY 长度不对
7 web curl -s -o /dev/null -w "%{http_code}" http://localhost:28083/ 200 octo-server 未 healthy
8 admin curl -s -o /dev/null -w "%{http_code}" http://localhost:28082/admin/ 200 octo-server 未 healthy
9 marketplace curl -s http://localhost:28080/market/healthz（经 nginx） 200 DB 密码不对；market-preflight 未执行
10 HTTPS curl -sk https://localhost:28443/_nginx_up 200 ok 证书路径错误；nginx 443 block 未启用 
# setup.sh 生成的环境可直接 curl
curl -s http://localhost:28080/_nginx_up && echo " ✅ nginx ok"
curl -s http://localhost:28080/v1/ping && echo " ✅ octo-server ok"
curl -sk https://localhost:28443/_nginx_up && echo " ✅ HTTPS ok"

六、步骤4：初始化超管账号

方式A（推荐）：.env 自动引导（docker-compose-setup.sh 默认支持）

  • 用户名：superAdmin
  • 密码：.env 中 OCTO_ADMIN_PWD 的值
# 查看自动生成的 admin 密码
grep OCTO_ADMIN_PWD .env

⚠️ 该引导是 one-shot：admin 行创建后重启不再执行。登录后请立即修改密码，并考虑从 `.env` 删除 `OCTO_ADMIN_PWD`。

方式B：手动创建（如果未设 OCTO_ADMIN_PWD）

# 生成 bcrypt hash
docker compose exec octo-server wget -qO- --post-data="..."  # 待验证：推荐通过API或直接SQL

# 直接SQL方式（在mysql容器内执行）
# 密码需要是 bcrypt hash；可用 htpasswd 或 python bcrypt 生成
# 角色必须是字符串 'superAdmin'

七、步骤5：开启内部模块（按 Profile 逐个开启）

开启 Profile 的通用方法

# 例如开启 summary 和 speech
# 编辑 .env，设置：
# COMPOSE_PROFILES=summary,speech
docker compose up -d
docker compose up -d --wait

5.1 开启 Summary（智能摘要）

  • 核心服务 healthy
  • LLM API 可用（LLM_API_URL/LLM_API_KEY/LLM_MODEL 已配置）
  • OCTO_SUMMARY_DB_PASSWORD/OCTO_SUMMARY_READER_PASSWORD 已生成
# 在 .env 中加入/修改：
# COMPOSE_PROFILES=summary
docker compose up -d
# summary-api 健康检查
curl -s http://localhost:28087/   # 直连 summary-api:8080
# 经 nginx 路由
curl -s http://localhost:28080/summary/api/v1/health   # 待验证：具体路径
# 查看容器
docker compose ps summary-api summary-worker

5.2 开启 Speech（语音转写）

  • 核心服务 healthy
  • 语音引擎 API 可用（默认 qwen，需 VOICE_QWEN_URL/VOICE_QWEN_KEY/VOICE_QWEN_MODELS）
  • SPEECH_DB_PASSWORD/SPEECH_ADMIN_PASSWORD/SPEECH_ADMIN_JWT_SECRET 已生成
# COMPOSE_PROFILES=speech
docker compose up -d
# speech-admin 控制台（仅 SSH 隧道可达）
ssh -L 28088:127.0.0.1:28088 user@host
# 浏览器访问 http://localhost:28088/speech-admin
# 登录后创建应用，获取 SPEECH_API_KEY
# 在 .env 中添加：
# SPEECH_API_KEY=sk-***
# 重启 octo-server
docker compose up -d --force-recreate octo-server

5.3 开启 Docs（文档协同）

  • 核心服务 healthy（mysql/redis/minio-init 均已完成）
  • OCTO_DOCS_DB_PASSWORD/OCTO_DOCS_COLLAB_SECRET/OCTO_DOCS_ATTACHMENT_SECRET 已生成（均 ≥32 hex）
# COMPOSE_PROFILES=docs
docker compose up -d
# docs-backend REST API
curl -s http://localhost:28080/api/v1/docs/  # 经 nginx
# 查看 docs-preflight/migrate 是否成功
docker compose logs docs-preflight
docker compose ps octo-docs-backend

5.4 开启 docs-html（HTML文档渲染，依赖docs）

  • 已启用 docs profile 且 octo-docs-backend healthy
  • DOCS_BACKEND_INTERNAL_REGISTER_TOKEN 已生成（32 hex）
# COMPOSE_PROFILES=docs,docs-html
docker compose up -d
curl -s http://localhost:28080/docs-html/   # 经 nginx
docker compose logs docs-html-migrate

5.5 开启 Drive（企业网盘）

  • 核心服务 healthy
  • OCTO_DRIVE_DB_PASSWORD 已生成
  • ⚠️ OCTO_DOMAIN 不能设为 localhost/127.0.0.1（drive-config 会警告，容器内无法访问宿主机 loopback）
# COMPOSE_PROFILES=drive
docker compose up -d
# drive 无 liveness probe（distroless 镜像），通过 nginx 验证
curl -s http://localhost:28080/v1/drive/   # 经 nginx
docker compose ps drive
docker compose logs drive-config drive-migrate

5.6 开启 Fleet/Loop（回路与运行时管理）

  • 核心服务 healthy（redis/octo-server healthy）
  • FLEET_JWT_SECRET（≥32 hex）、FLEET_LOOP_CREDENTIAL_HMAC_KEY（≥32 hex）已生成
  • 使用内置 PG 时还需 FLEET_POSTGRES_PASSWORD
# 使用内置 PostgreSQL：
# COMPOSE_PROFILES=fleet,fleet-db
# 使用外部 PostgreSQL（需设 FLEET_DATABASE_URL）：
# COMPOSE_PROFILES=fleet
docker compose up -d
# fleet-postgres 健康
docker compose exec fleet-postgres pg_isready -U fleet -d fleet
# fleet API
curl -s http://localhost:28089/healthz   # 直连
curl -s http://localhost:28080/fleet/api/healthz   # 经 nginx（待验证具体路径）
docker compose ps octo-fleet fleet-postgres

5.7 开启 Search（消息全文搜索）

  • 核心服务 healthy（尤其是 mysql/octo-server 已至少启动过一次，确保 octo_etl_es_cursor 表已由 octo-server migration 创建）
  • 预留足够内存（OpenSearch + Kafka 各约 0.5-1 GiB）
# COMPOSE_PROFILES=search
docker compose up -d
# 1. Kafka 启动
docker compose ps search-kafka
# 2. OpenSearch 启动（首次较慢）
curl -s http://localhost:29200
docker compose ps search-opensearch
# 3. search-kafka-init 创建 topic octo.message.v1 + .dlq
docker compose logs search-kafka-init
# 4. search-ensure 创建索引 octo-message + alias wukongim-messages-read
docker compose logs search-ensure
# 5. es-indexer 启动消费
docker compose ps es-indexer
# 待验证：脚本路径和参数
# cd octo-deployment/docker
# bash scripts/search-upgrade.sh
# 手动分步操作（脚本失败时参考）：
# 1. 种子游标（防止 producer 回放全历史）
COMPOSE_PROFILES=search,search-tools docker compose up -d search-cursor-seed
docker compose logs search-cursor-seed

# 2. 历史回填
COMPOSE_PROFILES=search,search-tools docker compose up -d search-backfill
docker compose logs -f search-backfill
# 等待 backfill 完成（exit 0）

# 3. 切换 octo-server 到 ES 搜索后端
# 在 .env 中设置：
# OCTO_SEARCH_BACKEND=es
# OCTO_SEARCH_PRODUCER_ON=true
docker compose up -d octo-server
# OpenSearch 集群健康
curl -s http://localhost:29200/_cluster/health | python3 -m json.tool
# 索引文档数
curl -s http://localhost:29200/wukongim-messages-read/_count
# Kafka topic 列表
docker compose exec search-kafka /opt/kafka/bin/kafka-topics.sh --bootstrap-server localhost:9092 --list

5.8 开启 doc-index（文档索引，依赖 docs+search）

# COMPOSE_PROFILES=docs,search,doc-index
docker compose up -d
# doc-indexer 健康检查（容器内端口3100，无host映射，需docker exec）
docker compose exec doc-indexer wget -qO- http://localhost:3100/readyz
# 预期：返回 ok
docker compose ps doc-indexer
docker compose logs doc-index-kafka-init doc-index-ensure
OCTO_DOCS_SEARCH_INDEX_ENABLED=true
OCTO_DOCS_SEARCH_ENABLED=true

5.9 开启 drive-index（网盘文件索引，依赖 drive+search）

# COMPOSE_PROFILES=drive,search,drive-index
docker compose up -d
# Tika 文本提取服务
curl -s http://localhost:9998/version   # tika（drive-index profile）
# drive-indexer（无 shell，通过日志验证）
docker compose logs drive-index-kafka-init drive-index-ensure
docker compose ps drive-indexer tika
OCTO_DRIVE_KAFKA_DISABLED=false
OCTO_DRIVE_SEARCH_DISABLED=false

5.10 Marketplace（默认启动）

curl -s http://localhost:28080/market/healthz
docker compose ps marketplace

八、步骤6：Nginx 验证与 HTTPS 配置

6.1 HTTP 验证

curl -s http://:28080/_nginx_up
# 预期：200 ok

curl -s http://:28080/_octo_up
# 预期：HTML 欢迎页

6.2 HTTPS 配置

curl -sk https://:28443/_nginx_up
# 预期：200 ok
  • certs/fullchain.pem — 服务器证书（含 CA 链）
  • certs/privkey.pem — 服务器私钥
# 将你的证书文件覆盖到 certs/ 目录
cp /path/to/your/fullchain.pem certs/fullchain.pem
cp /path/to/your/privkey.pem certs/privkey.pem
chmod 600 certs/privkey.pem
docker compose restart nginx
MINIO_SERVER_URL=https://:
TS_MINIO_DOWNLOADURL=https://:
TS_EXTERNAL_BASEURL=https://:
OCTO_WK_WSS_ADDR=wss://:/ws
docker compose up -d nginx octo-server minio

6.3 前置反向代理（推荐生产做法）

# 让栈内 nginx 只监听 loopback
echo "OCTO_NGINX_BIND=127.0.0.1" >> .env
docker compose up -d nginx

⚠️ 不能用 `ufw deny 28080` 代替——Docker 端口走 iptables DOCKER chain，ufw 规则不生效。

九、步骤7：首次登录验证

7.1 登录信息

项 值
Web 登录地址 https://:28443/（HTTPS）或 http://:28080/（HTTP）
管理后台地址 https://:28443/admin/
默认超管账号 superAdmin
默认超管密码 .env 中 OCTO_ADMIN_PWD 的值

7.2 功能检查清单

  • [ ] 登录成功，进入 Web 主界面
  • [ ] 能看到联系人列表
  • [ ] 能发送/接收文本消息
  • [ ] WebSocket 连接正常（浏览器 F12 → Network → WS，/ws 连接 101 Switching Protocols）
  • [ ] 能上传图片/文件（验证 MinIO presigned URL）
  • [ ] 头像/图片能正常显示（验证 MinIO 匿名下载策略）
  • [ ] 管理后台 /admin/ 能正常访问
  • [ ] 创建群聊，能邀请成员
  • [ ] （如启用 summary）左侧「智能总结」入口可见，能触发总结
  • [ ] （如启用 docs）左侧「文档」入口可见，能创建文档
  • [ ] （如启用 drive）左侧「网盘」入口可见，能上传文件
  • [ ] （如启用 fleet）管理员开启 dmloop 配置后左侧「回路」入口可见
  • [ ] （如启用 speech）用户设置→语音设置能开启，能使用语音输入转文字（⚠️Web端不能发送语音消息type=4）

7.3 前端入口开关

  1. 登录 `https://:28443/admin/`
  2. 进入「系统配置」
  3. 分别开启：`docs配置`、`drive配置`、`dmloop配置`（回路）、`dmpersonal配置`

十、部署验证 Checklist

  • [ ] 操作系统版本 ≥ Ubuntu 22.04 / Docker ≥ 24.0 / Docker Compose v2 ≥ 2.20
  • [ ] 磁盘空间 ≥ 10 GiB 空闲（全模块 ≥ 50 GiB）
  • [ ] .env 中所有密钥已生成（无 CHANGE_ME 占位符）
  • [ ] OCTO_MASTER_KEY 恰好 32 hex 字符
  • [ ] certs/fullchain.pem 和 certs/privkey.pem 已就位
  • [ ] docker compose up -d 无错误退出
  • [ ] 所有核心容器状态为 Up (healthy)
  • [ ] curl http://:28080/_nginx_up 返回 200 ok
  • [ ] curl http://:28080/v1/ping 返回正常响应
  • [ ] HTTPS curl -k https://:28443/_nginx_up 返回 200 ok
  • [ ] 能用 superAdmin + OCTO_ADMIN_PWD 登录 Web
  • [ ] WebSocket /ws 连接成功
  • [ ] 文件上传/下载正常
  • [ ] （按需）各内部模块 profile 已按顺序开启并验证
  • [ ] 管理后台功能门控已正确开启
  • [ ] 防火墙仅开放 28080/28443，内部端口仍绑定 127.0.0.1
  • [ ] 已备份 .env 文件到安全位置（密钥丢失 = 数据无法解密）

十一、常见报错与快速排查（Top 10）

1. preflight 容器 FATAL: XXX is still a CHANGE_ME placeholder

# 查看是哪个变量
docker compose logs preflight
# 重新生成
sed -i 's/^OCTO_NOTIFY_INTERNAL_TOKEN=.*/OCTO_NOTIFY_INTERNAL_TOKEN='$(openssl rand -hex 32)'/' .env
docker compose up -d

2. minio 容器反复重启，日志显示 "Server startup failed" 或密码长度错误

sed -i 's/^MINIO_ROOT_PASSWORD=.*/MINIO_ROOT_PASSWORD='$(openssl rand -hex 16)'/' .env
docker compose up -d minio minio-init

3. octo-server 启动失败，日志 "invalid master key" 或 "OCTO_MASTER_KEY length"

# 必须恰好 32 hex 字符 = openssl rand -hex 16
sed -i 's/^OCTO_MASTER_KEY=.*/OCTO_MASTER_KEY='$(openssl rand -hex 16)'/' .env
docker compose up -d octo-server

4. MySQL 启动后 init-extra-dbs.sh 报错或模块 DB 未创建

docker compose exec mysql mysql -u root -p"$MYSQL_ROOT_PASSWORD" -e "SHOW DATABASES;"
# 手动创建缺失的 DB（参考 scripts/init-extra-dbs.sh）

5. wukongim 健康检查失败，日志显示 token 认证错误

docker compose exec wukongim env | grep WK_MANAGERTOKEN
# 应与 .env 中 OCTO_WUKONGIM_MANAGER_TOKEN 一致

6. 浏览器访问显示证书不安全/自签名证书警告

  • 评估/内部使用：浏览器点"高级"→"继续访问"即可
  • 正式部署：替换 certs/ 下的证书为可信 CA 签发的证书
  • OpenClaw/octo-daemon 信任问题：参见 docker/README.md 的证书配置章节（设置 NODE_EXTRA_CA_CERTS/SSL_CERT_FILE）

7. drive 上传文件失败，HeadObject 报连接拒绝

sed -i 's/^OCTO_DOMAIN=.*/OCTO_DOMAIN=192.168.x.x/' .env
docker compose up -d drive-config
docker compose restart drive

8. fleet 容器启动慢/反复重启（start_period 300s 内未 ready）

docker compose logs octo-fleet
# 常见原因：DATABASE_URL 不对/JWT_SECRET 太短

9. search profile 启动后搜索无结果

grep OCTO_SEARCH_BACKEND .env
grep OCTO_SEARCH_PRODUCER_ON .env
# 应为 es 和 true
curl -s http://localhost:29200/wukongim-messages-read/_count
# 应返回文档数

10. docker compose down -v 误删其他实例数据

  • 部署前设置独立的 project name：
    •   export COMPOSE_PROJECT_NAME=octo-prod
  # 或在 .env 中加入 COMPOSE_PROJECT_NAME=octo-prod
  • down -v 前先确认卷名前缀：
    •   docker volume ls | grep "${COMPOSE_PROJECT_NAME:-octo}_"
  • 只删除 search 相关卷（不要项目级 down -v）：
    •   docker volume rm octo_opensearch-data octo_kafka-data octo_search-dlq-spill

十二、运维速查

启停命令

# 启动所有（含已启用的 profiles）
docker compose up -d

# 停止
docker compose stop

# 重启单个服务
docker compose restart octo-server

# 查看日志
docker compose logs -f --tail=100 

# 进入容器
docker compose exec octo-server sh

端口速查

端口 服务 说明
28080 nginx HTTP 主入口（0.0.0.0）
28443 nginx HTTPS 主入口（0.0.0.0，setup.sh 自动启用）
28081 octo-server REST 直连（127.0.0.1）
28082 admin 管理后台直连（127.0.0.1）
28083 web Web 直连（127.0.0.1）
28086 matter AI 助手/任务服务直连（127.0.0.1）
23306 mysql MySQL 直连（127.0.0.1）
26379 redis Redis 直连（127.0.0.1）
29000/29001 minio API/Console（127.0.0.1）
25001/25100/25200/25300 wukongim API/TCP/WS/Monitor（127.0.0.1）
25432 fleet-postgres Fleet PG 直连（127.0.0.1）
28089 octo-fleet Fleet 直连（127.0.0.1）
29092 kafka Kafka 外部（127.0.0.1）
29200 opensearch OpenSearch 直连（127.0.0.1）

卸载

# 停止并删除容器（保留数据卷）
docker compose down

# 停止并删除容器+数据卷（⚠️ 数据全丢，需打 YES 确认）
docker compose down -v

# 精确删除特定 profile 的卷（不影响核心数据）
docker volume rm octo_opensearch-data octo_kafka-data octo_search-dlq-spill
← 返回文档中心