自托管拓扑
规划私有部署时，将本地 Work 运行时与组织控制平面明确分离。
自托管应从所需能力开始，而不是从“部署全部服务”开始。一个私有远程工作区与带有身份、RBAC、共享提供商和托管 Worker 的组织部署具有不同拓扑。
执行工作区工作的本地 Server 与可选组织控制平面分离。入口、服务归属、数据和恢复边界必须明确。
- 01入口
TLS、路由、健康检查和组织公共访问入口。
- 02控制平面
可选身份、团队、RBAC、策略、共享模型和 Worker 生命周期。
- 03工作区运行时
执行 iPolloWork 工作区任务的本地或远程 Server。
- 04数据与恢复
数据库、备份、审计导出、恢复负责人和故障转移流程。
从真实 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 与路由。
Server 实际提供什么
Health、Capabilities、工作区状态、产物、文件、会话与审计数据。
客户端通向 Sidecar 的受支持路径。
敏感操作如何获得许可
需要本地主机审批操作的常规门控。
供明确管理的自动化使用的范围化 Bearer 替代方案。
决定部署范围
- 只需要私有工作区： 部署工作区 Server 及其受支持 Sidecar 边界。
- 需要组织控制平面： 部署 Web 与 Controller 服务，负责身份、团队、策略和管理。
- 需要模型网关或计量： 只有在确实需要时才增加推理服务。
检查你实际拥有的路径
| 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、数据库与备份的真实拓扑。
- 使用健康检查，避免单节点控制平面。
- 文档化恢复、故障转移和紧急访问的负责人。
- 使用最强可用认证保护组织管理能力。
- 不要将密钥写入源码或审计日志。
- 在事故发生前验证备份恢复与故障转移。
本地工作不依赖 Cloud 控制平面。让面向用户的 Work 客户端保持在本地 Server 路径上，只有确实出现身份、策略、连接器或托管 Worker 需求时，才增加组织服务。发布门控与恢复证据见 生产运维。