Collabora Online 26.04.5.1.1 配置参数详解

目标：逐域讲清 Collabora Online（CODE）26.04.5.1 主配置文件 coolwsd.xml 的参数体系——每个参数的含义、官方默认值与实测生效行为，并给出可直接落地的生产配置模板。文中所有默认值均取自 26.04.5.1 实际生成的配置文件（该文件对每个参数自带 desc 说明与 default 属性），关键参数均附实测验证回显；部署过程见 《Collabora Online 26.04.5.1.1 Docker Compose 部署指南》，命令行工具见 《Collabora Online 26.04.5.1.1 常用 CLI 命令与工具详解》。

一、环境信息

• 组件版本：Collabora Online（CODE）26.04.5.1（/hosting/capabilities 实测返回 productVersion: 26.04.5.1）
• 主配置文件：/etc/coolwsd/coolwsd.xml（RPM/DEB 装与官方发行形态路径一致）
• 实测环境：Ubuntu 22.04（x86_64），coolwsd 以默认参数启动
• 实测生成的配置文件规模：466 行，参数带内嵌 desc（含义）与 default（官方默认值）双注释
• 文档引擎验证接口：/hosting/capabilities（版本与能力 JSON）、/hosting/discovery（WOPI 发现 XML）、/cool/convert-to（格式转换）
• 组件定位与选型背景见 《Collabora Online 介绍与选型指南》

二、前置条件

1. coolwsd 已安装并可启动（裸机安装后由 systemd 托管，服务名 coolwsd；其他部署形态见部署篇）。启动验证：

   systemctl is-active coolwsd
   

   预期输出 active（服务在运行）。

2. 能访问本机服务端口（默认 9980）做验证：

   curl -s http://localhost:9980/hosting/capabilities | head -c 120; echo
   

   实测回显（本文实测环境端口映射后为 8145，下文同）：

   {"convert-to":{"available":true,"endpoint":"/cool/convert-to"},"hasDocumentSigningSupport":true,"hasMobileSupport":true,"hasProxyPrefix":false
   

3. 了解 coolwsd 的进程模型（理解参数的前提）：coolwsd 是常驻调度进程，为每份打开的文档派生沙箱化的 kit 子进程（内嵌 LibreOffice 引擎），内存占用随并发文档数线性增长——因此资源类参数（第五章 5.4）是生产调参重点。

三、参数查看与修改方式

coolwsd 的参数有三个入口，优先级从高到低为：命令行参数 > 配置文件 > 内置默认值。配置变更后需重启 coolwsd 服务生效。

3.1 配置文件 coolwsd.xml

主配置文件为 /etc/coolwsd/coolwsd.xml，XML 结构按功能域分层（<net>、<ssl>、<storage>、<logging> 等），每个参数节点带 desc（含义）与 default（默认值）属性。查看某一域的当前值：

grep -A3 '<ssl ' /etc/coolwsd/coolwsd.xml

实测回显（26.04.5.1 生成文件节选，enable 默认为 true）：

    <ssl desc="SSL settings">
        <!-- switches from https:// + wss:// to http:// + ws:// -->
        <enable type="bool" desc="Controls whether SSL encryption between coolwsd and the network is enabled (do not disable for production deployment). If default is false, must first be compiled with SSL support to enable." default="true">true</enable>

修改方式：直接编辑 XML 元素的文本值（如把 <enable> 的 true 改 false），保存后重启服务。

3.2 命令行参数 --o 覆盖

coolwsd 启动参数支持 --o:配置路径=值 形式就地覆盖任意配置项，无需改文件。systemd 部署时通过 drop-in 追加：

systemctl edit coolwsd

写入：

[Service]
Environment=COOLWSD_EXTRA_PARAMS=--o:num_prespawn_children=2

（并在 unit 的 ExecStart 行追加 $COOLWSD_EXTRA_PARAMS 后 systemctl daemon-reload。）

实测验证（本文实测环境以该参数启动后，启动日志会打印全部非默认值清单，目标行如下）：

        num_prespawn_children: 2

默认值为 4，覆盖为 2 后 dump 显示 2，证明 --o: 路径覆盖生效。多参数用空格分隔，如 --o:ssl.enable=false --o:ssl.termination=true。

3.3 变更生效与验证

重启服务并核对启动日志中的非默认值 dump（coolwsd 启动完成前会打印一份「Loaded config file ... (non-default values)」清单，是核对参数是否生效的最直接证据）：

systemctl restart coolwsd
journalctl -u coolwsd --no-pager | grep -A30 'non-default values'

实测回显节选（本文实测，<redacted> 为敏感值自动打码）：

        admin_console.password: <redacted>
        admin_console.username: <redacted>
        alias_groups[@mode]: groups
        num_prespawn_children: 2
        experimental_features: true

💡 说明：这份 dump 只列「与内置默认不同的项」——某参数没出现在 dump 里，说明它正使用官方默认值。这是排障时判断「配置到底生效没有」的第一现场。

四、参数总览

coolwsd.xml 按 XML 顶层域组织，各域职责与关键参数如下（域名为配置文件中的节点名，官方默认值以 26.04.5.1 生成文件为准）：

💡 技术拓展：「配置生效层级」不止 coolwsd.xml 一种载体，同类方案横向对比——

载体	生效方式	适用场景
配置文件	重启服务后长期生效	生产标准做法
命令行 --o	随进程启动生效，不改文件	临时验证、发行版注入（部署篇环境变量即走此通道）
管理控制台	在线改部分项，重启后以文件为准	快速查看与少量调整

本文主线采用配置文件方式（生产可审计、可版本化）。

五、核心参数分类详解

5.1 网络域 net（监听与访问控制）

做什么：控制 coolwsd 监听的协议与地址、POST/REST 访问来源、文档内外部数据源白名单与内容安全策略。预期结果：理解反代部署与内网访问控制的配置点。

实测行为：反代 TLS 终结部署时 coolwsd 本体用 HTTP，此时浏览器 → 反代是 HTTPS、反代 → coolwsd 是 HTTP，需配合 ssl.termination=true（见 5.2），本文部署篇实测 --o:ssl.enable=false --o:ssl.termination=true 后 HTTP 直访返回 200。

5.2 TLS 域 ssl（自身加密）

做什么：决定 coolwsd 与客户端（浏览器/反代）之间是否 TLS 加密、证书位置与协议下限。预期结果：正确选择「自持证书」或「反代终结」两种生产姿势。

⚠️ 注意：官方对 ssl.enable 的注释写明「do not disable for production deployment」——关闭自身 TLS 的前提是必须有反代终结，两者只能选其一，绝不能同时裸 HTTP 上生产。

5.3 存储域 storage（WOPI 白名单与文档加载）

做什么：声明文档从哪来（WOPI 宿主）、谁能连、多大能传。这是 Collabora 安全模型的核心域。预期结果：正确配置 WOPI 白名单，理解 first/groups 两种模式。

groups 模式白名单写法（对应生产模板）：

<storage desc="Backend storage">
    <wopi desc="Allow/deny wopi storage." allow="true">
        <alias_groups desc="The WOPI hosts that may connect." mode="groups">
            <group>
                <host allow="true">https://cloud.example.com:443</host>
            </group>
            <group>
                <host allow="true">https://other.example.com:443</host>
                <alias desc="regex pattern of aliasname">other\.internal\.lan:443</alias>
            </group>
        </alias_groups>
    </wopi>
</storage>

说明：host 支持正则（点号需转义）；alias 用于同一宿主的别名/内网名；多个宿主写多个 <group>。

5.4 文档进程域 per_document（资源与生命周期）

做什么：控制每份文档进程的并发线程、闲置回收、自动保存与资源上限，是内存规划的第一参数域。预期结果：按团队规模设定合理的回收与限额。

配套的全局资源参数（顶层）：

5.5 日志域 logging（级别与落盘）

做什么：控制日志级别、启动期级别、文件落盘与脱敏。预期结果：日常 warning，排障时按需放大。

实测行为：启动日志还会打印一份非默认配置 dump（见 3.3），admin_console.password 等敏感项自动 <redacted>。

5.6 安全域 security（隔离与宏）

做什么：进程隔离机制、管理台令牌时效、宏执行与指标端点鉴权。预期结果：保持默认隔离，按需收紧宏策略。

实测关联：文档进程隔离降级时日志会出现 ERR 级 usernamespace 提示并自动改用 coolforkit-caps（实测该实例服务 healthy、转换接口正常，属降级告警非致命），详见部署篇排障实录。

5.7 界面与视图域 user_interface / per_view / watermark / view_mode

做什么：控制界面形态、打开缩放、视图闲置降级与水印。预期结果：统一团队界面体验、按合规需要加水印。

另有 home_mode.enable（默认 false）：家庭模式，开启后关闭欢迎/反馈弹窗，代价是并发连接限 20、并发文档限 10——只适用于个人场景。

5.8 集成增强域 languagetool / deepl / ai / zotero / 其他

做什么：外挂语言服务、翻译、AI 助手与文献插件。预期结果：按需启用，注意外发数据的合规边界。

5.9 管理台域 admin_console

做什么：管理控制台开关与认证方式。预期结果：改默认凭据、必要时上 PAM。

实测关联：环境变量注入的凭据在该域生效（启动日志 dump 显示 admin_console.username: <redacted>），浏览器登录实测入口为 401 保护的 admin.html。

六、生产配置模板

以下模板面向：8–16GB 内存、NVMe 磁盘、200 人以下团队、Nginx 反代 TLS 终结、Nextcloud/ownCloud 宿主、中英文文档的典型生产场景。只列需要改动的项，其余保持默认：

<!-- /etc/coolwsd/coolwsd.xml 生产改动项（其余节点保持 26.04.5.1 默认值） -->
<config>
    <!-- 1. 语言：补中文写作辅助（需服务器已装 zh_CN 字典），精简默认列表加快启动 -->
    <allowed_languages default="de_DE en_GB en_US es_ES fr_FR it nl pt_BR pt_PT ru">en_GB en_US zh_CN</allowed_languages>

    <!-- 2. 网络：仅本机监听，全部流量经反代进入 -->
    <net desc="Network settings">
      <proto type="string" default="all" desc="Protocol to use IPv4, IPv6 or all for both">all</proto>
      <listen type="string" default="any" desc="Listen address that coolwsd binds to. Can be 'any' or 'loopback'.">loopback</listen>
      <content_security_policy desc="Customize the CSP header by specifying one or more policy-directive, separated by semicolons.">frame-ancestors https://cloud.example.com</content_security_policy>
    </net>

    <!-- 3. TLS：反代终结（Nginx 持证书），本体走 HTTP -->
    <ssl desc="SSL settings">
        <enable type="bool" default="true">false</enable>
        <termination type="bool" default="false">true</termination>
        <ssl_verification type="string" default="false">true</ssl_verification>
    </ssl>

    <!-- 4. WOPI 白名单：groups 模式显式列宿主 -->
    <storage desc="Backend storage">
        <wopi desc="Allow/deny wopi storage." allow="true">
            <max_file_size desc="Maximum document size in bytes to load. 0 for unlimited." type="uint">209715200</max_file_size>
            <alias_groups desc="The WOPI hosts that may connect." mode="groups">
                <group>
                    <host allow="true">https://cloud.example.com:443</host>
                </group>
            </alias_groups>
        </wopi>
    </storage>

    <!-- 5. 资源：8GB 内存机器的稳妥配额 -->
    <memproportion desc="The maximum percentage of available memory consumed" type="double" default="80.0">70.0</memproportion>
    <num_prespawn_children desc="Number of child processes to keep started in advance." type="uint" default="4">2</num_prespawn_children>
    <per_document desc="Document-specific settings, including LO Core settings.">
        <idle_timeout_secs desc="The maximum number of seconds before unloading an idle document." type="uint" default="3600">900</idle_timeout_secs>
        <limit_virt_mem_mb desc="The maximum virtual memory allowed to each document process. 0 for unlimited." type="uint">4096</limit_virt_mem_mb>
    </per_document>

    <!-- 6. 日志：文件落盘 + 按天轮换 -->
    <logging>
        <level type="string" default="warning">warning</level>
        <file enable="true">
            <property name="path" desc="Log file path.">/var/log/coolwsd.log</property>
            <property name="rotation" desc="Log file rotation strategy. See Poco FileChannel.">daily</property>
            <property name="purgeAge" desc="The maximum age of log files to preserve.">30 days</property>
            <property name="purgeCount" desc="The maximum number of log archives to preserve.">14</property>
            <property name="flush" desc="Enable/disable flushing after logging each line.">false</property>
        </file>
    </logging>

    <!-- 7. 安全：宏保持禁用；CSP 已在 net 域声明宿主嵌入 -->
    <security desc="Altering these defaults potentially opens you to significant risk">
        <enable_macros_execution type="bool" default="false">false</enable_macros_execution>
    </security>

    <!-- 8. 界面：统一紧凑形态 -->
    <user_interface>
        <mode type="string" default="default">compact</mode>
    </user_interface>
</config>

模板逐项解读：

• 语言：26.04 默认 9 种欧洲语言全开会拖慢启动（官方注释明确），生产只留实际需要的语言；zh_CN 需要系统已安装中文写作辅助字典，缺失时拼写检查对中文无效但文档可正常编辑。
• net.listen=loopback：coolwsd 只听 127.0.0.1:9980，外部必须经 Nginx 进入，杜绝绕过反代直连 9980 的口子。
• CSP frame-ancestors：只允许 Nextcloud 站点嵌入 iframe，防点击劫持与任意站点嵌用。
• ssl.enable=false + termination=true：与 Nginx 443 TLS 终结对成对；ssl_verification=true 让 coolwsd 校验宿主证书（宿主走公网证书时开启）。
• max_file_size=209715200：单文档上限 200MB，防超大文档拖垮 kit 进程；按业务调整。
• memproportion=70 + num_prespawn_children=2 + idle_timeout_secs=900：8GB 内存下给系统与其他服务留余量；15 分钟无人编辑即卸载文档进程，是内存回收的主杠杆。
• limit_virt_mem_mb=4096：单文档进程 4GB 虚拟内存上限，防失控文档；触发上限的文档会被终止，配合 cleanup 子域自动清理。
• 文件日志：/var/log/coolwsd.log 按天轮换保留 30 天/14 份；systemd 部署记得在 unit 的 ReadWritePaths 放行 /var/log（官方配置文件注释原文要求）。
• 适用性：16GB 以上机器可把 memproportion 回到 80、num_prespawn_children 回到 4；百人以上并发或重表格场景，优先扩内存而非调大 limit（LibreOffice 引擎内存消耗与文档复杂度强相关）。

配置完成后重启并验证：

systemctl restart coolwsd
journalctl -u coolwsd --no-pager | grep -E 'alias_groups|num_prespawn|memproportion'
curl -s http://localhost:9980/hosting/capabilities | head -c 100; echo

预期：dump 行显示改后值；capabilities 返回 JSON（服务健康）。本文实测环境中同款改动经启动日志 dump 验证生效（num_prespawn_children: 2、alias_groups[@mode]: groups）。

七、常见问题

Q1：改了配置不生效？ 按优先级排查：命令行 --o: 参数 > coolwsd.xml > 默认值——先用启动日志的 non-default dump 确认最终值（3.3 节），再确认是否忘了 systemctl restart coolwsd，最后检查 XML 是否改错了节点文本值（default 属性只是注释，真正的值是元素文本）。

Q2：启动日志出现 usernamespace failed 是不是坏了？ 不是致命错误。这是隔离方式降级（改用 coolforkit-caps chroot），实测该实例服务 healthy、convert-to 转换正常（部署篇排障实录三）。需要最高隔离等级时确保内核开启 user namespace。

Q3：白名单配置了宿主还是被拒？ 三点检查：① 正则点号必须转义（cloud\.example\.com）；② 生成配置的 alias_groups@mode 必须是 groups（dump 核对）；③ 若同时存在环境变量注入与文件配置两处白名单，以命令行（环境变量生成）为准，二选一配置。

Q4：中文文档显示方块/字体退化？ 服务器缺中文字体。安装字体包（如 fonts-noto-cjk）后重启 coolwsd；也可用 remote_font_config.url 统一分发字体清单。

Q5：想临时提高日志排一个协同问题？ --o:logging.level=information（或 debug/trace）重启复现，结束后改回 warning；注意 disabled_areas 默认屏蔽 Socket/WebSocket/Admin/Pixel 的高冗余日志，追协议级问题时临时清空该列表。

八、参考链接

• 官方配置文档（coolwsd.xml 全参数）：https://sdk.collaboraonline.com/docs/installation/Configuration.html
• 官方 WOPI/集成文档：https://sdk.collaboraonline.com/docs/installation/WOPI.html
• 官方代码仓库：https://github.com/CollaboraOnline/online
• 本专栏系列：
  • 《Collabora Online 介绍与选型指南》——定位、版本与竞品对比
  • 《Collabora Online 26.04.5.1.1 Docker Compose 部署指南》——从零部署、反代配置与升级运维
  • 《Collabora Online 26.04.5.1.1 常用 CLI 命令与工具详解》——coolconfig 等命令行工具与诊断