常見問題與排錯

先保留可用的錯誤信息

記錄發生時間、所在頁面、操作、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，並不自動恢複資料備份。完整步驟見本地開發和部署與恢復。