企业官网建设流程全解析

如何把 Outline 协作服务单独部署并配置 COLLABORATION_URL？

【免费下载链接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.项目地址: https://gitcode.com/GitHub_Trending/ou/outline

Outline 的后台被拆分为若干独立服务（docs/SERVICES.md）：Web 服务承载应用与 API，Websockets 服务负责与前端通信，Worker 处理队列任务，Collaboration 服务则负责协调所有文档的实时编辑与更新。默认情况下，官方 Docker 容器会一次性跑起全部生产服务；根目录的 Procfile 中主进程默认命令就是：

web: yarn start --services=web,websockets,collaboration worker: yarn start --services=worker

也就是说 collaboration 默认和 web 跑在同一个进程组里。当团队规模扩大、实时编辑连接数增加时，可以把 collaboration 服务挪到另一台机器或另一个域名上单独运行。这个场景下必须做两件事：在主服务上把 collaboration 从进程列表中摘掉，并设置COLLABORATION_URL告诉应用实时协作服务的新地址。本文只覆盖这一件事，worker 等其他服务的部署方式不变。

确认服务拆分方式

Outline 通过逗号分隔的服务列表控制每个进程启动哪些服务，有两种等价方式（见 docs/SERVICES.md）：

• CLI 参数：yarn start --services=web,worker这类形式；
• SERVICES环境变量。

单独部署 collaboration 时的目标进程组合是：

• 独立主机/进程：只跑 collaboration，命令为yarn start --services=collaboration（仓库中 server/collaboration/Procfile 定义的正是这一条：web: yarn start --services=collaboration）；
• 主服务：只保留web,websockets，即yarn start --services=web,websockets或设置SERVICES=web,websockets；
• worker 至少保留一个进程用于处理队列，docs/SERVICES.md 说明 Web 服务"必须由至少一个进程运行"，队列同理需要至少一个 worker。

配置 COLLABORATION_URL

COLLABORATION_URL需要设置在主服务一侧。.env.sample 中对应条目：

# See [documentation](https://link.gitcode.com/i/912929fe458297c79d6e394fde873964) on running a separate collaboration # server, for normal operation this does not need to be set. COLLABORATION_URL=

两点适用条件：

• 只有 collaboration 服务部署在不同域名/主机时才需要设置；协作服务与主应用同域名时该变量可不配置。
• 取值必须是公网可访问的 URL。docs/SERVICES.md 给出的文档示例：应用部署在https://docs.example.com时，可以配置为COLLABORATION_URL=wss://docs-collaboration.example.com。

从 server/env.ts 中的校验逻辑看，该变量要求带协议头，且协议限定在http、https、ws、wss之内，尾部斜杠会被自动去掉；未设置时默认由主应用的URL推导（http会转换为ws）。所以跨域部署时务必显式填写协作服务自己的地址，而不是沿用主应用地址。

启动两个进程

在主服务侧（沿用你现有的部署方式，例如 Docker 容器），把服务列表调整为不含 collaboration：

yarn start --services=web,websockets

在独立主机上启动协作服务：

yarn start --services=collaboration

如果沿用 Docker 镜像部署，主服务容器照旧基于 Dockerfile 构建的镜像运行，只是通过SERVICES环境变量或服务列表把 collaboration 排除掉；独立主机上的容器则运行--services=collaboration这一条。两个进程共用同一套配置（DATABASE_URL、REDIS_URL等来自 .env.sample 的变量），差别只在各自启动的服务子集和主服务上多出的COLLABORATION_URL。

一个必须注意的限制：无独立 Redis 时 collaboration 只能单进程

server/env.ts 对REDIS_COLLABORATION_URL的说明是："若未设置，collaboration 服务必须以单进程（singleton）方式运行。" 这一点在 server/index.ts 中有对应实现：当进程启用了 collaboration 但没有REDIS_COLLABORATION_URL时，进程数会被强制限制为 1，并输出日志：

Note: Restricting process count to 1 due to use of collaborative service without REDIS_COLLABORATION_URL

也就是说，单独部署的协作服务如果不开横向扩展，就是单进程；如果确实需要横向扩展 collaboration，则要提供REDIS_COLLABORATION_URL（可以是与REDIS_URL相同的 Redis，也可以是另一台），.env.sample 中的注释同样说明该变量用于 "enable horizontal scaling of the collaboration service"。单独部署本身不强制横向扩展，是否配置这个变量取决于你对单进程连接容量的判断。

验证服务是否正常运行

Dockerfile 中定义了容器的健康检查，collaboration 进程与 web 进程一样暴露 HTTP 端口（默认 3000）：

wget -qO- "http://localhost:${PORT:-3000}/_health" | grep -q "OK"

即在各自主机上请求/_health，输出包含OK说明该服务进程存活。功能层面的验证是打开一篇文档进行编辑：前端会连接到COLLABORATION_URL指向的协作服务，实时协作正常说明主服务配置生效；若编辑无实时响应，先核对主服务日志中打印的环境变量（生产环境会输出 JSON 日志，见 README.md 的 Logging 说明）确认COLLABORATION_URL是否如预期被加载，以及该地址从前端所在网络是否可访问。

小结

单独部署协作服务的完整变更只有三处：独立进程用yarn start --services=collaboration启动；主服务改为--services=web,websockets；主服务环境变量中新增COLLABORATION_URL=<协作服务的公网 wss/http 地址>。限制方面记住一条：未配置REDIS_COLLABORATION_URL时协作服务只能是单进程，日志中出现上述 "Restricting process count to 1" 提示即为该限制生效。

【免费下载链接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.项目地址: https://gitcode.com/GitHub_Trending/ou/outline