在 ServBay 中配置 Ngrok 反向代理服務指南

Ngrok 是一款功能強大的安全隧道工具，基於反向代理技術，可穿透防火牆與 NAT，將本地執行的服務映射至公網域名。本指南將詳盡說明如何在 ServBay 本地開發環境整合並設定 Ngrok 服務，使本地 Web 服務、API 或其它應用可於互聯網上存取，方便遠端展示、團隊協作或第三方服務回呼測試。

技術原理

Ngrok 的核心機制是在您的本機與 Ngrok 伺服器間建立加密隧道連線。外部用戶經由 Ngrok 分配的公網域名存取時，請求會先抵達 Ngrok 伺服器，然後再透過安全隧道轉發至您本地的 ServBay 服務。因此，即便本機無固定 IP 或處於防火牆後方，仍能跨網路對外提供服務。對於 ServBay 使用者而言，這代表無論是本地網站、後端 API 還是任何基於 HTTP/HTTPS 的服務，都可即時安全展示給外部世界進行測試或演示。

環境準備

在開始設定 Ngrok 前，請務必完成以下準備事項：

1. 已安裝並啟動 ServBay： 確認 ServBay 已正確安裝，且您欲經由 Ngrok 曝光的 Web 服務（如網站）已在 ServBay 設定並可正常運作。您可於 ServBay 的「網站」面板檢視及管理本地站台設定。
2. 安裝 Ngrok 客戶端： 按下列步驟部署 Ngrok CLI 工具：
   1. 前往 Ngrok 官方下載頁面 取得相對應作業系統的安裝檔。
   2. 下載後解壓縮，將取得的 ngrok 可執行檔移動或複製至系統 PATH 包含的目錄（如 macOS 的 /usr/local/bin），確保可於任何終端機直接執行 ngrok 指令。

      # 以 macOS ARM64 為例
      sudo unzip ~/Downloads/ngrok-v3-stable-darwin-arm64.zip -d /usr/local/bin

   3. 驗證安裝完整性，檢查 ngrok version 指令能否正常顯示版本號：

      ngrok version
      # 範例輸出: ngrok version 3.5.0

3. Ngrok 帳號（可選但建議）： 擁有 Ngrok 帳戶（免費/付費皆可）能更方便管理隧道或啟用固定網域等進階功能。請註冊 Ngrok 官網，並取得驗證 Token（ngrok config add-authtoken <YOUR_AUTH_TOKEN>），這將解除隧道連線的時限並解鎖更多功能。
4. 設定本地網站： 至少已在 ServBay 配置一個希望經由 Ngrok 曝露至公網的網站，例如使用 servbay.local 或 yourproject.servbay.demo 作本地存取域名。

隧道設定實戰

核心參數說明

執行服務映射的標準指令格式如下：

ngrok http --domain=<NGROK_DOMAIN> <LOCAL_ENDPOINT> \
  --request-header-add='host: <VIRTUAL_HOST>'

參數組件	功能說明
http	建立基於 HTTP 協議的隧道。Ngrok 會處理所有經由其入口的 HTTP/HTTPS 請求。
--domain <NGROK_DOMAIN>	指定 Ngrok 所分配的固定網域（請替換為您於 Ngrok Dashboard 設定或收到的實際網域）。免費方案通常可省略此參數，Ngrok 將自動產生隨機子域名。
<LOCAL_ENDPOINT>	您在 ServBay 上的本機服務地址。對於虛擬主機，通常是本地存取域名（如 https://servbay.local），也可用 http://localhost:端口 表示。
--request-header-add='host: <VIRTUAL_HOST>'	【重要】 重寫請求 Host 標頭。ServBay 依 HTTP Host 區分本地不同站台。此參數將外部請求的 Host 設定為您於 ServBay 設定的本地虛擬域名（如 servbay.local），確保正確路由到對應網站。

設定範例

假設您已在 ServBay 建立本地網站，域名為 servbay.local，想透過 Ngrok 曝露其至公網。如使用 Ngrok 免費方案，可直接映射本地地址：

# 將本地 ServBay 網站 servbay.local 映射到 Ngrok 隨機域名
ngrok http https://servbay.local --request-header-add='host: servbay.local'

若在 Ngrok Dashboard 設定過固定網域（如 your-servbay-demo.ngrok-free.app），則使用 --domain 參數：

# 將 servbay.local 映射到指定 Ngrok 網域
ngrok http --domain=your-servbay-demo.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'

執行上述指令後，Ngrok 客戶端將於終端機顯示隧道狀態資訊，包括分配的公網訪問網址（如 https://xxxx.ngrok-free.app 或您設定的域名），及流量監控儀表板的本地連結（一般為 http://127.0.0.1:4040）。

服務驗證

完成設定並啟動 Ngrok 隧道後，請依下列步驟檢查服務是否可透過公網正常訪問：

1. 取得公網網址： 於 Ngrok 終端找到 Forwarding 行，記錄 https:// 起始的公網 URL。
2. 瀏覽器測試： 於連網裝置，以瀏覽器開啟上一步取得的 Ngrok 公網 URL（如 https://cunning-lacewing-fresh.ngrok-free.app）。
3. 驗證結果：
   • 確認內容正確載入，即本地 ServBay 托管網站已顯示於外部裝置。
   • 檢查瀏覽器地址列有無 HTTPS 安全連線標識。Ngrok 預設為每個隧道提供有效 SSL 憑證。
   • 可在 Ngrok 終端或登入本地 Web 介面（一般為 http://127.0.0.1:4040）檢視請求日誌與流量數據，確認外部請求已由 ServBay 正常處理。

圖示：使用 Web 瀏覽器成功訪問 Ngrok 創建之隧道

進階技巧與注意事項

1. 網域管理：
   • Ngrok 免費方案會分配隨機 .ngrok-free.app 子網域，且連線有時限。
   • 註冊 Ngrok 帳號並於 Ngrok Dashboard 配置固定網域，能避免每次啟動後網址變動。
   • Ngrok 付費版支援綁定自有頂級網域、提升頻寬與連線數量，及解鎖更多功能。
2. 多服務映射： 如需同時映射多個 ServBay 本地服務或端口，可分別啟動多個 Ngrok 隧道程序，或編輯 Ngrok 組態檔（通常存於 ~/.config/ngrok/ngrok.yml）統一管理多條隧道。例如，同時映射 ServBay 站台與另一個本地服務：

   # 將 servbay.local（假設透過 HTTPS 443 並依 Host 路由）映射
   ngrok http --domain=servbay-website.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'
   
   # 於另一個終端或通過組態檔映射本地 3000 端口 Node.js 應用
   ngrok http --domain=nodejs-api.ngrok-free.app http://localhost:3000

   注意：針對 ServBay 虛擬主機，建議使用 https://[本地網址] 結合 --request-header-add 參數做映射，勿直接映射 ServBay 的 80/443 端口，因為 ServBay 會在這些端口統一處理所有虛擬主機請求。
3. 診斷指令：
   • ngrok config check：檢查 Ngrok 設定檔（如 ~/.config/ngrok/ngrok.yml）語法是否正確。
   • ngrok logs：終端即時顯示 Ngrok 用戶端詳細日誌，方便診斷連線或路由問題。
4. 安全性： 將本地服務曝光至公網有資安風險。請確保僅於必要時啟用 Ngrok 隧道並嚴管所曝光服務。Ngrok 付費方案能自訂 IP 白名單、限制訪問等進階資安設定。

疑難排解

現象	解決方案
連線逾時或網頁無法載入	請確認 ServBay 目標站台是否有正常啟動並可於本地域名連線（如本地瀏覽器開 https://servbay.local）。查驗 ServBay Web 伺服器（如 Caddy 或 Nginx）運作狀態，同時檢查本地防火牆是否有開放 Ngrok 所需網路連線。
HTTPS 憑證錯誤（瀏覽器警告）	Ngrok 預設會為公網地址發放合法 SSL 憑證。若訪問 Ngrok 領到之網址時遇到憑證錯誤，多屬 Ngrok 隧道配置或網路環境問題，本身非 ServBay 錯誤。請確保連的是 Ngrok 分配之 https:// 網址。若只於 ServBay 本地訪問時出現警告，需檢查 ServBay 的 SSL 組態。
間歇性斷線或速度緩慢	請確認本地網路穩定；不穩定會導致隧道中斷。若可能，建議用有線網路。對高可用需求後台服務，可考慮購買 Ngrok 付費方案，享有更穩定連線和更高頻寬。
開到 ServBay 預設首頁而非欲存取站台	請確認 ngrok http 指令中的 <LOCAL_ENDPOINT> 正確，且 --request-header-add='host: <VIRTUAL_HOST>' 參數的 <VIRTUAL_HOST> 必須精確設為您於 ServBay 設定的對應本地域名。這是確保 ServBay 將請求正確路由至目標網站的關鍵。

常見問題解答 (FAQ)

• Q: 能用 Ngrok 映射 ServBay 的資料庫服務嗎？

  A: Ngrok 主要適用於 HTTP/HTTPS 隧道。雖然支援 TCP 隧道（適用於資料庫等服務），但這已超出本指南範圍，且極不建議將本地資料庫直接公網曝光，存在嚴重資安隱憂。若需遠端資料庫訪問，請考慮 SSH 隧道或其它更安全聯外方式。

• Q: 為什麼每次啟動 Ngrok，公網域名都會更改？

  A: Ngrok 免費方案每次分配的 .ngrok-free.app 子網域多為隨機。若需固定公網網址，請先註冊 Ngrok 帳號並經 Dashboard 配置，或升級為付費帳戶。

• Q: Ngrok 會拖慢本地 ServBay 的速度嗎？

  A: Ngrok 會帶來小幅網路延遲，因所有流量需經由 Ngrok 伺服器中轉。但對於開發、測試或展示場景，此延遲一般可接受。實際 ServBay 本地服務效能仍取決於您電腦及網站/應用表現。

總結

結合 Ngrok，ServBay 用戶可輕易、安心地將本地 Web 成果分享至互聯網。全程無須繁雜的網路設置，尤其適合遠端協作、客戶演示，或行動端及第三方服務串連測試。Ngrok 提供即時流量監控與強大安全選項（部分功能需付費）。若應用屬業務關鍵或需穩定固定網址，亦建議採用 Ngrok 付費服務以享有更加穩定豐富的體驗。