常见问题与排错

先保留可用的错误信息

记录发生时间、所在页面、操作、HTTP 状态与脱敏错误；区分没有数据、没有权限、后台处理和服务失败。不要把验证码、Cookie、access token、grant、完整分享链接或用户资料粘贴给文档 AI。

登录与收信

| 现象 | 检查与下一步 | | --- | --- | | 邮件没有收到 | 核对邮箱和垃圾邮件；等待 60 秒冷却；202 不等于实际收信 | | 六位码仍无法登录 | 确认最新 challenge、同一邮箱、前导零、10 分钟期限和未消费状态 | | 429 | 等待限流窗口或申请新的有效挑战；不要持续试码 | | 本地 8025 看不到邮件 | fake-email 没有公开收件箱网页；测试读取需私有 token，默认 overlay 未提供 | | 刷新后登录丢失 | 核对正确 HTTPS 同源入口、cookie 与会话有效性；重新走登录流程 | | 旧密码/邀请码入口无效 | 当前主线为邮箱验证码；不要套用归档注册说明 |

上传与文件列表

| 现象 | 检查与下一步 | | --- | --- | | 100% 后一直处理中 | 分片已发送但后台尚未确认；等待、刷新，核对版本、大小和下载内容 | | 新上传同名返回冲突 | 不等于自动覆盖；需要替换版本时使用对应 fileId 的替换意图 API | | 选择空文件无法上传 | 使用非空文件；API 大小应为正整数字符串 | | 上传 401 | 核对 uploadGrant 最长 300 秒的时效；15 分钟意图不代表 grant 也有效 15 分钟 | | 取消失败或空间仍被占用 | 重读 quota，检查意图状态和到期预留释放；勿重复创建大量意图 | | 文件存在却不能下载 | currentVersion 可能仍为 null；不要仅凭文件名判断已完成 | | 找不到删除、移动或恢复按钮 | 当前个人中心没有这些完整操作；不是账户权限切换能解决 |

后台处理卡住时，由运营者检查 storage-worker、Core 回调、Redis、对象存储和数据库。不要从浏览器调用 internal 完成接口或直接改配额记录来补救。

下载、分享与发布

下载票据是 60 秒单次授权，旧链接或同一 grant 重用会失败；重新点击获取新票据。大文件下载使用 Blob，留意浏览器内存和网络中断。

分享 404 可能是口令、过期、次数、撤销或文件可用性问题，联系发送者核对。分享次数在签发票据时消耗，下载中断不保证退还。看板完整成功下载口径与此不同。

文件上传后不在 /download 是正常的，必须保存 published 状态才进入公开目录。草稿或 disabled 不公开；目录页面只读第一批，无翻页控件，必要时用分页 API 检查。管理员发布页只列自己的文件。

管理页面与指标

401/403 先解决登录或角色，503 检查依赖。用户列表空状态与加载错误不同。System Health 的 partial/unavailable 和 null 不要解读成健康零值；业务数据还需看 freshness、coverage 和所选 Asia/Shanghai 日期范围。

通知流重连后重新查询列表，不能仅依靠 SSE 补全断线期间消息。已读是管理记录状态，不是故障解决证明。

本地与部署

Docker 无法连接时先启动自己的 Docker 服务；Compose 太旧时不能正确应用 !override。查看 ./manage-services.sh status、logs core-api、logs storage-worker；不要用 reset --confirm 代替排查，它会删除本地数据卷。

生产发布退出 75 表示有并发发布锁。先检查当前发布，而不是删除锁。回滚需要已有 manifest，并不自动恢复数据备份。完整步骤见本地开发和部署与恢复。