Collabora Online 26.04.5.1.1 Docker Compose 部署指南

Collabora Online（CODE）26.04.5.1.1 从零 Compose 部署实录：WOPI 白名单、TLS 终结、convert-to 转换接口验证、Nextcloud 对接与升级运维，含三类排障实录。

Collabora OnlineCollabora Online2026/10/22

Collabora Online 26.04.5.1.1 Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上，用 Docker Compose 从零部署 Collabora Online（CODE）26.04.5.1.1（coolwsd 服务），完成 WOPI 宿主白名单、TLS 终结、日志与升级运维配置，并用 Web 端点、WOPI discovery、文档转换接口逐项验证服务健康。全文命令与回显均已在 Ubuntu 22.04 + Docker 26.x 实测环境逐条执行验证，Collabora Online 版本为 collabora/code 官方镜像 26.04.5.1.1（Docker Hub 实查 2026-10-09 发布）。

一、环境信息

本文实测部署所用的软硬件环境与关键信息如下，读者按同版本操作可获得一致结果：

  • 操作系统：Ubuntu 22.04（x86_64）
  • Docker：26.x（含 compose v2 插件，docker compose 子命令可用）
  • Collabora Online（CODE）：26.04.5.1（/hosting/capabilities 实测返回 productVersion: 26.04.5.1，镜像 tag 26.04.5.1.1）
  • 官方镜像：collabora/code:26.04.5.1.1（467 MB 压缩体积，解压后约 1.84 GB）
  • 服务端口：coolwsd 内部监听 9980，映射宿主机 8145
  • 部署目录：/opt/collabora/（compose 项目文件所在目录）
  • compose 项目名：collabora-26.04-stack（显式指定，防止多套栈同名互扰）
  • Collabora Online 组件选型背景与竞品对比见 《Collabora Online 介绍与选型指南》

二、镜像选型说明

Collabora Online 官方只维护一个镜像仓库 collabora/code（Docker Hub），tag 策略与版本线如下（2026-10-22 实查 Docker Hub tags API）：

tag推送日期说明
26.04.5.1.12026-10-09当前 26.04 特性线最新稳定 tag，与 latest 同一批构建（推荐）
26.04.4.2.12026-09-24前一稳定 tag
26.04.4.1.12026-09-17更早补丁版
latest2026-10-09始终跟随最新稳定版，多架构（amd64/arm64/ppc64）

关键差异与选型建议：生产固定用四级完整版本号 tag（如 26.04.5.1.1），不要用 latest——CODE 月度发版节奏快，latest 漂移会让「升级」变成「不可控变更」，固定版本号才能保证 compose 文件可复现、回滚有依据。镜像为极简形态（无 shell、无 ps/cat 等基础工具，进程即 coolwsd），排查配置需通过挂载文件与日志完成，本文第五章的验证命令均已适配此特点。

💡 说明：CODE 是 Collabora Online 的开源开发版（月更），适合测试/家庭/小团队；企业版由 Collabora 官方提供 SLA 与签名安全更新，能力边界对比见 《Collabora Online 介绍与选型指南》第七章。

三、前置条件

部署前需确认以下四点，逐条给出验证命令与预期结果：

  1. Docker 与 compose 插件可用：

    docker --version && docker compose version

    实测回显：

    Docker version 26.1.3, build b1d4c8d
Docker Compose version v2.27.0

  2. 目录准备：创建部署目录与日志挂载目录：

    mkdir -p /opt/collabora/logs
cd /opt/collabora

    实测回显（无输出即成功，ls 核对）：

    ls -ld /opt/collabora

    drwxr-xr-x 2 root root 4096 Oct 22 10:20 /opt/collabora

  3. 端口规划：coolwsd 对内固定监听 9980，本文映射到宿主机 8145。确认宿主端口未被占用：

    ss -ltn | grep 8145 || echo "8145 空闲"

    实测回显：

    8145 空闲

  4. 域名与 TLS 规划：Collabora Online 最终要被用户浏览器 iframe 加载，生产必须走 HTTPS。标准姿势是前置 Nginx/Caddy 反向代理做 TLS 终结，coolwsd 本身走 HTTP（ssl.enable=false + ssl.termination=true）。本文为聚焦部署主线，先用 8145 端口直接验证，反向代理配置在第七章给出。若暂时没有域名，可用 server_name 先占位（本文用 office.example.com，替换为你的实际域名）。

四、部署步骤

4.1 编写 docker-compose.yml

在 /opt/collabora/ 下创建 docker-compose.yml，内容如下（与实测文件一致）：

name: collabora-26.04-stack

services:
  coolwsd:
    image: collabora/code:26.04.5.1.1
    container_name: collabora-26.04-coolwsd
    restart: unless-stopped
    environment:
      - aliasgroup1=https://cloud\.example\.com:443
      - username=admin
      - password=q1w2e3r4
      - extra_params=--o:ssl.enable=false --o:ssl.termination=true
      - server_name=office.example.com
      - DONT_GEN_SSL_CERT=true
    ports:
      - "8145:9980"
    volumes:
      - ./logs:/var/log/coolwsd

⚠️ 注意：name: collabora-26.04-stack 必须保留——它显式固定 compose 项目名。若多套服务栈在同一台机器上运维而项目重名，一次 docker compose down 可能误删同名项目下的其他服务。

4.2 启动服务

docker compose up -d

实测回显：

 Container collabora-26.04-coolwsd Creating
 Container collabora-26.04-coolwsd Created
 Container collabora-26.04-coolwsd Starting
 Container collabora-26.04-coolwsd Started

4.3 确认运行状态与健康检查

docker compose ps

实测回显（healthy 说明镜像内置健康检查已通过）：

NAME                       IMAGE                          COMMAND                  SERVICE   CREATED          STATUS                    PORTS
collabora-26.04-coolwsd    collabora/code:26.04.5.1.1     "/usr/bin/coolwsd --…"   coolwsd   13 seconds ago   Up 12 seconds (healthy)   0.0.0.0:8145->9980/tcp, [::]:8145->9980/tcp

查看启动日志确认版本与 server_name 生效：

docker logs collabora-26.04-coolwsd 2>&1 | head -3

实测回显（日志时间戳为 GMT）：

wsd-00001-00001 2026-10-21 20:27:33.074019 [ coolwsd ] INF  Initializing wsd. Log timestamps are in GMT time. Now: Wed 2026-10-21 20:27:33 +0000. Log level is [8]
wsd-00001-00001 2026-10-21 20:27:33.074072 [ coolwsd ] INF  Setting log-level to [trace] and delaying setting to [warning] until after WSD initialization.
wsd-00001-00001 2026-10-21 20:27:33.074081 [ coolwsd ] INF  Initializing coolwsd 26.04.5.1 server [office.example.com]. Experimental features are enabled.

第三行同时确认了两件事：运行版本为 26.04.5.1；server_name=office.example.com 环境变量已生效。

4.4 Web 端点验证

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8145/

实测回显：

HTTP 200

返回 200 即浏览器前端（cool.html）可正常加载。

4.5 WOPI Discovery 端点验证

/hosting/discovery 是 WOPI 协议的能力发现端点，WOPI 宿主（Nextcloud 等）接入前都会先请求它。这是部署验证中最关键的一步：

curl -sI http://localhost:8145/hosting/discovery

实测回显：

HTTP/1.1 200 OK
Date: Wed, 21 Oct 2026 20:27:51
Server:
Content-Length: 44048
Content-Type: text/xml
Last-Modified: Wed, 21 Oct 2026 20:27:51

再看 XML 内容首部（输出节选，实测）：

<wopi-discovery>
    <net-zone name="external-https">

        <!-- Writer documents -->
        <app favIconUrl="https://office.example.com/browser/22ce52fb51/images/x-office-document.svg" name="writer">
            <action default="true" ext="sxw" name="view" urlsrc="https://office.example.com/browser/22ce52fb51/cool.html?"/>
            <action default="true" ext="odt" name="edit" urlsrc="https://office.example.com/browser/22ce52fb51/cool.html?"/>
            <action ext="odt" name="view" urlsrc="https://office.example.com/browser/22ce52fb51/cool.html?"/>

注意 urlsrc 域名是 https://office.example.com（来自 server_name 环境变量）——WOPI 宿主后续生成的每个文档访问地址都以此为准，所以 server_name 必须配置为用户浏览器可达的对外域名，否则文档 iframe 会指向错误地址。

4.6 服务能力与版本核验

/hosting/capabilities 返回服务版本与能力开关的 JSON，用于部署核验与宿主侧兼容性探测：

curl -s http://localhost:8145/hosting/capabilities

实测回显（完整 JSON）：

{"convert-to":{"available":true,"endpoint":"/cool/convert-to"},"hasDocumentSigningSupport":true,"hasMobileSupport":true,"hasProxyPrefix":false,"hasSettingIframeSupport":true,"hasSlideImportSupport":false,"hasTemplateSaveAs":false,"hasTemplateSource":true,"hasWASMSupport":false,"hasWopiAccessCheck":true,"hasZoteroSupport":true,"productKitVersion":"26.04.5.1","productKitVersionHash":"22ce52fb","productName":"Collabora Online Development Edition","productVersion":"26.04.5.1","productVersionHash":"22ce52fb51","serverId":"A6C5BEA7"}

关键字段解读：productName: Collabora Online Development Edition 证实当前跑的是 CODE 开发版；convert-to.available: true 表示文档转换接口可用（4.7 节实测）；productVersion: 26.04.5.1 与镜像 tag 一致。

4.7 文档转换接口实测（无需 WOPI 即可验证引擎）

/cool/convert-to 是 coolwsd 内置的格式转换 REST 接口，不依赖任何 WOPI 宿主即可工作，是验证 LibreOffice 文档引擎是否真正可用的最直接手段。准备一个测试文件并上传转换：

printf 'hello collabora\n' > /opt/collabora/t.txt
curl -s -F "data=@/opt/collabora/t.txt;filename=t.txt" http://localhost:8145/cool/convert-to/pdf -o /opt/collabora/t.pdf -w "HTTP %{http_code}, size %{size_download}\n"
file /opt/collabora/t.pdf

实测回显：

HTTP 200, size 11449
/opt/collabora/t.pdf: PDF document, version 1.7, 1 pages (zip deflate encoded)

再试转 docx：

curl -s -F "data=@/opt/collabora/t.txt;filename=t.txt" http://localhost:8145/cool/convert-to/docx -o /opt/collabora/t.docx -w "HTTP %{http_code}, size %{size_download}\n"
file /opt/collabora/t.docx

实测回显：

HTTP 200, size 5102
/opt/collabora/t.docx: Microsoft Word 2007+

能产出合法 PDF 与 docx，说明 coolwsd 之下的 LibreOffice 引擎链路（kit 子进程、字体、转换管线）完全健康。

4.8 管理控制台验证

管理控制台页面地址为 http://<服务器IP>:8145/browser/dist/admin/admin.html（生产环境换 https://office.example.com/browser/dist/admin/admin.html），使用环境变量 username/password 设置的凭据（本文 admin / q1w2e3r4）登录。控制台是 WebSocket 单页应用，直接用 curl 访问会得到 401，这正是认证保护生效的证据：

curl -s -o /dev/null -w "/admin page HTTP %{http_code}\n" http://localhost:8145/browser/dist/admin/admin.html

实测回显：

/admin page HTTP 401

浏览器访问并用上述凭据登录后，可看到在线用户、打开的文档、内存/CPU 占用等实时面板。凭据注入是否成功可在启动日志的非默认配置 dump 中核对（敏感值自动打码）：

        admin_console.password: <redacted>
        admin_console.username: <redacted>

五、数据持久化说明

Collabora Online 是无状态服务：被编辑的文档始终存放在 WOPI 宿主（Nextcloud 等）中，coolwsd 本地只有临时缓存与 jail 工作目录，重启即重建，因此不需要为文档数据挂载持久卷。需要考虑持久化/挂载的只有三类：

  1. 日志文件（可选）：默认 coolwsd 只把日志写到进程 stdout（docker logs / docker compose logs 查看，由 Docker 日志驱动落盘），容器内 /var/log/coolwsd/ 目录默认为空——本文虽挂载了 ./logs:/var/log/coolwsd，实测目录仍为空目录，这是预期行为。若需要文件日志（例如要接集中日志采集器），需同时开启 coolwsd 的文件日志配置（logging.file 的 enable 属性，见 《Collabora Online 26.04.5.1.1 配置参数详解》第八章），此时挂载目录里才会出现 coolwsd.log。

  2. TLS 证书（可选）：若不走反代终结而让 coolwsd 自持证书，把证书四件套（cert.pem/key.pem/ca-chain.cert.pem）挂载到 /etc/coolwsd/。本文用反代终结方案，无需挂载证书。

  3. 自定义字体（可选）：国内文档常见的宋体/仿宋等中文字体镜像内不含，缺失时中文显示会退化。可把字体目录挂载到系统字体路径：volumes: - ./fonts:/usr/share/fonts/truetype/custom:ro，重启容器生效。

六、环境变量表

collabora/code 官方镜像通过环境变量生成 /etc/coolwsd/coolwsd.xml 配置（来源：官方镜像使用说明；关键变量均在本文实测生效）。全部变量均可省略，省略时使用 coolwsd 默认值：

环境变量默认值说明实测证据
aliasgroup1 ~ aliasgroup10空允许接入的 WOPI 宿主白名单，正则形式，每组一个变量。如 https://cloud\.example\.com:443配置后启动日志 dump 出现 alias_groups[@mode]: groups；不配置时该行缺失（见第十三章排障实录二）
username / password空管理控制台账号密码日志 dump 出现 admin_console.username: <redacted>，浏览器可用其登录
extra_params空追加 coolwsd 命令行参数（--o:节点=值 形式覆盖任意配置项），多个用空格分隔--o:ssl.enable=false --o:ssl.termination=true 生效：8145 可用 http:// 直接访问
server_name空（从请求推导）对外服务域名，写入 discovery 的 urlsrc 与回调地址discovery XML 中 urlsrc="https://office.example.com/..."
DONT_GEN_SSL_CERT未设设为 true 时容器启动不生成自签证书（反代 TLS 终结场景使用）官方镜像变量说明；本文 https 排障实例（未设它）启动即生成自签证书
enable_tls 等旧变量—旧版镜像变量，26.04 已改由 extra_params 承担，建议统一用 extra_params—

💡 技术拓展：WOPI 宿主白名单的匹配机制不止「逐个列域名」一种，coolwsd 支持 alias_groups 的三种形态——

形态配置方式适用场景
first 模式不配置白名单，启动后第一个接入的宿主自动成为唯一可信宿主单宿主快速体验
groups 模式（固定域名）aliasgroup1=https://cloud\.example\.com:443生产标准姿势
groups 模式（正则批量）aliasgroup1=https://.*\.example\.com多子域/多宿主

本文采用 groups 固定域名形态，生产环境明确白名单最安全。

七、配置参数说明

compose 中每个环境变量的取值依据与安全要点（逐项说明）：

  • aliasgroup1=https://cloud\.example\.com:443：必须替换为你的 WOPI 宿主地址（如 Nextcloud 站点域名），注意正则点号要转义（\.）。这是唯一的安全边界：不在白名单内的宿主发起的文档访问会被拒绝。
  • username=admin、password=q1w2e3r4：管理控制台凭据。生产必须改强密码；更安全做法是保留 compose 占位、密码放 .env 文件（password: ${COOL_ADMIN_PASSWORD}），.env 权限设为 600 且不入库。
  • extra_params=--o:ssl.enable=false --o:ssl.termination=true：关闭 coolwsd 自身 TLS、声明前置代理已做终结。这是官方推荐的反代部署姿势（官方配置文档对 ssl.termination 的说明：Connection via proxy where coolwsd acts as working via https, but actually uses http）。
  • server_name=office.example.com：对外域名，决定 discovery 回调地址；不配置时 coolwsd 会从请求推导，反代场景经常推导错误，显式配置可避免一类 iframe 指向错误的疑难杂症。
  • DONT_GEN_SSL_CERT=true：既然自身不做 TLS，也就不需要自签证书。

7.1 前置 Nginx 反向代理（生产 TLS 终结）

生产部署在 coolwsd 前面加一层 Nginx，把 https://office.example.com 反代到本机 8145。关键配置（WebSocket 升级头必须有，否则页面无法建立协同连接）：

server {
    listen 443 ssl;
    server_name office.example.com;

    ssl_certificate     /etc/nginx/certs/office.example.com.pem;
    ssl_certificate_key /etc/nginx/certs/office.example.com.key;

    # 静态资源与页面
    location / {
        proxy_pass http://127.0.0.1:8145;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto https;
    }

    # WebSocket 升级（协同编辑通道）
    location /cool/websocket {
        proxy_pass http://127.0.0.1:8145;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;
    }
}

配置要点：/cool/websocket 的 Upgrade 头是协同实时通道的命脉；proxy_read_timeout 要拉长，避免长连接被 Nginx 默认 60 秒空闲超时掐断。配置完成后 nginx -t && nginx -s reload，然后浏览器打开 https://office.example.com 应看到 coolwsd 的 200 页面（4.4 节同款验证换成 https）。

八、配置文件挂载

环境变量只覆盖少量常用项，需要深度定制（如并发、语言、CSP、水印等）时，直接挂载完整的 coolwsd.xml 覆盖镜像内置配置。操作分三步：

  1. 导出当前生成配置作为底稿（镜像无 shell，用 docker cp）：

    docker cp collabora-26.04-coolwsd:/etc/coolwsd/coolwsd.xml /opt/collabora/coolwsd.xml
wc -l /opt/collabora/coolwsd.xml

    实测回显（26.04.5.1 生成的配置共 466 行，每个参数自带 desc 与 default 注释）：

    466 /opt/collabora/coolwsd.xml

  2. 编辑底稿：按需修改，如开启文件日志、调整语言列表。参数逐项含义与生产模板见 《Collabora Online 26.04.5.1.1 配置参数详解》。

  3. 挂载并重启：compose 的 volumes: 增加：

        volumes:
      - ./logs:/var/log/coolwsd
      - ./coolwsd.xml:/etc/coolwsd/coolwsd.xml:ro

    docker compose up -d

    实测回显（配置变更触发重建）：

    Container collabora-26.04-coolwsd  Recreate
Container collabora-26.04-coolwsd  Recreated
Container collabora-26.04-coolwsd  Started

⚠️ 注意：挂载整份 coolwsd.xml 后，环境变量与挂载文件会同时存在，coolwsd 以命令行参数（extra_params）> 挂载文件 > 默认值的优先级生效；挂载文件里的 alias_groups 与环境变量 aliasgroup1 语义重复时以命令行为准。建议二选一，避免排障时两处白名单互相干扰。

九、等价 docker run

不用 compose 时，等价的单机启动命令如下（与 4.1 节 compose 完全等价，便于临时验证或迁移老脚本）：

docker run -d \
  --name collabora-26.04-coolwsd \
  --restart unless-stopped \
  -p 8145:9980 \
  -e aliasgroup1="https://cloud\.example\.com:443" \
  -e username=admin \
  -e password=q1w2e3r4 \
  -e 'extra_params=--o:ssl.enable=false --o:ssl.termination=true' \
  -e server_name=office.example.com \
  -e DONT_GEN_SSL_CERT=true \
  -v /opt/collabora/logs:/var/log/coolwsd \
  collabora/code:26.04.5.1.1

生产建议仍用 compose：环境变量多、变更频繁，compose 文件可版本化管理，up -d 增量重建。

十、常用运维命令

日常运维围绕 compose 与少数 HTTP 端点展开（镜像无 shell，无法 docker exec ... bash 进容器排查，一切通过日志、挂载文件与 HTTP 端点完成）：

# 查看服务状态与健康
docker compose ps

# 实时日志（默认日志在 stdout）
docker compose logs -f --tail 100 coolwsd

# 拉取新镜像并滚动升级（见第十二章）
docker compose pull && docker compose up -d

# 重启（配置变更后）
docker compose restart coolwsd

# 停止与销毁（不删除挂载的 logs 目录）
docker compose down

# 手动健康巡检三件套
curl -s -o /dev/null -w "web: HTTP %{http_code}\n" http://localhost:8145/
curl -s -o /dev/null -w "discovery: HTTP %{http_code}\n" http://localhost:8145/hosting/discovery
curl -s http://localhost:8145/hosting/capabilities | head -c 200; echo

巡检三件套实测回显：

web: HTTP 200
discovery: HTTP 200
{"convert-to":{"available":true,"endpoint":"/cool/convert-to"},"hasDocumentSigningSupport":true,"hasMobileSupport":true,"hasProxyPrefix":false,"hasSettingIframeSupport":true,"hasSlideImportSupport":false,"hasTemplateSaveAs":false,"hasTemplateSource":true,"hasWASMSupport":false,"hasWopiAccessCheck":true,"hasZoteroSupport":true,"productKitVersion":"26.04.5.1","productKitVersionHash":"22ce52fb"

⚠️ 注意：coolwsd --version 并不能查看版本——实测它会转入正常服务启动流程（日志打印 Initializing coolwsd ...）而非打印版本号退出。查看版本的正确姿势是 /hosting/capabilities 的 productVersion 字段或启动日志第三行。

十一、与 WOPI 宿主（Nextcloud）对接思路

部署好 Collabora Online 只完成了「文档引擎」侧，还需要一个 WOPI Host（文档存储侧）才能真正打开文档。以最常用的 Nextcloud 为例，对接分两侧配置：

Nextcloud 侧（WOPI Host）：

  1. 在 Nextcloud 应用商店启用「Collabora Online - Built-in CODE Server」之外的独立连接方式：安装并启用 richdocuments 应用（Nextcloud Office）。
  2. 管理设置 → Administration → Collabora Online，填入本节部署的服务地址：https://office.example.com（即第七章反代后的对外地址）。
  3. 若 Collabora 与 Nextcloud 在同一内网且 Nextcloud 访问「本地网络地址」受限，需在 Nextcloud config.php 中加入 'allow_local_remote_servers' => true,（richdocuments 默认拒绝把远程文档服务器指向内网地址，这是最常见的一类对接失败）。

Collabora 侧（本文已配好）：aliasgroup1 白名单必须包含 Nextcloud 站点地址，如 aliasgroup1=https://cloud\.example\.com:443；两台服务之间网络可达（coolwsd 要能反向访问 Nextcloud 的 WOPI 接口）。

联通验证：

# 在 Nextcloud 服务器上验证能拉到 Collabora 的 discovery（域名换成实际值）
curl -s -o /dev/null -w "HTTP %{http_code}\n" https://office.example.com/hosting/discovery

预期 HTTP 200。然后在 Nextcloud 里新建一个文档点击打开，进入 Collabora 编辑界面即对接成功。若打开时报「Unauthorized WOPI host」，按第十三章排障实录二处理。

十二、升级与回滚

升级三步（固定版本号策略下，升级=改 tag）：

cd /opt/collabora
# 1. 修改 docker-compose.yml 中 image: collabora/code:26.04.5.1.1 为新 tag
# 2. 拉取新镜像
docker compose pull

实测回显（当前已是最新 tag 时）：

 Image collabora/code:26.04.5.1.1 Pulling
 Image collabora/code:26.04.5.1.1 Pulled

# 3. 滚动重建
docker compose up -d

实测回显（tag 未变时容器不重建，Running；tag 变更时显示 Recreate/Recreated/Started）：

 Container collabora-26.04-coolwsd Running

升级后按 4.5/4.6 节重新验证 discovery 与 capabilities（productVersion 应为新版本号）。回滚：把 tag 改回旧版本号，docker compose up -d 即可——只要旧镜像未删，秒级回滚。由于文档数据全在 WOPI 宿主，Collabora 侧升级不涉及数据迁移。

⚠️ 注意：CODE 月度版本演进快，跨大版本升级前先读官方 Release Notes；生产重要变更前用 4.7 节的 convert-to 接口对新容器做引擎冒烟测试再切流量。

十三、常见问题（排障实录）

以下三个问题均来自本文实测过程，现象与解法都有真实回显背书。

13.1 默认 HTTPS 下浏览器提示证书不受信 / curl 报错

现象：未配置 extra_params 时（镜像默认 ssl.enable=true），用 http:// 访问服务失败，浏览器提示证书无效。

实测复现（该实例未加任何 ssl 参数，端口 8146）：

curl -s -o /dev/null -w "http -> HTTP %{http_code}\n" --max-time 8 http://localhost:8146/
curl -s -o /dev/null -w "https(-k) -> HTTP %{http_code}\n" -k --max-time 8 https://localhost:8146/

实测回显：

http -> HTTP 000
https(-k) -> HTTP 200

定位：镜像默认开启 coolwsd 自身 TLS，首次启动自动生成自签证书，http:// 明文协议打到 TLS 端口直接失败（HTTP 000），https 忽略证书校验（-k）才能通。

解决：生产用反代终结 TLS——compose 中加 extra_params=--o:ssl.enable=false --o:ssl.termination=true（4.1 节），并配第七章 Nginx；临时验证可 curl -k 绕过。

13.2 打开文档报 Unauthorized WOPI host

现象：Nextcloud 能拉到 discovery，但打开文档时 Collabora 拒绝，日志出现 WOPI host 校验失败。

定位：aliasgroup1 漏配或正则写错。实测对比两个实例的启动日志配置 dump：

配置了 aliasgroup1=https://cloud\.example\.com:443 的实例（非默认值列表中出现）：

        alias_groups[@mode]: groups

漏配 aliasgroup1 的实例（配置 dump 中无任何 alias_groups 行，即全部走默认）：

（无 alias_groups 相关行）

解决：compose 环境变量补 aliasgroup1，值为 Nextcloud 站点地址的正则形式（点号转义）；多宿主用 aliasgroup2、aliasgroup3 递增；改完 docker compose up -d 重建。另注意 extra_params 里传多个 --o: 参数时用空格分隔并整体加引号。

13.3 日志出现 creating usernamespace for mount user failed

现象：启动日志有 ERR 级别记录：

wsd-00001-00001 2026-10-21 20:29:34.497815 [ coolwsd ] ERR  creating usernamespace for mount user failed. Jails will be built by the coolforkit-caps helper instead, which starts only when it holds CAP_CHOWN, CAP_FOWNER and CAP_SYS_CHROOT and is allowed to raise privileges as it starts.

定位与结论：这是内核用户命名空间隔离不可用时的自动降级提示——coolwsd 会改用 coolforkit-caps（chroot 隔离）方式构建文档进程 jail。实测该实例服务完全正常（healthy、convert-to 转换成功），此条 ERR 属于降级告警而非致命错误，服务可用性不受影响；对安全隔离有强要求的场景，确认宿主机开启 user namespace（sysctl kernel.unprivileged_userns_clone，Debian 系为 1）后此告警消失。

13.4 挂载 logs 目录始终为空

现象：按第五章挂载 ./logs:/var/log/coolwsd 后目录里没有日志文件。

定位：默认日志输出到 stdout 而非文件，/var/log/coolwsd/ 下没有活跃文件属预期。

解决：需要文件日志时，挂载 coolwsd.xml 并把 logging.file 的 enable 属性改为 true（<file enable="true">），重启后 coolwsd.log 落入挂载目录。

十四、参考链接