> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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 镜像，国内网络访问更快、更稳定：
```bash
docker run -d \
  --name octop \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  ghcr.nju.edu.cn/tencentcloud/octop:latest
```


**GitHub 源（官方）**

使用 GitHub Packages (GHCR) 官方镜像源，适合海外服务器或可直连 GitHub 的网络环境：
```bash
docker run -d \
  --name octop \
  -p 8088:8088 \
  -v octop-data:/data/.octop \
  -e HOME=/data \
  ghcr.io/tencentcloud/octop:latest
```


### 参数说明

| 参数                                | 说明                                                                                                      |
| --------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `--name octop`                    | 指定容器名称为 `octop`。                                                                                        |
| `-p 8088:8088`                    | 将容器内部的 8088 端口映射到宿主机 8088 端口。若需使用其他端口，例如 9090，可改为 `-p 9090:8088`。                                       |
| `-v octop-data:/data/.octop`      | 使用 Docker 命名数据卷 `octop-data` 持久化保存所有数据库、密钥与配置。容器重建或升级时数据不会丢失。若希望挂载宿主机目录，可改为 `-v ~/.octop:/data/.octop`。 |
| `-e HOME=/data`                   | **必需项**。将用户主目录指定为 `/data`，使容器内的 `~/.octop` 映射到挂载的数据卷路径 `/data/.octop`。                                  |
| `-e OCTOP_DEFAULT_PASSWORD="..."` | _(可选)_ 预设管理员密码（须 ≥8 位且同时包含字母与数字）。未设置时首次启动将进入 Web 设置向导。                                                  |

***

## 方式二：Docker Compose 部署

对于生产环境或需要持久化配置管理的多用户部署，推荐使用 Docker Compose。Octop 官方提供了两个版本的 Compose 配置文件：


**国内镜像源配置 (docker-compose.cn.yml)**

配置文件链接：[docker-compose.cn.yml](https://github.com/TencentCloud/Octop/blob/main/docker/docker-compose.cn.yml)
**核心特点**：
- **免本地构建**：直接使用南京大学 GHCR 镜像源 `ghcr.nju.edu.cn/tencentcloud/octop:latest`。
- **无需克隆完整代码仓库**：您可以单独下载该 YAML 文件直接启动。
- 针对国内网络优化，彻底避免海外镜像拉取慢或失败的问题。
**使用步骤**：
```bash
# 步骤 1：单独下载 Compose 配置文件（无需 git clone）
curl -fsSL https://raw.githubusercontent.com/TencentCloud/Octop/main/docker/docker-compose.cn.yml -o docker-compose.cn.yml

# 步骤 2：启动容器
docker compose -f docker-compose.cn.yml up -d
```
若您已克隆了 Octop 仓库，也可以在仓库根目录直接执行：
```bash
docker compose -f docker/docker-compose.cn.yml up -d
```


**标准 / 源码构建配置 (docker-compose.yml)**

配置文件链接：[docker-compose.yml](https://github.com/TencentCloud/Octop/blob/main/docker/docker-compose.yml)
**核心特点**：
- 包含构建指令（使用 `docker/Dockerfile` 进行前端与 Python 运行时的多阶段构建）。
- 镜像名称标记为 `octop:latest`。
- 适合海外网络环境，或者进行二次开发、修改代码后在本地重新构建镜像的用户。
**使用步骤**（需在克隆仓库的根目录下执行）：
```bash
# 启动容器（首次会自动从源码构建）
docker compose -f docker/docker-compose.yml up -d

# 修改代码后重新构建并启动
docker compose -f docker/docker-compose.yml up -d --build
```


***

## Docker Compose 核心配置解析

无论是 `docker-compose.cn.yml` 还是 `docker-compose.yml`，两者的服务配置与环境变量体系保持一致：

### 1. 服务与系统限制 (`services.octop`)

```yaml
services:
  octop:
    container_name: octop
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 65535
        hard: 65535
```

- **`restart: unless-stopped`**：保证容器崩溃或宿主机重启后自动恢复。
- **`ulimits.nofile`**：将最大文件描述符限制提高到 65535，确保在高并发 WebSocket 连接、Agent 多任务运行和大量文件读写时系统稳定。

### 2. 端口与数据持久化

```yaml
    ports:
      - "${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"
    volumes:
      - ${OCTOP_DATA:-~/.octop}:/data/.octop
```

- **`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`）：

```bash
cp .env.example docker/.env
# 编辑 docker/.env 填入自定义参数
```


> **说明**
> 
> `docker/.env` 仅用于 Compose 文件的变量插值。只有在 Compose 文件的 `environment:` 列表中声明的变量，才会真正进入容器内部。或者，您也可以将配置写入宿主机挂载目录下的 `~/.octop/env`。
> 


Compose 文件预置支持以下环境变量：

| 环境变量                       | 默认值       | 作用与说明                                        |
| -------------------------- | --------- | -------------------------------------------- |
| `HOME`                     | `/data`   | **必需为 `/data`**，使容器内部 `~/.octop` 解析到挂载的数据卷路径 |
| `OCTOP_BIND_HOST`          | `0.0.0.0` | 容器内部服务绑定的监听地址                                |
| `OCTOP_PORT`               | `8088`    | 服务监听端口                                       |
| `OCTOP_LOG_LEVEL`          | `info`    | 日志级别（`debug`、`info`、`warning`、`error`）       |
| `OCTOP_ADMIN_USERNAME`     | `admin`   | 首次初始化管理员用户名                                  |
| `OCTOP_ADMIN_DISPLAY_NAME` | `Admin`   | 首次初始化管理员显示名称                                 |
| `OCTOP_DEFAULT_PASSWORD`   | _(空)_     | 预设管理员密码（须 ≥8 位且同时包含字母与数字）。未设置时打开页面走设置向导      |
| `OCTOP_DATABASE_URL`       | _(空)_     | 外部数据库连接串（例如 PostgreSQL）                      |
| `OCTOP_DATABASE_DRIVER`    | _(空)_     | 数据库驱动，例如 `postgresql`                        |
| `OPENAI_API_KEY`           | _(空)_     | OpenAI 兼容接口 API 密钥，注入后直接供 Agent 运行时使用        |
| `DASHSCOPE_API_KEY`        | _(空)_     | 阿里云 DashScope（通义千问）API 密钥                    |
| `LANGFUSE_TRACING_ENABLED` | `true`    | 是否启用 Langfuse 链路追踪与可观测性                      |
| `LANGFUSE_PUBLIC_KEY`      | _(空)_     | Langfuse 公钥                                  |
| `LANGFUSE_SECRET_KEY`      | _(空)_     | Langfuse 密钥                                  |
| `LANGFUSE_BASE_URL`        | _(空)_     | 自建或云端 Langfuse 服务地址                          |

***

## 首次登录与设置向导

容器启动后，在浏览器中打开：

```text
http://localhost:8088
```

容器入口脚本会根据是否配置了 `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` 后，输入向导口令解锁，即可在页面中设置管理员用户名与密码。

### 查看凭据与向导口令

```bash
# Docker Compose 方式（宿主机绑定挂载 ~/.octop）
cat ~/.octop/octop-login.txt       # 设置向导解锁口令（未设密码时）
cat ~/.octop/credential.txt        # 凭据说明文件

# 仅 Docker 方式（命名数据卷 octop-data）
docker exec octop cat /data/.octop/octop-login.txt
docker exec octop cat /data/.octop/credential.txt
```

### 修改管理员密码

登录后请立即在右上角头像菜单中点击**修改密码**。您也可以在宿主机上通过 CLI 命令随时修改密码：

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


> **说明**
> 
> 在页面中修改密码后，`credential.txt` 不会自动重写，以您在页面中设置的新密码为准。忘记密码时请参阅[重置密码](/guide/guides/reset-password.md)。
> 


***

## 常用运维操作

升级镜像并保留数据卷的步骤见[升级版本](/guide/guides/upgrade.md)。

```bash
# 查看实时运行日志
docker logs -f octop

# 在容器内执行 CLI 命令（检查版本）
docker exec -it octop octop --version

# 停止并删除容器（仅 Docker 方式）
docker stop octop && docker rm octop

# 停止 Compose 服务
docker compose -f docker-compose.cn.yml down
# 或
docker compose -f docker/docker-compose.yml down

# 检查容器健康状态
curl http://localhost:8088/api/health
```

## 挂在子路径下

默认镜像假定站点在域名根路径。要发布到 `https://example.com/octop/`，用 `VITE_BASE_PATH=/octop/` 重新构建前端，并在反向代理里去掉这个前缀（`proxy_pass` 末尾加斜杠）。


[**物理机快速入门**](/guide/quickstart.md)

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

[**配置参考**](/guide/configuration/config-file.md)

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

[**在腾讯云中使用**](/guide/use-in-tencent-cloud.md)

用官方镜像在轻量或 CVM 上开通预装 Octop 的云主机。

[**飞牛OS**](/guide/fnos.md)

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