登录时提示账号或密码错误，但确认无误？

优先检查：1) Caps Lock 是否开启；2) 是否被管理员冻结；3) SSO 场景下 IdP 侧密码是否变更；4) 重试 3 次触发风控锁定，需等待 15 分钟或管理员解锁。若私有部署，可查看 auth-service 日志的 errorCode。

用户在应用中看不到本应能访问的数据？

按顺序排查：1) 应用 → 成员权限；2) 工作表 → 角色与数据范围；3) 视图 → 过滤条件；4) 字段 → 字段级可见性；5) 外部协作者 → 客户门户权限设置。管理员可在『权限预览』中以该用户身份模拟。

工作流配置后没有触发？

1) 确认触发条件匹配（新增/修改/定时/手动）；2) 检查工作流是否启用状态；3) 触发条件中的字段路径是否正确；4) 运维查看工作流日志（成功/失败/跳过）；5) 大量记录变更建议加节流。

移动端收不到消息推送？

1) App 通知权限是否开启；2) 是否被系统限制后台进程；3) IM 侧（钉钉/企微/飞书）消息订阅是否配置；4) 私有部署的 push-service 是否可达公网推送网关；5) iOS 建议使用真机而非模拟器。

API 调用频繁返回 401 / 403？

401：AppKey/Secret 错误或过期；403：IP 白名单或应用未开放该 API；429：触发限流，默认 100 次/分钟；5xx：检查服务端日志。建议实现指数退避重试与令牌自动刷新。

页面加载很慢或超时？

1) 单工作表记录数 > 100 万需启用聚合表/归档；2) 视图未加索引字段作为筛选；3) 列表视图默认拉取大字段；4) 仪表盘单次数据点 > 10 万；5) 私有部署检查 MySQL 慢查询、Redis 命中率、Nginx 连接池。

私有部署后服务启动失败？

按『健康检查 → 依赖服务 → 应用日志』顺序排查：1) MySQL/Redis/MongoDB/ES 是否全部可连；2) 配置文件域名/端口/密码一致；3) 许可证是否过期；4) docker 镜像拉取是否完整；5) 查看各 service 的 logs/error.log 获取具体堆栈。

明道云故障排查与常见问题 FAQ - 登录 / 权限 / 工作流 / 性能

① 登录与 SSO

账号密码正确却提示错误

检查 Caps Lock、是否冻结、SSO 侧密码是否变更、是否触发 3 次错误锁定（等待 15 分钟或联系管理员解锁）。

SSO 登录跳转失败或循环重定向

验证 IdP 返回的 NameID 是否与明道云账号映射一致；检查回调地址、证书指纹、时钟偏差（< 5 分钟）。

钉钉 / 企微 / 飞书扫码无反应

确认集成配置的 CorpID 与当前域名绑定；IM 管理后台的应用可见范围是否包含当前用户；清除浏览器缓存重试。

② 权限与数据可见

用户在应用中看不到本该可见的记录

按『应用成员 → 工作表角色与数据范围 → 视图过滤 → 字段可见性 → 外部协作』顺序排查；管理员可在『权限预览』中以该用户身份模拟。

字段编辑按钮变灰无法修改

字段级权限被设置为『只读』，或记录处于流程节点中，或字段被公式/子表约束；检查角色权限矩阵与字段只读规则。

数据导出时提示"无权限"

管理员可能启用了"导出需审批"策略，或限制了单次导出记录上限（默认 5000），建议分批导出或申请临时权限。

③ 工作流

工作流配置完成后未被触发

排查：1) 工作流是否启用；2) 触发条件字段路径是否正确；3) 触发对象数据是否满足过滤；4) 查看工作流日志『成功/失败/跳过』；5) 大量变更建议加节流/批量合并。

工作流报错并卡在某节点

打开节点日志查看堆栈：API 节点看接口返回，代码块看 console，审批节点看办理人是否已离职。配置重试 3 次与异常分支。

审批到期未收到提醒

检查定时检查频率（默认 1 小时）、消息模板是否空、IM 订阅是否开启、用户邮箱是否填写；系统管理员可查询『消息队列』定位。

④ 移动端

App 收不到推送通知

检查系统通知权限、后台保活白名单、IM 消息订阅；私有部署需确认 push-service 能访问 APNs / FCM / 厂商通道。

拍照上传失败或压缩后模糊

检查 App 存储权限、网络带宽、附件大小上限（默认 10MB）；可在管理员后台调整压缩质量与上限。

离线缓存记录同步后数据冲突

明道云以"最后修改时间胜出"策略处理；关键字段建议加唯一约束或在工作流中做冲突检测。

⑤ API 与错误码对照

错误码	含义	常见原因	处理建议
401	身份验证失败	AppKey/Secret 错误、Token 过期	刷新 Token；核对凭证是否泄露
403	权限不足	IP 白名单未配置 / 应用未授权该 API	后台开放权限；加入白名单
404	资源不存在	workSheetId / rowId 错误	核对 ID；确认数据未被删除
429	限流	QPS 超限（默认 100/分钟）	指数退避重试；合并批量接口
500	服务端异常	数据库 / 中间件异常	联系管理员；检查服务端日志
timeout	请求超时	大数据量 / 复杂查询	加分页；走异步导出接口

⑥ 性能

单工作表查询很慢

建索引（高频筛选字段）、拆冷热数据、归档历史、禁用视图默认拉取大字段；超过百万行记录建议用聚合表/数据工厂做预处理。

仪表盘加载缓慢或卡顿

单图表数据点 < 10k；合并同源指标；使用预聚合视图；避免前端全量计算；开启后端缓存（默认 5 分钟）。

批量导入很慢或中途失败

按 1000-5000 行分批；关闭触发工作流；校验文件编码（UTF-8 BOM 会导致首字段异常）；失败走『断点续传』功能。

⑦ 私有部署运维

某个服务启动失败

健康检查：MySQL / Redis / MongoDB / ES 全部可连；配置文件域名端口一致；许可证未过期；容器镜像完整；查看 logs/error.log 堆栈。

升级后部分功能异常

确认各服务版本一致；清理前端静态缓存；执行数据库迁移脚本；对照版本日志检查 breaking change；必要时回滚到上个稳定版本。

备份恢复后数据丢失或重复

优先整站快照恢复；应用级恢复需关闭写入后再执行；恢复完成后跑一致性校验脚本（工作表记录数 / 文件附件 / 流程实例数）。

明道云故障排查与常见问题 FAQ