故障排查

先按现象定位，再按检查项排除。

登录后无入口

• 确认角色已授权对应菜单。
• 文档中心入口是 /document，在线编辑在文档详情中打开。

文件上传或下载失败

• 查 file.storage.max-size 和上传大小限制。
• 查上传目录 ./uploads 或生产目录权限。
• 查文件记录是否写入且未被删除。

ONLYOFFICE 编辑器不显示

• 浏览器打开 Document Server 的编辑器脚本地址。
• 查 onlyoffice.enabled、document-server-url、public-base-url、jwt-secret。
• 确认文档已有可打开的最新文件。
• 查编辑配置接口返回是否启用及错误信息。

ONLYOFFICE 保存后无新版本

• 查 Document Server 是否能访问 public-base-url。
• 查文档回调是否到达后端。
• 查文档日志是否出现保存失败。
• 查文档版本与最新文件是否已更新。

数据库迁移失败

• 查 flyway_schema_history 的 success 列。
• 已执行脚本保持不可变，用新增脚本修复。
• 历史记录与当前脚本不一致时，先备份再评估，不要在生产库手改校验值。

无法发起流程

• 确认已有可发起的流程模板（联系管理员创建并发布）
• 确认用户角色已授予发起相关菜单
• 确认流程模板状态为已发布

待办任务列表为空

• 确认是否有流程任务分配给你
• 确认角色权限包含待办入口
• 检查是否所有待办已处理完成

登录后白屏或页面加载异常

• 检查浏览器控制台是否有网络请求错误
• 确认前端 API 地址指向正确的后端入口（直接连后端用根路径；经前端容器反代时常见为 /oars）
• 尝试清除浏览器缓存后重新登录

消息收不到

• 确认消息中心菜单是否可见
• 查看消息模板与站内信通道是否启用（管理员：系统配置）
• 确认流程节点是否配置了消息规则

Redis 连不上或会话异常

• 确认 Redis 地址、密码与当前环境配置一致
• 查后端日志中的 Redis 连接错误（见 日志）
• 容器部署时确认 Redis 容器健康且与后端在同一网络

接口返回 429（请求过于频繁）

• 是否脚本或客户端在短时间密集重试
• 反向代理是否未转发真实客户端 IP，导致多人共用一个出口 IP 被限流
• 生产环境 Redis 不可用时，接口也可能返回 429；先确认 Redis 健康（见上一节）
• 调整阈值属部署配置，由实施/运维处理；管理员说明见 系统配置

登录后反复掉线或 Token 无效

• 多节点部署时确认 JWT 密钥与时钟一致
• 用户是否在其他端点执行过登出
• 查认证相关日志关键字（见 日志）

移动端打不开或空白

• 确认访问地址带移动端路径（如 /m），见 移动端
• 查浏览器控制台网络错误与 API 地址是否与现场一致
• 确认账号具备移动端所需业务权限

具体客户环境的网关、HTTPS、容器网络、备份恢复和集中日志平台，需要现场补充排查。