排查指南

部署相关

现象	可能原因	解决方案
首次部署后访问报 500	Worker 还没绑定资源，属正常现象	完成 R2 / D1 绑定后重新 `npm run deploy`
报错 `r2 is not defined`	注释掉了 `wrangler.jsonc` 的 R2 绑定，但后台设置仍是 `r2` 模式	恢复 R2 绑定，或在后台切换到 S3 / WebDAV 模式
数据库表不存在 / 报错 no such table	尚未触发首次访问建表	正常访问任意页面一次即可，建表自动完成

现象	可能原因	解决方案
登录返回 429	同 IP 登录失败超过 10 次/分钟触发限流	等待一分钟后再试
收到 2FA 验证码却登录失败	服务器时间偏差超出 ±90 秒窗口	检查验证器 App 的时间同步
忘记面板密码	——	D1 控制台执行 `DELETE FROM settings WHERE key = 'admin_password_hash';` 回退用 `admin` 登录
2FA 完全丢失	——	使用 Cloudflare Secret `totp_recovery` 万能恢复码；否则使用系统生成的 8 个消耗型恢复码之一
想访问 `/admin` 却被拒绝	设置了管理员 IP 白名单	在白名单 IP 网络下访问，或让白名单内的管理员调整列表

现象	可能原因	解决方案
上传报 500 `Storage write failed`	S3 Endpoint / Region / Bucket 配置错误，或网络不通	后台 → 设置 → 测试连接，按返回的原始错误排查
下载报 404 文件不存在	存储中无该对象（迁移遗漏或被清理）	调用 `/api/admin/shares/cleanup` 清理孤儿记录
下载报 502 `Storage Error`	外部 S3 临时不可达 / 网络抖动	稍后重试或切回 R2
S3 测试连接超时	Worker 无法访问 S3 Endpoint（如内网 MinIO）	用 Cloudflare Tunnel 暴露到公网
上传大文件失败	关闭了分片上传，或单文件超过 100 MB	设置中开启「大文件分片上传」

现象	可能原因	解决方案
Turnstile 不弹出	未配置 `turnstile_secret`，或模式为 `off`	检查 Secret 与后台模式设置，见 Turnstile
全球分布 Tab 空数据	Analytics Engine 数据写入有分钟级延迟	多下载几次后稍等再刷新
Analytics Engine SQL 查不到数据	dataset 名称拼错或未配置绑定	核对 `wrangler.jsonc` 中的 `r2pan_downloads`
下载报 403	IP 已被自动封禁，或 Turnstile 校验未通过	后台 → 封禁 Tab 检查并解封；确认验证码已完成

实时查看线上日志：

bash

npm run tail

管理后台内的日志入口：