ONLYOFFICE DocumentServer 的 JWT 密钥：怎么生成、配置、改

ONLYOFFICE DocumentServer 在编辑器（浏览器）和后端服务之间每次 API 调用都
加一个 JSON Web Token，用一个共享密钥签名。这个 token 阻止未认证的浏览器
直接跟你的编辑器对话、强制它们渲染任意文档。从 v7.2 起 JWT 默认
开启、密钥在首次启动时自动生成——意思是一般你什么都不用做。只有两种
情况需要碰这个设置：把 DocumentServer 接到外部服务（Nextcloud、
WordPress、Confluence、或者你自己的应用）的时候，以及把它放在需要事先
知道密钥的负载均衡器后面。

这是 2026 年 Linux + Docker 安装的完整走查：怎么读当前密钥、把它改成
你自己的，以及规避”DocumentServer 拒绝我的 JWT”那 90% 的两个常见陷阱。

密钥放在哪里

原生 Linux 安装（.deb / .rpm）：

/etc/onlyoffice/documentserver/local.json

Docker 安装默认没有文件。密钥在首次启动时生成，存在容器内存加上你
挂载的 named volume 里。通过 JWT_SECRET 环境变量自己设。

两种情况密钥都在同一 JSON 路径：

{
  "services": {
    "CoAuthoring": {
      "token": {
        "enable": {
          "browser": true,
          "request": {
            "inbox": true,
            "outbox": true
          }
        }
      },
      "secret": {
        "inbox":   { "string": "YOUR_SECRET_HERE" },
        "outbox":  { "string": "YOUR_SECRET_HERE" },
        "session": { "string": "YOUR_SECRET_HERE" }
      }
    }
  }
}

三件事要注意：

• inbox / outbox / session 三个地方的密钥必须完全一样。 这是
  JWT 认证失败的第一大原因——管理员从一台服务器复制密钥文件粘贴到
  另一台，结果漏改了第三个 section。
• 7.2 起 token 验证默认开启。 7.2 之前你还得手动把三个 enable.*
  开关从 false 翻到 true。如果你从旧版本升上来，手动设的密钥会保留，
  但 enable 开关保持原状。
• HTTP header 携带 token 用 `Authorization: Bearer *** （默认），JWT 是标准 HS256。

改密钥 —— Linux 原生安装

sudo nano /etc/onlyoffice/documentserver/local.json
# 把三处的 YOUR_SECRET_HERE 改成你自己的——三处必须完全一样

sudo systemctl restart ds-converter ds-docservice ds-metrics
# 验证一下：
sudo cat /etc/onlyoffice/documentserver/local.json | grep '"string"'
# 应该看到 YOUR_SECRET_HERE 连续出现三次。

重启顺序很重要：ds-converter（处理文件格式转换）、ds-docservice
（编辑器服务本体）、ds-metrics（Prometheus exporter）。按这个顺序重启，
老的 token session 干净死掉，新密钥才生效。

改密钥 —— Docker

Docker 上不要直接编辑容器里的 local.json。 容器文件系统是临时的，
任何手动改动在重启时会消失。用环境变量：

docker run -i -t -d -p 80:80 
  -e JWT_ENABLED=true 
  -e JWT_SECRET='你自己的密钥' 
  -e JWT_HEADER=Authorization 
  -e JWT_IN_BODY=false 
  onlyoffice/documentserver

注意：

• JWT_ENABLED=false 完全关掉 token 验证。生产环境别用——这只是调试。
• JWT_HEADER=AuthorizationJwt（老惯例）依然支持；v6.x 起的默认就是
  Authorization。
• JWT_IN_BODY=false 表示 token 放在 Authorization header 里。如果设
  true，ONLYOFFICE 会从请求体里读 token。默认是 false。
• JWT_SECRET 只在启动时读一次。改密钥必须重建容器。 docker restart
  不会重读。

改完 JWT_SECRET 还要同步更新连接的那个服务的密钥
（Nextcloud 的 ONLYOFFICE connector、你应用里的配置、随便是谁）。

生成一个够强的密钥

默认生成的是 64 字符随机 hex 串。你自己设的话用同等不可猜测的就行。
不要用 UUID、也不要拿你们团队的 slack 频道名。openssl rand -hex 32 足够：

openssl rand -hex 32
# → 7c2c89ff04e3...（64 字符 hex）

密钥只要在 DocumentServer + connector 完全一致就行，其他字符没任何
意义。挑 64 字符 hex 能避开所有”你的字符串里有 $，bash 把
它吃掉了”这种坑边情况。

读当前的密钥

忘了自己设过啥：

# Linux 原生
cat /etc/onlyoffice/documentserver/local.json | 
  jq -r '.services.CoAuthoring.secret | to_entries[] | .value.string'

# Docker（不重启容器）
docker exec documentserver 
  cat /etc/onlyoffice/documentserver/local.json | 
  jq -r '.services.CoAuthoring.secret | to_entries[] | .value.string'

没 jq 的话直接 grep -A 1 'string' 循环跑也能拿到。

两个常见陷阱

1. 升级后密钥失配

GitHub 上大量的 “DocumentServer keeps rejecting my JWT” 都来自这个场景：
connector 配置的是老密钥，但系统升级脚本自动生成了一个新的。
DocumentServer 这时候两端都有密钥，但不一样。修复方法是两边完全相同
的字符串，包括不能有前后空格。

2. JWT_IN_BODY=false vs true 默认值跨版本变了

v6.x 里 JWT_IN_BODY 默认 false。某些 v7.x 点版本里，取决于你怎么升
的，会变成 true。如果你的 connector 一会儿工作一会儿不工作，看这个开关：

docker exec documentserver cat /etc/onlyoffice/documentserver/local.json 
  | jq '.services.CoAuthoring.token.enable | .browser, (.request.inbox, .request.outbox)'

应该看到 true 三个。如果是 false，升级时你把它们覆盖了。

2026 我真会怎么配

Docker 单 VM 部署，connector 配置进版本控制：

# docker-compose.yaml
services:
  documentserver:
    image: onlyoffice/documentserver
    restart: unless-stopped
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET_FILE: /run/secrets/jwt_secret
      JWT_HEADER: Authorization
    volumes:
      - /var/run/secrets/jwt_secret:/run/secrets/jwt_secret:ro
      - documentserver_data:/var/lib/onlyoffice
    ports:
      - "8080:80"

通过 Docker secrets 生成密钥（openssl rand -hex 32 | docker secret create jwt_secret -）的好处是旋转密钥时不用改
docker-compose.yaml 本身。JWT_SECRET_FILE 环境变量从文件路径读密钥
——v7.4 起可用——在 Swarm 或者任何带 secrets store 的编排器下都是正确
姿势。

参考资料

• ONLYOFFICE Docs 官方 JWT 配置文档：https://helpcenter.onlyoffice.com/docs/installation/docs-configure-jwt.aspx
• ONLYOFFICE Docs 故障排查（JWT 部分）：https://helpcenter.onlyoffice.com/docs/installation/docs-troubleshooting-linux.aspx
• ONLYOFFICE DocumentServer Docker Hub：https://hub.docker.com/r/onlyoffice/documentserver