ONLYOFFICE Docs 10.0 配置参数详解

目标：系统讲清 ONLYOFFICE Docs（Document Server）10.0 社区版的参数体系——环境变量层、local.json/default.json 配置文件层的查看方法、默认值与实测行为，并给出生产配置模板。全部关键行为在 10.0.0.1 实例上实测验证。部署过程见《ONLYOFFICE Docs 10.0 Docker Compose 部署指南》，选型背景见《ONLYOFFICE Docs 介绍与选型指南》。

一、环境信息

操作系统：Ubuntu 22.04；服务版本：onlyoffice/documentserver:10.0.0.1（社区版，Docker Hub 2026-10-12 更新）；
配置文件目录：/etc/onlyoffice/documentserver/（default.json 全量默认值、local.json 运行时叠加值）；示例服务配置在 /etc/onlyoffice/documentserver-example/；
参数查看与修改验证工具：官方自带 JSON CLI（/var/www/onlyoffice/documentserver/npm/json），以下回显均为实测。

二、前置条件

已按部署篇完成 10.0 服务部署并可访问（/healthcheck 返回 true）；
修改配置文件需具备 root 权限（配置目录属主为 ds 用户，修改前用 root 执行）；
理解参数分层的三个事实（本环境实测归纳）：
1. 环境变量是第一层：容器启动脚本读取 JWT_SECRET 等环境变量，在启动时写入/合并到 local.json；
2. local.json 是运行时层：覆盖 default.json 同名项，服务读取的最终值以 local.json 为准；
3. 部分项由启动脚本自动管理：手工修改会在重启时被脚本重写（实测详见 4.3 节），改这类项必须走环境变量。

三、参数查看与修改方式

3.1 查看最终生效值

官方 JSON CLI 读取（实测）：

docker exec onlyoffice-ds /var/www/onlyoffice/documentserver/npm/json \
  -q -f /etc/onlyoffice/documentserver/local.json services.CoAuthoring.secret.browser.string

实测输出：

q1w2e3r4

💡 说明：CLI 用法为 json -q -f <文件> <点分路径>，路径即配置 JSON 的键路径。docker exec 前缀是本文实验环境的执行方式，装在服务器本机时去掉前缀直接执行即可。

也可直接读文件（local.json 为 JSON 格式，可用 python/jq 格式化）：

python3 -m json.tool /etc/onlyoffice/documentserver/local.json

3.2 修改方式与实测

方式一（推荐）：改环境变量，重建容器——部署篇 compose 的 environment: 段即此方式，对 JWT_*、EXAMPLE_ENABLED、NGINX_*、SSL_* 等脚本托管项一律走这条路。

方式二：手工改 local.json——只对脚本不管的项有效。修改语法（官方 CLI 的 -I 原地编辑，实测）：

cd /etc/onlyoffice/documentserver
cp local.json local.json.bak
/var/www/onlyoffice/documentserver/npm/json -q -I -f local.json \
  -e 'this.services.CoAuthoring.expire.presence=600'

⚠️ 注意语法：-I 必须搭配 -f local.json，写成 -I -e '...' local.json（文件放末尾）会报错 json: error: must specify exactly one file with "-f FILE" to use -I/--in-place（实测）。改完重启服务生效，改前备份。

四、参数总览与核心分类详解

4.1 参数全景

10.0 的参数分布在四个层面（按「谁管它」划分）：

层面	载体	代表参数	修改方式
部署编排	环境变量	`JWT_ENABLED/JWT_SECRET/JWT_HEADER`、`EXAMPLE_ENABLED`、`WOPI_ENABLED`	compose environment，重建容器
运行时叠加	`local.json`	token/secret、WOPI 密钥、storage	手工编辑（脚本托管项除外）
全量默认	`default.json`	一切配置的默认基线	只读，不改
nginx/系统层	`/etc/onlyoffice/documentserver/nginx/`、logrotate	虚拟主机、日志轮转	手工编辑，重启 nginx

4.2 JWT 与安全令牌（token/secret 段）

服务最终生效的令牌配置由环境变量写入 local.json，实测 local.json 的实际内容（结构节选）：

"services": {
  "CoAuthoring": {
    "token": {
      "enable": { "browser": true, "request": { "inbox": true, "outbox": true } },
      "inbox": { "header": "Authorization", "inBody": false },
      "outbox": { "header": "Authorization", "inBody": false }
    },
    "secret": {
      "browser": { "string": "q1w2e3r4" },
      "inbox":  { "string": "q1w2e3r4" },
      "outbox": { "string": "q1w2e3r4" },
      "session": { "string": "q1w2e3r4" }
    }
  }
}

逐项说明（默认值均实测核对）：

token.enable.browser/inbox/outbox：浏览器侧与双向服务间令牌校验开关，default.json 默认全 true（实测 default.json 同路径值一致）——10.0 的 JWT 默认强制开启；
secret.string 四段：browser/inbox/outbox/session 分别对应「下发给浏览器的令牌、接收外部请求、发出外部请求、会话」四个用途的签名密钥，由 JWT_SECRET 环境变量统一填充（实测四段同值）；
inbox.header/outbox.header：即环境变量 JWT_HEADER 的落点，默认 Authorization；
inBody：默认 false，令牌放请求体 JSON 的 token 字段而非整个请求体签名。

实测验证行为（完整签名与请求过程见命令篇）：无令牌请求转换端点返回 {"error":-8}；密钥错误同样 -8；密钥与签名正确才放行。

4.3 会话与过期控制（expire 段）

default.json 的 expire 段默认值（实测原样取回）：

"expire": {
  "saveLock": 60, "presence": 300, "locks": 604800, "changeindex": 86400,
  "lockDoc": 30, "message": 86400, "lastsave": 604800, "forcesave": 604800
}

关键项解读：

presence（默认 300 秒）：协同会话中判定用户在线的窗口，实时协作掉线重连场景可适当调大；
locks（默认 604800 秒 = 7 天）：编辑锁最长保留时间；
lastsave（默认 604800）：距上次保存的最大时长，超时强制落盘；
forcesave（默认 604800）：强制保存命令的时效窗口；
lockDoc（默认 30 秒）：打开文档时的加锁超时。

4.4 请求过滤与 IP 限制（ipfilter / request-filtering-agent）

default.json 默认值（实测原样）：

"ipfilter": { "rules": [ { "address": "*", "allowed": true } ], "useforrequest": false, "errorcode": 403 },
"request-filtering-agent": { "allowPrivateIPAddress": false, "allowMetaIPAddress": false }

解读与实测关联：

ipfilter.rules：默认放行所有来源（* allow true）；改写为白名单时按 allowPrivateIPAddress 语义逐条列出地址，命中拒绝返回 errorcode（默认 403）；
request-filtering-agent.allowPrivateIPAddress=false：服务端转出请求（如转换服务下载源文件）默认禁止访问私网/回环地址——这正是部署篇 Q4「转换 url 指向内网存储被拒」的配置根源；需要内网存储时用环境变量 ALLOW_PRIVATE_IP_ADDRESS=true 开启；
allowMetaIPAddress=false：同理禁止元地址（169.254.169.254 类元数据端点），云上部署保持默认。

4.5 存储配置（storage 段）

10.0 存储后端默认 storage-fs（本地文件系统），default.json 相关默认值（实测原样）：

"storage": { "name": "storage-fs", "fs": { "urlExpires": 900, "secretString": "verysecretstring" }, "urlExpires": 604800 }

实测重要行为：storage.fs.secretString（local.json 中实际值）由启动脚本每次启动重新随机生成。本环境实测过程：手工用 -I 改成 new-secret-2026 → docker compose restart → 回读变为全新随机值 K9hNTdCh0LoSQyVbGjV9，手工值被覆盖。该项属「脚本托管」，请勿手工改；而同一重启周期内 services.CoAuthoring.secret.browser.string 保持环境变量值 q1w2e3r4 不变（对照组实测），证明脚本只重写它托管的项。

⚠️ 结论：识别「脚本托管项」的方法——改完重启被弹回/变化的项（storage secret、secure_link 等随机项）一律走环境变量或不改；需要固定的密钥类值（JWT）用环境变量固化。

4.6 WOPI 配置（wopi 段）

local.json 中的 wopi 段由 WOPI_ENABLED 与启动脚本管理，实测字段：enable（默认 false）、privateKey/privateKeyOld（RSA 私钥，首次启动自动生成并打印 Generating WOPI private key...Done）、publicKey/modulus/exponent（对应公钥材料，供 WOPI 客户端校验）。启用 WOPI 的标准方式是环境变量 WOPI_ENABLED=true，密钥无需手工管理。

4.7 数据库与消息队列参数（CE 不生效，商业版专用）

default.json 中存在 services.CoAuthoring.sql（type=postgres、dbHost=localhost:5432、库名/账号 onlyoffice）与 rabbitmq（amqp://localhost:5672）等配置，但 10.0 社区版实测不使用它们：启动脚本以 DB_AVAILABLE/RABBITMQ_AVAILABLE/REDIS_AVAILABLE（是否商业版 PRODUCT_EDITION 决定）为开关，CE 下三者皆 false（脚本第 63-64、795-797 行实测），容器内无 postgres/rabbitmq/redis 进程、supervisorctl status 也无对应单元。DB_*/AMQP_*/REDIS_* 环境变量系列仅在商业版生效（官方 README 参数表同样标注）。CE 排障时不要在此浪费时间。

4.8 nginx 层参数

NGINX_WORKER_PROCESSES：nginx worker 进程数，默认未设（取 nginx 编译默认，一般等于 CPU 核数）；
NGINX_WORKER_CONNECTIONS：单 worker 最大连接数，默认取 ulimit -n 软限制（官方 README）；
NGINX_ACCESS_LOG：默认 true，输出 JSON 过滤后的访问日志（排查请求级问题后建议关闭省磁盘）；
SECURE_LINK_SECRET：nginx secure_link 签名密钥，默认随机串（与 4.5 同理为脚本托管类，随机项）。

五、生产配置模板

适用场景：8 GB 内存、4 核、NVMe SSD、≤20 并发连接（CE 许可边界）的团队级部署。compose environment: 段模板：

environment:
  - JWT_ENABLED=true
  - JWT_SECRET=<32位以上长随机串，与集成方一致>
  - JWT_HEADER=Authorization
  - WELCOME_PAGE_ENABLED=true
  - EXAMPLE_ENABLED=false
  - GENERATE_FONTS=false
  - NGINX_WORKER_PROCESSES=4
  - METRICS_ENABLED=false

逐项说明：JWT_SECRET 生产必改且定期轮换（轮换时集成方同步）；GENERATE_FONTS=false 关闭每次启动重建字体清单以加快启动（安装新字体后需手动触发一次重建，见命令篇）；NGINX_WORKER_PROCESSES=4 对齐 CPU 核数；示例服务与指标默认关闭保持最小暴露面。数据卷、健康检查与网络配置沿用部署篇 compose 模板即可。

六、常见问题

Q1：改了 local.json 重启后被改回/变成随机值？

该项由启动脚本托管（实测案例见 4.5：storage.fs.secretString 每次启动重生成）。解决办法：改环境变量重建容器，或接受随机值（随机生成的项本来就无需固定）。

Q2：JWT 密钥轮换怎么做？

改 compose 的 JWT_SECRET → docker compose up -d 重建 → local.json 四段 secret 自动更新（实测：browser/inbox/outbox/session 均随环境变量填充）。轮换窗口内集成方两侧密钥同步，否则返回 -8。

Q3：怎么确认某个参数的「最终生效值」？

用 3.1 节的 JSON CLI 读 local.json（运行时层）；local.json 没有的项读 default.json（默认层）。两者都没有的看环境变量与脚本（如 storage secret 是运行时生成，只存在于 local.json）。

Q4：转换服务连不上内网存储？

request-filtering-agent.allowPrivateIPAddress 默认 false 所致（4.4 节），用环境变量 ALLOW_PRIVATE_IP_ADDRESS=true 放行私网；元地址限制同理用 ALLOW_META_IP_ADDRESS。

七、参考链接

官方容器仓库参数表（实查日期 2026-10-22）：https://github.com/ONLYOFFICE/Docker-DocumentServer
官方编辑器接入 API：https://api.onlyoffice.com
站内配套：部署与排障见《ONLYOFFICE Docs 10.0 Docker Compose 部署指南》；转换 API 与管理脚本实测见《ONLYOFFICE Docs 10.0 常用 CLI 命令与工具详解》；选型见《ONLYOFFICE Docs 介绍与选型指南》