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

使用 Docker Compose 或独立的 docker run 命令部署 Octop。包括数据卷挂载、环境变量和首次运行设置。

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

1. 拉取并使用 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 实例。

2. 或使用独立的 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=Octop123 \
     octop:latest
   

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

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

3. 打开页面并完成首次设置

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

   http://localhost:8088
   

   首次启动会创建固定管理员：用户名 admin，密码 Octop123。Octop 把凭据写进容器内的 /data/.octop/credential.txt。这不是随机密码，也不是裸机安装用的 ~/octop-login.txt。登录后请立刻改密。

   用 OCTOP_ADMIN_USERNAME 和 OCTOP_DEFAULT_PASSWORD 覆盖默认值。裸机首次设置见快速开始。

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

   curl http://localhost:8088/api/health
   
4. 配置模型提供商

   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 的 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_DEFAULT_PASSWORD	Octop123	首次运行管理员密码（Docker 引导）
OPENAI_API_KEY	—	OpenAI 兼容 API 密钥，提供给 Agent 运行时使用
DASHSCOPE_API_KEY	—	阿里云 DashScope（通义千问）API 密钥

首次启动后请到管理 → 用户修改密码。能从网络访问的主机不要继续使用 Octop123。

​

常用操作

# 跟踪容器日志
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

物理机快速入门

在不使用 Docker 的情况下，通过单行安装程序直接在 macOS、Linux 或 Windows 上安装 Octop。

配置参考

查阅所有 config.json 配置项和环境变量覆盖，实现精细控制。

飞牛 FnOS

在飞牛 NAS 上安装 Docker 版或本地版 .fpk。