# 疑難排解

按順序檢查：哨站程序 → 信箱 → 訂閱資料夾 → 通知管道 → 手機。管道測試跳過信箱監聽，新郵件才能驗證完整鏈路。

## 哨站或控制台無法存取

檢查 `docker compose ps` 和 `docker compose logs --tail=100 core`。預設埠綁定本機；其他裝置透過 SSH 隧道或正常工作的 [HTTPS 代理](https.md)存取。啟動報告 `data_directory_permission_denied` 或 `data_directory_read_only` 時，檢查資料卷寫權限。容器使用 `10001:10001` 使用者。

## 初始化碼或管理員密碼問題

完成初始化前，每次重啟哨站都會輪換初始化碼，請讀取當前程序日誌。重置管理員密碼時，停止哨站，使用同一 Compose 專案和資料卷執行：

```sh
docker compose stop core
docker compose run --rm -it core admin reset-password
docker compose start core
```

互動式重置會退出瀏覽器會話，保留 API Token、信箱和待處理任務。恢復命令需要獲取資料目錄鎖定，因此操作前停止正在執行的哨站。

## 新郵件沒有通知

1. 驗證信箱連線和 IMAP 憑據。
2. 檢查郵件所在的實際伺服器資料夾是否已訂閱。新訂閱會跳過已有郵件。
3. 等待所選定時間隔，或檢查實時連線狀態。
4. 檢視投遞歷史。沒有事件時檢查監聽；事件失敗時檢視管道錯誤。
5. 傳送管道測試。使用 Mailwake App 時，同時檢查接收手機選擇和普通推播權益。

重試次數為 0 表示只嘗試一次。需要自動重試時先明確設定次數。管道“已接受”表示服務接收了請求，最終顯示問題還要檢查下游服務和手機。

## App 連線失敗

先用 Safari 開啟哨站的 HTTPS 地址。確認證書與網路正常，建立新的 5 分鐘邀請，並核對哨站指紋。出現 `clock_skew` 時同步哨站宿主機時間。檢查站主是否授予所需權限，以及需要 Pro 的操作是否已有有效權益。

手機被撤銷後，選擇新接收手機並儲存管道。更換推播中繼服務環境後，按[部署說明](deploy.md)執行運維重置並重新配對，各環境身分獨立。

## 尋求幫助

可復現的哨站問題可以提交到 [GitHub Issues](https://github.com/mingzaily/mailwake/issues)，附上版本、錯誤碼、時間和控制台脫敏診斷。公開報告中保留診斷線索，移除密碼、API Token、邀請連結和郵件內容。安全問題按 [SECURITY.md](https://github.com/mingzaily/mailwake/blob/main/SECURITY.md) 私下報告。