> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

**1. 拉取并使用 Docker Compose 启动**

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

```bash theme={null}
docker compose -f docker/docker-compose.yml up -d --build
```

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

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

```bash theme={null}
cp .env.example docker/.env
# 编辑 docker/.env 填入您的配置，然后：
docker compose -f docker/docker-compose.yml up -d --build
```

> [!TIP]
>
> 在 `docker/.env` 中设置 `OCTOP_DATA` 可以为所有持久化数据指定自定义主机目录。这样，您只需复制单个目录即可轻松备份或迁移整个 Octop 实例。

**2. 或使用独立的 docker run 启动**

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

```bash theme={null}
# 从源代码构建镜像
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。

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

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

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

```text theme={null}
http://localhost:8088
```

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

> [!NOTE]
>
> 用 `OCTOP_ADMIN_USERNAME` 和 `OCTOP_DEFAULT_PASSWORD` 覆盖默认值。裸机首次设置见[快速开始](https://octop.mintlify.site/zh/quickstart.md)。

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

```bash theme={null}
curl http://localhost:8088/api/health
```

**4. 配置模型提供商**

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

```text theme={null}
管理 → 模型
```

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

```bash theme={null}
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 密钥 |

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

## 常用操作

```bash theme={null}
# 跟踪容器日志
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
```

> [card] [物理机快速入门](https://octop.mintlify.site/zh/quickstart.md)
>
> 在不使用 Docker 的情况下，通过单行安装程序直接在 macOS、Linux 或 Windows 上安装 Octop。

> [card] [配置参考](https://octop.mintlify.site/zh/configuration/config-file.md)
>
> 查阅所有 `config.json` 配置项和环境变量覆盖，实现精细控制。

> [card] [飞牛 FnOS](https://octop.mintlify.site/zh/guides/fnos.md)
>
> 在飞牛 NAS 上安装 Docker 版或本地版 `.fpk`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.