私有化部署
Neutree Agent Platform — 私有化部署在你自己的 Kubernetes 集群上安装平台，从公共镜像仓库拉取镜像
一次安装能得到什么
这是 联网 / 在线 安装器：目标集群必须能访问公网。镜像直接从公共仓库（ghcr.io / docker.io / registry.k8s.io）拉取，前置 chart/manifest 也从各自的公共来源获取。没有离线镜像包、没有集群内仓库，也没有主机侧加载镜像的步骤。对于完全隔离网络的场景，另有一套离线安装器，提供镜像 tarball、集群内仓库和主机准备步骤。
核心平台（始终安装）
- Control plane — Agent 管理、调度、用户与 Workspace 管理
- Channel gateway — 外部事件（webhook、Slack 等）到达 Agent 的入口
- 数据层 — PostgreSQL（CloudNativePG）+ 共享 NFS
- Agent Workspace 运行时 — 每个 Workspace 一个 pod 运行 Agent；Agent 之间可以互相
@、共享文件并共用记忆存储
可选模块（默认关闭）
- Code Sandbox — 让 Agent 运行代码并提供临时 web 预览。由第三方 OpenSandbox 提供能力，需自行安装；平台通过
OPENSANDBOX_URL指向它 - Remote Browser — 让 Agent 驱动真实浏览器，用户通过 WebRTC 实时观看。内置 TURN 中继（coturn）和已发布的有头 Chromium 镜像
- LDAP — 让用户用 LDAP 账号登录
前置条件
基础设施
| 资源 | 要求 | 说明 |
|---|---|---|
| Kubernetes | v1.28+（多节点），或单个 k3s 节点（single-node profile） | 推荐 3 个及以上 worker |
| Worker 节点 | 至少 4 vCPU / 8GB 内存 | Agent pod 按 Workspace 动态创建 |
| 公共仓库访问 | 节点能从 ghcr.io、docker.io、registry.k8s.io 拉取镜像 | 仅在使用镜像源时才覆盖 REGISTRY |
| RWX 共享存储 | 支持 ReadWriteMany 的 CSI（最常见的是 NFS） | 承载 AFS 共享目录，默认 500Gi |
| RWO 卷存储 | 任何能运行 PostgreSQL 的 CSI（Ceph RBD、vSAN 等；同一套 NFS 也可以） | PostgreSQL 数据卷 + Agent Workspace 容器磁盘 |
网络
| 项目 | 要求 |
|---|---|
| 节点 IP | 至少一个用户可达的 worker IP（NodePort 会用到） |
| NodePort | 30000–32767 范围内 3 个空闲端口：TOS_NODE_PORT / BROWSER_NODE_PORT / SANDBOX_NODE_PORT |
| TURN 端口 | 启用 Remote Browser 的 TURN 中继时：在 coturn 节点上开放 3478/tcp+udp 和 49152-49252/udp |
| 存储可达性 | 所有节点都能挂载上面两个 storage class（NFS / 块存储 CSI 等） |
| 仓库可达性 | 所有节点都能从公共仓库拉取镜像 |
LLM API
平台不内置任何模型。根据启用的 Agent 类型，你需要提供协议兼容的 API endpoint：
| Agent 类型 | 所需 API 协议 |
|---|---|
| Codex | OpenAI Responses API（注意：不是 Chat Completions） |
| Claude Code | Anthropic API |
如果你现有的模型服务只支持 OpenAI Chat Completions API，一种做法是在其前面加一个转换代理，把 OpenAI Chat 协议转成 Anthropic 协议，再让 Claude Code 类的 Agent 指向该代理。
kubeconfig 权限
安装需要 cluster-admin — install.sh 会操作命名空间级管理员无法操作的资源（CRD、webhook、ClusterRole、StorageClass 等）。安装完成后可立即回收该权限；稳态运行时，control plane 通过它自己的集群内 ServiceAccount 鉴权，权限范围收得很紧（命名空间内的常规读写 + 仅对 nodes 的集群级 get/list）。
操作者的 kubeconfig 永远不会挂载进任何平台 pod。如果无法接受临时的 cluster-admin，这里给出一个等价的最小 ClusterRole。
等价的最小 ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: nap-installer
rules:
- apiGroups: [apiextensions.k8s.io]
resources: [customresourcedefinitions]
verbs: [get, list, watch, create, update, patch, delete]
- apiGroups: [admissionregistration.k8s.io]
resources: [validatingwebhookconfigurations, mutatingwebhookconfigurations]
verbs: [get, list, watch, create, update, patch, delete]
- apiGroups: [""]
resources: [namespaces]
verbs: [get, list, create, update, patch]
- apiGroups: [rbac.authorization.k8s.io]
resources: [clusterroles, clusterrolebindings, roles, rolebindings]
verbs: [get, list, watch, create, update, patch, delete]
- apiGroups: [storage.k8s.io]
resources: [storageclasses]
verbs: [get, list, create, update, patch]
- apiGroups: [postgresql.cnpg.io]
resources: ["*"]
verbs: ["*"]
- apiGroups: [opensandbox.alibaba.com]
resources: ["*"]
verbs: ["*"]
- apiGroups: ["", apps, batch, networking.k8s.io, policy]
resources: ["*"]
verbs: ["*"]
- apiGroups: [""]
resources: [nodes]
verbs: [get, list, watch]实际上这仍然接近 cluster-admin（在 core/apps/batch 这几个组上是 */*），但把资源逐项列出来会让安全评审更容易。
前置条件就绪后：