故障排查

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

登录后无入口

• 查 sys_menu 是否有对应菜单。
• 查角色菜单授权和权限码。
• 文档中心入口是 /document，旧 /sys/document 只是重定向。

文件上传或下载失败

• 查 file.storage.max-size 和 Spring multipart 限制。
• 查上传目录 ./uploads 或生产目录权限。
• 查 sys_file 是否写入，deleted 是否为 0。

ONLYOFFICE 编辑器不显示

• 浏览器打开 document-server-url/web-apps/apps/api/documents/api.js。
• 查 onlyoffice.enabled、document-server-url、public-base-url、jwt-secret。
• 查文档是否有 latestFileId。
• 查接口 GET /app/document/{id}/editor-config 返回的 enabled 和错误信息。

ONLYOFFICE 保存后无新版本

• 查 Document Server 是否能访问 public-base-url。
• 查 POST /app/document/callback/{id} 是否进后端。
• 查 doc_document_log 是否出现 save_error 或 forcesave_error。
• 查 doc_document_version 和 doc_document.latestFileId 是否更新。

数据库迁移失败

• 查 flyway_schema_history 的 success。
• 旧 V1.x 记录残留时，按 oars-java/oars-migration/README.md 处理。
• 已执行脚本保持不可变，新增时间戳脚本修复。

无法发起流程

• 确认是否有可发起的流程模板（联系管理员创建并发布）
• 确认用户角色是否授予了流程发起权限（flow:start）
• 确认流程模板状态为已发布

待办任务列表为空

• 确认是否有流程任务分配给你（联系发起人确认）
• 确认角色权限是否包含待办任务入口（flow:todo）
• 检查是否所有待办已处理完成

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

• 检查浏览器控制台是否有网络请求错误
• 确认前端 API 地址是否指向正确的后端地址（包含 /oars 路径）
• 尝试清除浏览器缓存后重新登录

消息收不到

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

Redis 连不上或会话异常

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

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

• 是否脚本或客户端在短时间密集重试
• 反向代理是否未转发真实客户端 IP，导致多人共用一个出口 IP 被限流
• 调整阈值属部署配置，由实施/运维处理；管理员说明见 系统配置

登录后反复掉线或 Token 无效

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

移动端打不开或空白

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

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