Octop 详细部署教程

1. 部署方式选择

Octop 提供多种安装方式，其中 Docker 部署最适合生产环境，具有数据持久化、环境隔离、升级便捷等优势。本教程将重点介绍 Docker 部署，同时涵盖其他可选方案。

部署方式 适用场景 推荐度
Docker Compose 生产环境、服务器部署 ⭐⭐⭐⭐⭐
一键安装脚本 个人电脑、快速体验 ⭐⭐⭐⭐
PyPI 安装 已有 Python 环境、开发者 ⭐⭐⭐

2. Docker 部署（推荐）

2.1 环境准备

确保服务器已安装 Docker 和 Docker Compose。建议配置：多核 CPU、4GB+ 内存，以及足够的磁盘空间用于数据库、Agent 工作区和文档语料库。

2.2 获取源码与配置

1
2
3
4
5
6
# 克隆仓库
git clone https://github.com/TencentCloud/Octop.git
cd Octop

# 创建环境配置文件
cp .env.example docker/.env

编辑 docker/.env，设置必要参数：

1
2
3
4
OCTOP_PORT=8088
OCTOP_ADMIN_USERNAME=admin
OCTOP_DEFAULT_PASSWORD=<你的强密码>
OCTOP_DATA=/srv/octop-data

⚠️ 重要提醒：OCTOP_DEFAULT_PASSWORD 仅在首次启动时生效。容器首次启动后，修改此变量不会改变已创建的管理员密码。密码策略要求至少 8 位，包含字母和数字。

2.3 关键安全配置（必读）

默认 Compose 文件会将端口绑定到所有网络接口 (0.0.0.0:8088)，这意味着仪表板会以明文形式暴露在公网，且使用默认密码。务必修改端口映射，使其仅监听本地回环：

编辑 docker/docker-compose.yml，找到 ports: 行：

1
2
3
4
5
# 修改前（危险）
- "${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"

# 修改后（安全）
- "127.0.0.1:${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"

这样只有通过反向代理才能从外部访问，直接暴露的端口无法被外网连接。

2.4 构建与启动

1
2
3
4
5
6
7
8
# 构建并启动
docker compose -f docker/docker-compose.yml up -d --build

# 检查状态
docker compose -f docker/docker-compose.yml ps

# 健康检查
curl http://127.0.0.1:8088/api/health

正常响应为 {"status":"ok","version":"..."}。

2.5 获取初始凭据

1
docker exec -it octop cat /data/.octop/credential.txt

首次启动会自动创建管理员账户，凭据写入上述文件。登录后请立即在「设置 → 用户」中修改密码。

2.6 配置反向代理（HTTPS）

生产环境强烈建议使用 Caddy 或 Nginx 作为反向代理，配置 TLS 加密。

Caddy 配置示例（自动申请证书、自动代理 WebSocket）：

1
2
3
octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

注意：Octop 通过 WebSocket 传输聊天内容，Nginx 需要额外配置 WebSocket 代理规则。

3. 一键安装脚本（个人电脑）

适用于 macOS、Linux 和 Windows，无需预装 Python——安装器会使用 uv 在 ~/.octop/ 下创建隔离的 Python 3.12 环境。

macOS / Linux：

1
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

Windows (PowerShell)：

1
irm https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.ps1 | iex

安装后开启新终端或执行 source ~/.zshrc，然后初始化并启动：

1
2
octop init    # 交互式向导，创建数据库和管理员账户
octop run     # 启动服务

打开 http://127.0.0.1:8088 即可访问。

可选扩展： 如需浏览器自动化或飞书通道支持，安装时添加 --extras 参数：

1
2
3
4
5
# 浏览器自动化
curl ... | bash -s -- --extras browser

# 飞书通道
curl ... | bash -s -- --extras channels-feishu

4. 配置 LLM 提供商

Octop 支持 OpenAI 兼容 API、DashScope (Qwen)、Ollama 等，需在仪表板或通过 octop provider 命令按 Agent 配置。

使用本地 Ollama 的注意事项： Docker 容器无法直接访问宿主机的 127.0.0.1:11434。需在 Compose 文件中添加：

1
2
extra_hosts:
  - "host.docker.internal:host-gateway"

然后将提供商 Base URL 设为 http://host.docker.internal:11434/v1。

⚠️ Ollama 安全警告：Ollama 默认无认证。如果将其端口暴露在公网，任何人都能免费使用你的模型服务器。建议仅允许 Docker 私有网段访问：sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp。

本地模型的隐藏问题：Agent 依赖工具调用，而系统提示词 + 工具定义 + 历史记录会构成很长的上下文。Ollama 默认上下文窗口较小，可能导致工具定义被截断，模型无法正确调用工具。建议将 num_ctx 提升至 16k 或 32k，并选择真正支持 Function Calling 的模型。

5. 版本升级与数据备份

1
2
3
4
5
# 升级（保留数据库、工作区、密钥和配置）
octop update

# 升级前务必备份
octop backup

数据库模式会在下次启动时自动迁移。跨大版本升级前务必先备份。

6. 常见问题排查

容器启动后无法访问？ 先检查日志：docker compose logs -f octop，再进行浏览器操作。

修改了 .env 但没生效？ Compose 只会将 .env 中同时在 environment: 下声明的变量传入容器。仅写入 .env 不会自动生效，也不会报错。

如何停用系统服务？

1
octop service stop

忘记管理员密码？ 如果使用 Docker 且密码已写入 credential.txt，可通过 docker exec 读取。若文件丢失，需要重建数据卷或使用管理命令重置。

7. 关键安全提醒

  1. 永远不要将 8088 端口直接暴露到公网，必须绑定 127.0.0.1 并通过反向代理访问。
  2. 首次登录后立即修改管理员密码。
  3. Ollama 等本地模型服务不要暴露在公网。
  4. 定期使用 octop backup 备份数据。
  5. 用户离职时：删除用户 → 轮换 JWT 密钥（octop admin rotate-jwt-secret）→ 通知其他用户重新登录。