09 常见问题与故障排查

定位： 汇总用户日常使用中可能遇到的问题及解决方法，方便自助排查。

登录问题

忘记密码

• 原因： 用户遗忘登录密码，或长时间未登录导致记忆模糊。
• 解决：
  1. 在登录页面点击 「忘记密码」
  2. 输入注册时绑定的 手机号 或 邮箱
  3. 获取验证码，验证身份
  4. 设置新密码（至少 12 位，需包含字母和数字）
  5. 如无法自助找回，联系管理员在「系统管理 → 用户管理」中重置密码

账号锁定

• 原因： 平台配置了登录安全策略，连续 5 次登录失败后账户自动锁定 15 分钟（基于 django-axes）。
• 解决：
  1. 等待 15 分钟后自动解锁，重新尝试登录
  2. 如需立即解锁，联系管理员操作：python3 manage.py axes_reset <用户名>
  3. 建议启用双因素认证（2FA）避免误锁

Token 过期

• 原因： JWT Token 有效期已到（Access Token 默认 30 分钟，Refresh Token 默认 24 小时），或服务端清除了 Token 缓存。
• 解决：
  1. 系统会自动尝试使用 Refresh Token 获取新的 Access Token
  2. 如自动续期失败，页面会跳转到登录页，重新登录即可
  3. 登录后系统自动签发新 Token
  4. 若频繁过期，联系检查服务器时间是否与 NTP 同步

TOTP 验证失败

• 原因： 手机验证器 App 生成的动态码与服务端不匹配，常见于设备时间不同步。
• 解决：
  1. 确保手机验证器 App（Google Authenticator / Authy / Microsoft Authenticator）中的账户信息正确
  2. 同步手机时间 — 打开「设置 → 日期与时间 → 自动设置」
  3. 验证码 30 秒刷新一次，等待新验证码生成后重试
  4. 如持续失败，使用备用 恢复码 登录
  5. 恢复码丢失请联系管理员，审核身份后重置 2FA 绑定

使用问题

表单保存失败

• 原因：
  • 必填字段未填写
  • 网络请求超时（超过 30 秒）
  • 提交内容包含非法字符或超长字段
  • 服务器校验不通过（如格式错误）
• 解决：
  1. Chrome 浏览器按 F12 → Console 查看具体错误信息
  2. 检查标红色边框的必填项是否都已填写
  3. 检查网络连接，尝试刷新页面重试
  4. 如字段提示「格式不正确」，按照示例格式重新输入
  5. 截图错误信息，联系技术支持

页面空白 / 白屏

• 原因：
  • 前端资源加载失败（JS/CSS 文件未正确加载）
  • 浏览器版本过旧，不支持 ES6+ 语法
  • 路由跳转异常
  • 浏览器缓存了旧的 JS 文件（版本更新后常见）
• 解决：
  1. 强制刷新 — 按 Ctrl + F5（Mac: Cmd + Shift + R）
  2. 清除缓存 — Chrome: 设置 → 隐私和安全 → 清除浏览数据 → 缓存的图片和文件
  3. 确保使用 Chrome / Edge / Safari 最新版本
  4. 尝试使用 无痕模式 打开页面
  5. 如仍然白屏，在 Console 面板截图，联系技术支持

数据不刷新

• 原因：
  • 浏览器缓存了旧数据
  • 后端分页查询返回了已缓存的结果
  • WebSocket 连接中断，未收到实时推送
• 解决：
  1. 点击页面 刷新按钮（⭕）或使用页内「刷新」链接
  2. 退出重新登录
  3. 检查页面右下角 WebSocket 连接状态是否正常（绿色=在线，红色=断开）
  4. 清空浏览器缓存后重试

通知不推送

• 原因：
  • WebSocket 连接断开
  • 浏览器 Tab 页处于后台，浏览器限制了 WebSocket 活动
  • 通知过滤器设置导致某些类型通知被屏蔽
  • 用户未在列表中或被分配了错误的角色
• 解决：
  1. 确认系统右下角 WebSocket 图标为 绿色
  2. 如果是红色，刷新页面重新建立连接
  3. 检查「通知中心」的通知过滤器是否勾选了正确的通知类型
  4. 检查用户是否在通知的接收人列表中
  5. 检查浏览器是否允许该站点发送通知

移动端问题

扫码不成功

• 原因：
  • 摄像头权限未授权
  • 二维码模糊、破损或反光
  • 光线不足
  • 二维码与摄像头距离不当
  • iOS 15+ 限制 canvas 访问摄像头
• 解决：
  1. 授权摄像头 — iOS: 设置 → Safari → 摄像头 → 允许 / Android: 浏览器设置中授予摄像头权限
  2. 确保二维码清晰完整，不要反光
  3. 保持 15-30cm 距离，稳住手机
  4. 在光线充足的环境下扫描
  5. 如仍然不行，使用扫码页的 「手动输入设备编码」 功能
  6. 尝试更换浏览器（推荐 Chrome / Safari）

iOS 摄像头不工作

• 原因：
  • iOS 限制了非 HTTPS 页面的摄像头访问
  • Safari 的「相机」权限设置为「询问」但被拒绝了
  • iOS 17+ 新增隐私限制导致摄像头无法被 H5 页面调用
• 解决：
  1. 必须使用 HTTPS 访问系统（iOS 要求安全上下文）
  2. 开发环境可通过 localhost 测试（iOS 对 localhost 豁免 HTTPS 要求）
  3. Safari 设置 → 隐私与安全性 → 相机 → 允许对应网站
  4. 如果持续失败，尝试使用 Chrome for iOS
  5. 最终备选：使用扫码页的 手动输入 功能

定位不准

• 原因：
  • 手机 GPS 未开启
  • 在室内或信号遮挡严重的位置
  • iOS 定位权限设置为「使用期间」但在后台运行
  • 浏览器未允许地理位置权限
• 解决：
  1. 打开手机 GPS / 定位服务
  2. 到室外或开阔区域操作
  3. iOS: 设置 → 隐私 → 定位服务 → Safari → 设为「使用 App 期间」
  4. 浏览器中允许网站访问位置信息（地址栏左侧锁图标 → 位置 → 允许）
  5. 刷新页面后重试

报错对照表

常见 HTTP 错误

后端错误码

以下为后端业务层返回的自定义错误码：

技术支持联系方式

如以上方法无法解决您的问题，可通过以下渠道获取帮助：

联系前请准备： 操作时间、错误截图/录屏、浏览器版本、操作账号，可大幅缩短排查时间。