跳到主要内容

Terminals（编排层）

Terminals 是面向 Open Terminal 的企业级编排层。它会为每个用户分配一个完全隔离的 terminal 容器，而不是让所有人共享一个容器。

快速导航

工作原理​

  1. 用户在 OPL 数据空间中启用 terminal
  2. OPL 数据空间把请求转给 orchestrator
  3. orchestrator 为该用户创建一个 Open Terminal 容器，或者恢复已有容器
  4. 所有流量都经由 orchestrator 代理，用户不会直接连到容器
  5. 空闲容器可按策略自动清理，数据可选持久化

它同时暴露与 Open Terminal 相同的工具接口，因此 AI 仍然能像平时一样执行命令、读文件、跑代码，只不过现在这些能力都被限定在“当前用户自己的容器”里。

部署​

前置条件​

用 Docker Compose 快速启动​

下面这个 Compose 文件会同时部署 OPL 数据空间和 Terminals orchestrator：

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - >-
        TERMINAL_SERVER_CONNECTIONS=[{
          "id": "terminals",
          "name": "Terminals",
          "enabled": true,
          "url": "http://terminals:3000",
          "key": "${TERMINALS_API_KEY}",
          "auth_type": "bearer"
        }]
    depends_on:
      - terminals

  terminals:
    image: ghcr.io/open-webui/terminals:latest
    environment:
      - TERMINALS_BACKEND=docker
      - TERMINALS_API_KEY=${TERMINALS_API_KEY}
      - TERMINALS_IMAGE=ghcr.io/open-webui/open-terminal:latest
      - TERMINALS_NETWORK=open-webui-network
      - TERMINALS_IDLE_TIMEOUT_MINUTES=30
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

.env 文件示例：

TERMINALS_API_KEY=change-me-to-a-strong-random-value

启动：

docker compose up -d

部署完成后， OPL 数据空间会在 http://localhost:3000 可用。用户激活 terminal 时，orchestrator 会自动为其创建独立容器。

Docker socket 访问

orchestrator 需要通过 /var/run/docker.sock 管理容器。生产环境建议配合 Docker socket proxy 来收窄权限。

常见配置项​

变量默认值说明
TERMINALS_BACKENDdocker当前部署模式
TERMINALS_API_KEY空OPL 数据空间与 orchestrator 共享密钥
TERMINALS_IMAGEghcr.io/open-webui/open-terminal:latest用户 terminal 的默认镜像
TERMINALS_PORT3000orchestrator 监听端口
TERMINALS_HOST0.0.0.0orchestrator 监听地址
TERMINALS_NETWORK空用户容器所加入的 Docker 网络
TERMINALS_DOCKER_HOST127.0.0.1无 TERMINALS_NETWORK 时用于 published ports
TERMINALS_DATA_DIRdata/terminals每用户工作目录数据位置
TERMINALS_IDLE_TIMEOUT_MINUTES0空闲超时
TERMINALS_MAX_CPU空CPU 上限
TERMINALS_MAX_MEMORY空内存上限
TERMINALS_OPEN_WEBUI_URL空若设置则改用 JWT 校验

局限性​

  • 单主机场景
  • 无内建高可用
  • 依赖 Docker socket

认证方式​

orchestrator 支持三种认证：

模式适用场景配置方式
OPL 数据空间 JWT生产推荐设置 TERMINALS_OPEN_WEBUI_URL
Shared API key常规部署OPL 数据空间与 orchestrator 共享 TERMINALS_API_KEY
Open仅开发环境不配置 JWT 也不配置 API key

故障排查​

Terminal 无法启动​

  1. 查看 orchestrator 日志
  2. 检查 TERMINALS_API_KEY 是否两边一致
  3. 如果使用私有镜像仓库，确认拉取权限已配置

认证失败​

  • JWT 模式下，确认 TERMINALS_OPEN_WEBUI_URL 可达
  • API key 模式下，确认 key 两边完全一致

容器被回收得太快​

调高 TERMINALS_IDLE_TIMEOUT_MINUTES，例如设为 30。

Connection refused​

  • Docker：确认 TERMINALS_NETWORK 已设置
  • Kubernetes：确认 orchestrator Service 对 OPL 数据空间 Pod 可达

延伸阅读​

License​

Terminals 需要 OPL 数据空间 Enterprise License 才能在生产中使用。