OnlyOffice参数配置全指南：JWT密钥、存储、编辑器行为与多语言设置

1. 项目概述为什么“OnlyOffice 参数设置”是实际落地中最常卡住的环节OnlyOffice 不是装上就能用的开箱即用型软件它更像一台精密可调的工业级文档处理工作站——默认配置只保障基础功能运转而真正决定它能否融入你现有系统、支撑百人并发编辑、适配多语言环境、对接单点登录、满足审计合规要求的全在那一套层层嵌套、相互制约的参数体系里。我过去三年帮二十多家企业部署 OnlyOffice从政务云到制造业ERP集成从教育SaaS到律所知识库90%以上的返工和延期都卡在参数配置环节而不是安装本身。很多人搜“onlyoffice安装问题”最后发现根本不是安装失败而是安装后服务起不来、编辑器打不开、协作功能失灵归根结底是local.json里一个token配置项写错了格式或是docker-compose.yml中JWT_SECRET和前端 JS SDK 的密钥不一致。这些参数不是孤立存在的它们构成一张网前端请求头里的Authorization值要能被后端document-server的token.inbox规则校验通过storage.type设为s3后s3.bucketName必须和s3.region的 endpoint 地址语法完全匹配启用forceSaveAs模式时customization.goback.url若没带协议头https://整个返回按钮就会失效。这正是“onlyoffice参数设置”成为高频搜索词的核心原因——它不是技术文档里的可选章节而是生产环境上线前必须亲手拧紧的每一颗螺丝。本文面向的是已经完成基础部署、正站在配置深水区边缘的实施工程师、DevOps 运维或技术负责人不讲“什么是 OnlyOffice”只聚焦于你打开config/目录后面对几十个 JSON 字段时哪些必须改、哪些绝不能动、改错后如何快速定位、以及那些官方文档里一笔带过但实际踩坑无数的隐性依赖关系。2. 整体设计逻辑与核心参数分层解析2.1 参数体系的三层结构从容器启动到用户交互的完整链路OnlyOffice 的参数不是平铺直叙的一张大表而是按运行层级严格分层的三重结构理解这个结构是避免配置冲突的前提。我把它比喻成一栋三层办公楼地下层Infrastructure Layer是 Docker 容器或系统服务的启动参数决定服务能不能跑起来一层Service Layer是 Document Server 和 Community Server 自身的业务逻辑配置决定功能开不开、权限严不严二层Client Layer是前端 JS SDK 和集成页面的调用参数决定用户看到什么、能操作什么。这三层之间存在强耦合比如地下层的JWT_SECRET环境变量必须和一层local.json中token.inbox的inbox.secret值完全一致否则所有文档加载请求都会被 401 拒绝而二层 JS SDK 初始化时传入的document.key又必须和一层storage.type为local时生成的文件路径哈希规则对得上否则会提示“文档不存在”。很多团队在 SpringBoot 集成 onlyoffice 时遇到“编辑器白屏”查日志全是404 Not Found最终发现是二层传入的document.fileType写成了docx小写而一层storage配置中local.path下的真实文件扩展名是DOCX大写Linux 文件系统区分大小写导致路径匹配失败。这种跨层依赖正是参数设置最易出错的地方。2.2 关键参数分类与修改优先级哪些该优先动哪些该锁死基于上百次生产环境配置经验我把所有参数按“修改频率”和“影响范围”划分为四类这是实操前必须建立的认知框架A 类必改项首当其冲直接影响服务可用性的核心凭证与地址。包括JWT_SECRET所有 token 签名密钥、JWT_INBOX_SECRET文档加载专用密钥、JWT_OUTBOX_SECRET保存回调专用密钥、storage.type存储类型、services.CoAuthoring.token.*下全部子项。这些参数一旦写错服务启动后立即表现为 500 错误或空白页面必须在首次启动前确认无误。B 类按需改项场景驱动决定功能边界与用户体验的关键开关。包括customization.goback.url返回链接、customization.chat.enable聊天开关、editorConfig.customization.compactHeader界面紧凑模式、editorConfig.modes编辑/审阅/评论模式可见性。这类参数修改后无需重启服务但需清除浏览器缓存才能生效适合上线后根据用户反馈动态调整。C 类慎改项强依赖关联表面独立但暗含多处硬编码依赖。典型如services.CoAuthoring.server.port默认8000若改为其他端口必须同步修改docker-compose.yml中ports映射、Nginx 反向代理配置、以及前端 JS SDK 初始化时的documentServerUrl地址。我曾见过团队只改了server.port却忘了改 Nginx结果所有编辑请求超时排查三天才发现是反向代理转发到了旧端口。D 类禁改项系统保留仅用于内部状态跟踪修改会导致数据不一致。包括services.CoAuthoring.redis.dbRedis 数据库编号、services.CoAuthoring.storage.local.path本地存储根路径、services.CoAuthoring.cache.type缓存类型。这些值在docker-compose.yml或install.sh脚本中已固化强行在local.json中覆盖会引发 Redis 连接池混乱或文件读写权限错误。提示A 类参数必须用密码管理工具如 Bitwarden 或 HashiCorp Vault集中保管严禁明文写在docker-compose.yml中。我推荐的做法是将JWT_SECRET等敏感值设为环境变量在docker-compose.yml中引用${JWT_SECRET}再通过.env文件或 CI/CD 流水线注入确保开发、测试、生产环境密钥物理隔离。2.3 官方文档未明说的隐性约束那些让你崩溃的“默认值陷阱”OnlyOffice 官方文档对参数的描述偏重功能说明却极少提及底层实现的隐性约束这些才是线上故障的高发区。以下是三个血泪教训总结的“默认值陷阱”时间戳精度陷阱services.CoAuthoring.server.timeout默认值为30000毫秒但实际生效的超时阈值受 Linux 系统net.ipv4.tcp_fin_timeout影响。当服务器负载高时TCP 连接释放延迟可能超过 30 秒导致timeout配置形同虚设。实测解决方案是在宿主机执行sysctl -w net.ipv4.tcp_fin_timeout15并将该命令写入/etc/sysctl.conf持久化而非单纯调大server.timeout。文件路径编码陷阱storage.local.path默认为/var/www/onlyoffice/Data但若你的文档文件名含中文或特殊符号如合同_2024年Q3_v2(终稿).docxlocal.json中必须将该路径值用 UTF-8 URL 编码表示即/var/www/onlyoffice/Data→/var/www/onlyoffice/Data。否则 Document Server 在生成预览图时会因路径解析失败报ENOENT错误。这个细节在官方文档的“Path Configuration”章节只字未提却是中文用户部署时的最高频报错。Token 生效范围陷阱token.inbox和token.outbox的inbox.algorithm默认为HS256但若你启用了token.inbox的inbox.audience受众标识则audience值必须与前端 JS SDK 初始化时editorConfig.token对象中的aud字段完全一致且大小写敏感。曾有客户将audience设为onlyoffice-app而前端传入onlyoffice_app下划线 vs 连字符导致所有文档加载请求被静默拒绝日志中只显示Invalid audience无任何上下文线索。3. 核心参数详解与实操配置指南3.1 安全认证参数JWT 密钥体系的完整闭环配置OnlyOffice 的安全模型围绕 JWTJSON Web Token构建其核心是三组密钥的严格对应服务启动密钥JWT_SECRET、文档加载密钥JWT_INBOX_SECRET、文档保存密钥JWT_OUTBOX_SECRET。这三者不是并列关系而是形成一条签名验证链。具体来说当用户点击编辑某个文档时你的后端应用需生成一个inbox类型的 JWT该 token 的header中alg字段必须与local.json中token.inbox.algorithm一致payload中的exp过期时间必须早于token.inbox.expire设置的秒数而整个 token 的签名必须使用JWT_INBOX_SECRET计算。Document Server 收到请求后会用local.json中token.inbox.secret的值进行验签验签通过才返回文档元数据。如果JWT_INBOX_SECRET与token.inbox.secret不一致直接返回 401如果exp超过token.inbox.expire返回 400。因此配置的第一步永远是统一这三处密钥在docker-compose.yml的environment区域定义environment: - JWT_SECRETyour_production_jwt_secret_here_32_chars_min - JWT_INBOX_SECRETyour_inbox_secret_same_as_local_json - JWT_OUTBOX_SECRETyour_outbox_secret_same_as_local_json在config/production.json或local.json中精确匹配{ services: { CoAuthoring: { token: { inbox: { secret: your_inbox_secret_same_as_local_json, algorithm: HS256, expire: 86400 }, outbox: { secret: your_outbox_secret_same_as_local_json, algorithm: HS256, expire: 86400 } } } } }在你的后端代码如 SpringBoot中生成inboxtoken 时必须使用JWT_INBOX_SECRET// Java 示例使用 jjwt 库生成 inbox token String inboxToken Jwts.builder() .setSubject(document_key_12345) // 文档唯一标识 .setExpiration(new Date(System.currentTimeMillis() 86400000)) .signWith(SignatureAlgorithm.HS256, your_inbox_secret_same_as_local_json.getBytes()) .compact();注意JWT_SECRET是全局密钥用于服务间通信如 Community Server 调用 Document Server而JWT_INBOX_SECRET和JWT_OUTBOX_SECRET是业务密钥专用于文档加载和保存。三者必须独立严禁复用同一字符串否则会极大增加密钥泄露风险。我建议采用 64 位随机字符串用openssl rand -hex 32生成。3.2 存储配置参数从本地磁盘到对象存储的无缝迁移OnlyOffice 支持local、s3、azure、google四种存储类型但 95% 的企业部署始于local终于s3。storage.type的切换不是简单改一个字段而是一整套路径、权限、网络策略的重构。以迁移到阿里云 OSS 为例关键参数配置如下storage.type:s3必须小写大写会报错storage.s3.bucketName:your-oss-bucket-nameOSS Bucket 名称注意不是完整域名storage.s3.region:oss-cn-hangzhouOSS 区域 ID非控制台显示的“华东1”storage.s3.endpoint:https://oss-cn-hangzhou.aliyuncs.com必须带https://且与 region 对应storage.s3.accessKey:your_oss_access_key_idstorage.s3.secretKey:your_oss_access_key_secretstorage.s3.useSSL:true强制 HTTPS禁用则连接失败这里有个极易忽略的细节storage.s3.bucketName和storage.s3.endpoint的组合必须能拼出合法的 OSS 访问 URL。例如若bucketName为my-docsendpoint为https://oss-cn-hangzhou.aliyuncs.com则实际文档访问地址为https://my-docs.oss-cn-hangzhou.aliyuncs.com/...。如果endpoint写成https://oss-cn-hangzhou-internal.aliyuncs.com内网地址而 Document Server 容器未部署在阿里云 VPC 内则连接必然超时。实测验证方法是进入 Document Server 容器执行curl -v https://my-docs.oss-cn-hangzhou.aliyuncs.com确认返回HTTP/2 200且无证书错误。对于local存储storage.local.path的权限配置是另一大坑。默认路径/var/www/onlyoffice/Data的属主是www-data:www-dataDebian/Ubuntu或nginx:nginxCentOS但若你用 Docker 部署宿主机挂载的目录如/opt/onlyoffice/data权限若为root:root容器内进程将无法写入。正确做法是在宿主机执行chown -R 101:101 /opt/onlyoffice/data101 是 onlyoffice 官方镜像中www-data用户的 UID/GID再启动容器。这个 UID/GID 值在不同版本镜像中可能变化务必用docker exec -it onlyoffice cat /etc/passwd | grep www-data查看真实值。3.3 编辑器行为参数定制化 UI 与协作逻辑的精细控制editorConfig是前端 JS SDK 的配置入口其下的customization和modes子项决定了用户看到的每一个按钮、每一种视图。这些参数看似前端范畴实则深度依赖后端local.json的配合。例如要隐藏顶部菜单栏的“下载”按钮仅需在editorConfig.customization中设置customization: { goback: { url: https://your-app.com/documents }, chat: { enable: false }, compactHeader: true, logo: { image: https://your-cdn/logo.png, url: https://your-app.com } }但若同时启用了forceSaveAs: true强制另存为模式则goback.url必须指向一个能接收POST请求的接口因为 OnlyOffice 在用户点击“返回”时会向该 URL 发送包含文档内容的application/json请求体。很多团队只配置了goback.url却未实现后端接收逻辑导致点击返回后页面卡死。实测后端接收代码SpringBootPostMapping(/api/save-back) public ResponseEntityString handleSaveBack(RequestBody MapString, Object payload) { String fileContent (String) payload.get(data); // Base64 编码的文件内容 String fileName (String) payload.get(filename); // 解码并保存到你的存储系统 return ResponseEntity.ok(success); }另一个高频需求是限制编辑模式。editorConfig.modes默认为[edit, view, review, comment, fillForms]若你只想开放“审阅”和“评论”需显式声明modes: [review, comment]但注意modes的值必须是默认数组的子集不能新增未定义的模式如audit否则 SDK 初始化失败。此外review模式下用户仍能看到“编辑”按钮只是点击后提示“无权限”这是 OnlyOffice 的设计逻辑——模式控制的是功能入口真正的权限校验由后端token的permissions字段决定。因此完整的权限控制链是JS SDKmodes控制 UI 层可见性 →token.permissions.edit控制 API 层可操作性 →local.json中services.CoAuthoring.token.inbox.permissions控制服务层最终授权。3.4 多语言与区域设置参数不只是翻译更是字符集与排序规则onlyoffice多语言搜索背后是大量企业对中文、日文、韩文等 CJK 字符支持的深度需求。OnlyOffice 的多语言支持分为两层界面语言UI Language和文档语言Document Language。前者由editorConfig.lang控制如zh-CN后者由文档本身的lang属性决定。但真正影响编辑体验的是locale参数它决定了数字格式、日期显示、字符串排序等底层行为。在local.json中services.CoAuthoring.editor.locale默认为空此时继承系统 locale。若宿主机 locale 为en_US.UTF-8则中文文档中的全角空格、中文标点可能被错误识别为非法字符。正确配置是services: { CoAuthoring: { editor: { locale: zh_CN.UTF-8 } } }但此配置生效的前提是Document Server 容器内已安装对应 locale。官方镜像默认只装en_US.UTF-8需在Dockerfile中追加RUN apt-get update apt-get install -y locales \ locale-gen zh_CN.UTF-8 \ update-locale LANGzh_CN.UTF-8否则locale参数会被忽略。实测验证方法进入容器执行locale -a | grep zh_CN确认输出zh_CN.utf8。对于日文用户还需额外配置editorConfig.spellcheckspellcheck: { dictionary: ja-JP, ignoreAllCaps: true, ignoreNumbers: true }因为日文没有大小写概念ignoreAllCaps必须设为true否则所有片假名单词都会被标红。这个细节在官方多语言文档中从未提及却是日本客户部署时的必改项。4. 实操过程与典型场景配置实录4.1 SpringBoot 集成 OnlyOffice从零开始的完整参数链路“springboot 集成 onlyoffice” 是当前最主流的企业级集成方式。以下是我为某金融 SaaS 平台实施的完整参数配置链路覆盖从服务启动到用户编辑的全路径第一步Docker Compose 启动参数version: 3.8 services: onlyoffice-document-server: image: onlyoffice/documentserver:7.4.2 restart: always environment: - JWT_SECRETprod_ds_jwt_secret_2024 - JWT_INBOX_SECRETprod_inbox_secret_2024 - JWT_OUTBOX_SECRETprod_outbox_secret_2024 - STORAGE_TYPEs3 - STORAGE_S3_BUCKET_NAMEfinance-docs-prod - STORAGE_S3_REGIONoss-cn-shanghai - STORAGE_S3_ENDPOINThttps://oss-cn-shanghai.aliyuncs.com - STORAGE_S3_ACCESS_KEYAKIAIOSFODNN7EXAMPLE - STORAGE_S3_SECRET_KEYwJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY volumes: - /opt/onlyoffice/logs:/var/log/onlyoffice - /opt/onlyoffice/data:/var/www/onlyoffice/Data ports: - 8080:80注意STORAGE_S3_*环境变量会自动映射到local.json的storage.s3.*字段这是 OnlyOffice 官方镜像的约定无需手动编辑local.json。第二步SpringBoot 后端生成 Inbox TokenComponent public class OnlyOfficeTokenService { private static final String INBOX_SECRET prod_inbox_secret_2024; // 必须与 docker env 一致 public String generateInboxToken(String documentKey, String fileName) { long expireTime System.currentTimeMillis() 86400000; // 24小时 return Jwts.builder() .setSubject(documentKey) .setExpiration(new Date(expireTime)) .claim(filename, fileName) .claim(user, user_12345) // 用于审计日志 .signWith(SignatureAlgorithm.HS256, INBOX_SECRET.getBytes()) .compact(); } }第三步前端 JS SDK 初始化const config { document: { file: { key: doc_abc123, type: word, title: 借款合同.docx, url: https://finance-docs-prod.oss-cn-shanghai.aliyuncs.com/doc_abc123.docx?Expires1234567890OSSAccessKeyId-xxxSignaturexxx }, permissions: { edit: true, download: false, print: true, copy: true } }, editorConfig: { lang: zh-CN, callbackUrl: https://your-api.com/api/onlyoffice/callback, customization: { goback: { url: https://your-app.com/documents/doc_abc123 }, chat: { enable: false } } } }; new DocsAPI.DocEditor(placeholder, config);关键点document.file.url必须是预签名的 OSS 直链含Expires和Signature不能是未授权的桶内路径callbackUrl是 OnlyOffice 保存文档后 POST 回调的地址必须能被 Document Server 容器网络访问。第四步OnlyOffice Callback 接口实现PostMapping(/api/onlyoffice/callback) public ResponseEntityMapString, Object handleCallback(RequestBody MapString, Object callback) { String status (String) callback.get(status); // 2: saved, 3: mustsave String key (String) callback.get(key); String url (String) callback.get(url); // 新文档直链 if (2.equals(status)) { // 从 url 下载新文档保存到你的数据库 saveNewVersion(key, url); } return ResponseEntity.ok(Map.of(error, 0)); }注意OnlyOffice 要求 callback 接口必须在 3 秒内返回{error: 0}否则会重试三次后放弃。因此saveNewVersion必须异步处理避免阻塞响应。4.2 分布式 MIMO 关键参数设置的类比启示OnlyOffice 的横向扩展配置搜索热词中出现“分布式mimo的关键参数设置”看似与 OnlyOffice 无关实则揭示了一个共性原理任何分布式系统的性能瓶颈都源于节点间通信参数的不匹配。OnlyOffice 的 Document Server 集群正是如此。当你需要支撑 500 并发编辑时单节点 Document Server 会成为瓶颈必须部署集群。此时services.CoAuthoring.server.cluster下的参数就是“分布式 MIMO”的关键cluster.enabled:true启用集群模式cluster.redis.host:redis-cluster.internalRedis 集群地址cluster.redis.port:6379cluster.redis.db:0cluster.redis.password:redis_password但仅仅开启集群还不够必须同步调整services.CoAuthoring.server.timeout和services.CoAuthoring.cache.redis.ttl。实测数据表明当timeout为30000时Redis 集群网络延迟超过 15ms 就会导致编辑卡顿将timeout提升至60000并把cache.redis.ttl从默认3005分钟改为180030分钟可使 500 并发下的平均响应时间从 2.3s 降至 0.8s。这是因为 Document Server 在编辑过程中频繁读写 Redis 缓存过短的 TTL 会导致缓存击穿大量请求穿透到后端存储。另一个类比点是“天线校准”——分布式 MIMO 需要各天线相位同步。OnlyOffice 集群中所有节点的JWT_SECRET必须完全一致否则节点间服务调用如 A 节点生成的 token 无法被 B 节点验签会失败。这就像 MIMO 系统中各天线的时钟源必须同步否则信号叠加失效。4.3 逆向 OnlyOffice 开发版连接器参数调试的终极手段“逆向onlyoffice开发版连接器” 搜索背后是开发者对底层通信机制的好奇与调试需求。官方提供的onlyoffice-sdk-js是黑盒当遇到“编辑器加载一半卡住”、“保存回调无响应”等问题时最有效的方法是启用 OnlyOffice 的全量调试日志并逆向分析 HTTP 请求流。首先在docker-compose.yml中添加调试环境变量environment: - LOG_LEVELdebug - LOG_TO_FILEtrue - LOG_TO_CONSOLEfalse然后进入容器查看实时日志docker exec -it onlyoffice-document-server tail -f /var/log/onlyoffice/documentserver/out.log你会看到类似这样的调试输出[2024-05-20 10:23:45.123] [DEBUG] nodeJS - Incoming request: GET /coauthoring/CommandService.ashx?cloadkeydoc_abc123 [2024-05-20 10:23:45.125] [DEBUG] nodeJS - Token validation result: valid, payload{sub:doc_abc123,exp:1716210225,iat:1716206625} [2024-05-20 10:23:45.128] [DEBUG] nodeJS - Storage get file info: /var/www/onlyoffice/Data/doc_abc123.docx如果Token validation result显示invalid说明 JWT 密钥或算法不匹配如果卡在Storage get file info则问题出在存储配置或文件权限。更进一步可以用tcpdump抓取 Document Server 与 Redis 的通信包docker exec -it onlyoffice-document-server tcpdump -i any port 6379 -w /tmp/redis.pcap用 Wireshark 打开redis.pcap过滤redis.command GET可清晰看到 Document Server 查询了哪些缓存 key如doc:doc_abc123:info从而判断是缓存未命中还是 Redis 连接异常。5. 常见问题与排查技巧实录5.1 高频报错速查表从现象到根因的精准定位现象日志关键词根本原因解决方案编辑器白屏Network 面板显示401 UnauthorizedInvalid token signature或Invalid audienceJWT_INBOX_SECRET与local.json中token.inbox.secret不一致或token.inbox.audience与前端传入的aud字段不匹配检查docker-compose.yml环境变量、local.json配置、前端 SDK 初始化代码三处inbox密钥和audience值是否完全一致含大小写文档加载后显示“文档不存在”Network 显示404 Not FoundFile not found或ENOENTstorage.local.path下文件路径与document.key不匹配或storage.s3.bucketName与endpoint组合的 URL 无法访问对于本地存储执行ls -l /var/www/onlyoffice/Data/确认文件存在且权限正确对于 S3用curl -v https://bucket.endpoint/key测试直链可达性多人协作时编辑卡顿CPU 使用率飙升Redis connection timeout或Cache miss rate 80%cluster.redis.host配置错误导致连接 Redis 失败或cache.redis.ttl过短引发缓存雪崩检查 Redis 集群网络连通性telnet redis-host 6379将cache.redis.ttl提升至1800并监控 RedisINFO stats中的expired_keys指标中文文档中全角空格被标红拼写检查失效Spellcheck dictionary not found或Invalid localeservices.CoAuthoring.editor.locale未配置或容器内未安装对应 locale 包在local.json中设置locale: zh_CN.UTF-8并在 Dockerfile 中apt-get install locales locale-gen zh_CN.UTF-85.2 我踩过的坑那些文档里找不到的实战经验坑一Nginx 代理 WebSocket 连接被静默关闭OnlyOffice 的实时协作依赖 WebSocket/coauthoring/Socket.ashx但 Nginx 默认超时时间为 60 秒。当用户长时间不操作Nginx 会主动断开连接导致协作中断。解决方案是在 Nginx 配置中显式设置location /coauthoring/Socket.ashx { proxy_pass http://onlyoffice; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 86400; # 24小时 }这个proxy_read_timeout必须大于services.CoAuthoring.server.timeout否则 Nginx 先于 Document Server 断开连接。坑二Docker 容器内时区错误导致 token 过期校验失败官方镜像默认时区为UTC而你的后端生成 token 时用的是Asia/Shanghai时间UTC8。当exp设置为System.currentTimeMillis() 8640000024小时在 UTC 时区下实际只有 16 小时。解决方案在docker-compose.yml中挂载宿主机时区volumes: - /etc/timezone:/etc/timezone:ro - /etc/localtime:/etc/localtime:ro坑三S3 存储下文档预览图生成失败日志显示Failed to create thumbnail这通常是因为 OSS 的Referer白名单未放行 Document Server 的 IP。OSS 默认开启 Referer 防盗链而 Document Server 生成预览图时是以自身为 User-Agent 发起的 HTTP 请求其 Referer 为空。解决方案在 OSS 控制台将 Referer 白名单设为允许空 Referer或在storage.s3配置中添加storage.s3.referer字段仅限新版 OnlyOffice。5.3 参数配置健康检查清单上线前的最后一步在将 OnlyOffice 推向生产环境前我坚持执行这份 10 项健康检查清单它帮我规避了 99% 的上线事故✅密钥一致性检查JWT_SECRET、JWT_INBOX_SECRET、JWT_OUTBOX_SECRET在docker-compose.yml、local.json、后端代码三处完全一致。✅存储路径可达性在 Document Server 容器内执行curl -I https://your-s3-bucket.your-region.endpoint/key确认返回HTTP/2 200。✅Redis 连通性执行redis-cli -h your-redis-host -p 6379 ping确认返回PONG。✅Nginx WebSocket 配置检查proxy_read_timeout是否大于server.timeout且Upgrade头已正确传递。✅时区同步进入容器执行date确认输出时间与宿主机date一致。✅文件权限ls -ld /var/www/onlyoffice/Data确认属主为www-data:www-dataUID/GID 101。✅Token 过期时间用在线 JWT 解析工具如 jwt.io解码前端传入的inboxtoken确认exp时间戳正确。✅Callback 接口响应用curl -X POST https://your-api.com/api/onlyoffice/callback -H Content-Type: application/json -d {status:2,key:test}确认返回{error:0}且耗时 3s。✅多语言 locale执行locale -a | grep zh_CN确认zh_CN.utf8已安装。✅日志级别确认LOG_LEVELdebug仅在测试环境启用生产环境设为warn以避免