策略 (Policies)

策略（Policies）是具名的环境配置文件，用于定义终端容器的规格：镜像、资源限制、存储、环境变量和空闲超时。它们允许您从单个编排器为不同的团队提供不同的终端环境。

例如，您可以创建一个 data-science 策略，指定大型镜像、4 个 CPU 核心和 16 GiB 内存，而 development 策略则使用默认的 slim 镜像，配备 1 个 CPU 和 2 GiB 内存。

策略如何工作

管理员创建策略：通过编排器的 REST API 在编排器上创建策略（请参阅本页末尾的 API 参考）。
管理员创建终端连接：在 Open WebUI 中的 Settings → Connections → Open Terminal 下创建连接。每个连接都包含一个 policy_id 字段，将其映射到编排器上的特定策略。
用户打开终端：Open WebUI 将请求路由到 /p/{policy_id}/...，随后编排器配置（或重用）符合该策略规格的容器。

每个用户在每个策略下都会获得自己独立的容器。如果一个用户可以访问具有不同策略的两个连接，他们将获得两个独立的终端。

策略字段

所有字段均为可选。当省略某个字段时，编排器将回退到其全局默认值（通过环境变量设置）。

字段	类型	默认值	描述
`image`	string	`TERMINALS_IMAGE` · `ghcr.io/open-webui/open-terminal:latest`	要运行的容器镜像
`cpu_limit`	string	无限制	最大 CPU（例如，`"2"`、`"500m"`）
`memory_limit`	string	无限制	最大内存（例如，`"4Gi"`、`"512Mi"`）
`storage`	string	无（临时存储）	持久化卷的大小（例如，`"10Gi"`）。缺失时，容器将使用临时存储，容器被移除时数据将丢失。
`storage_mode`	string	`TERMINALS_KUBERNETES_STORAGE_MODE` · `per-user`	持久化卷的配置方式：`per-user`、`shared` 或 `shared-rwo`。请参阅存储模式。仅适用于 Kubernetes 后端。
`env`	object	`{}`	注入到容器内的键值对环境变量
`idle_timeout_minutes`	integer	`TERMINALS_IDLE_TIMEOUT_MINUTES` · `0`（已禁用）	容器在停止并移除前的无活动空闲时间（分钟）

存储模式

storage_mode 字段控制在 Kubernetes 后端如何分配持久化卷。它对 Docker 后端没有影响（Docker 后端总是直接绑定挂载宿主机目录）。

模式	行为	PVC 访问模式
`per-user`	每个用户获得自己专属的 PVC。完全隔离。	ReadWriteOnce
`shared`	所有用户共享单个 PVC，每个用户的数据存储在以其用户 ID 命名的 `subPath` 下。需要支持 ReadWriteMany 的存储类（例如 NFS、EFS）。	ReadWriteMany
`shared-rwo`	共享单个 ReadWriteOnce PVC。所有终端 Pod 都通过 Pod 亲和性（affinity）调度到同一个节点上（Kubernetes 确保它们全部运行在挂载了该卷的机器上）。在 ReadWriteMany 存储不可用时非常有用。	ReadWriteOnce

ReadWriteOnce (RWO) 意味着该卷一次只能被单个节点上的 Pod 挂载。ReadWriteMany (RWX) 意味着多个节点可以同时挂载并向该卷写入数据。

环境变量

env 字段在终端容器中以环境变量的形式注入任意的键值对。常见用途：

API 密钥：向用户提供对 LLM API、云服务等的访问权限。
出口过滤：设置 OPEN_TERMINAL_ALLOWED_DOMAINS 以限制出站网络访问（例如，"*.pypi.org,github.com"）。当存在此变量时，Docker 后端会自动为容器添加 NET_ADMIN 能力。
自定义配置：您的终端镜像支持的任何其他设置。

注意

策略中的环境变量对终端用户是完全可见的（他们可以在 shell 中运行 env 查看）。请勿在此处存储用户不应看到的敏感机密。

管理策略

您可以在 Open WebUI 管理面板中的 Settings → Connections → Open Terminal 下管理策略。在其中您可以创建、编辑和删除策略，将它们分配给终端连接，并按用户组限制访问。

信息

更新策略不会影响当前正在运行的终端。新规格将在下一次为该策略配置容器时应用（例如，在旧容器因空闲超时被回收或被手动删除之后）。

将策略连接到 Open WebUI

一旦在编排器上创建了策略，您就需要在 Open WebUI 中将其串联起来，以便用户可以访问。

1. 添加终端连接

在 Open WebUI 管理面板中，转到 Settings → Connections 并添加一个 Open Terminal 连接：

字段	值
URL	编排器的 URL（例如，`http://terminals-orchestrator:3000`）
API Key	编排器的 `TERMINALS_API_KEY`
Policy ID	您创建的策略名称（例如，`data-science`）

保存后，Open WebUI 会将该连接的所有请求通过编排器上的 /p/data-science/... 进行路由。

2. 使用用户组限制访问

每个终端连接都支持授权许可 (access grants)，用于控制哪些用户或用户组可以看到它。这允许您为不同的团队提供不同的策略：

[
  {
    "url": "http://orchestrator:3000",
    "key": "sk-...",
    "policy_id": "development",
    "config": {
      "access_grants": [
        { "principal_type": "group", "principal_id": "engineering", "permission": "read" }
      ]
    }
  },
  {
    "url": "http://orchestrator:3000",
    "key": "sk-...",
    "policy_id": "data-science",
    "config": {
      "access_grants": [
        { "principal_type": "group", "principal_id": "data-team", "permission": "read" }
      ]
    }
  }
]

在此示例中，研发团队（engineering）只能看到 development 终端，而数据团队（data-team）只能看到 data-science 终端。同时属于这两个组的用户则可以看到这两个终端。

全局资源限制

管理员可以在编排器上设置全局限制来**限制（clamp）**策略值，防止任何策略超出允许的最大值。这些限制在编排器本身的环境变量中设置：

环境变量	示例	描述
`TERMINALS_MAX_CPU`	`8`	任何策略可以请求的最大 CPU。请求更多 CPU 的策略会被静默限制为该值。
`TERMINALS_MAX_MEMORY`	`32Gi`	任何策略可以请求的最大内存
`TERMINALS_MAX_STORAGE`	`100Gi`	任何策略可以请求的最大持久化存储大小
`TERMINALS_ALLOWED_IMAGES`	`ghcr.io/open-webui/,gcr.io/my-org/`	以逗号分隔的通配符（glob）模式。如果设置，策略的 `image` 必须与至少一个模式匹配，否则请求将被拒绝并返回 HTTP 400。

这些限制在策略创建和更新时强制执行。如果策略的 cpu_limit 为 "16"，但 TERMINALS_MAX_CPU 为 "8"，则保存的值会被静默限制为 "8"。

提示

全局资源限制为平台管理员提供了一张安全网。他们可以将策略创建委托给团队主管，同时确保没有任何单一策略会消耗不合理数量的集群资源。

“default” 默认策略

如果您没有创建任何策略，也完全不需要担心。编排器开箱即用，会将其全局环境变量作为事实上的默认设置：

设置	环境变量
镜像	`TERMINALS_IMAGE`
空闲超时	`TERMINALS_IDLE_TIMEOUT_MINUTES`
存储模式	`TERMINALS_KUBERNETES_STORAGE_MODE`

当 Open WebUI 中的终端连接未设置 policy_id（或者编排器收到没有 /p/ 前缀的请求）时，将应用这种零配置回退。此时不需要数据库条目，这相当于单策略部署。

如果您随后在数据库中创建了名为 default 的策略，其字段将与全局设置合并（策略值优先）。

API 参考（用于程序化访问）

编排器上的所有端点均以 /api/v1 为前缀，并需要携带 Authorization: Bearer {TERMINALS_API_KEY} 请求头。

方法	终结点	描述
`GET`	`/policies`	列出所有策略
`POST`	`/policies`	创建新策略（Body：`{ "id": "...", "data": { ... } }`）。如果已存在则返回 409。
`GET`	`/policies/{policy_id}`	获取单个策略
`PUT`	`/policies/{policy_id}`	创建或更新策略（Body：包含 `PolicyData` 字段）
`DELETE`	`/policies/{policy_id}`	删除策略

请求体：PolicyData

{
  "image": "ghcr.io/open-webui/open-terminal:latest",
  "cpu_limit": "4",
  "memory_limit": "16Gi",
  "storage": "20Gi",
  "storage_mode": "per-user",
  "env": { "KEY": "value" },
  "idle_timeout_minutes": 60
}

所有字段均为可选。省略的字段将继承自编排器的全局默认值。

响应体：PolicyResponse

{
  "id": "data-science",
  "data": {
    "image": "ghcr.io/open-webui/open-terminal:latest",
    "cpu_limit": "4",
    "memory_limit": "16Gi",
    "storage": "20Gi",
    "env": { "OPEN_TERMINAL_ALLOWED_DOMAINS": "*.pypi.org" },
    "idle_timeout_minutes": 60
  },
  "created_at": "2025-06-01T12:00:00",
  "updated_at": "2025-06-01T12:00:00"
}

示例：多团队设置

一家拥有三个团队（研发、数据科学和实习生）的公司希望拥有不同的终端环境。

1. 在 Open WebUI 中创建策略

在管理面板的 Settings → Connections → Open Terminal 下，创建三个策略：

策略	镜像	CPU	内存	存储	空闲超时
`engineering`	默认	2	4Gi	10Gi	120 分钟
`data-science`	自定义数据科学镜像	8	32Gi	50Gi	60 分钟
`intern`	默认	1	1Gi	无	15 分钟

2. 创建终端连接

添加三个连接，全部指向同一个编排器 URL，但使用不同的 policy_id 值：engineering、data-science 和 intern。

3. 分配用户组

在每个连接上使用授权许可来限制可见性：

研发团队连接 → 分配给 engineering 组
数据科学连接 → 分配给 data-science 组
实习生连接 → 分配给 interns 组

属于 engineering 组的用户只能看到研发终端。数据科学家只能看到他们自己的终端。实习生获得有限的资源，并在无活动 15 分钟后自动清理。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.

策略如何工作​

策略字段​

存储模式​

环境变量​

管理策略​

将策略连接到 Open WebUI​

1. 添加终端连接​

2. 使用用户组限制访问​

全局资源限制​

“default” 默认策略​

请求体：PolicyData​

响应体：PolicyResponse​

示例：多团队设置​

1. 在 Open WebUI 中创建策略​

2. 创建终端连接​

3. 分配用户组​