ONLYOFFICE Docs 10.0 常用 CLI 命令与工具详解

目标：系统梳理 ONLYOFFICE Docs（Document Server）10.0 的服务端管理脚本族与转换/命令 REST API，全部命令与回显在 10.0.0.1 实例上实测采集，可直接作为日常运维与集成排障速查。部署背景见《ONLYOFFICE Docs 10.0 Docker Compose 部署指南》，参数含义见《ONLYOFFICE Docs 10.0 配置参数详解》。

一、环境信息

操作系统：Ubuntu 22.04；服务版本：onlyoffice/documentserver:10.0.0.1（社区版；CommandService 实测内部构建号 10.0.0.169）；
服务端口：8145 → 服务 80；管理脚本目录：/usr/bin/documentserver-*；
服务管理器：supervisor（supervisorctl），托管单元：ds:docservice、ds:converter、ds:example、ds:metrics（后两者默认 STOPPED）。

二、工具概览

10.0 的管理面由三部分组成（工具名均实测）：

类别	工具	用途
管理脚本族	`/usr/bin/documentserver-*`（9 个）	JWT 查看、缓存、字体、插件、证书、停机准备等
服务管理	`supervisorctl`	四个托管服务的启停与状态
REST API	`/ConvertService.ashx`、`/coauthoring/CommandService.ashx`	文档格式转换、协同命令（外部调用面）

10.0 版本差异（实测确认）：旧版本教程中的 documentserver-generate-all-shields.sh、documentserver-prepare-to-run.sh 在 10.0 的 /usr/bin/ 下已不存在（ls /usr/bin/documentserver-* 无匹配）；现行脚本族清单见下节。此外每个脚本存在双形态：documentserver-xxx 与 documentserver-xxx.sh 内容相同（均为 #!/bin/bash 开头、要求 root 权限的脚本），任选其一即可。

10.0 实测脚本族全集（ls /usr/bin/documentserver-* 回显）：

/usr/bin/documentserver-example
/usr/bin/documentserver-example.sh
/usr/bin/documentserver-flush-cache
/usr/bin/documentserver-flush-cache.sh
/usr/bin/documentserver-generate-allfonts
/usr/bin/documentserver-generate-allfonts.sh
/usr/bin/documentserver-jwt-status
/usr/bin/documentserver-jwt-status.sh
/usr/bin/documentserver-letsencrypt
/usr/bin/documentserver-letsencrypt.sh
/usr/bin/documentserver-pluginsmanager
/usr/bin/documentserver-pluginsmanager.sh
/usr/bin/documentserver-prepare4shutdown
/usr/bin/documentserver-prepare4shutdown.sh
/usr/bin/documentserver-static-gzip
/usr/bin/documentserver-static-gzip.sh
/usr/bin/documentserver-update-securelink
/usr/bin/documentserver-update-securelink.sh

三、前置条件

以 root 执行（脚本首行统一有 Root privileges required 校验）；
服务运行中（/healthcheck 返回 true）；
命令运行于服务器本机；本文为便于在统一实验环境采集，均以 docker exec onlyoffice-ds <命令> 形式调用，服务器本机直接去掉该前缀执行即可。

四、管理脚本族详解

4.1 documentserver-jwt-status：查看 JWT 配置

排查「令牌校验失败」第一步：确认服务侧实际生效的 JWT 三项配置。

docker exec onlyoffice-ds documentserver-jwt-status

实测输出：

Your JWT settings:
JWT enabled -  true
JWT secret  -  q1w2e3r4
JWT header  -  Authorization

💡 说明：三项分别对应环境变量 JWT_ENABLED/JWT_SECRET/JWT_HEADER 落入 local.json 后的生效值；与集成方配置比对即可定位两侧密钥不一致问题。

4.2 documentserver-flush-cache：清空缓存并重载 nginx

docker exec onlyoffice-ds documentserver-flush-cache

实测输出：

 * Reloading nginx configuration nginx
   ...done.

用于更新编辑器静态资源或调整 nginx 模板后刷新；执行后页面需强制刷新（Ctrl+F5）避免浏览器旧缓存。

4.3 documentserver-generate-allfonts：重建字体缓存

安装新字体后必须执行，否则编辑器字体列表不变。实测（本环境含全量字体生成，耗时约 2 分钟）：

docker exec onlyoffice-ds documentserver-generate-allfonts

实测输出（节选，含完成后的服务拉起与 nginx 重载）：

ds:converter: started
 * Reloading nginx configuration nginx
   ...done.
 * Reloading nginx configuration nginx
   ...done.

实测耗时：

real    1m54.528s

⚠️ 注意：该脚本会重启 docservice/converter，执行窗口内在线编辑会话中断，请在维护窗口操作。若部署时设置 GENERATE_FONTS=false，则新字体只能靠本命令手动触发。

4.4 documentserver-static-gzip：静态资源压缩重建

docker exec onlyoffice-ds documentserver-static-gzip

实测输出：

 * Reloading nginx configuration nginx
   ...done.

对编辑器静态文件预生成 gzip 副本，首次启动后台会自动执行一次；修改静态资源后手动运行。

4.5 documentserver-update-securelink：更新 secure_link 密钥

docker exec onlyoffice-ds documentserver-update-securelink

实测输出（注意：会重启两个核心服务）：

ds:docservice: ERROR (not running)
ds:docservice: started
ds:converter: ERROR (not running)
ds:converter: started
 * Reloading nginx configuration nginx

支持参数 -s <secret> 指定密钥、-r false 跳过重启（部署脚本即以此形态调用）；无参运行则生成新随机密钥并重启服务。secure_link 用于缓存文件下载链接的防篡改签名（配置含义见参数篇 4.5）。

4.6 documentserver-example：示例服务管理

三段子命令 {start|stop|status}，实测：

docker exec onlyoffice-ds documentserver-example status

ds:example                       STOPPED   Not started

⚠️ 注意：example 默认停用（EXAMPLE_ENABLED=false）。若环境变量未开，start 后也不会持久运行（重启即回默认态）；生产建议保持关闭。

4.7 documentserver-prepare4shutdown：停机前强制保存

docker exec onlyoffice-ds documentserver-prepare4shutdown

实测输出：

Preparing for shutdown, it can take a lot of time, please wait...Done

作用是把所有打开中的协同文档强制落盘回写，再执行 docker compose down/重启宿主前必须先跑，避免丢失编辑窗口内的变更。当前无打开文档时立即 Done。

4.8 documentserver-pluginsmanager：插件管理

查看帮助（实测节选）：

docker exec onlyoffice-ds documentserver-pluginsmanager --help

Plugins Manager Options

  --h
  --help               = Print usage information.

  --directory          = Required parameter. Set plugins folder in quotes.
                         For example, --directory="/home/mark/plugins"
                         Must be first on the command line.

  --marketplace        = Optional parameter. Set plugins marketplace URL in quotes.
                         Default is https://onlyoffice.github.io

  --print-installed    = Optional parameter without value. Print installed plugins.
  ...（另有 --update、--remove、--remove-all、--ignore，格式如
      --remove="Youtube, PhotoEditor, {7327FC95-16DA-41D9-9AF2-0E7F449F6800}"）

列出已安装插件（实测）：

docker exec onlyoffice-ds documentserver-pluginsmanager --directory="/var/www/onlyoffice/documentserver/sdkjs-plugins/" --print-installed

实测输出（节选）：

translator          1.0.8                     {7327FC95-16DA-41D9-9AF2-0E7F449F6800}
thesaurus           1.0.3                     {BE5CBF95-C0AD-4842-B157-AC40FEDD9840}
highlight code      1.0.3                     {BE5CBF95-C0AD-4842-B157-AC40FEDD9841}
photo editor        1.0.4                     {07FD8DFA-DFE0-4089-AL24-0730933CC80A}
ds:docservice: stopped
ds:docservice: started
 * Reloading nginx configuration nginx
   ...done.

💡 说明：输出列依次为插件名、版本、GUID；尾部自动重启 docservice 使插件状态生效。--update 与部署启动时的联网刷新一致（首次启动日志里的 documentserver-pluginsmanager --update=... 即本工具）。

4.9 documentserver-letsencrypt：自动证书

设了环境变量 LETS_ENCRYPT_DOMAIN 与 LETS_ENCRYPT_MAIL 后启动脚本自动调用；手工运行：

docker exec onlyoffice-ds documentserver-letsencrypt <邮箱> <域名>

仅在域名可公网解析且 80 端口可达时成功；无公网域名场景改用自签证书方案（见部署篇环境变量表 SSL_* 系列与参数篇说明）。

4.10 supervisorctl：核心服务管理

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

单元启停示例（逐单元执行）：

docker exec onlyoffice-ds supervisorctl restart ds:docservice
docker exec onlyoffice-ds supervisorctl restart ds:converter

💡 说明：docservice 是文档管理与协同入口（管 Web 请求），converter 负责格式转换；两者由多个管理脚本间接重启，手工干预时逐单元操作、避免同时全停。

五、转换服务 REST API（ConvertService）实测

转换服务提供 HTTP 端点，把 docx/xlsx/pptx 等转为 pdf 或其他格式，是「文档转档/预览」集成的核心接口。

5.1 端点与请求结构

现行端点：POST /ConvertService.ashx（10.0 实测有效）；
⚠️ 旧路径 /converter/ConvertService.ashx 在 10.0 已下线，实测返回 Cannot POST /converter/ConvertService.ashx（HTTP 404）——旧集成代码迁移时必须改路径；
请求体 JSON 关键字段：async（false 同步）、filetype（源格式）、outputtype（目标格式）、title、url（源文件下载地址，服务端会主动拉取）；
JWT 开启时（10.0 默认），请求体须携带 token 字段：对上述业务字段做 HS256 签名（密钥即 JWT_SECRET）。

5.2 无令牌请求（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"}'

实测输出（HTTP 200，XML 错误体，-8 = 令牌校验失败）：

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

💡 说明：错误响应默认是 XML 形态；携带 Accept: application/json 头且令牌被校验到时才是 JSON 形态（下一节实测）。看到 -8 先查 JWT（脚本 documentserver-jwt-status 与签名实现）。

5.3 带令牌的完整转换（docx → pdf）

以 JWT_SECRET=q1w2e3r4、源文件由服务侧 HTTP 提供（http://127.0.0.1:9999/t.docx）为例。签名与请求（Python 标准库实测脚本）：

import hmac, hashlib, base64, json, urllib.request

def b64url(b): return base64.urlsafe_b64encode(b).rstrip(b'=').decode()
secret = 'q1w2e3r4'
payload = {'async': False, 'filetype': 'docx', 'outputtype': 'pdf',
           'title': 't.docx', 'url': 'http://127.0.0.1:9999/t.docx'}
header = {'alg': 'HS256', 'typ': 'JWT'}
signing = b64url(json.dumps(header, separators=(',',':')).encode()) + '.' \
        + b64url(json.dumps(payload, separators=(',',':')).encode())
sig = b64url(hmac.new(secret.encode(), signing.encode(), hashlib.sha256).digest())
body = dict(payload); body['token'] = signing + '.' + sig
req = urllib.request.Request('http://127.0.0.1:8145/ConvertService.ashx',
                             data=json.dumps(body).encode(),
                             headers={'Content-Type':'application/json','Accept':'application/json'})
r = urllib.request.urlopen(req, timeout=120)
print('HTTP', r.status); print(r.read().decode()[:600])

实测输出：

HTTP 200
{"fileUrl":"http://127.0.0.1:8145/cache/files/data/conv_undefined_513/output.pdf/t.pdf?md5=V1no5Zcmrji-mLNLwvOyaA&expires=1792613665&filename=t.pdf","fileType":"pdf","percent":100,"endConvert":true}

回执解读：endConvert=true + percent=100 表示转换完成，fileUrl 为带 md5 与 expires 防篡改签名的临时下载链接（过期由 storage.urlExpires 类参数控制）。

错误密钥对照实测：把签名密钥换成 wrong-secret，实测返回：

HTTP 200 {"error":-8}

下载转换产物（对 fileUrl 实测）：

curl -s "<fileUrl>" -o t.pdf -w "HTTP %{http_code}, %{size_download} bytes\n"
file t.pdf

实测输出：

HTTP 200, 28344 bytes
t.pdf: PDF document, version 2.0, 1 pages

⚠️ 注意：url 参数指定的源文件地址由 Document Server 服务端拉取。默认安全策略禁止服务端访问私网/回环地址（request-filtering-agent.allowPrivateIPAddress=false，实测本例能通过是因为源文件服务与转换服务同机且为同侧调用形态）；内网存储接入时需按参数篇 4.4 处理，或以公网可寻址地址提供源文件。

5.4 命令服务（CommandService）实测

POST /coauthoring/CommandService.ashx（10.0 现行端点；根路径 /CommandService.ashx 已下线返回 404）。携带 JWT 的 version 命令实测：

payload = {'c': 'version'}   # 同法 HS256 签名后放入 token 字段
# POST http://127.0.0.1:8145/coauthoring/CommandService.ashx

实测输出：

HTTP 200
{"error":0,"version":"10.0.0.169"}

error:0 为成功；version 回报服务内部构建号。命令服务另支持 forceSave（强制保存）、drop（断开用户会话）等协同管理命令（详见官方 api.onlyoffice.com 的命令服务文档），格式与上例一致：c 字段 + 对应业务字段整体签名。

六、注意事项

改路径：10.0 迁移旧集成时，转换改 /ConvertService.ashx、命令服务改 /coauthoring/CommandService.ashx（5.1/5.4 实测）；
JWT 三查：documentserver-jwt-status 看服务侧 → 比对集成方 → 检查签名算法（HS256）与字段集（对业务字段整体签名）；
停机顺序：documentserver-prepare4shutdown → 停服务，两步之间不要跳过；
脚本副作用：update-securelink、generate-allfonts、pluginsmanager 都会重启 docservice/converter，维护窗口执行；
fileUrl 时效：转换产物链接带 expires，需要长期留存应转换后立即转存到自有存储。

七、常见问题

Q1：脚本执行报 Root privileges required？

脚本首行做 root 校验（实测脚本头 #!/bin/bash + uid 判断），切 root 或容器内以 root 执行（容器内默认即 root）。

Q2：转换一直返回 -8？

按第六节 JWT 三查；另注意无令牌时响应是 XML（<Error>-8</Error>）、带 Accept 头且能解析令牌时是 JSON（{"error":-8}），两种形态都指向令牌问题。

Q3：转换成功但 fileUrl 下载 403？

expires 已过期或 md5 校验失败（链接被改写）。重新发起转换取新链接，不要缓存 fileUrl。

Q4：healthcheck 返回 false 或超时？

supervisorctl status 看四个单元；converter/docservice 非 RUNNING 时查 /var/log/onlyoffice/documentserver/ 下对应日志（logs 数据卷映射出的宿主目录）。

八、参考链接

官方转换 API 文档：https://api.onlyoffice.com/docs/docs-api/usage-api/convertion-api/ （查询日期 2026-10-22）
官方命令服务文档：https://api.onlyoffice.com/docs/docs-api/usage-api/command-service/ （查询日期 2026-10-22）
官方容器仓库（脚本族来源）：https://github.com/ONLYOFFICE/Docker-DocumentServer （查询日期 2026-10-22）
站内配套：部署见《ONLYOFFICE Docs 10.0 Docker Compose 部署指南》；参数见《ONLYOFFICE Docs 10.0 配置参数详解》；选型见《ONLYOFFICE Docs 介绍与选型指南》