故障排查指南 (隧道啟動失敗)

本文件配合 使用者指南「隧道狀態與失敗原因」章節使用。當隧道卡片顯示紅色「失敗」狀態時, 先點卡片上的「複製錯誤資訊」取得失敗摘要, 再依下述路徑排查。

常見失敗類別

啟動失敗會被對應為以下幾類 (卡片上直接顯示可讀文案, 非原始日誌):

§1 認證失敗

表現: 失敗摘要含「認證失敗 / token 無效 / 未授權」等字樣, 或伺服器端傳回 401。

排查路徑:

1. 重新登入一次 (登出帳號後重新登入, 重新整理本機 token), 再啟動隧道。
2. 確認帳號仍有該隧道的使用權限 (節點是否停用、帳號是否欠費/被封鎖)。
3. 若頻繁出現, 檢查系統時間是否正確 (偏差過大會導致 token 簽章校驗失敗)。
4. 仍失敗: 複製錯誤資訊並附上帳號節點資訊提交回報。

§2 連接埠占用

表現: 失敗摘要含「連接埠被占用 / address already in use」等字樣。

排查路徑:

1. 確認遠端連接埠沒有被其他隧道占用 (同一節點的同一遠端連接埠只能分配給一條隧道)。
2. 確認本機連接埠沒有被本機其他程式占用 (如 80 連接埠被 IIS/nginx 等占用)。
   • Windows: netstat -ano | findstr :連接埠號 查看占用處理程序。
   • Linux/macOS: lsof -i :連接埠號 或 ss -ltnp | grep 連接埠號。
3. 確認占用後: 停掉占用程式, 或在建立/編輯隧道時更換連接埠。

§3 節點無法連線

表現: 失敗摘要含「無法連線 / 連線被拒絕 / 節點無法連線」, 或啟動後 30 秒無上線確認 (逾時)。

排查路徑:

1. 使用隧道管理頁的「重新整理測速」確認該節點是否可連線 (延遲/逾時/失敗)。
   • 逾時: 節點過載或網路波動, 稍後重試, 或換一個節點。
   • 失敗 (連線被拒): 節點可能已下線或未開放該連接埠。
2. 檢查本機網路: 能否正常存取其他網站/服務; 代理/VPN 是否干擾了到節點的連線。
3. 檢查本機防火牆/安全軟體是否攔截了 mefrpc 的連出連線。

§4 處理程序崩潰

表現: 失敗摘要含「處理程序異常結束 (結束代碼 N)」等字樣。

排查路徑:

1. 確認 mefrpc 版本是否與目前節點伺服器端相容 (更新頁可查看最新版本; 必要時重新下載客戶端)。
2. 查看崩潰前終端機輸出: 在終端機頁手動執行同樣的啟動指令, 觀察報錯點。
3. 設定檔損毀時也會導致崩潰: 刪除 Config/frp 下對應的臨時設定後重試。
4. 仍崩潰: 複製錯誤資訊 (含結束代碼), 提交回報。

§5 未知錯誤

表現: 失敗摘要為原始 API 錯誤資訊。

排查路徑:

1. 摘要通常已包含伺服器端傳回的原始資訊, 可依此關鍵字搜尋或直接回報。
2. 將「複製錯誤資訊」的內容 (應用程式版本 + mefrpc 版本 + 摘要) 完整貼到回報中。

通用建議

• 回報問題前, 一律使用卡片上的「複製錯誤資訊」, 內容包含應用程式版本與 mefrpc 版本, 能大幅加快定位。
• 修改網路環境 (代理、DNS、防火牆) 後, 重新「重新整理測速」驗證節點連線能力, 再嘗試啟動。

憑證申請失敗 (26.4)

「憑證助手」基於 lego 的 DNS-01 流程, 有兩種驗證方式 (見使用者指南「憑證助手 → 驗證方式」): DNS 帳戶 (一鍵自動) 由應用程式呼叫 DNS 服務商 API 自動讀寫 TXT 記錄; 手動 DNS 由您自行新增 TXT 記錄。

lego 下載失敗 (無法準備憑證元件)

• 表現: 點「開始申請」後長時間停留在「正在準備 lego…」, 或直接提示「無法準備憑證元件 lego (下載或校驗失敗)」。
• 原因: 網路無法存取 GitHub (主來源) 與備用鏡像, 或下載內容校驗不通過。
• 處理: 確認網路與代理後重試; 應用程式會依序嘗試主來源與備用來源, 校驗失敗通常代表下載不完整, 重試即可。若始終無法使用, 可改用「手動 DNS」模式 (仍需 lego, 僅驗證方式不同)。

手動 DNS: 一直停留在「請新增 TXT 記錄後繼續」

• 這是正常的等待狀態 (僅手動模式有這一步): 應用程式在等您到 DNS 服務商新增 TXT 記錄, 不會自動逾時。
• 處理: 複製視窗中的「記錄主機」與「記錄值」到 DNS 控制台 (類型選 TXT), 儲存後點視窗上的「我已新增」。
• 若誤關閉視窗, 本次申請會被取消 (lego 處理程序被終止), 重新申請即可。

DNS 帳戶 (一鍵自動) 模式失敗

自動模式下應用程式已取得服務商傳回的明確錯誤, 介面文案通常直接給出原因:

申請過程中視窗會即時顯示「執行日誌」(已去識別化的 lego 輸出), 失敗時可直接展開定位原因。

手動 DNS 模式常見失敗

憑證填了卻啟動失敗

• Staging 憑證不可用於正式環境: Staging 憑證不被瀏覽器信任, 僅用於流程驗證; 正式使用需改用 Production 重新申請。
• 憑證與私密金鑰不符: 請使用同一次申請產出的 fullchain.pem 與 privkey.pem; 用「從憑證助手選擇」會成對填入, 避免手動配錯。
• 憑證即將到期提醒: 選擇 Staging 憑證時會提示「Staging (測試)」; 其他憑證距到期不足 30 天會提示「即將到期 (N d)」。

更新內容視窗 (26.4)

視窗顯示「暫時無法取得更新說明」

• 表現: 升級後首次啟動彈出「本次更新內容」, 但內容區顯示「暫時無法取得更新說明, 可稍後在更新頁查看。」。
• 原因: 更新介面無法連線 (網路/代理) 或伺服器端暫無目前版本條目。
• 處理: 檢查網路後到「更新」頁查看完整版本變更; 該視窗失敗不會影響啟動, 也不會因此重試彈窗。
• 「部落格更新」頁籤拉取失敗: 同上, 會提示取得失敗; 可切換回「更新日誌 (API)」頁籤或到更新頁查看。

不希望再次彈出

• 視窗只要展示過即記為已讀 (記錄在 Cache/whats-new.json), 同一版本不會二次打擾; 版本號未變化時也不會彈出。

更新失敗

取得更新資訊失敗

表現: 「更新」頁狀態區顯示「取得更新失敗」, 無最新版本資訊。

排查路徑:

1. 檢查網路連線 (能否存取其他網站); 代理/VPN 是否攔截了到更新 API 的請求。
2. 點擊「檢查更新」重試; 若更新通道為「預覽」, 可切回「穩定」通道再試 (預覽通道偶發無發佈)。

下載失敗 / 校驗失敗

表現: 狀態區顯示「更新下載失敗…」或「下載檔案校驗失敗…」, 出現「重試下載」按鈕。

排查路徑:

1. 點擊「重試下載」重試一次 (網路波動常見)。
2. 仍失敗: 在「設定」頁切換下載來源 (TPCA ↔ 官方) 後重試。
3. 校驗失敗且重試仍出現: 下載來源檔案可能損毀, 等待一段時間後重試, 或切換下載來源。
4. 若為 Windows 且下載的是安裝套件, 確認磁碟空間充足 (安裝套件數百 MB, 需預留 Cache 目錄空間)。

首次啟動隧道時 mefrpc 下載失敗

表現: 啟動隧道時提示下載 mefrpc 客戶端失敗, 隧道無法啟動。

排查路徑:

1. 確認 bin/mefrpc.exe (Windows) 或 bin/mefrpc.tar (Linux/macOS) 是否存在; 缺少時啟動隧道會自動下載。
2. 下載失敗: 在「設定」頁切換下載來源 (TPCA ↔ 官方) 後重新啟動隧道。
3. 校驗失敗 (檔案損毀): 刪除 bin 下殘留的 mefrpc*.tmp 與損毀檔案後重試。

連結啟動隧道 (pml2://)

應用程式支援 pml2:// 通用連結, 用於從瀏覽器/網頁一鍵啟動指定隧道:

pml2://StartProxy/<隧道ID>?Name=<隧道名>

(mefrp:// 前置字元同樣可辨識; Name 可省略, 省略時終端機分頁顯示 #隧道ID。)

首次使用的平台差異

註冊在主執行個體啟動時進行一次; 應用程式目錄被移動或重新安裝後, 下次啟動會自動改寫為新路徑。

點擊連結的行為

• 應用程式未執行 (冷啟動): 連結參數寫入 Cache/startup.json, 主視窗在 2 分鐘內讀到即拉起對應隧道 (讀取後立即刪除該臨時檔案, 不會重複啟動)。
• 應用程式已在執行: 第二次啟動會把連結透傳給已執行的執行個體 (具名管道 tech.rycb.pml2), 由它顯示主視窗並啟動隧道。

連結點了沒反應?