Collabora Online 私有化部署指南拆解进程隔离与多副本负载均衡的架构设计【免费下载链接】onlineIssue tracker only. Active development is on Gerrit at https://gerrit.collaboraoffice.com/.项目地址: https://gitcode.com/gh_mirrors/on/online文档要不要继续放在公有 SaaS 上这是不少企业架构评审里的老话题。Collabora Online 是 Collabora 主导的开源项目一套可以私有化部署的在线协作办公套件基于 LibreOffice 内核在浏览器里对文档、表格、演示文稿做多人实时协同编辑并通过 WOPI 协议对接 Nextcloud、ownCloud、Seafile 等存储。文件始终躺在你自己的存储里它只负责编辑这一件事。本文结合项目仓库里的镜像构建脚本与 Helm chart把它的组件分工、多副本调度、安全边界和上线步骤一次讲清。一、为什么企业想把文档协作搬回自己的机房 把文档协作完全交给公有 SaaS通常卡在三个问题上数据主权与合规合同、图纸、财报这类文件出境或托管在第三方存储上可能直接触发合规红线。网络环境政务、军工、制造行业的大量办公终端在内网外网 SaaS 根本不可达离线环境需要一套能整体落地的在线办公套件。成本与锁定按席位订阅的费用随人数线性增长数据迁移还受制于对方的导出能力。自建的思路是把编辑引擎和文件存储拆开文件继续放在现有的存储系统里只把在线编辑能力私有化。Collabora Online 正是按这个思路设计的——它不托管文档而是以 WOPIWeb-Based Open Platform Interface客户端的身份去访问你的存储没有现成存储时也可以让它直接读写本地文件系统。核心能力包括文档、电子表格、演示文稿的浏览器端实时协作多人光标与选区同步ODF 与 OOXML.docx/.xlsx/.pptx双格式保真转换版本历史与修订追踪与存储端的版本能力打通通过JWT / 令牌机制完成用户与文档权限的校验Docker 镜像与 Helm chart 交付Kubernetes 环境原生支持自动扩缩容。需要说明仓库的分工这个项目在 GitHub 上的仓库承担 Issue 跟踪与发布产物每晚构建的容器镜像、Helm chart、构建脚本管理源码开发在 Collabora 的 Gerrit 上进行。因此本文引用的文件路径都来自仓库内真实存在的部分例如 docker/ 下的镜像构建与 Seccomp 配置、kubernetes/helm/collabora-online/ 下的完整 Helm chart。二、wsd 与 kit 的分工一份文档在系统里如何流转理解这套架构先看一次打开文档并编辑的完整请求链路。可以把它想象成一家餐厅wsd 是前台负责所有对外连接——TLS 终结、身份校验、文档会话的生命周期管理、与浏览器的长连接。它很轻不做任何排版计算。kit 是后厨承载 LibreOffice 核心引擎真正执行解析、排版与渲染。每打开一个文档系统就为该文档单独派生一个 kit 进程。两者之间是独立的内部通信通道浏览器的 WebSocket 帧由前台转给后厨对应的进程渲染结果再原路返回。一次典型编辑会话的流程客户端携带 WOPI 请求参数打开文档前端经反向代理到达 wsdwsd 校验 JWT 令牌与文档权限随后拉起或复用该文档的kit 进程建立 WebSocket 通道kit 把版面切分、渲染前端负责合成与交互回显多名协作者同时输入时各自的改动在同一个 kit 进程内合并浏览器端只看到最终版面与光标的同步更新。这个一文档一进程的选择是刻意的隔离粒度做到进程级。单个文档崩溃、内存泄漏代价只损失这一个 kit 进程不会波及其他编辑会话。进程之外还叠了沙箱kit 进程运行在 chroot 环境内与系统调用白名单构成多层防御。三、多副本部署下的粘性会话与故障转移设计水平扩展时一个矛盾绕不开副本本身应该是无状态的才好扩缩但编辑状态却实实在在活在某个副本的 kit 进程内存里。同一文档如果一会儿落到 A 副本、一会儿落到 B 副本两个副本就会各起各的 kit 进程编辑操作互相打架。项目的解法是按文档做会话粘性session affinity反向代理层对请求中的文档标识参数chart 里的hashParam默认取WOPISrc即文档在存储端的 URL做哈希保证同一文档的所有请求、包括 WebSocket 升级与重连始终落到同一个副本副本本身不保存跨副本共享的状态所以可以随时增减副本某个副本被重建时只有落在它上面的文档会话会中断重连其余文档不受影响。配套细节都藏在 chart 配置里值得逐条看编辑是长连接场景反向代理的proxyTimeout默认3600 秒HAProxy、OpenShift Route 等前端代理的 WebSocket 超时注解也同步调到这一档避免连接被中途掐断探针为慢启动留足窗口startup 探针 30 次 × 3 秒等于给副本90 秒冷启动时间加载 LibreOffice 引擎不是一件快事readiness 连续 2 次失败才摘流liveness 连续 4 次失败才重建自动扩缩默认从2 个副本起步、上限 100 个触发线是 CPU 70% 与内存 50%。隔离纵深方面docker/cool-seccomp-profile.json 是一份 844 行的 Seccomp 策略覆盖 x86_64、AArch64、MIPS 系列架构defaultAction设为SCMP_ACT_ERRNO即默认拒绝白名单只放行 32 项系统调用。kit 进程能触碰内核的口子被压到最小即使单文档进程被攻破横向移动的空间也非常有限。Helm chart 内置了 DaemonSetinstallCOOLSeccompProfile可以把这份策略分发到各节点的 kubelet seccomp 目录再配合 Pod 的securityContext启用。无状态副本带来的另一个好处是滚动升级新副本先接新流量旧副本上的文档会话自然收敛不需要把状态迁到 Redis 之类的中心存储里——会话状态跟着文档走文档跟着粘性路由走。四、用 Docker 镜像和 Helm chart 上线前的检查清单 ⚙️生产部署不需要从源码编译官方每晚构建镜像Helm 默认拉取docker.io/collabora/codekubernetes/helm/collabora-online/ 下的 chart 覆盖了从 Service、Ingress 到监控的完整拓扑。从源码构建docker/from-source-gh-action/Dockerfile主要用于定制开发。安装前对照下面几项server_name必须与对外访问域名一致。副本位于反向代理之后时这个值决定 WebSocket 升级与文档 URL 的生成配错是最常见的页面白屏、连接断开根因。多域名部署用aliasgroups声明别名组。资源预算副本规格resources默认留空需要自己拍。可执行算法估算峰值并发文档数每个文档进程按256MB起步预算大型文件、密集批注要上浮副本内存请求 ≈ 并发文档数 × 单文档预算 × 1.3。副本数 2 起步扩缩看 CPU/内存双指标。配置覆盖方式coolwsd_xml_content/coolkitconfig_xcu_content是整体替换容器内默认的 coolwsd.xml 与 coolkitconfig.xcu不是片段合并——覆盖前要先取回默认全文再改。热更新配置dynamicConfig模块单独起一个 nginx对外提供 coolwsd.xml改完无需重启副本即可生效适合需要频繁调参的环境。字体customFonts通过 PVC 挂载字体文件中文环境务必补齐 CJK 字体否则渲染出现方框。管理端点收口/cool/adminws/、/cool/getMetrics、/browser/dist/admin/admin.html必须挡在外网之外chart 提供了专门的拒绝代理nginxDeny来完成这件事。五、认证、WOPI proof key 与可观测性配置安全与监控是私有化落地后最先要接好的两块。JWT 与 WOPI proof key 各管什么用户认证走 JWT存储端或自建网关为每次文档请求签发令牌wsd 验签通过后才会放行文档级权限也在令牌声明里体现WOPI proof key是服务对密钥存储端用它对文档请求签名防止任意来源伪造文档请求。chart 支持两种管理方式——proofKeyGeneration自动在首个安装时生成 4096 位 RSA 密钥并存入 Helm 管理的 Secret或proofKeysSecretRef指向自建 Secret。GitOpsArgo CD / Flux 这类用helm template渲染的工具场景下建议固定 Secret自动生成的方式依赖回读集群里的现有 Secret纯渲染模式每次都会生成新密钥导致 WOPI 校验反复失败。监控接什么指标chart 内置 PrometheusRule 与 Grafana 面板grafana_dashboards/ 里的 overview 与 ha-allocation 两块默认告警规则直接可用重点盯这几个重复文档比例doc_info去重 0 说明同一文档在多个副本上各起了 kit 进程粘性路由配置有问题error_unauthorized_request持续增长——JWT 配置错误或节点时钟漂移error_storage_connections上升——到存储端的 WOPI 通道断了每副本文档数 / 总文档数与观看者数——决定扩缩容节奏的先行指标503 服务不可用计数——副本级故障信号。ha-allocation 面板在多副本环境下尤其有用一眼看出文档在副本间是怎么分布的粘性是否失效一目了然。六、什么团队适合上 Collabora Online什么场景别硬上适合的场景有 Kubernetes 或 Docker 运维能力、数据合规敏感的企业要一套可审计、可离线运行的在线协作办公套件已经在跑 Nextcloud / ownCloud / Seafile需要把浏览器编辑能力原生嵌进现有存储对文档格式保真度有硬要求ODF/OOXML 双格式、修订追踪且接受基于 LibreOffice 的渲染能力边界。不建议的场景个人和小团队——这套东西的维护成本镜像升级、JWT 体系、副本调度超过了收益直接用成熟 SaaS纯浏览器体验优先、重度依赖 Office 高级特性的用户Web 端还原度与桌面版仍有差距应保留桌面客户端兜底需要复杂审批流、企业流程引擎的场景——它不内置工作流需要在上层系统集成没有专职运维的中小组织能跑起来和长期跑稳是两件事。落地路径建议先在一套两副本的测试集群按生产参数完整跑一遍——压 20 个并发文档会话核对内存占用与 3600 秒长连接是否稳定确认 Prometheus 指标与粘性路由正常再按生产规模铺开。仓库内的 CONTRIBUTING.md 说明了源码开发走 Gerrit、本仓库只接受 Helm chart 与构建脚本相关变更后续有定制需求前先读一遍。【免费下载链接】onlineIssue tracker only. Active development is on Gerrit at https://gerrit.collaboraoffice.com/.项目地址: https://gitcode.com/gh_mirrors/on/online创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考