常見問題與排錯

依登入、上傳、下載、公開目錄、管理頁面和開發環境分類的排查指引。

先保留可用的錯誤信息

記下發生時間、所在頁面、做了什麼操作、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 中已有的標籤，回滾本身不會自動恢復資料備份。完整步驟請參考本地開發和部署與恢復。