部署
自托管拓扑
配置私有工作区服务的访问、数据与恢复边界。
自托管应从所需能力开始,而不是从“部署全部服务”开始。一个私有远程工作区与带有身份、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 提供工作区与运行时能力。管理性写入受 Host Approval 或范围化 Owner Token 门控,因此网络可达性本身不是权限模型。
入口
请求从哪里到达
设置窄范围 Host 和明确 Origins。不要为了方便而使用通配策略。
在本地 Server 进程之外负责外部 TLS 与路由。
工作区 API
Server 实际提供什么
Health、Capabilities、工作区状态、产物、文件、会话与审计数据。
客户端通向 Sidecar 的受支持路径。
写入权限
敏感操作如何获得许可
需要本地主机审批操作的常规门控。
供明确管理的自动化使用的范围化 Bearer 替代方案。
决定部署范围
- 只需要私有工作区: 部署工作区 Server 及其受支持 Sidecar 边界。
- 需要模型网关或计量: 只有在确实需要时才增加推理服务。
检查你实际拥有的路径
| Endpoint 或检查 | 用途 | 使用时机 |
|---|---|---|
GET /health | Server 存活、版本信息和基本可达性 | 进程与 Ingress 检查 |
GET /status | 当前 Server 状态 | 可达性已确认后的运维诊断 |
GET /capabilities | 支持的运行时特性 | 客户端兼容性与发布验证 |
GET /w/{workspaceId}/health | 范围化工作区存活状态 | 隔离单个远程或本地工作区故障 |
经由 Server 的 /opencode/* | 受支持 Sidecar 路径 | 检查执行边界,而不是直接调用 Sidecar |
将 IPOLLOWORK_APPROVAL_MODE=manual 作为常规运行姿态。任何 auto 的使用都应有明确的本地自动化范围、负责人和恢复路径。
生产检查清单
- 明确入口、应用、API、Worker、数据库与备份的真实拓扑。
- 文档化恢复、故障转移和紧急访问的负责人。
- 使用最强可用认证保护组织管理能力。
- 不要将密钥写入源码或审计日志。
- 在事故发生前验证备份恢复与故障转移。
服务上线前请完成健康检查、备份与恢复演练,见生产运维。