常见问题
登录与会话
1. 为什么登录后提示用户名或密码错误？
- 检查
ADMIN_USER与ADMIN_PASS是否部署到当前环境。 - 注意 Preview 与 Production 可能使用不同变量集。
2. 为什么会出现 401 未授权？
- 登录会话已过期。
AUTH_SECRET变更会让旧会话失效。- 请求可能没有带 Cookie。
3. 为什么登录接口返回 500？
- 常见原因是
AUTH_SECRET缺失。 - 检查环境变量拼写和部署环境。
桶配置与 KV
4. 为什么登录后看不到桶配置？
- 优先检查 KV 连接与环境变量是否完整。
- 检查
BUCKET_STORE_PROVIDER是否与实际后端匹配。
5. 为什么保存桶失败？
- KV Token 权限不足。
- endpoint 不是完整
https://地址。 - 桶参数（bucket/access key/secret key）错误。
6. 为什么测试连接失败但参数看起来对？
- 检查 region 是否与桶兼容（部分服务可用
auto）。 - 检查 endpoint 是否指向正确节点。
- 检查网络是否可访问对象存储域名。
7. 为什么重部署后桶配置丢失或不可读？
- 可能切换了 Vercel 环境（Preview/Production）。
- 可能变更了
BUCKET_ENCRYPTION_KEY，导致旧密文无法解密。
8. 默认桶为什么不能删除？
- 默认桶来自环境变量兜底，通常为只读配置。
- 可以切换激活桶，但不建议删除该兜底入口。
上传与媒体
9. 上传成功但列表看不到文件
- 当前激活桶不是目标桶。
- 上传路径与当前浏览目录不一致。
- 列表分页/过滤导致暂未显示，刷新或回到上级再进。
10. 视频为什么上传后不能播放？
- 检查文件后缀是否在支持范围内。
- 检查
Content-Type是否正确。 - m3u8 播放依赖分片资源可访问。
11. ZIP 上传后部分文件缺失
- ZIP 内非媒体文件会被忽略。
- 路径过深或文件名异常可能触发过滤。
12. 大文件上传经常失败怎么办？
- 当前版本建议对单文件 >= 64MB 启用分片上传。
- 默认参数建议：分片 32MB、分片并发 3、大文件场景文件并发 1。
- 若分片失败，优先使用“继续失败分片”而不是整文件重传。
- 若决定放弃，请执行 abort 清理未完成分片，避免残留计费。
- 检查对象存储 CORS 是否暴露
ETag，否则 complete 会失败。 - 检查上游代理是否存在请求体积限制（常见 100MB）。
浏览与代理
13. 图片加载慢怎么办？
- 开启代理缩略图模式。
- 使用离用户更近的存储区域或 CDN。
- 控制单目录对象数量，减少首屏遍历成本。
14. 代理接口返回 403
- 目标域名不在白名单。
- 检查
PROXY_ALLOWED_HOSTS与当前桶 endpoint 主机名。
15. 代理接口返回 504
- 上游对象存储响应超时。
- 检查网络连通性和对象体积。
批量操作
16. 批量移动很慢
- 减小单批路径数。
- 按目录分批执行。
- 尽量避免跨区域桶操作。
17. 批量复制后目录结构不对
- 确认源路径是否以
/结尾表示文件夹。 - 文件与文件夹混合复制时，先用小样本验证。
18. 批量删除后还有残留
- 可能是对象存储分页尚未完全处理完前端已刷新。
- 稍后刷新再次确认；必要时重复一次删除。
部署与运行
19. 项目只能部署到 Vercel 吗？
不是。只要运行环境支持 Next.js 服务端并可访问外部 KV，也可自建部署。
20. 为什么本地能跑，线上报配置错误？
- 常见是线上环境变量缺失或拼写错误。
- 检查 Production 环境变量是否已重新触发部署。
21. 升级版本后行为变了怎么办？
- 先看 版本迁移指南。
- 核对是否有配置项新增或默认行为变化。
22. 如何快速判断问题在应用还是存储侧？
建议按顺序排查：
- 应用日志是否报参数或鉴权错误。
- 直接测试桶连通是否正常。
- 用最小样本（单图上传/单文件删除）验证基础链路。
23. 为什么 HTTP 下登录后马上又回到登录页？
- 常见原因是会话 Cookie 在 HTTP 场景下未被正确保存。
- 推荐方案是启用 HTTPS 并保持
AUTH_ALLOW_HTTP_LOGIN=false。 - 如需临时排障，可将
AUTH_ALLOW_HTTP_LOGIN=true后重新部署。 - 排障结束后建议改回
false，避免降低会话安全性。