使用 FRP 於 ServBay 本地開發環境進行公網訪問（內網穿透）

FRP 是一款高效能、易於使用的反向代理工具，特別適合需要將本地開發服務（如網站、API、資料庫等）安全便捷地暴露於公網的情境。透過其客戶端（frpc）與服務端（frps）架構，FRP 能有效實現內網穿透。

本指南將詳細說明 ServBay 用戶，尤其是在 macOS 環境下，如何配置並使用 FRP 客戶端（frpc）以建立安全隧道，讓您在 ServBay 執行的本地 web 服務得以透過公網訪問。這對於遠端演示、協作開發、接收 Webhook 請求或進行外部 API 測試等用途至關重要。

技術原理概述

FRP 的核心原理，是於內網機器（運行 frpc，即您的 ServBay 所在機器）與公網伺服器（運行 frps）間建立加密傳輸隧道。當外部用戶從公網訪問您的服務時，請求首先抵達運行 frps 的公網伺服器，再經由預先建立的隧道轉發至您的內網 frpc。frpc 收到請求後，進一步轉送至 ServBay 本地運行的服務（例如網站或 API）。服務回應則沿著反向路徑返回給外部用戶。

此機制能巧妙繞過內網防火牆與路由器限制，實現內網服務對外公開，同時支援 TCP/UDP/HTTP/HTTPS 等多種協議，為 ServBay 開發環境帶來極大遠端存取能力。

適用情境

ServBay 結合 FRP，能輕鬆應對以下開發情境：

• 遠端演示與協作： 無需布署至遠端伺服器，直接將本機正開發的網站或應用即時演示給團隊成員或客戶。
• Webhook 測試： 直接於本地接收並調試來自 GitHub、Stripe、微信支付等第三方的 Webhook 通知。
• API 聯調： 將本地開發的後端 API 對外開放，讓前端開發人員或合作方即時測試調用。
• 行動端測試： 於手持設備（手機/平板）直接訪問本地 ServBay 環境的網站或應用，進行跨裝置相容性測試。
• 臨時分享： 快速分享本地檔案或服務，無需繁雜設定。

前置條件

開始配置 FRP 前，請確認已具備下列條件：

1. 已安裝並啟動 ServBay： 您的 macOS 機器已成功安裝並運行 ServBay，且想要公開的本地服務（如網站）已於 ServBay 完成配置並可用本地瀏覽器開啟。
2. 擁有一台公網 FRP 伺服器（frps）： 需有一台具有公網 IP 的伺服器，並已部署且運行 FRP 服務端（frps）。本文件重點聚焦於客戶端（frpc）配置。
3. 公網網域名稱（可選，但建議 HTTP/HTTPS 必須）： 若您打算以網域名稱訪問服務，需要持有可控網域並能做 DNS 設定。
4. 已安裝 FRP 客戶端（frpc）： FRP 客戶端預設不包含於 ServBay，請自行下載並安裝。

環境準備與 FRP 客戶端安裝

請依下列步驟於您安裝 ServBay 的 macOS 機器上安裝 FRP 客戶端（frpc）。

1. 下載 FRP 客戶端： 前往 FRP GitHub Releases 頁面，下載符合您 macOS 架構的 最新版本 FRP 安裝包。

   • 適用 Apple Silicon (M1/M2/M3 等) 架構者，下載 frp_*.darwin_arm64.tar.gz 檔。
   • 適用 Intel 架構者，下載 frp_*.darwin_amd64.tar.gz 檔。

2. 安裝 FRP 客戶端： 解壓縮下載的檔案，並將 frpc 執行檔複製到系統 PATH 目錄（如 /usr/local/bin），以便在任意終端可直接執行 frpc 命令。

   注意，下列指令中的版本號（0.52.3 為撰寫時新版本，請依實際檔名調整）與架構名稱（darwin_arm64）僅作示範。

   # 假設您下載的是 frp_0.52.3_darwin_arm64.tar.gz
   # 進入下載目錄
   cd ~/Downloads
   
   # 解壓縮檔案（請替換成您的實際檔名）
   tar -zxvf frp_0.52.3_darwin_arm64.tar.gz
   
   # 進入解壓後的目錄（請替換成您的實際目錄名）
   cd frp_0.52.3_darwin_arm64
   
   # 將 frpc 可執行檔複製到 /usr/local/bin
   sudo cp frpc /usr/local/bin/
   
   # （可選）亦可將 frpc.toml 範例檔複製到家目錄
   # cp frpc.toml ~/

   輸入您的使用者密碼以完成 sudo 指令。

3. 驗證安裝： 開啟新終端視窗，執行下列指令，確認 frpc 已裝妥且可於 PATH 使用：

   frpc -v
   # 預期輸出類似：frpc version 0.52.3

   若能看到版本資訊，則安裝成功。

配置 FRP 客戶端隧道

FRP 客戶端主要以名為 frpc.toml 的檔案設定（新版 FRP 建議用 TOML 格式）。您需建立或編輯此檔，指示 frpc 如何連線至 FRP 伺服器（frps）及將 ServBay 本地服務映射到公網。

frpc.toml 配置檔詳解

以下為基礎 frpc.toml 配置示例，展示連線資訊及單一代理設置：

# frpc.toml - FRP 客戶端設定檔示例

# [common] 段：連線伺服器設定
serverAddr = "your-frps-server.com" # 您的 FRP 服務端公網 IP 或網域
serverPort = 7000 # FRP 服務端供客戶端連線之埠號（預設 7000）

# 驗證設定（建議用 token）
auth.method = "token"
auth.token = "your_authentication_token" # 與服務端一致之認證密碼

# 可選：啟用 TLS 加密 client-server 連線，提升安全性
# tls_enable = true

# [[proxies]] 段：定義代理隧道
[[proxies]]
name = "my-web-service" # 代理名稱，於一份 frpc.toml 內需唯一
type = "http" # 代理型態：http, https, tcp, udp, stcp, xtcp 等
localIP = "127.0.0.1" # 本地服務 IP，一般預設 127.0.0.1
localPort = 80 # 本地服務埠號（如 ServBay HTTP 預設 80）
customDomains = ["servbay.your-domain.com"] # 公網訪問網域（僅適 http/https）；需預先將域名 DNS 指向 FRP 服務端

# 可添加多組 [[proxies]] 以映射多項服務
# [[proxies]]
# ...（其他服務代理設定）

配置項	所屬區塊	功能說明
serverAddr	[common]	FRP 服務端（frps）公網 IP 或網域
serverPort	[common]	FRP 服務端供客戶端連線之埠號，預設 7000，請依實際調整
auth.method	[common]	連線驗證方式，常用 token，須與服務端設定一致
auth.token	auth（於 [common] 下）	驗證金鑰，需與服務端一致，務必保密
tls_enable	[common]	是否啟用 client-server 間 TLS，加密連線；建議設為 true
[[proxies]]	根層級	代理隧道設定陣列。每塊 [[proxies]] 定義一組映射規則
name	[[proxies]]	當前代理的唯一名稱，建議以服務功能命名
type	[[proxies]]	代理協議型態，如 http, https, tcp, udp 等
localIP	[[proxies]]	本地服務 IP，通常保持 127.0.0.1
localPort	[[proxies]]	本地服務埠號，如 ServBay 預設 HTTP 80、HTTPS 443，MySQL 3306，PostgreSQL 5432 等
remotePort	[[proxies]]	（僅 tcp/udp 類型適用）FRP 服務端對外暴露的埠，公網用戶將經由 serverAddr:remotePort 連入
customDomains	[[proxies]]	（僅 http/https）外部通過域名訪問的設定，為字串陣列，可設多個。需預先將這些域名經 DNS 設定指向您 FRP 服務端公網 IP。
subdomain	[[proxies]]	（僅 http/https，且服務端支援）若服務端有 subdomain_host，可設子網域，最終會為 subdomain.subdomain_host。與 customDomains 擇一使用。
[proxies.plugin]	[[proxies]]	特定位插件設定，如 https2https 處理本地 HTTPS 服務
hostHeaderRewrite	[proxies.plugin] 或 [[proxies]] （依型態/插件）	重寫 Host header，對於 ServBay 虛擬主機非常重要。須設為該網站於 ServBay 配置的本地域名。

典型配置範例：映射 ServBay HTTPS 網站服務

ServBay 通常為本地網站開啟 HTTPS 並自動管理 SSL 憑證。若需透過 FRP 將 HTTPS 站點暴露至公網，通常使用 https 類型（可結合 https2https 插件），或直接以 tcp 代理 443 埠。由於 ServBay 虛擬主機仰賴 Host header，建議以 https 搭配 hostHeaderRewrite 為主。

下例為將 ServBay 中已設定域名如 servbay.test 的本地站點，經 FRP 映射至公網域名的配置。請務必將您的公網域名（如 test-frp.servbay.app）透過 DNS CNAME 或 A 紀錄正確解析到 FRP 服務端（如 frps.servbay.demo）的公網 IP。

請在家目錄建立名為 frpc.toml 的設定檔，並填上如下內容：

# frpc.toml 範例：映射 ServBay HTTPS 網站

# [common] 連線 FRP 服務端設定
serverAddr = "frps.servbay.demo" # 請替換成您的 FRP 服務端地址
serverPort = 7000 # 換成您的服務端埠號

auth.method = "token"
auth.token = "servbay_demo_token" # 換成服務端配置的 token

# 推薦啟用 TLS 加密 client-server 連線
tls_enable = true

# [[proxies]] 映射本地 HTTPS 網站
[[proxies]]
name = "servbay-website-https" # 代理名稱（可自訂，如 servbay-test-site）
type = "https" # 代理型態

# 公開的公網網域，必須已指向 FRP 服務端 IP
customDomains = ["test-frp.servbay.app"] # 請換成您想要的公網域名

# 指向本地服務的細節
localIP = "127.0.0.1" # ServBay 通常監聽於本機
localPort = 443 # ServBay 預設 HTTPS 埠

# 重寫 Host header，與 ServBay 中網站的域名相符
# 因 ServBay web server（Nginx/Caddy）以 Host header 判別資源
hostHeaderRewrite = "servbay.test" # 請換成 ServBay 中此站的域名

# 可選：轉發自訂 request header，以利後端識別來源
[proxies.requestHeaders.set]
x-from-where = "frp-tunnel"

請將上述 serverAddr、serverPort、auth.token、customDomains、hostHeaderRewrite 依實際對應資訊替換。

hostHeaderRewrite 重要性說明： ServBay 採用 web server（如 Nginx、Caddy）管理站台，通常根據外部請求的 Host header 判斷網站歸屬。當請求經 FRP 隧道送達 ServBay 時，Host 為您訪問的公網域（如 test-frp.servbay.app），而非本地設定的域名（如 servbay.test）。若未設定 hostHeaderRewrite，ServBay web server 可能無法定位正確站台而回傳 404 或預設網站內容。因此，hostHeaderRewrite 必須對應本地對應網站之域名。

啟動 FRP 客戶端服務

完整設定好 frpc.toml 檔後，於終端機切換至該檔案所在目錄（如已存於家目錄 ~/frpc.toml，亦可於任意目錄執行下述命令加路徑）：

# 若 frpc.toml 檔在當前目錄
frpc -c frpc.toml

# 若在 user 家目錄
# frpc -c ~/frpc.toml

此指令會以前景模式執行 frpc 並嘗試連到 frps 伺服器。成功後，終端將顯示隧道建立及代理啟動的即時日誌。

欲於背景執行，可利用 nohup 或 macOS 的 launchctl（較進階）。舉例來說（nohup）：

# 假設 frpc.toml 在家目錄
nohup frpc -c ~/frpc.toml &

nohup 會自動將日誌導向 nohup.out 並於背景執行。須留意，macOS 上更正統的方式為用 launchctl 管理服務，設定較為繁瑣，可參見官方文件，此處略過。

服務驗證與日誌診斷

服務驗證

啟動 frpc 且日誌顯示連線成功後，請於瀏覽器輸入您 frpc.toml 所設公網域名（例如 https://test-frp.servbay.app），驗證項目包括：

• 能正常載入網頁，無連線或憑證（若為 HTTPS）等錯誤警告。
• 返回 HTTP 200 或預期狀態碼。
• 頁面內容與您本地訪問 https://servbay.test 一致。
• 若為 HTTPS，瀏覽器地址列顯示安全鎖且 SSL 憑證為有效（應簽發予您的公網域名）。

日誌診斷

FRP 客戶端之日誌為連線與代理問題的重要診斷參考。執行 frpc -c frpc.toml 預設於終端顯示日誌，可即時觀察錯誤或警告。

可於啟動加 debug 參數獲得更詳細日誌，利於排錯：

frpc -c frpc.toml --log_level debug

若您於 frpc.toml 指定了 log_file（如 log_file = "/var/log/frpc.log"），則日誌將寫入該檔。可用 tail -f /path/to/your/frpc.log 監看實時狀況。

常見故障排查

若 FRP 配置或使用過程遇到問題，可參考下表狀況與對應解決辦法：

現象	解決方案
連線 FRP 伺服器認證失敗	請檢查 frpc.toml 內 [common] 的 auth.token 與 auth.method 是否與 FRP 服務端完全一致，同時檢視伺服器端日誌是否有認證失敗紀錄。
公網域名無法訪問或解析異常	確認 frpc.toml 的 customDomains 已於 DNS 實現 CNAME 或 A 記錄映射到 FRP 伺服器公網 IP。可用 ping your-frp-domain.com 或線上查詢工具檢查，如 DNS 有延遲，請耐心等待。
訪問公網域名僅見 FRP 歡迎頁	這表示 DNS 答對 FRP 服務端但無代理規則。檢查 customDomains 是否與瀏覽器輸入網址完全相符，type 是否正確指定為 http 或 https，並檢視伺服器映射規則。
本地埠被佔用或服務未啟動	確保 ServBay 已執行且需公開的本地服務（如網站）已經啟動並監聽於 frpc.toml 所設的埠。可用 lsof -i :PORT（將 PORT 換成實際數字）檢查該埠由何程式持有。
隧道連結不穩定	請檢查您電腦與 FRP 服務端的網路是否穩定，可於 [common] 加大 heartbeat_timeout = 30，或適度提升 pool_count 以增加連線池數，並檢視伺服器資源是否足夠或有異常。
訪問 HTTP 服務卻被瀏覽器自動導向 HTTPS	檢查 ServBay 相關網頁之 Nginx/Caddy 設定是否已設強制 HTTP 跳轉 HTTPS。若要公開 HTTP，請將代理型態設為 http，移除不必要插件；欲公開 HTTPS，請確保 type 正確且相關證書配置齊全。
HTTPS 憑證錯誤（瀏覽器警告）	若以 https 代理型態，共用自簽或 ServBay CA 憑證，瀏覽器將提示不被信任。若需消除此警告，可於本機安裝 ServBay User CA，或採用 https2http/https2https 插件並指定 ServBay 生成的憑證路徑，或於伺服器端部署有效證書。當以 https 型態搭配 hostHeaderRewrite 時，憑證信任度取決於 ServBay 本地憑證。
訪問出現 404 錯誤	檢查 hostHeaderRewrite 是否對應 ServBay 內本地站台的域名（如 servbay.test），若 Host 不匹配，Web 服務將無法正確定位網站。
FRP 伺服器防火牆阻擋連線	請確保已開放 serverPort（預設 7000）與 frpc.toml 代理服務設的對外端口（如 HTTP 80、HTTPS 443、或 TCP/UDP 之 remotePort）於 FRP 伺服器防火牆
本地防火牆阻擋連線	請確保 macOS 防火牆未阻斷 frpc 連線至 FRP 服務端之 serverPort（通常出站預設允許），也勿阻擋 ServBay 服務對 127.0.0.1 的本地端口連接。
FRP 客戶端日誌顯示連線成功但訪問失敗	可能為伺服器端配置問題，請檢查 frps 日誌是否有錯誤或是否完成對應轉發規則，並確認伺服器到您內網客戶端的網路未受阻擋。

FRP 方案於 ServBay 環境下的優勢與安全建議

結合 FRP 與 ServBay，能為開發者帶來極大彈性與便利：

• 多協議支援： FRP 支援 HTTP、HTTPS、TCP、UDP 等協議，不僅適用於 web 服務，也可公開本地資料庫（如 MySQL/PostgreSQL/MongoDB）、Redis、SSH 服務等。
• 彈性配置： 僅需編輯簡易 TOML 設定，即可同時映射多個 ServBay 站點或服務。
• 開源可自控： FRP 為成熟開源專案，內網穿透方案可全面主控，無需倚賴第三方平台。
• 安全性高： FRP 支援 Token 認證、TLS 加密（tls_enable = true），配合 ServBay 的 SSL 憑證管理，可打造更安全的開發環境。

安全建議：

• 啟用 TLS 加密： 強烈推薦於 [common] 段設 tls_enable = true，保護 client-server 傳輸安全。
• 使用強認證 Token： 選用複雜且難以破解的 auth.token 並定期更換。
• 只公開必要服務： 僅暴露有需求的本機服務及端口，避免多餘風險。
• 優先使用公網域名： HTTP/HTTPS 型態建議僅用 customDomains 公網域名存取，盡量避免直接用 IP 與埠號。
• 強化 FRP 伺服器本身安全： 僅開放必要埠，並於主機層設好防火牆規則。
• 可考慮設置存取控制： 若 FRP 伺服器支援，可增設 IP 白名單等更嚴密的存取政策。

根據以上指南與配置，您將能成功將 ServBay 本地服務安全地透過 FRP 發布到公網，有效提升開發流程便利性與彈性。