iPolloWork Docs
部署

自托管拓扑

配置私有工作区服务的访问、数据与恢复边界。

自托管应从所需能力开始,而不是从“部署全部服务”开始。一个私有远程工作区与带有身份、RBAC、共享提供商和托管 Worker 的组织部署具有不同拓扑。

从真实 Server 边界开始

apps/server 打包了基于文件系统的 iPolloWork Server。它可以使用编译后二进制运行,无需在运行时安装 Bun;也可在贡献仓库时从源码运行。

# 编译后二进制
ipollowork-server --workspace /srv/ipollowork/workspace --approval manual

# 在 iPolloWork Checkout 中从源码运行
pnpm --filter ipollowork-server dev -- \
  --workspace /srv/ipollowork/workspace \
  --approval manual

Server 的默认配置文件是 ~/.config/ipollowork/server.json。其中可以定义监听 Host 与 Port、审批模式与超时、显式工作区列表和允许的 CORS Origins。环境变量可覆盖这些类别,以及 Host/Owner Token、OpenCode 连接、Token Storage 和运行时相关行为。

Server 信任边界让本地工作区 API 保持私有且明确

Server 提供工作区与运行时能力。管理性写入受 Host Approval 或范围化 Owner Token 门控,因此网络可达性本身不是权限模型。

01
入口

请求从哪里到达

绑定 Host 与 CORS

设置窄范围 Host 和明确 Origins。不要为了方便而使用通配策略。

远程时的 TLS 终止

在本地 Server 进程之外负责外部 TLS 与路由。

02
工作区 API

Server 实际提供什么

状态与工作区路由

Health、Capabilities、工作区状态、产物、文件、会话与审计数据。

受支持的 OpenCode 代理

客户端通向 Sidecar 的受支持路径。

03
写入权限

敏感操作如何获得许可

Host Approval

需要本地主机审批操作的常规门控。

Owner Token

供明确管理的自动化使用的范围化 Bearer 替代方案。

决定部署范围

  • 只需要私有工作区: 部署工作区 Server 及其受支持 Sidecar 边界。
  • 需要模型网关或计量: 只有在确实需要时才增加推理服务。

检查你实际拥有的路径

Endpoint 或检查用途使用时机
GET /healthServer 存活、版本信息和基本可达性进程与 Ingress 检查
GET /status当前 Server 状态可达性已确认后的运维诊断
GET /capabilities支持的运行时特性客户端兼容性与发布验证
GET /w/{workspaceId}/health范围化工作区存活状态隔离单个远程或本地工作区故障
经由 Server 的 /opencode/*受支持 Sidecar 路径检查执行边界,而不是直接调用 Sidecar

将 IPOLLOWORK_APPROVAL_MODE=manual 作为常规运行姿态。任何 auto 的使用都应有明确的本地自动化范围、负责人和恢复路径。

生产检查清单

  1. 明确入口、应用、API、Worker、数据库与备份的真实拓扑。
  2. 文档化恢复、故障转移和紧急访问的负责人。
  3. 使用最强可用认证保护组织管理能力。
  4. 不要将密钥写入源码或审计日志。
  5. 在事故发生前验证备份恢复与故障转移。

服务上线前请完成健康检查、备份与恢复演练,见生产运维。