OneCLI 自托管部署:每人一个沙箱代理
了解如何用 Docker Compose、PostgreSQL 和 VPS 自托管 OneCLI,为每个人运行独立沙箱代理,并由单一网关保管 API 密钥。注意每个代理默认需要 2 GiB 内存,1 GB VPS 不适用。
自托管 OneCLI 后的组成
自托管 OneCLI 后,团队中的每个人都可以拥有自己的代理。每个代理都运行在独立的沙箱中。API 密钥由代理无法读取的网关保存。安装结果是一套 Docker Compose 堆栈,后端使用 PostgreSQL,可通过 http://localhost:10254 访问。应使用配置充足的实际服务器。文档规定每个代理沙箱默认限制为 2 GiB 内存,因此应分别为基础堆栈和代理的实际工作内存预留资源。
该堆栈包含八个组件。了解各组件的职责后,后续内容会更容易理解。
- Web 控制面板(Next.js),端口
10254。用于创建代理、聊天、编辑记忆和技能,以及管理连接和密钥。 - API 服务器,端口
10256。控制平面,负责数据库、会话处理和工作队列。 - Rust 网关,端口
10255。拦截代理发出的出站请求,并注入凭据。 - Runner。README 将其描述为负责“启动、暂停和回收代理沙箱”的组件。它只处理出站连接,并且不会访问数据库。
- Sandbox Supervisor。README 将其描述为“在每个沙箱内运行,并使用与厂商无关的 harness 接口,因此可以替换代理运行时”。
- SSH 终止器,端口
10257。README 称其为“SSH 前门”:它使用 API 签发的短期证书终止 SSH 连接,并将每个会话桥接到代理的沙箱中。它与 Runner 使用相同的runner配置文件。 - Channel adapter。连接 Slack 应用的守护进程,使代理可以使用自己的名称在频道和私信中回复。
- PostgreSQL。随附的 compose 文件使用
postgres:18-alpine,并挂载pgdata卷。
名称虽为 CLI,但产品本质是服务器
OneCLI 是一个服务器平台。其名称容易让人误以为是安装在笔记本电脑上的命令行工具,但这种理解与本指南所描述的产品不符。确实存在一个独立的命令行客户端,位于 onecli/onecli-cli 仓库中,它负责将本地编码代理的流量通过网关进行路由。而您在此处部署的是一个多用户 Web 应用程序:它包含组织与邀请功能的账户系统、对话与密钥数据库,以及一个用于启动容器的运行器。
“按人分配”模型是整个设计的核心。README 中写道:“为每个人创建一个代理,授予该代理所需的访问权限,使其在沙箱中运行;流量通过网关路由,由网关注入凭据并执行您的策略。”每个代理都有自己的文件系统和 Shell、专属的对话页面、平台维护的记忆空间,以及您只需编写一次的技能。凭据的工作方式与常规设置相反。您无需将 API 密钥复制到每个人的环境中,只需存储一次密钥,并将其授权给允许使用的代理即可。
开始前主机需要满足的条件
- Docker,且 Compose 插件版本为 2.24.0 或更高版本。随附的 compose 文件使用带有
required: false的可选env_file映射,Docker 从 2.24.0 起支持该功能。文件中的迁移注释说明,所述的 2.19 最低版本要求是为了支持up --wait下的一次性依赖,但这并不涵盖文件中的可选环境文件。 - 内存,这是实际的限制因素。选择方案前,请先阅读下面的容量规划部分。
- 空闲的回环端口
10254、10255、10256、10257和5432。端口10257是 SSH 入口,本指南启用的runner配置会从该端口开始。
无需自行安装 PostgreSQL:compose 文件会将其作为服务运行。下面的设置向导要求主机已安装 Node.js 和 pnpm。修改代码本身还会使用 mise 固定工具链,其中包括网关使用的 Rust。
VPS 可以容纳多少个代理沙箱?
运行器文档提供了具体数值,而不是模糊估算。每个沙箱最多使用 2048 MB 内存(RUNNER_SANDBOX_MEMORY_MB)、1 个 CPU(RUNNER_SANDBOX_CPUS)和 512 个进程(RUNNER_SANDBOX_PIDS)。并发上限为 4(RUNNER_MAX_SANDBOXES)。文档建议,除基础服务栈外,额外预留约 10 GiB 可用内存,以满足该上限。
此图表背后的数据
[
{
"plan": "2 GB box",
"ram_gb": 2,
"sandbox_slots": 0
},
{
"plan": "4 GB box",
"ram_gb": 4,
"sandbox_slots": 1
},
{
"plan": "8 GB box",
"ram_gb": 8,
"sandbox_slots": 3
},
{
"plan": "16 GB box",
"ram_gb": 16,
"sandbox_slots": 7
},
{
"plan": "32 GB box",
"ram_gb": 32,
"sandbox_slots": 15
}
]这些槽位数量是算术结果,不是基准测试结果:用总内存减去 PostgreSQL 和其他长期运行服务假定占用的约 2 GB,再除以沙箱 2 GiB 上限。按此计算,2 GB box 可按完整内存上限为 0 个沙箱提供预算;0 表示在这些假设下没有足够预算支持完整内存上限,并不表示 Docker 拒绝启动代理。16 GB box 可容纳 7,明显高于默认的 4 个并发沙箱,也高于运行器文档要求的约 10 GiB 可用内存。32 GB box 可容纳 15。如果要同时运行超过 4 个沙箱,还需要提高 RUNNER_MAX_SANDBOXES。
有两点会影响上述计算。只要沙箱中有后台进程运行,它就不会进入停放状态,并会永久占用一个槽位。因此,应按持续负载而不是最繁忙的一分钟来规划 RUNNER_MAX_SANDBOXES。平台对此设有上限:默认情况下,每个运行器最多保持 RUNNER_MAX_SANDBOXES 减 1 个保持唤醒的沙箱,且不会少于 1 个;也可以通过 API 上的 MAX_HELD_AWAKE_SANDBOXES 覆盖该设置。超过上限后,运行器会驱逐空闲时间最长的沙箱,并将其监控的进程报告为丢失。内存和 CPU 使用量取决于工作负载。每个沙箱最多使用 1 个 CPU,因此 4 个繁忙的代理可以使用 4 个核心。但 2 GiB 内存设置是上限,而不是预留值:4 个空闲但保持唤醒的代理不会自动消耗 8 GiB。
可能需要修改的运行器设置
RUNNER_MAX_SANDBOXES(默认值:4):同时运行的沙箱数量。RUNNER_SANDBOX_MEMORY_MB(默认值:2048):每个沙箱的内存上限。RUNNER_SANDBOX_CPUS(默认值:1):每个沙箱的 CPU 上限。RUNNER_SANDBOX_PIDS(默认值:512):每个沙箱的进程上限。RUNNER_NETWORK_INTERNAL(默认值:true):使沙箱网络无法访问外部路由。保持启用。RUNNER_SANDBOX_NETWORK(默认值:onecli-sandboxes):沙箱加入的网络。RUNNER_RECONCILE_SECONDS(默认值:60):运行器协调状态的频率。RUNNER_ORPHAN_GRACE_SECONDS(默认值:3600):孤立容器和卷被销毁的存续时间。RUNNER_AGENT_IMAGE:覆盖沙箱镜像;否则镜像跟随ONECLI_VERSION。
使用 Docker Compose 安装 OneCLI
上游自托管文档中的原始步骤会将 3 个密钥写入 compose 文件旁的 docker/.env。该步骤遗漏了所启用服务需要的 runner token、Docker socket 组和 SSH 凭据,因此请先运行设置向导,再启动服务栈。
git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --wait运行前先阅读该代码块。heredoc 标记未加引号,因此 shell 会执行其中的每个 head -c 32 /dev/urandom | base64,并写入执行结果,而不是写入字面文本。SECRET_ENCRYPTION_KEY 是数据库中所有密钥使用的 AES-256-GCM 密钥。GATEWAY_INTERNAL_SECRET 用于对 gateway 向 API 进行身份验证。BETTER_AUTH_SECRET 用于签名会话 cookie。COMPOSE_PROFILES=runner 是最重要的一行,因为 runner 服务位于 Compose profile 后面:省略该行后,服务栈仍会正常启动,但不会启动任何 agent sandbox。
--wait 会等待服务处于运行或健康状态,并等待 migrations 依赖成功完成。因此,非零退出码是发现问题的第一个信号。然后查看实际启动了哪些服务。
docker compose ps
docker compose logs migrations固定版本。ONECLI_VERSION 会一次性为所有服务设置标签;除非 RUNNER_AGENT_IMAGE 指向其他位置,否则 agent sandbox 镜像也会使用该版本。使用不带前缀的版本号:已发布的镜像标签不包含 v 前缀。截至 1 November 2026,当前版本为 v2.17.0,于 31 October 2026 发布。将其添加到同一个文件中,然后按照文档说明的升级路径操作,使正在运行的 sandbox 也迁移到该镜像。
echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd docker此外还提供安装程序 curl -fsSL https://onecli.sh/install | sh,它会将配置写入 ~/.onecli/.env,并执行相同的操作。它会为本次运行设置 ONECLI_VERSION=latest,因此会覆盖仅保存在该 .env 文件中的版本固定值。Compose 路径允许您在任何内容运行前查看每个文件;如果主机上已经运行其他 Compose 服务栈,应使用此路径。上面的 checkout 设置通过 pnpm run setup --upgrade 升级。该路径要求主机安装 Node.js 和 pnpm;如果还要修改代码,则需要 mise 和 Rust 来构建 gateway,因此适合计划修改 OneCLI 的用户。对于 Kubernetes,版本 v2.11.0(8 October 2026)新增了 Helm chart;当前 chart 会使用带持久卷的 Jobs 运行 agent sandbox,不需要 Docker daemon,并记录了所需的密钥、数据库和路由配置。
从笔记本访问控制面板
随附 compose 文件中的每个已发布端口都绑定到 ${ONECLI_BIND_HOST:-127.0.0.1}。在 VPS 上,这表示控制面板正在运行,但服务器外部无法访问它。这是正确的默认设置。保留该设置,并建立隧道:
ssh -N -L 10254:127.0.0.1:10254 you@your-server现在在笔记本上打开 http://localhost:10254。流量通过 SSH 连接传输,因此公网中不会暴露未加密的控制面板,也无需为额外端口配置防火墙规则。
设置 ONECLI_BIND_HOST=0.0.0.0 会通过明文 HTTP 发布控制面板,同时发布 PostgreSQL;如果未设置 POSTGRES_PASSWORD,则使用 compose 文件中的默认密码 onecli。它还会在端口 10257 上发布 SSH 入口服务,而该服务会挂载 Docker socket。如果多人需要访问控制面板,请在前面配置支持 TLS(传输层安全)的反向代理,并保留绑定主机设置不变。将 ONECLI_EXTERNAL_URL 设置为其 HTTPS URL,并使用上游项目的反向代理配置,将控制面板、API 和网关路径路由到各自的服务。代理本身不能阻止陌生人访问。自托管文档说明,注册按设计处于开放状态,没有可关闭注册的开关:任何能够访问控制面板的人都可以创建账户,并获得自己的组织;只有加入您的组织才需要邀请。文档建议将控制面板置于网络边界之后。如果该代理已经为其他自托管应用提供入口,则通过 自托管的单点登录层转发身份验证,可让控制面板使用团队已有的登录方式;这样,在一个位置移除用户也会同时关闭这条访问路径。
创建第一个账户,然后授予模型密钥
打开控制面板后立即创建账户。每个新账户都会获得自己的组织,团队成员通过邀请加入您的组织。此后注册仍保持开放,这也是控制面板应放在隧道或经过身份验证的代理之后的另一个原因。如果您从不支持登录的旧版本升级,请立即注册:自托管文档说明,现有数据会归属于第一个注册的账户。因此,在可访问的主机上,您应确保该账户属于您。
然后在创建代理前存储模型密钥。托管代理需要已授予的模型密钥,顺序很重要:先在控制面板中存储密钥,再将其授予代理,最后开始对话。如果跳过授权,沙箱就不会启动;代理会在对话线程中回复,说明它需要模型密钥。
请限制授权范围。每个代理只能使用您授予它的内容,网关会在每次请求时强制执行这些限制。因此,只读取一个代码仓库的代理无法访问您的支付服务提供商密钥。相同的授权列表也可用于控制支出。允许某个用户的代理调用您拥有的任何模型,就相当于为该用户单独生成一份账单。因此,在分发十个代理前,建议先阅读如何限制代理在模型调用上的支出。
网关如何避免在代理端保存密钥
该网关是使用 Rust 编写的 HTTPS 代理,监听 10255 端口。代理端的 HTTP 客户端指向该网关,代理端携带占位凭据,而不携带真实凭据。网关根据代理端的授权检查出站请求,解密真实密钥,将其替换到请求中,然后转发请求。密钥使用 AES-256-GCM(高级加密标准、256 位、伽罗瓦/计数器模式)加密后存储在 PostgreSQL 中,仅在请求时解密。每次调用都会记录代理端身份和目标地址,形成审计跟踪;如果密钥分散在 10 个人的 shell 配置文件中,则无法获得这样的审计记录。
部署方式取决于以下两项机制。
- HTTPS 拦截属于中间人攻击。网关生成本地证书颁发机构,代理端信任该证书颁发机构。网关先终止代理端的 TLS 连接,再与上游服务建立新的 TLS 连接。因此,如果代理端的 HTTP 客户端不信任网关的证书颁发机构,它会报告证书验证错误,而不是身份验证错误。
- 代理端使用
Proxy-Authorization请求头标识自身。在同一台主机上,代理端与网关共享内部 Docker 网络,该请求头不会经过任何不受您控制的网络。将主机外的代理端指向网关时,应使用 VPN 或 TLS 传输保护连接,因为该请求头是持有者令牌;对于原始 CONNECT 代理端口,上游建议使用 VPN。
需要明确的是:网关会按设计以明文读取代理端发出的每个请求。它是主机上最敏感的进程。应相应保护运行该网关的主机,并通过 最小权限 Linux 用户限制可登录该主机的人员数量。
运行器为何不需要入站端口
运行器仅发起出站连接。其文档说明:“它不占用任何公网可访问的端口,因此笔记本电脑、家庭实验室或位于 NAT 后面的 VPC 都可以在不配置入站连接、隧道或 TLS 终止的情况下运行。”NAT 是网络地址转换,也就是家用路由器执行的功能。运行器向控制平面发起连接并从中拉取任务,因此无需转发任何连接,也无需开放任何端口。
这种设计在沙箱网络中很有用。compose 文件定义了第二个标记为 internal: true 的网络;在 Docker 中,这表示该网络无法连接外部网络。沙箱会加入此网络。网关同时连接两个网络,因此它是唯一的出网路径。运行器文档明确说明了这一点:“让网关同时连接到一个 internal 网络,才能使仅通过网关出站成为实际边界,而不是建议。”代理无法通过直接连接外部地址来绕过网关;仍由网关策略决定允许哪些请求。
请在自己的主机上进行确认,不要只相信上面的说明。
docker network ls
docker network inspect onecli-sandboxes | grep -i internal您应看到 "Internal": true。如果显示 false,则出站控制未启用,网关又只是一个建议。请使用 docker network ls 输出的沙箱网络名称,因为 onecli-sandboxes 只是默认值。
OneCLI 沙箱的隔离强度如何?
请仔细阅读本节。因为项目自己的说明中反复强调“沙箱化”,但具体机制记录在 runner 文档和后端代码中。
README 称,每个代理都有“自己的隔离沙箱,其中包含文件系统和 shell”,并称 Sandbox Supervisor 是“在每个沙箱内运行的组件,通过供应商无关的 harness 接口通信,因此可以替换代理运行时”。这两句话都没有说明隔离由什么构成。runner 文档给出了答案:默认后端是 Docker(RUNNER_BACKEND=docker),沙箱是一个 Docker 容器,设置了内存上限、CPU 上限和进程数上限,并连接到内部网络。代码为其他后端保留了扩展接口。当前 runner 代码还实现了 Kubernetes 后端,Helm chart 使用该后端创建沙箱 Job 和持久卷。在本指南的 Compose 安装中,沙箱是一个 Docker 容器。
runner 文档现在说明了 Docker 隔离边界:代理以 node 运行,具有 no-new-privileges,并且已删除所有 Linux capabilities,同时使用 Docker 的默认 seccomp 配置文件。后端只将代理的持久化 home 目录挂载到沙箱中。因此,应采用较为严格的解读。这里的限制是资源限制。内部网络确实限制了出站访问。代理与主机之间的隔离依赖这些容器控制机制,而容器与主机共享内核。
还需要考虑另一个事实。runner 服务挂载了 /var/run/docker.sock,因为它需要通过该 socket 创建沙箱。访问 rootful Docker daemon 的 socket 等同于拥有主机上的 root 权限,因为能够调用该 API 的用户可以启动一个容器,并将主机文件系统挂载到容器内。随附的 Docker 后端 runner 使用了这个 socket。因此,runner 进程与 gateway 一样敏感。SSH terminator 也挂载同一个 socket,以便在沙箱容器中执行命令;Compose 文件中的注释也明确指出,在主机上,这种挂载等同于 root 权限。因此,除非有充分理由对外开放,否则应将 10257 端口限制在 loopback 上。
请谨慎对待共享内核这一隔离边界。实际操作中,这意味着遵循以下三点。
- 在一台不运行其他业务的主机上运行 OneCLI。不要在其上运行无关的生产服务、共享数据库,也不要存放其他团队的数据。
- 假设获得沙箱内任意代码执行能力的代理可能触及主机,并通过将备份保存在该主机之外,使这一结果可恢复。
- 在向同事说明代理已被隔离之前,先阅读
apps/runner/src,或向上游项目维护者确认。
如需了解文档化隔离边界应如何描述,以及应向上游提出哪些问题,请将本节与真实代理沙箱隔离边界的样子进行比较。关键在于:文档所述机制是否覆盖了您需要阻止的威胁。
许可证划分,以及构建前检查的原因
OneCLI 的核心部分采用 Apache-2.0 许可证,允许在生产环境中自行托管。名为 ee/ 的目录适用单独的 OneCLI Enterprise License:开发、测试和评估可免费使用,生产环境使用则需要订阅。2026 年 8 月 18 日发布的 v2.0.1 版本说明提到,项目恢复了可被 GitHub 检测到的 Apache-2.0 许可证文件,因此仓库页面上的许可证标识最近发生了变化。请检查实际部署的 tag,不要依据其他日期编写的摘要。
cd onecli && find . -type d -name ee -not -path '*/node_modules/*'这些路径下的内容都属于商业部分。如果计划依赖的功能位于其中,请先确认价格,再围绕该功能构建流程。
升级、迁移,以及不能丢失的那个文件
升级必须更新服务镜像和独立的代理镜像,然后重启正在运行的沙箱。每次 up 时,都会先运行一次性迁移服务,再启动 API。如果迁移失败,堆栈会拒绝启动,而不是在模式只完成部分迁移的情况下继续提供服务。这正是需要的行为,因为升级失败会表现为服务中断,而不是静默数据损坏;docker compose logs migrations 说明了原因。
有一个步骤很容易遗漏。自托管文档警告不要仅使用裸 docker compose pull && docker compose up -d 进行升级,因为代理沙箱镜像不是 Compose 服务。它是 Runner 上的 RUNNER_AGENT_IMAGE 值,因此 docker compose pull 永远不会处理它。这样,托管代理可能会在没有任何警告的情况下继续使用旧的沙箱镜像。更新代码检出版本,修改该固定值,然后运行文档规定的升级工具。该工具会拉取沙箱镜像并重启正在运行的沙箱。
cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations将 2.17.0 替换为要升级到的版本。重启沙箱会中断正在进行的工作,但每个代理的持久化工作区都会保留。
如果使用安装脚本完成安装,应重新运行该脚本,而不是手动拉取镜像。这样可以确保 compose 文件与其引用的镜像保持同步。如果需要指定版本,请先导出 ONECLI_VERSION,因为该脚本会覆盖仅保存在其 .env 文件中的固定版本。
备份数据库、配置和代理工作区卷。PostgreSQL 保存代理、会话、记忆和加密密钥。docker/.env 文件保存 SECRET_ENCRYPTION_KEY。没有该密钥,即使数据库的其他内容已恢复,加密密钥也无法读取。每个代理的 /workspace 都位于独立的持久化卷上,也需要单独备份。
cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup将这些备份和工作区备份保存在服务器之外。该流程与任何有状态 Compose 堆栈所需的流程相同。因此,如果你已经定期备份和升级 Docker Compose 堆栈,只需将数据库、配置和工作区卷加入其中,然后无需再额外处理。
无法正常工作
- 整个服务栈始终未进入正常状态,并且
docker compose up -d --wait以非零状态退出。先查看docker compose logs migrations,因为 API 会有意等待该服务。 - Agent 一直处于空闲状态,且没有出现 sandbox。确认
COMPOSE_PROFILES=runner位于docker/.env中,并确认docker compose ps列出了一个 runner。然后检查该 agent 是否获得了模型密钥,因为没有模型密钥时不会启动 sandbox。 - 没有剩余 slot。
RUNNER_MAX_SANDBOXES的默认值为 4。运行后台进程的 sandbox 会一直占用其 slot,直到达到保持唤醒上限并被逐出。docker ps可显示当前实际运行的内容。 - 服务栈无法启动,Docker 报告端口已被占用。启用
runnerprofile 后,SSH 入口除了其他 4 个端口外,还需要使用10257。 - 容器消失,或主机运行缓慢。使用
dmesg -T | grep -i oom检查内存是否耗尽;默认内存上限允许单个 sandbox 使用最多 2048 MB。 - Agent 的 HTTPS 请求因证书验证错误而失败,而不是因身份验证错误而失败。其 HTTP 客户端不信任网关的证书颁发机构。
- 删除 agent 后,旧容器或卷仍然存在。runner 每 60 秒执行一次状态协调,并销毁存在时间超过
RUNNER_ORPHAN_GRACE_SECONDS的孤立对象。RUNNER_ORPHAN_GRACE_SECONDS的默认值为 3600,因此应等待 1 小时后再判断这是内存泄漏。
这适合您运行吗?
适用性测试非常简短。当多个人都需要一个 Agent,且您希望将凭据集中管理时,OneCLI 是合适的选择:只需维护一个存储库、查看一份审计日志,并在一个控制面板中撤销某人的访问权限。这是一个实际的运维难题,而将 API key 复制到 6 台笔记本电脑上并不是好的解决方案。
对于个人用户而言,这套架构过于复杂且没有收益。为了运行一个 Agent 而部署 PostgreSQL、控制平面、网关和运行器,会带来不必要的开销;当密钥仅由您一人持有,网关所解决的凭据问题几乎不存在。建议在小型服务器上运行单个 harness:在 VPS 上运行单个 Agent harness 可以用极少的内存完成该任务。如果您尚未确定方向,自托管 AI Agent 对比 中的调查报告是更经济的起步方式。如果您不熟悉的是 Agent 本身而非其运行的服务器,请先完成 学习 Agent 工作原理的分阶段路径,因为理解工具调用(tool call)和内存存储(memory store)的实际作用,才能决定应授予每个人的 Agent 哪些权限。
FAQ
自托管 OneCLI 的最低服务器要求是什么?
需要 Docker Compose plugin 2.24.0 或更高版本、Node.js 和 pnpm(用于本文的设置向导),以及足够的内存。PostgreSQL 已包含在 compose 文件中,无需单独安装。内存决定了规划方式:runner 默认将每个 agent sandbox 限制为 2048 MB,其文档要求在基础堆栈之外预留约 10 GiB 可用内存,以支持默认的 4 个 sandbox。按照图表假定的 2 GB 基础堆栈预算,4 GB 服务器可按每个 sandbox 的完整上限运行 1 个 sandbox,16 GB 服务器可达到默认并发上限。这些是规划参考值,不是经过测量的最低要求,也不是固定的内存分配。
OneCLI 是否需要 PostgreSQL,还是可以使用 SQLite?
需要 PostgreSQL。文档将 DATABASE_URL 定义为 PostgreSQL 连接字符串,随附的 compose 文件使用 postgres:18-alpine 和 pgdata 卷,并由独立的迁移服务在 API 启动前应用数据库架构。文档没有提供 SQLite 选项。使用外部 PostgreSQL 服务器时,应将 API 和迁移服务都配置为使用该服务器;随附的 compose 文件将它们的连接字符串设置为内置 PostgreSQL 服务。
OneCLI agent sandbox 是否是真正的安全边界?
文档中的 Compose 机制使用 Docker 容器,并设置内存、CPU 和进程数限制。容器连接到标记为 internal: true 的网络,因此外部流量会通过网关。出口流量控制确实生效,可以使用 docker network inspect 验证。agent 以 node 身份运行,配置了 no-new-privileges,删除了所有 Linux capability,并使用 Docker 的默认 seccomp 配置文件,但仍共享宿主机内核。runner 和 SSH 终止器都会挂载 /var/run/docker.sock;在使用 rootful Docker daemon 的主机上,这相当于获得 root 权限。请在专用服务器上运行 OneCLI,并将备份保存到其他服务器。
OneCLI 是否需要开放入站端口?
不需要。runner 只发起出站连接,不监听外部网络可访问的端口,因此无需隧道即可在 NAT 后运行。默认情况下,compose 文件会将 dashboard、gateway、API、PostgreSQL,以及在 runner profile 下的 SSH 入口(端口 10257)绑定到 127.0.0.1。可以通过 SSH 隧道访问 dashboard;如果需要让多人访问,则使用上游提供的反向代理配置,并配置 TLS 以及所需的 dashboard、API 和 gateway 路由。请注意,任何能够访问注册入口的人都可以注册。端口 10255 上的 gateway 供 agent 使用;在单服务器部署中,这些 agent 会通过内部 Docker 网络访问它。
在公司内部使用 OneCLI 是否免费?
核心组件采用 Apache-2.0 许可,允许在生产环境中自托管使用,无需商业许可。名为 ee/ 的目录受 OneCLI Enterprise License 约束;该许可可免费用于开发、测试和评估,但生产环境需要订阅。目录划分会随版本发布而变化。2026 年 8 月 18 日发布的 v2.0.1 说明提到恢复了可被 GitHub 识别的 Apache-2.0 许可文件,因此在基于某项功能构建工作流之前,请检查你要部署的确切 tag 中的 LICENSE 和 ee/ 目录。