一、直击痛点：权限报错的诡异场景

做 Onlyoffice9 集成开发时，你是否遇到过这样的怪事？

用Config config = createConfig(fileId, mode, type);创建配置后，明明参数都填对了，可往 config 里加完自定义参数（列如文档标题、权限设置），传到前端就弹出

**“您正在尝试执行您没有权限的操作”** 。

查日志无异常，权限配置也没错，问题到底出在哪？实则这是 Onlyoffice9 的 JWT 令牌机制在 “搞鬼”！

二、根源剖析：JWT 校验的底层逻辑

Onlyoffice 从 v7.2 开始默认启用 JWT（JSON Web Token）安全机制，所有配置参数的合法性都靠它校验，核心原理有 3 点：

1. 令牌自动生成：createConfig方法会自动生成 token，这个 token 是用当前 config 的完整数据（如 fileId、mode 等）作为 payload 加密生成的；
2. 三段式令牌结构：JWT 由 header（算法）、payload（配置数据）、signature（密钥签名）组成，三者缺一不可且无法篡改；
3. 严格校验规则：前端传递 config 到文档服务器时，服务器会解密 token 中的 payload，与实际 config 数据比对 —— 一旦修改 config 却没更新 token，两者就会不一致，直接触发权限校验失败。

简单说：初始 token 是 “旧 config 的通行证”，改了 config 就得换 “新通行证” 。

三、终极解决方案：3 行代码 Fix 问题

关键操作只有一个：修改 config 后，必须重新生成并设置 token！

结合官方安全最佳实践，直接复用这套代码模板：

// 1. 初始创建配置

Config config = createConfig(fileId, mode, type);

// 2. 此处添加你的自定义配置（如修改文档权限、添加水印等）

config.setDocumentTitle("机密文档");

config.setPermissions(new Permissions(true, false)); // 允许编辑，禁止下载

// 3. 核心：修改后重新生成token（关键一步！）

if (getSettingsManager().isSecurityEnabled()) { // 检查安全配置是否启用

config.setToken(getJwtManager().createToken(config)); // 用新config生成token

}

代码说明：

• isSecurityEnabled()：判断 Onlyoffice 是否开启安全校验（v9 默认开启），避免无意义的 token 生成；
• createToken(config)：通过 JWT 管理器，用最新的 config 数据和服务器密钥重新生成令牌，确保 payload 与 config 完全匹配。

四、避坑补充：2 个关键注意事项

1. 密钥必须一致

生成 token 的密钥要和文档服务器local.json配置中的密钥完全一样：

// Linux路径：/etc/onlyoffice/document-server/local.json

"secret": {

  "inbox": {"string": "你的密钥"},

  "outbox": {"string": "你的密钥"},

  "session": {"string": "你的密钥"}

}

密钥不匹配会直接导致 “token 格式错误”（error code: -20）。

1. Docker 环境特殊处理

用 Docker 部署时，不能直接改local.json（重启会重置），需通过环境变量设置密钥：

docker run -e jwt_secret=你的密钥 onlyoffice/documentserver

五、快速排错：3 步定位问题

若仍报错，按这个顺序排查：

1. 查日志：看/var/log/onlyoffice/documentserver/日志，是否有 “token invalid” 提示；
2. 验 token：用 JWT 解码工具（如 jwt.io）解析 token，对比 payload 与实际 config；
3. 查配置：确认services.coauthoring.token.enable.browser是否为true（默认启用）。