1 基础知识
1.1 Collabora Online
1.1.1 Collabora Online简介
– Collabora Online简称COOL
– Collabora Online是由Collabora开发的开源在线办公套件
– Collabora Online基于LibreOffice Online（LibreOffice办公套件的Web版本）
– Collabora Online支持Web浏览器实时协作编辑文档 、电子表格、演示文稿和矢量图形。
– Collabora Online支持部分应用程序在Android、ChromeOS、IOS、iPadOS、Linux、macOS和Windows上离线使用
– Collabora Online支持OpenDocument格式并兼容其他主流格式（包括MS Office）
1.1.2 Collabora Online优势
– Collabora Online定位是Google Workspace和Microsoft 365等专有云平台的低成本开源替代。
– Collabora Online与这些服务不同，他并非默认托管（用户可自行托管或使用第三方提供商）
– Collabora Online主要面向寻求更大数字主权，摆脱美国“大型科技”公司的束缚的企业和公共机构
1.1.3 Collabora Online文档编辑应用程序
– Collabora Writer,基于LibreOffice Writer文字处理器，可与Microsoft Word和Google Docs媲美
– Collabora Calc，基于LibreOffice Calc 的电子表格编辑器，类似于Microsoft Excel和Google Sheets
– Collabora Impress，基于LibreOffice Impress 的演示程序，可与Microsoft PowerPoint和Google Slides媲美
– Collabora Draw，基于LibreOffice Draw的矢量图形编辑器，可与Microsoft Visio和Google Drawings相媲美
1.1.4 Collabora Online特点
– Collabora Online支持通过Web浏览器访问，无需插件或者附加组建
– Collabora Online支持实施编辑文字处理文档、电子表格、演示文稿和矢量图形
– Collabora Online协作功能包括评论、文档比较和带还原的版本跟踪以及与聊天或视频通话等通讯工具集成
– Collabora Online支持嵌入式集成到各种第三方应用程序中
– Collabora Online客户端应用程序不是使用基于Web套件的必需条件
– Collabora Online支持Android、ChromeOS、IOS、iPadOS、Linux、macOS和Windows上离线使用可选应用程序
– Collabora Online离线应用程序与服务器版本共享基于LibreOffice相同的核心，从而保证跨平台的兼容性
– Collabora Online得益于LibreOffice核心的持续开发使线上服务器和客户端应用程序同时受益
– Collabora Online的移动应用程序提供针对触摸优化的界面，可适应不同尺寸的屏幕并可离线工作，并可选择集成到云存储中
– Collabora Online支持符合ISO/IEC 26300的开放文档格式并且兼容MS Office格式
– Collabora Online核心用C++编写，并利用LibreOfficeKit编程接口（允许重用LibreOffice大部分现有代码来保存、加载和渲染文档）
– Collabora Online的运行原理是文档保留在服务器上，用户查看文档的平铺渲染图像，并将编辑内容回发到服务器。
– Collabora Online用户界面采用JavaScript实现
– Collabora Online对于文件访问和文件托管服务的身份验证使用MS的WOPI协议，从而兼容任何支持MS 365集成的服务。
1.1.5 Collabora Online服务器
– 服务器组件可以自行托管，也可以通过第三方 企业开源云平台部署
– 服务器适用于各Linux发行版并且提供Docker镜像
– 服务器支持浏览器内文档编辑、文件同步和实时通讯等功能。
1.2 Collabora Online架构或工作原理
1.2.1 Collabora Online系统架构
WSD（（Web服务主要守护进程）进程
– WSD负责创建唯一的ForKit、设置childroot目录并监听传入的客户端连接
– WSD是顶层服务器，旨在作为服务运行
– WSD一旦就绪，进程将在默认的9980端口上接受客户端的传入连接
– WSD支持通过SSL加密WebSocket直接与客户端通讯
– WSD通常在反向代理后面运行，实际情况下代理与WSD之间一般不使用加密传输
ForKit进程
– ForKit进程负责将Collabora Office的动态共享对象库（DSO）加载到内存中并创建Kit实例
– 动态共享对象库实现文档查看和编辑的核心逻辑，被称为Core库
– 动态共享对象库还实现了与WSD进行通讯的API（Collabora Online接口），接口层被成为Kit
– 每个WSD实例仅有一个ForKit,而每个文档则对应一个Kit实例进程
– Kit和Core库被加载到ForKit进程中时，ForKit就准备好创建可以加载文档的额外进程
– ForKit进程本身从来不加载文档，仅负责根据WSD的需求创建而外的进程来加载文档。
– ForKit进程会提前创建Kit实例，以便加快文档的加载速度（提前创建通过“num_prespawn_children”参数控制）
– ForKit名称是对“fork it”和“fork Kit”的双关语，将后者缩合为一个单词。
Kit进程
– Kit进程由ForKit进程创建，因此功能几乎与ForKit相同
– Kit进程与ForKit进程不同，Kit进程负责加载文档，并将用户的输入和命令传递给文档，同时向客户端反馈事件。
– Kit进程不会创建任何进程，每个文档对应一个Kit实例。
– Kit加载的文档对WSD可见之前，会创建一个隔离环境。
关于Kit隔离，以下供你参考，
– 在隔离Kit进程之前，需要创建影子文件系统（通过从模板目录进行“bind-mount”或“连接”，如两者都不可用则改为复制）
– 模板目录包含运行Core所需的重要文件和各种系统文件（如“/etc”中的时区、主机和类似文件）
– 当默认首先“bind-mount”方式可用时，则设置非常快速且以只读方式进行，该方式安全性高
– 影子文件系统就绪，会调用chroot来将当前Kit进程的根文件系统变更为影子文件系统的根，Kit通过chroot与主机隔离
进程之间的运行机制
– WSD是顶层服务器，旨在作为服务运行，负责创建ForKit,并在公共端口倾听客户端连接
– ForKit仅负责创建Kit实例，每个WSD实例只有一个ForKit，每个文档则对应一个Kit实例
– WSD在公共端口监听，并通过内部管道请求ForKit启动子实例（Kit）来托管文档
– ForKit根据公共URI作为唯一的键查找已存在的Kit实例，同时转发请求之Kit,Kit加载文档的新视图
– 无论是第一次加载文档，还是对已有文档的新视图，Kit都会通过内部端口与WSD建立套接字连接
– WSD作为客户端与Kit之间的桥梁，作为两个套接字之间流量隧道（客户端往返WSD，WSD往返Kit）
另外，
– 单例Admin类，该类会在所有重要变更时接收同志并相应地更新AdminModel对象
– AdminModel对象有订阅者，与管理面板会话相对应
– 订阅者支持订阅特定命令，以获取实例同志并相应更新用户界面。
1.2.2 Collabora Online文件系统架构
WSD的监禁目录使用流程
– WSD通过设置“child_root_path”获得childroot参数监禁文件系统的根目录
– WSD一般会指定“/childroot”作为默认的监禁根目录
ForKit的监禁目录使用流程
– ForKit实例创建前，WSD需要创建一个随机的“Jail-ID”作为监禁目录名称
– ForKit通过参数“jailid”的到该“Jail-ID”
– ForKit根目录，例如“/childroot/”通过参数“jailid”创建该监禁目录“/childroot/jailid”
– ForKit将LO安装到自己的chroot目录中
– ForKit切换根目录到chroot目录中并降级全线（drop caps）
– ForKit在读取管道上等待，WSD会在接收到来至客户端的新请求时会向该管道写入数据
– ForKit负责创建Kit实例，每个文档由一个Kit实例托管
需要注意的是，
– 出于安全需求，Jail-ID的目录名称随机生成，并且不会透露给客户端
– 由于WDS只有一个forKit,因此只会有一个JailID
Kit目录的使用流程
– Kit每个文档存储在ForKit的chroot目录中的专用目录
– Kit的文档根目录相对路径为“/user/docs”即绝对路径“/childroot/jailid/user/docs”
– Kit根据每个文档随即创建“Child-ID”（可以是Kit的进程ID）
– Kit每个文档的绝对路径为“/childroot/jailid/user/docs/childid”
1.2.3 Collabora Online客户端连接流程
接收连接请求
– WSD公共套接字受到连接请求，并接收到“Load”命令
– 请求包含wopiSrc唯一的URL和用户令牌
查找DocumentBroker实例
– 根据提供的wopiSrc（不包括令牌）查找现有的DocumentBroker实例
– 如果找到则，表示文档已加载则加载现有文档的新视图
– 如果没有找到，则创建新DocumentBroker实例并内部注册
查找可用的Kit进程
– WSD会查找一个可用的Kit进程
– 如果没有可用进程，则请求ForKit创建更多的进程
创建CLientSession
– 创建ClientSession（ToClient）
– 接管传入的套接字，以便处理客户端流量
向Kit发送请求
– ForKit通过内部的Unix套接字向主机URL发送Kit请求
Kit连接WSD
– Kit通过内部端口连接到WSD
创建Document和ChildSession实例
– Kit内部创建Document和ChildSession实例，以抽象文档及其视图
创建按ToPrisoner ClientSession
– WSD创建另一个ClientSession（ToPrisoner）来服务Kit
连接ClientSession
– ClientSession（ToClient）与ToPrisoner实例链接，将文档复制到“监狱”中（仅首次加载）
– 通过ToPrisoner向Kit发加载请求
加载文档
– Kit加载文档，并设置与LOKit的回调
双向流量隧道
– ClientSession（ToClient）和ClientSession（ToPrisoner）在客户端和Kit之间双向隧道流量
1.2.4 Collabora Online Kit文档渲染格栅图的流程
文档渲染为Tiles
– 文档被分割为多个小块（tiles）
– 每个tile都是一个栅格图像，按预定义尺寸进行处理
客户端显示Tiles
– 客户端跟中这些tiles,并在界面上进行显示
– 确保用户能够看到文档的不同部分
修改通知
– 当文档被任何用户（包括当前用户）修改时
– Kit会向所有活跃的客户端发送失效通知，告知他们某些Tiles已过期
请求重新渲染
– 接到通知的每个客户端会发送请求
– 要求渲染那些已经过期的Tiles
唯一性请求处理
– 服务器跟中来至所有客户端的请求
– 确保每个唯一的tile请求只渲染一次
– 唯一性不仅基于坐标和大小，还包括缩放因子
– 该机制保证同一个tile不会被重复渲染
缓存机制
– 渲染tiles会被缓存
– 以保证后续相同的唯一tile请求直接从缓存中提供服务，而无需重复渲染
渲染成本控制
– 由于渲染过程资源消耗较高
– 系统采用上述机制来尽量减少不必要的渲染操作，提供性能和响应速度
1.2.5 Collabora Online的协议
– 客户端与服务器之间的协议是哟跟明文格式
– 如果需要结构化数据，偶尔使用JSON格式
– 在某些情况下，负载需要以二进制格式传输
– 例如，渲染的图块（tiles），图块的响应必须包含他们所含的图块二进制数据
1.2.6 Collabora Online的线程模型
– 在WSD侧，每个文档由一个线程处理
– 在Kit中，每个文档也由单一主线程，负责处理相关操作
– 主要线程负责套接字通讯以及命令、事件处理，确保操作的集中管理
– 在WSD则，DocumentBroker是该线程的拥有者，通过使用poll系统调用进行管理
– 当套接字没有新的数据可读时，线程会进入有效的等待状态，等待来自该文档相关的任何套接字的新输入或超时(简单高效)
– Kit中，处理文档输入、命令和事件的线程也是处理套接字逻辑的线程
– 通过调用runLoop() Kit API实现，API的注册回调，文档的主线程在其主循环中调用这些回调
1.2.7 Collabora Online的文件服务器
– CoolWSD除了作为处理文档加载、编辑和保存的服务器组建外，还充当文件服务器
– CoolWSD的文件服务器之服务于已知文件，即文件在启动和初始化服务器时已预知，进行枚举并从磁盘读取加载到内存缓存中
– 该设计带来超越的性能，服务已知目录(如browser或dist）避免暴露任何未知目录的风险
– 启动过程中可以派出任何不应该提供服务的文件（处于任何原因）
– 此外，文件服务器还负责提供特定服务的文件，例如hosting、discovery、favicon.ico、robots.txt等
– 一旦服务器初始化，只能服务于已缓存的文件，所以其他请求被忽略并记录使用的错误，同时返回HTTP错误码（如403或404）
– 文件服务仅通过HTTP和HTTPS完成，支持HTTP动词仅有GET和POST,GET用于文件服务，POST则专门用于与文档交互，如转换、下载
– POST进行文档交互原因是传递认证密钥，密钥用于验证用户对存储服务器的身份及对相关文件的访问，认证在请求体中比URL更安全。
– 加载文档和服务器与客户端之间建立连接时，HTTP套接字会升级为WebSocket,以支持用户在文档上的会话持续期间的通讯
1.2.8 Collabora Online的通讯安全
Collabora Online 对外部访问的控制机制
– 当主机集成客户端发起请求以查看或编辑Collabora Online中的文档时
– 他会传输并创建一个认证令牌到WSD
– WSD在进行任何WOPI请求时，该认证令牌一并返回
– 该令牌需要由主机（WOPI服务器）进行验证
– WOPI请求通过HTTPS进行
– WSD在执行请求时会验证主机的TLS证书的有效性
Collabora Online 对内部访问的控制机制
– WSD会与新创建的LOKit实例建立客户端连接
– 该实例运行在chroot监狱中，限制系统调用和文件系统访问，并且一次仅加载一个文档
– LOKit实例和WSD在同一台及其上运行，通讯通过UNIX域套接字进行
– 连接的合法性通过标准的UNIX套接字对等凭据机制以及UID/GID匹配进行验证。
注：不能放置超级管理员的任何篡改
1.3 Collabora Office
– Collabora Office是一款基于LibreOffice的独立桌面套件
– Collabora Office尽管日益占据核心地位，但与LibreOffice仍可并行使用（类似于MS Office和MS 365）
1.4 Collabora在线开发版
– Collabora在线开发版简称CODE
– Collabora在线开发版免费提供给个人、小型团队和开发者
– Collabora在线开发版提供新功能的早期体验
– Collabora在线开发版作为开源社区贡献者的测试和开发平台
1.5 运行环境
– Collabora为64位Linux发行版本提供签名二进制包
– Collabora Onlinu开发板（CODE）和Collabora Online（COOL）包支持x86-64、arm64和ppc64le平台
– 其中x86-64构建的软件包基准操作系统是EL7
– 其中arm64和ppc64le平台上，基准操作系统是EL8
– 理论上软件包应该可以在任何现代的，受支持的Linux发行版上运行（需要glibc）
2 最佳实践
2.1 系统配置
2.1.1 系统信息
OS = CentOS 7.x x86_64
IP Address = 10.168.0.128
Host Name = collabora01.cmdschool.org
2.1.2 升级系统版本
yum update -y
2.1.3 配置SELinux
setenforce 0 sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config
2.1.4 设置时区
timedatectl set-timezone Asia/Shanghai
2.1.5 安装所需的软件包
yum install -y yum-utils wget
2.2 安装配置Collabora
2.2.1 导入证书
wget https://www.collaboraoffice.com/repos/CollaboraOnline/CODE-rpm/repodata/repomd.xml.key rpm --import repomd.xml.key
2.2.2 配置存储库
yum-config-manager --add-repo https://www.collaboraoffice.com/repos/CollaboraOnline/CODE-rpm
2.2.3 安装软件包
yum install -y coolwsd CODE-brand coolwsd-deprecated
2.2.4 修改必要的配置
cp /etc/coolwsd/coolwsd.xml /etc/coolwsd/coolwsd.xml.default vim /etc/coolwsd/coolwsd.xml
修改如下配置，
<config>
<logging>
<file enable="true">
<property name="path" desc="Log file path.">/var/log/coolwsd/coolwsd.log</property>
</file>
</logging>
<ssl desc="SSL settings">
<cert_file_path desc="Path to the cert file" type="path" relative="false">/etc/coolwsd/wildcard.cmdschool.org.crt</cert_file_path>
<key_file_path desc="Path to the key file" type="path" relative="false">/etc/coolwsd/wildcard.cmdschool.org.key</key_file_path>
<ca_file_path desc="Path to the ca file" type="path" relative="false">/etc/coolwsd/DigiCert_Global_G2_TLS_RSA_SHA256_2020_CA1.crt</ca_file_path>
</ssl>
<admin_console desc="Web admin console settings.">
<enable desc="Enable the admin console functionality" type="bool" default="true">true</enable>
<username desc="The username of the admin console. Ignored if PAM is enabled.">admin</username>
<password desc="The password of the admin console. Deprecated on most platforms. Instead, use PAM or coolconfig to set up a secure password.">adminpwd</password>
</admin_console>
</config>
需要注意的是，证书请自行准备，笔者建议你申请权威的腾讯云证书，使用申请Apache的格式证书即可，
https://cloud.tencent.com/product/ssl
根据配置文件的要求，你需要手动创建如下目录，
mkdir -p /var/log/coolwsd/ chown cool:cool /var/log/coolwsd/ chmod 770 /var/log/coolwsd/
2.2.5 测试服务启动
sudo -u cool bash -c '/usr/bin/coolwsd --version --o:sys_template_path=/opt/cool/systemplate --o:child_root_path=/opt/cool/child-roots --o:file_server_root_path=/usr/share/coolwsd --o:cache_files.path=/opt/cool/cache'
如第一次启动，如果你没有准备证书，你会见到如下错误提示，
wsd-01585-01585 2025-08-05 20:56:56.521285 -0400 [ coolwsd ] FTL Failed to initialize COOLWSD: File not found: /etc/coolwsd/ca-chain.cert.pem| wsd/COOLWSD.hpp:263
另外，如果你参阅官方的教程安装，可能会遗漏安装”coolwsd-deprecated”，因此你可能会见到如下错误提示，
wsd-01510-01517 2025-08-05 20:48:20.148272 -0400 [ prisoner_poll ] FTL coolforkit-caps does not exist, install coolwsd-deprecated package| wsd/COOLWSD.cpp:2855
2.2.6 启动服务并设置自启动
systemctl start coolwsd systemctl enable coolwsd systemctl status coolwsd
服务启动后，你可以使用如下命令查看服务端口的倾听状态，
ss -anp | grep coolwsd
正常状态下可见如下显示，
LISTEN 0 64 [::]:9980 [::]:* users:(("coolwsd",pid=18878,fd=14))
根据上面的倾听端口，你可能还需要使用如下命令设置防火墙开放端口，
firewall-cmd --permanent --add-port 9980/tcp firewall-cmd --reload firewall-cmd --list-all
如果有异常，你可以使用如下命令查看软件启动的日志，
journalctl -u coolwsd tail -f /var/log/coolwsd/coolwsd.log
比如如第一次启动，如果你没有准备证书，用该命令你会见到如下错误提示，
Aug 05 04:51:11 collabora01.cmdschool.org coolwsd[8510]: Failed to initialize COOLWSD: File not found: /etc/coolwsd/ca-chain.cert.pem
2.3 测试服务
2.3.1 设置名称解析
vim /etc/hosts
加入如下配置，
10.168.0.128 collabora01.cmdschool.org
2.3.2 测试服务
curl https://collabora01.cmdschool.org:9980
可见如下回应，
OK
2.3.3 测试管理控制台登陆
https://collabora01.cmdschool.org:9980/browser/dist/admin/admin.html
user: admin
password: adminpwd
参阅文档
=========================
Collabora Wiki
———————
https://en.wikipedia.org/wiki/Collabora_Online
Collabora Online
—————–
https://github.com/CollaboraOnline/online
Collabora Online的安装指南
———————-
https://sdk.collaboraonline.com/docs/installation/index.html
https://sdk.collaboraonline.com/docs/why_integrate.html
Collabora Online的配置指南
———————-
https://sdk.collaboraonline.com/docs/installation/Configuration.html
Collabora Online的订阅
—————-
Collabora Office
—————–
Collabora Online内置CODE Server
——————————–
https://apps.nextcloud.com/apps/richdocumentscode
https://github.com/CollaboraOnline/richdocumentscode
NextCloud Office插件(配合CODE使用)
——————–
https://apps.nextcloud.com/apps/richdocuments
wopi（最近3个版本没有维护更新）
———————–
https://apps.nextcloud.com/apps/wopi
officeonline集成
——————–
https://apps.nextcloud.com/apps/officeonline
没有评论