Octop Docker 部署指南：Compose、数据卷与环境变量

Octop 提供了预构建的 Docker 镜像，将完整的平台——Web 页面、CLI、即时通讯通道和 Agent 运行时——打包在单个容器中。对于生产环境和多用户部署，推荐使用 Docker Compose，因为它开箱即用地处理了数据卷挂载和环境配置。您的所有数据都持久化保存在命名数据卷（或主机绑定挂载）中，因此升级永远不会影响您的对话、Agent 或凭据。

拉取并使用 Docker Compose 启动

在克隆仓库的根目录下，使用单个命令启动 Octop：

docker compose -f docker/docker-compose.yml up -d --build

Docker Compose 会从源代码构建镜像，将您主机的 ~/.octop 目录挂载到容器内的 /data/.octop，并以分离模式（后台）启动服务器。

如需传递自定义环境变量（API 密钥、端口覆盖等），请在运行命令前创建 docker/.env 文件：

cp .env.example docker/.env
# 编辑 docker/.env 填入您的配置，然后：
docker compose -f docker/docker-compose.yml up -d --build

提示

在 docker/.env 中设置 OCTOP_DATA 可以为所有持久化数据指定自定义主机目录。这样，您只需复制单个目录即可轻松备份或迁移整个 Octop 实例。首次管理员密码请设 OCTOP_DEFAULT_PASSWORD；不设则自动生成随机密码。

或使用独立的 docker run 启动

如果您不想使用 Compose，可以手动构建镜像并直接运行容器：

# 从源代码构建镜像
bash docker/docker_build.sh

# 运行容器
docker run -d \
  --name octop \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OCTOP_DEFAULT_PASSWORD="<自定义强密码；省略则自动生成>" \
  octop:latest

命名数据卷 octop-data 会在容器重启和升级期间持久化保存您的数据库、密钥和 Agent 工作区。镜像不包含 Playwright Chromium。若需要工作台浏览器自动化，请在宿主机用 --extras browser 重装，或在镜像中加入 browser extra。

说明

HOME=/data 环境变量是必需的，这样 ~/.octop 在容器内部才能解析为挂载了命名数据卷的 /data/.octop 路径。

打开页面并登录

容器启动后，打开浏览器访问：

http://localhost:8088

用 credential.txt 里的用户名和密码登录。Compose 默认把宿主机 ~/.octop 挂到容器 /data/.octop，所以两处是同一份文件：

# Compose（宿主机绑定挂载）
cat ~/.octop/credential.txt

# 命名卷或任意部署
docker exec octop cat /data/.octop/credential.txt

说明

用 OCTOP_ADMIN_USERNAME 覆盖用户名。裸机首次设置见快速开始。密码规则与改密方式见下方首次登录密码。

如需在打开页面前验证容器是否健康，请运行：

curl http://localhost:8088/api/health

配置模型提供商

Octop 内置了腾讯云、OpenAI、Anthropic、DeepSeek、Ollama 等大量预设。您可以直接从页面添加您的第一个提供商：

管理 → 模型

选择一个预置提供商，填入 API 密钥并启用。您也可以将常用的 API 密钥作为环境变量传递，以便它们在首次启动时立即对 Agent 运行时可用：

docker run -d \
  --name octop \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  -e OPENAI_API_KEY=sk-... \
  octop:latest

配置好提供商后，打开页面中的对话部分，开始您的第一次对话。

首次登录密码

入口脚本只在数据卷里还没有 octop.db 时执行一次 octop init，并把访问地址、用户名和密码写入容器内 /data/.octop/credential.txt（权限 600）。这不是裸机安装用的 ~/octop-login.txt。

情况	结果
未设置 `OCTOP_DEFAULT_PASSWORD`	生成 16 位随机密码并写入 `credential.txt`
你设置了符合策略的密码	按你的值初始化
你设置的密码过弱或过于常见	自动改用随机密码重试，首次初始化不会因此失败

密码须至少 8 位，同时包含字母和数字，且不能是常见弱口令（例如 password123、admin123、octop123）。可在 docker/.env 或 docker run -e 里设置 OCTOP_DEFAULT_PASSWORD。

登录后请立刻在头像菜单中点击修改密码，或运行：

docker exec -it octop octop user passwd <用户名> --password <密码>

在页面里改密后，credential.txt 不会自动更新，以页面里的新密码为准。能从网络访问的主机不要继续使用生成或引导密码。忘记密码时按安装方式重置，见重置密码。

环境变量

使用这些变量来配置 Octop 的 Docker 部署。对于 Docker Compose，请将它们添加到 docker/.env 文件中。对于 docker run，请使用 -e KEY=value 传递。

变量	默认值	描述
`OCTOP_PORT`	`8088`	容器内部 HTTP 监听端口
`OCTOP_DATA`	`~/.octop`	Compose 绑定挂载的主机目录（映射到容器内的 `/data/.octop`）
`HOME`	`/data`	必须为 `/data`，以便 `~/.octop` 解析到挂载的数据卷路径
`OCTOP_ADMIN_USERNAME`	`admin`	首次运行管理员用户名
`OCTOP_ADMIN_DISPLAY_NAME`	`Admin`	首次运行管理员显示名
`OCTOP_DEFAULT_PASSWORD`	(未设置)	首次运行管理员密码。未设置时自动生成随机密码并写入 `credential.txt`；被策略拒绝时回退为随机密码
`OPENAI_API_KEY`	—	OpenAI 兼容 API 密钥，提供给 Agent 运行时使用
`DASHSCOPE_API_KEY`	—	阿里云 DashScope（通义千问）API 密钥

说明

首次启动后请在头像菜单中修改密码。能从网络访问的主机不要继续使用生成或引导密码。

常用操作

# 跟踪容器日志
docker logs -f octop

# 在运行中的容器内执行 CLI 命令
docker exec -it octop octop --version

# 停止 Compose 栈
docker compose -f docker/docker-compose.yml down

# 在代码更新后重新构建并重启
docker compose -f docker/docker-compose.yml up -d --build