For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guide/quickstart-docker.md.
  • 简体中文
  • 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 容器。

    国内源(推荐)
    GitHub 源(官方)

    使用南京大学开源镜像站代理的 GHCR 镜像,国内网络访问更快、更稳定:

    docker run -d \
      --name octop \
      -p 8088:8088 \
      -v octop-data:/data/.octop \
      -e HOME=/data \
      ghcr.nju.edu.cn/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.yml)

    配置文件链接:docker-compose.cn.yml

    核心特点:

    • 免本地构建:直接使用南京大学 GHCR 镜像源 ghcr.nju.edu.cn/tencentcloud/octop:latest。
    • 无需克隆完整代码仓库:您可以单独下载该 YAML 文件直接启动。
    • 针对国内网络优化,彻底避免海外镜像拉取慢或失败的问题。

    使用步骤:

    # 步骤 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 仓库,也可以在仓库根目录直接执行:

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

    Docker Compose 核心配置解析

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

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

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

    2. 端口与数据持久化

        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):

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

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

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

    环境变量默认值作用与说明
    HOME/data必需为 /data,使容器内部 ~/.octop 解析到挂载的数据卷路径
    OCTOP_BIND_HOST0.0.0.0容器内部服务绑定的监听地址
    OCTOP_PORT8088服务监听端口
    OCTOP_LOG_LEVELinfo日志级别(debug、info、warning、error)
    OCTOP_ADMIN_USERNAMEadmin首次初始化管理员用户名
    OCTOP_ADMIN_DISPLAY_NAMEAdmin首次初始化管理员显示名称
    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_ENABLEDtrue是否启用 Langfuse 链路追踪与可观测性
    LANGFUSE_PUBLIC_KEY(空)Langfuse 公钥
    LANGFUSE_SECRET_KEY(空)Langfuse 密钥
    LANGFUSE_BASE_URL(空)自建或云端 Langfuse 服务地址

    首次登录与设置向导

    容器启动后,在浏览器中打开:

    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 后,输入向导口令解锁,即可在页面中设置管理员用户名与密码。

    查看凭据与向导口令

    # 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 命令随时修改密码:

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

    在页面中修改密码后,credential.txt 不会自动重写,以您在页面中设置的新密码为准。忘记密码时请参阅重置密码。


    常用运维操作

    升级镜像并保留数据卷的步骤见升级版本。

    # 查看实时运行日志
    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 末尾加斜杠)。