常见问题与排错

按登录、上传、下载、公开目录、权限、指标和开发环境分类，帮你快速定位问题。

先保留可用的错误信息

记下发生时间、所在页面、你做了什么操作、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，并不会自动恢复数据备份。完整步骤见本地开发和部署与恢复。