ONLYOFFICE Docs 10.0 Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上以官方 onlyoffice/documentserver:10.0.0.1 镜像、Docker Compose 编排完成 ONLYOFFICE Docs（Document Server）社区版的从零部署，含 JWT 密钥配置、数据持久化、健康验证与升级运维，全部命令与回显均在 Ubuntu 22.04 环境实测通过。产品选型背景见 《ONLYOFFICE Docs 介绍与选型指南》。

一、环境信息

本篇部署与验证所用环境如下，读者复现时保证版本一致即可：

• 操作系统：Ubuntu 22.04；
• Docker 与 Compose：Docker Engine 24+（官方要求 docker-engine 更新至较新版本，官方 README 撰写时为 20.10.21 以上，镜像基于 ubuntu:24.04 构建）、Docker Compose v2；
• ONLYOFFICE 镜像：onlyoffice/documentserver:10.0.0.1（10.0 系列最新四段版本 tag，Docker Hub 2026-10-12 更新；GitHub 侧对应 Release v10.0.0）；
• 服务端口：宿主 8145 → 服务 80；
• 部署目录：/opt/onlyoffice/（compose 文件与数据目录均置于其下）；
• 硬件基线：官方要求 RAM ≥ 4 GB、CPU 双核 2 GHz 以上（Docker-DocumentServer README）；本次实测为 32 GB 内存服务器，空闲时服务常驻内存约 421.6 MiB（docker stats 实测），编辑高并发时建议按 8 GB 规划。

二、镜像选型说明

官方在 Docker Hub 维护 onlyoffice/documentserver 镜像，2026-10-22 实查 tags（Docker Hub tags 接口）：

选型结论：生产部署锁定四段完整 tag 10.0.0.1（x.y.z.w 第四段为内部构建号）。若希望自动跟随 10.0 系列补丁可用 10.0，但升级前应阅读官方 Release Notes 并验证数据兼容。

⚠️ 注意 10.0 社区版的一个重要架构变化（本环境实测确认）：CE 镜像内不再内置/启动 PostgreSQL、RabbitMQ、Redis。启动脚本 /app/ds/run-document-server.sh 中这三项依赖仅在商业版（PRODUCT_EDITION 非空）时标记可用（DB_AVAILABLE/RABBITMQ_AVAILABLE/REDIS_AVAILABLE 均由是否商业版决定，脚本第 63-64 行），随后以 [ "${DB_AVAILABLE}" = "true" ] && setup_db（脚本第 795-797 行）决定是否初始化与启动。CE 实测容器内进程仅 nginx + docservice + converter（supervisorctl status 见后文），因此无需也不应为 CE 再单独部署数据库与消息队列。

三、前置条件

• 服务器已安装 Docker Engine 与 Docker Compose v2（docker compose version 可执行）；
• 内存 ≥ 4 GB、磁盘剩余 ≥ 10 GB（镜像本体 3.14 GB，实测 docker images 大小）；
• 服务器可访问外网拉取镜像；首次启动会联网刷新默认插件清单（实测日志中存在对 github.com/ONLYOFFICE/onlyoffice.github.io 的访问），离线环境启动会慢一些但不影响服务可用；
• 规划端口：本示例用 8145（保持 80/443 留给反代场景亦可）。

四、部署步骤

4.1 目录与 compose 文件

创建部署目录与数据目录：

mkdir -p /opt/onlyoffice/compose /opt/onlyoffice/data/logs /opt/onlyoffice/data/data /opt/onlyoffice/data/files

编写 /opt/onlyoffice/compose/docker-compose.yml（本环境实测文件，可直接复用）：

name: onlyoffice-10.0-stack
services:
  onlyoffice-ds:
    image: onlyoffice/documentserver:10.0.0.1
    container_name: onlyoffice-ds
    restart: always
    stop_grace_period: 60s
    environment:
      - JWT_ENABLED=true
      - JWT_SECRET=q1w2e3r4
      - JWT_HEADER=Authorization
    ports:
      - "8145:80"
    volumes:
      - /opt/onlyoffice/data/logs:/var/log/onlyoffice
      - /opt/onlyoffice/data/data:/var/www/onlyoffice/Data
      - /opt/onlyoffice/data/files:/var/lib/onlyoffice/documentserver/App_Data/cache/files
    networks:
      - onlyoffice-net
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost/healthcheck"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 120s
networks:
  onlyoffice-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.74.0/24

逐项说明：

• name: onlyoffice-10.0-stack：显式 Compose 项目名，避免多套栈同名项目互相覆盖；
• JWT_SECRET：JWT 签名密钥，是唯一必改项。10.0 镜像 JWT 默认开启且默认随机值，显式设置才能与集成方（Nextcloud 等）约定一致；本示例用演示口令 q1w2e3r4，生产请换长随机串；
• JWT_HEADER=Authorization：令牌随该 HTTP 头传递（镜像默认值，显式写出便于集成方对照）；
• 三个数据卷：日志、证书与用户数据（Data）、转换缓存文件（cache/files），分别对应「可排查日志 / 可留存数据 / 可清理缓存」；
• stop_grace_period: 60s：沿用官方 compose 模板，给协同会话落盘留时间；
• healthcheck：以容器内 curl /healthcheck 判定健康（该端点正常返回 true，后文实测）。

4.2 启动

cd /opt/onlyoffice/compose && docker compose up -d

实测输出（首次启动，网络与容器创建）：

[+] Running 2/2
 ✔ Network onlyoffice-10.0-stack_onlyoffice-net  Created
 ✔ Container onlyoffice-ds                       Started

首次启动需 1~2 分钟完成初始化（生成 WOPI 密钥、字体缓存、启动服务）。观察启动日志：

docker logs onlyoffice-ds

实测关键回显（节选，出现 done 与 started 即初始化完成）：

Generating WOPI private key...Done
Generating WOPI public key...Done
Starting supervisor: supervisord.
 * Starting periodic command scheduler cron
   ...done.
 * Starting nginx nginx
   ...done.
Generating AllFonts.js, please wait...Done
Generating presentation themes, please wait...Done
Generating js caches, please wait...Done
ds:docservice: stopped
ds:docservice: started
ds:converter: stopped
ds:converter: started
 * Reloading nginx configuration nginx
   ...done.

4.3 健康验证

第一步，容器状态（等 healthy 出现）：

docker compose ps

实测输出：

NAME           STATUS                 PORTS
onlyoffice-ds  Up 3 minutes (healthy) 443/tcp, 0.0.0.0:8145->80/tcp, [::]:8145->80/tcp

第二步，健康端点与欢迎页：

curl -s http://127.0.0.1:8145/healthcheck

实测输出：

true

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

实测输出：

HTTP 200

浏览器打开 http://<服务器IP>:8145/：根路径会先 302 跳转，落地页标题为 ONLYOFFICE Docs Community Edition（实测 79.8 KB 欢迎页），页面内提供各编辑器在线示例入口。

第三步，转换服务冒烟（证明「能转换、JWT 生效」）。10.0 的转换端点为 /ConvertService.ashx，先做无令牌请求，预期被 JWT 拦截：

curl -s -X POST http://127.0.0.1:8145/ConvertService.ashx \
  -H "Content-Type: application/json" \
  -d '{"async":false,"filetype":"docx","outputtype":"pdf","title":"t.docx","url":"http://127.0.0.1/notexist.docx"}'

实测输出（无令牌，返回 XML 错误体，错误码 -8 为令牌校验失败）：

<?xml version="1.0" encoding="utf-8"?><FileResult><Error>-8</Error></FileResult>

带正确 JWT 的完整转换实测（含签名脚本、成功回显与产物下载）见 《ONLYOFFICE Docs 10.0 常用 CLI 命令与工具详解》转换服务一章，实测结论为：签名正确时返回 {"fileUrl":"...t.pdf?md5=...&expires=...","fileType":"pdf","percent":100,"endConvert":true}，下载产物为合法 PDF。

第四步，服务进程确认：

docker exec onlyoffice-ds supervisorctl status

实测输出：

ds:converter                     RUNNING   pid 857, uptime 0:02:50
ds:docservice                    RUNNING   pid 846, uptime 0:02:52
ds:example                       STOPPED   Not started
ds:metrics                       STOPPED   Not started

💡 说明：example 与 metrics 默认关闭。若想启用欢迎页自带的示例服务，加环境变量 EXAMPLE_ENABLED=true（默认 false，官方 README 参数表）。

4.4 与集成平台对接（思路）

Document Server 部署完成后即可作为「编辑器服务」被集成：集成方（如 Nextcloud 的 ONLYOFFICE 连接器）配置服务地址 http://<服务器>:8145/ 与相同 JWT_SECRET，即可在文件列表中直接在线编辑 Office 文档。集成协议（文档编辑器接入 API、转换 API、命令服务）由官方 api.onlyoffice.com 提供；Nextcloud 侧的完整接入属于集成平台专题，本篇点到为止。

五、数据持久化说明

三个数据卷的宿主目录在 /opt/onlyoffice/data/ 下，职责与留存策略：

持久化实测：重建容器后（docker compose up -d 因配置变化 Recreate 容器），服务自动恢复 healthy、/healthcheck 再次返回 true、欢迎页 200，日志与数据目录内容完整保留——bind mount 宿主目录的数据不受容器重建影响。

⚠️ 注意：协同编辑过程中的源文档本体始终存放在集成方（如 Nextcloud），Document Server 只缓存编辑态；「备份 Document Server」备份的是服务配置与缓存，不是用户文档。备份体系应以集成方存储为主。

六、环境变量表

以下为 CE 10.0 常用环境变量（完整清单见官方 Docker-DocumentServer README，实查日期 2026-10-22；本表关键值均在 10.0.0.1 上实测核对）：

参数逐项细节与 local.json 对应关系见 《ONLYOFFICE Docs 10.0 配置参数详解》。

七、配置参数说明

compose 文件中的三段配置是部署的关键面：

1. JWT 三件套：JWT_ENABLED/JWT_SECRET/JWT_HEADER 决定所有进出请求的令牌校验。实测校验严格：无令牌或密钥不符的转换请求一律返回错误码 -8，配置正确且签名正确才放行。集成方两侧密钥必须一致，这是排障高频点。
2. 端口映射：8145:80。生产建议前置 Nginx/Caddy 反代并启用 TLS，容器侧 443 与自签证书方案仅在「无反代直连」时使用。
3. 资源与停止策略：stop_grace_period: 60s 保证协同会话保存窗口；restart: always 跟随宿主自启。

网络层面示例用了显式子网的自定义 bridge（10.89.74.0/24），多套 ONLYOFFICE 或与其他服务共主机时可避免网段漂移；单套部署直接省略 networks 段使用默认网络亦可。

八、等价 docker run

不使用 Compose 时，等价的单命令启动方式（参数与 compose 逐项对应，官方 README 也以此形态给出最小示例）：

docker run -i -t -d --name onlyoffice-ds --restart=always \
  -p 8145:80 \
  -e JWT_ENABLED=true -e JWT_SECRET=q1w2e3r4 -e JWT_HEADER=Authorization \
  -v /opt/onlyoffice/data/logs:/var/log/onlyoffice \
  -v /opt/onlyoffice/data/data:/var/www/onlyoffice/Data \
  -v /opt/onlyoffice/data/files:/var/lib/onlyoffice/documentserver/App_Data/cache/files \
  onlyoffice/documentserver:10.0.0.1

💡 说明：官方 README 的最小示例为 docker run -i -t -d -p 80:80 --restart=always onlyoffice/documentserver（未配置 JWT 与数据卷），适合本机快速体验；生产一律补齐密钥与持久化，即上例形态。

九、常用运维命令

在 /opt/onlyoffice/compose 下执行（实测环境回显见各命令后）：

docker compose ps            # 状态：Up (healthy) 为正常
docker logs -f onlyoffice-ds # 跟踪日志
docker compose restart       # 重启服务
docker compose down          # 停止并移除容器（数据卷在宿主目录，不受影响）
docker stats onlyoffice-ds --no-stream

docker stats 空闲态实测：

MEM 421.6MiB / 31.3GiB | CPU 100.64%

💡 说明：空载 CPU 为瞬时值（首次启动后台仍在生成插件清单/字体缓存，完成后回落至接近 0）；内存 421.6 MiB 为空载常驻，打开多人协同文档时会上浮。

升级流程（以 10.0 系列内补丁为例）：

cd /opt/onlyoffice/compose
docker compose pull          # 拉取新版本镜像
docker compose up -d         # 重建容器，数据卷保留

升级后必做：curl /healthcheck 应为 true，转换冒烟与集成方在线编辑各验证一次；跨大版本升级先读官方 Release Notes 与兼容性说明，并按第五章确认集成方文档不受影响。

十、常见问题

Q1：访问 /converter/ConvertService.ashx 返回 404 Cannot POST？

10.0 路由已调整（实测）：/converter/ConvertService.ashx 与根路径 /CommandService.ashx 已下线，返回：

Cannot POST /converter/ConvertService.ashx

HTTP 404。现行有效端点（POST 实测状态码）：

旧教程/旧集成代码请把转换端点改为 /ConvertService.ashx，命令服务改为 /coauthoring/CommandService.ashx。

Q2：集成方报「令牌校验失败」或转换返回 -8？

排查顺序：① 两侧 JWT_SECRET 是否一致；② 令牌是否放在约定的 JWT_HEADER 头（默认 Authorization）；③ 服务器与集成方时间偏差是否过大（JWT 校验含时间窗）。实测中密钥不符与无令牌均返回错误码 -8，可据此定位。

Q3：首次启动后 docker compose ps 一直 health: starting？

首次启动要生成字体缓存与插件清单（日志可见 Generating AllFonts.js、documentserver-pluginsmanager 联网更新），1~2 分钟内会转 healthy。healthcheck 已设 start_period: 120s，超时仍未恢复再查 docker logs。

Q4：转换请求报错 Error while downloading the document file 或连接被拒？

转换服务需要从 url 参数指定的地址下载源文件。10.0 默认 ALLOW_PRIVATE_IP_ADDRESS=false（官方 README 参数表），转换目标为私网/本机回环地址会被安全策略拒绝；内网存储接入时评估开启该变量或改由可公网寻址的地址提供源文件。

Q5：要不要为 CE 部署独立的 PostgreSQL/RabbitMQ/Redis？

不需要（实测确认，见第二章）：10.0 CE 启动脚本对三项依赖均标记不可用，容器内也没有对应进程与数据目录内容；相关 DB_*/AMQP_*/REDIS_* 环境变量仅在商业版生效。旧版本（9.x 及以前）「单容器内置四组件」的记忆不适用于 10.0 CE。

十一、参考链接

• 官方容器仓库（README：配置参数/Compose/硬件要求）：https://github.com/ONLYOFFICE/Docker-DocumentServer （查询日期 2026-10-22）
• 官方镜像与 tags：https://hub.docker.com/r/onlyoffice/documentserver （查询日期 2026-10-22）
• 官方编辑器/转换 API 文档：https://api.onlyoffice.com （查询日期 2026-10-22）
• 站内配套：选型背景见 《ONLYOFFICE Docs 介绍与选型指南》；参数详解见 《ONLYOFFICE Docs 10.0 配置参数详解》；CLI 与转换 API 实测见 《ONLYOFFICE Docs 10.0 常用 CLI 命令与工具详解》