Octop Docker 部署指南:仅 Docker、Compose 与配置解析
Octop 提供了预构建的 Docker 镜像,将完整的平台——Web 页面、CLI、即时通讯通道和 Agent 运行时——打包在单个容器中。
:latest 和 :<version> 是精简镜像。虚拟桌面、OCR 和本地向量在 :<version>-full 与 :full 上。本地构建默认是完整版,除非传入 --build-arg OCTOP_IMAGE_VARIANT=lite。
根据使用场景,您可以选择以下部署方式:
- 仅 Docker(
docker run):单条命令快速拉取并启动,适合单机测试、NAS 或轻量环境。支持国内南京大学镜像加速源与 GitHub 官方源。 - Docker Compose(
docker compose):适合生产环境和持久化配置管理。官方提供免构建的国内镜像配置(docker-compose.cn.yml)与标准构建配置(docker-compose.yml)。
方式一:仅 Docker 运行(docker run)
如果您无需管理复杂的服务依赖,直接运行单条 docker run 命令即可启动 Octop 容器。
使用南京大学开源镜像站代理的 GHCR 镜像,国内网络访问更快、更稳定:
参数说明
方式二:Docker Compose 部署
对于生产环境或需要持久化配置管理的多用户部署,推荐使用 Docker Compose。Octop 官方提供了两个版本的 Compose 配置文件:
配置文件链接:docker-compose.cn.yml
核心特点:
- 免本地构建:直接使用南京大学 GHCR 镜像源
ghcr.nju.edu.cn/tencentcloud/octop:latest。 - 无需克隆完整代码仓库:您可以单独下载该 YAML 文件直接启动。
- 针对国内网络优化,彻底避免海外镜像拉取慢或失败的问题。
使用步骤:
若您已克隆了 Octop 仓库,也可以在仓库根目录直接执行:
Docker Compose 核心配置解析
无论是 docker-compose.cn.yml 还是 docker-compose.yml,两者的服务配置与环境变量体系保持一致:
1. 服务与系统限制 (services.octop)
restart: unless-stopped:保证容器崩溃或宿主机重启后自动恢复。ulimits.nofile:将最大文件描述符限制提高到 65535,确保在高并发 WebSocket 连接、Agent 多任务运行和大量文件读写时系统稳定。
2. 端口与数据持久化
OCTOP_PORT:默认监听8088端口。您可以通过环境变量指定自定义端口(例如OCTOP_PORT=9090)。OCTOP_DATA:默认将宿主机当前用户的~/.octop目录绑定挂载到容器内的/data/.octop。可通过OCTOP_DATA自定义宿主机路径(例如OCTOP_DATA=/var/lib/octop)。
3. 环境变量注入与 .env
Compose 文件支持使用 ${VAR:-default} 进行变量插值。您可以在 docker/ 目录下放置 .env 文件(可参考仓库中的 .env.example):
docker/.env 仅用于 Compose 文件的变量插值。只有在 Compose 文件的 environment: 列表中声明的变量,才会真正进入容器内部。或者,您也可以将配置写入宿主机挂载目录下的 ~/.octop/env。
Compose 文件预置支持以下环境变量:
首次登录与设置向导
容器启动后,在浏览器中打开:
容器入口脚本会根据是否配置了 OCTOP_DEFAULT_PASSWORD 自动处理初始化逻辑:
情况 A:已预设符合策略的密码
若您在 docker run -e 或 docker/.env 中提供了符合安全策略的 OCTOP_DEFAULT_PASSWORD(长度 ≥8 位,同时包含字母与数字,非弱口令):
- 容器首次启动会自动执行
octop init,创建管理员账号。 - 登录凭据会写入数据卷中的
credential.txt。 - 您可以直接在登录页使用管理员用户名(默认
admin)和该密码登录。
情况 B:未设置密码或密码较弱(设置向导)
若未设置 OCTOP_DEFAULT_PASSWORD,或者密码未通过强度策略:
- 容器不会静默重试或死循环,而是启动 Web 设置向导。
- 系统会生成一次性向导解锁口令,并写入数据卷中的
octop-login.txt(credential.txt中也会同步提示)。 - 浏览器打开
http://localhost:8088后,输入向导口令解锁,即可在页面中设置管理员用户名与密码。
查看凭据与向导口令
修改管理员密码
登录后请立即在右上角头像菜单中点击修改密码。您也可以在宿主机上通过 CLI 命令随时修改密码:
在页面中修改密码后,credential.txt 不会自动重写,以您在页面中设置的新密码为准。忘记密码时请参阅重置密码。
常用运维操作
升级镜像并保留数据卷的步骤见升级版本。
挂在子路径下
默认镜像假定站点在域名根路径。要发布到 https://example.com/octop/,用 VITE_BASE_PATH=/octop/ 重新构建前端,并在反向代理里去掉这个前缀(proxy_pass 末尾加斜杠)。

