Gluetun 連接埠轉送與 torrent client 設定
下載正常卻沒有任何連線進來?了解 gluetun 連接埠轉送、每次重新連線後同步新連接埠到 torrent client,並完成實際驗證。
沒有轉送連接埠時,為什麼沒有任何連線進來
Gluetun 的連接埠轉送功能會要求 VPN 供應商,將其出口位址上的一個公開連接埠對應回你的容器。這是其他 peer 能向 torrent client 建立連線的唯一方式。沒有這項對應時,tunnel 仍然正常、下載也會執行,但不會有連線自行進入。所有正常建立的連線,都是由你的 client 先發起。
這套機制是 NAT(network address translation,網路位址轉譯)。你的容器會與許多其他客戶共用供應商的出口位址。當 client 向外建立連線時,供應商會記錄該連線流程,並將回應透過 tunnel 傳回。陌生 peer 從外部連入時,找不到相符的既有連線流程,因此封包抵達出口位址後就會在那裡遭到丟棄。你的 client 仍能連線到本身可接受連線的每個 peer,因此下載仍可完成,問題也不容易被發現。問題會在做種時顯現,因為 seeder 是其他人會連線到的機器。
開放一個入站連接埠會帶來兩項變化。你能更快加入 swarm,因為無法自行接受連線的 peer 現在可以連到你;同時,你也能向這些 peer 上傳資料。
為什麼大多數 VPN 供應商不提供連接埠轉送
連接埠轉送是共用位址上的稀缺資源。供應商會在一個出口 IP 上保留一個連接埠號碼給一名客戶,並負責處理該客戶透過此連接埠進行的所有活動。多家大型供應商已移除這項功能,理由是需要處理濫用問題。評估支援情況時,應將其視為分類問題,而不是單純的核取方塊:確認供應商目前是否提供連接埠轉送、你的方案是否包含此功能,以及你是否能實際選擇支援此功能的伺服器。
提供連接埠轉送時,該連接埠通常是動態的。它隸屬於 VPN 工作階段,而不是你的帳戶,因此每次重新連線後都可能取得不同的號碼。Private Internet Access 會發放簽署的連接埠,由 gluetun 進行更新;上游文件指出,只要將 /gluetun 目錄 bind mount,使狀態可在重新啟動後保留,就能在 60 days 內維持相同的連接埠。ProtonVPN 會透過 NAT-PMP (NAT port mapping protocol) 指派隨機連接埠,但租約時間較短,必須持續續租。因此,只在 client 中設定一次連接埠,無法持續正常運作。
gluetun 可向哪些供應商要求連接埠
截至 2026 年 7 月 30 日發布的 gluetun v3.41.3,原生整合會驗證 4 個供應商名稱:Private Internet Access、ProtonVPN、Perfect Privacy 和 PrivateVPN。使用 VPN_PORT_FORWARDING=on 啟用此功能,預設值為 off。較舊的指南會使用 PORT_FORWARDING 或 PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING。這兩個名稱在此版本中仍可作為相容舊版的名稱使用,但即將淘汰。
有 2 項供應商設定會決定要求是否能夠成功。ProtonVPN 需要付費方案,且必須啟用 NAT-PMP:產生 WireGuard 設定時,請在 VPN 選項中啟用 NAT-PMP (Port Forwarding);使用 OpenVPN 時,請將 +pmp 附加到使用者名稱。Private Internet Access 的 OpenVPN 設定包含 PORT_FORWARD_ONLY,會將伺服器選擇限制在支援連接埠轉送的伺服器,避免連線到從未支援此功能的伺服器。WireGuard 與 OpenVPN 要求連接埠的方式不同,因此請先閱讀供應商的說明頁面,再選擇使用方式。
gluetun 使用自訂設定而非內建供應商時,VPN_PORT_FORWARDING_PROVIDER 會指定 gluetun 應呼叫的 API。上游 Private Internet Access 頁面會將此變數與 VPN_PORT_FORWARDING_USERNAME 和 VPN_PORT_FORWARDING_PASSWORD 搭配使用;這些變數會提供連接埠要求所需的帳戶認證資訊。
在 docker compose 中啟用 gluetun 連接埠轉送
這裡假設通道已正常運作。若尚未運作,請先依照將 Docker 容器流量透過 gluetun 路由操作,確認下載可以執行後再回到這裡。
services:
gluetun:
image: qmcgaw/gluetun:v3.41.3
container_name: gluetun
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
ports:
- 8080:8080/tcp
- 8000:8000/tcp
volumes:
- ./gluetun:/gluetun
environment:
- VPN_SERVICE_PROVIDER=protonvpn
- VPN_TYPE=wireguard
- WIREGUARD_PRIVATE_KEY=${WIREGUARD_PRIVATE_KEY}
- VPN_PORT_FORWARDING=on
- TZ=Etc/UTC
restart: unless-stopped
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:5.2.3
container_name: qbittorrent
network_mode: "service:gluetun"
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
- WEBUI_PORT=8080
volumes:
- ./qbittorrent:/config
- ./downloads:/downloads
depends_on:
- gluetun
restart: unless-stopped固定映像標籤。qmcgaw/gluetun:latest 會跟隨 master 分支,而連接埠轉送的內部實作正在為 v4 變更,因此未固定的映像可能在下次 docker compose pull 時改變行為。請使用用於 compose secret 的 env 檔案,不要將私密金鑰放在 compose 檔案中。
Gluetun 寫入轉送連接埠的位置
Gluetun 會在 3 個位置公開連接埠,而且這些位置的值都相同。
每次取得連接埠時,Gluetun 都會記錄一次。該行內容為 port forwarded is 45678;如果要求未取得任何值,則為 no port forwarded。
docker logs gluetun 2>&1 | grep -i "port forwarded"Gluetun 會將數字寫入由 VPN_PORT_FORWARDING_STATUS_FILE 指定的檔案,預設為 /tmp/gluetun/forwarded_port。檔案每行包含 1 個連接埠,檔案模式為 0644,並會將擁有者與群組變更為容器的 PUID 和 PGID。停止轉送時,Gluetun 會清空檔案而不刪除檔案,因此讀取端會讀到空檔案,不會因檔案不存在而失敗。
docker exec gluetun cat /tmp/gluetun/forwarded_portGluetun 也會在 control server 上提供此值。該伺服器預設監聽 :8000,並由 HTTP_CONTROL_SERVER_ADDRESS 設定。
curl -s http://127.0.0.1:8000/v1/portforward{"port":45678,"ports":[45678]}Gluetun 也會在 VPN 介面上的自有防火牆中開放該連接埠,因此使用原生整合功能時不需要 FIREWALL_VPN_INPUT_PORTS。此變數適用於另一種情況:Gluetun 無法查詢該 provider,而你是透過其他管道取得固定連接埠,必須手動放行該連接埠。
這 3 種方式中,只有 1 種具持久性,另外 2 種則沒有。上游文件已將 status file 標記為在 v4.0.0 中棄用,而 GET /v1/openvpn/portforwarded 已經會回覆 301 Moved Permanently,並指向 /v1/portforward。新的實作應讀取 control server。
每次重新連線時都必須告知用戶端連接埠
torrent 用戶端會將監聽連接埠儲存在自己的設定中,並在重新啟動後沿用該連接埠。轉送的連接埠則屬於 VPN 工作階段。重新連線後,這兩個連接埠會不一致,因此供應商會將連接埠對應到沒有服務監聽的連接埠,而用戶端則監聽沒有對應轉送的連接埠。重新連線並不罕見:可能是容器重新啟動、伺服器變更、連線中斷後由 gluetun 的 health check 重新啟動,或租約無法續期。結果是原本昨天仍可連線的設定,今天會在沒有任何錯誤日誌的情況下悄悄變得無法連線。
因此,必須在 gluetun 取得連接埠的當下套用該連接埠。有兩種方式可以完成整合,差別在於由哪個程序執行這項工作。
選項 1:gluetun 使用 up 命令推送連接埠
VPN_PORT_FORWARDING_UP_COMMAND 會在連接埠轉送建立時執行,VPN_PORT_FORWARDING_DOWN_COMMAND 會在連接埠轉送停止時執行。Gluetun 會在執行命令前替換 {{PORT}}(第一個連接埠)、{{PORTS}}(所有連接埠,以逗號分隔)及 {{VPN_INTERFACE}}(通道介面名稱,預設為 tun0)。Shell 語法需要明確的 /bin/sh -c wrapper。以下是 upstream qBittorrent 範例,寫成兩個 compose 環境變數項目:
- VPN_PORT_FORWARDING_UP_COMMAND=/bin/sh -c 'wget -O- -nv --retry-connrefused --post-data "json={\"listen_port\":{{PORT}},\"current_network_interface\":\"{{VPN_INTERFACE}}\",\"random_port\":false,\"upnp\":false}" http://127.0.0.1:8080/api/v2/app/setPreferences'
- VPN_PORT_FORWARDING_DOWN_COMMAND=/bin/sh -c 'wget -O- -nv --retry-connrefused --post-data "json={\"listen_port\":0,\"current_network_interface\":\"lo\"}" http://127.0.0.1:8080/api/v2/app/setPreferences'該呼叫中的每個欄位都有特定用途。listen_port 是新的連接埠。current_network_interface 會將 qBittorrent 綁定至通道。將 random_port 設為 false,可避免 qBittorrent 在下次啟動時自行選擇連接埠。將 upnp 設為 false,可避免它嘗試透過不存在的路由器對映連接埠。
這種作法有兩項要求。qBittorrent 的 Web UI 必須啟用並監聽 8080 連接埠,而共用 gluetun 的 network namespace,才能讓它在 gluetun 容器內回應 127.0.0.1:8080。此外,必須啟用 Bypass authentication for clients on localhost(bypass_local_auth),因為該命令不會傳送認證資訊。加入 down 命令是必要的,因為 qBittorrent 在中斷連線後不一定會重新建立連接埠轉送。
該命令會在 gluetun 容器內執行。此容器以 Alpine 為基礎,並內建 wget。該映像檔不包含 curl。如果命令指定映像檔中不存在的二進位檔,每次連接埠轉送建立時都會執行失敗。
選項 2:gluetun 外部的程序讀取連接埠
另一種模式是在 gluetun 旁執行小型程序,取得連接埠後,透過用戶端自己的 API 將連接埠寫入用戶端。從控制伺服器讀取:
port=$(curl -s http://127.0.0.1:8000/v1/portforward | jq -r .port)如果該程序能看見檔案,也可以直接讀取檔案。/tmp/gluetun/forwarded_port 位於 gluetun 容器內,因此 sidecar 必須在兩個容器中都將共用 volume 掛載至 /tmp/gluetun;或者,將 VPN_PORT_FORWARDING_STATUS_FILE 指向現有掛載 volume 下的路徑。
這裡必須處理驗證。在 v3.41.3 中,路由 GET /v1/portforward 屬於名為 public 的預設角色,該角色具有 auth = "none",因此不需憑證即可回應;gluetun 也會記錄以 route GET /v1/portforward is unprotected by default, please set up authentication 開頭的警告。上游將在後續版本關閉此入口,而目前的控制伺服器文件已說明,所有路由預設均為私有。現在就在 bind mount 至 /gluetun/auth/config.toml 的檔案中定義角色:
roles = [
{ name = "qbittorrent", routes = ["GET /v1/portforward"], auth = "apikey", apikey = "myapikey" }
]使用 docker run --rm qmcgaw/gluetun:v3.41.3 genkey 產生金鑰,並將其放在 X-API-Key 標頭中傳送。HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE 會將預設角色定義為一個 JSON 編碼的環境變數,套用至檔案中角色未涵蓋的所有路由。只要定義任何角色,v3.41.3 就不再套用內建的 public 角色,因此之後呼叫的每個路由都必須有列出該路由的角色,或使用設定的預設角色。未定義任何角色時,內建的 public 角色也會涵蓋 PUT /v1/vpn/status;因此,在未設定驗證的情況下公開連接埠 8000,任何能連線到該連接埠的人都能控制 VPN 狀態。請審慎決定其可達範圍,並參考如何讓主機與其他容器連線至 gluetun。
當用戶端提供可由一次 wget 呼叫完成操作的 API 時,請選擇 up command,因為它會在每個事件發生時執行一次,不會留下任何常駐程序。當用戶端需要登入流程、改寫設定檔或重新啟動時,請選擇外部程序。在單一 gluetun 容器後方的 arr stack中,通常只需一個小型輪詢程序,因為只有 torrent 用戶端需要該連接埠。
陷阱:共用 network namespace 不會設定監聽連接埠
這個問題最浪費排查時間。network_mode: "service:gluetun" 會將用戶端放入 gluetun 的 network namespace,因此用戶端會取得 VPN 位址、通道路由和 gluetun 的防火牆規則。但這些設定都不會設定用戶端的監聽連接埠。Gluetun 會在 VPN 介面上開啟轉送連接埠,前往該連接埠的封包會抵達這個 namespace;如果用戶端監聽的是另一個連接埠,kernel 就沒有對應的目標可以交付封包。此時連線會遭拒或逾時,但所有對外連線檢查看起來都正常。轉送連接埠和用戶端的監聽連接埠是兩個獨立的數字,讓兩者保持一致就是完整的設定工作。
不要猜測,直接比較兩者。以下兩個指令都會針對同一個 namespace 執行:
docker exec gluetun cat /tmp/gluetun/forwarded_port
docker exec gluetun wget -qO- http://127.0.0.1:8080/api/v2/app/preferences | grep -o '"listen_port":[0-9]*'另一項設定也會讓人朝錯誤方向排查。VPN_PORT_FORWARDING_LISTENING_PORT 會使用 iptables,將來自轉送連接埠的入站流量重新導向至固定的本機連接埠。上游文件建議不要將它與 torrent 用戶端搭配使用,因為用戶端會向 tracker 和對等節點宣告自己的監聽連接埠,導致 swarm 得知錯誤的連接埠號碼。
如何確認轉送的連接埠可連線
用戶端本身的連線指示器反映的是對外的 tracker 連線,因此即使沒有任何連線能到達你的服務,指示器仍可能顯示綠色。請使用你能控制的監聽程式,從 VPN tunnel 外部的網路進行測試。上游提供了一個小型工具。請先停止 torrent client,因為兩個程序無法繫結至同一個連接埠。
docker stop qbittorrent
docker exec -it gluetun /bin/sh在 container 內,將 amd64 改為符合 CPU architecture 的值,並將 4567 改為轉送的連接埠:
wget -qO port-checker https://github.com/qdm12/port-checker/releases/download/v0.4.0/port-checker_0.4.0_linux_amd64
chmod +x port-checker
./port-checker --listening-address=":4567"接著找出 gluetun 使用的出口位址。回應格式為 JSON,位址位於 public_ip 欄位。
curl -s http://127.0.0.1:8000/v1/publicip/ip在以下 3 種情況下,不含認證資訊的這個請求會直接取得回應:v3.41.3 未設定 auth config,且內建的 public role 可處理該請求;auth config 在某個 role 中列出 GET /v1/publicip/ip,且該 role 設定了 auth = "none";或檔案中的任何 role 都未涵蓋該路由,此時會使用 HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE='{"auth":"none"}'。上游文件將 none 定義為不需要認證。如果你像 Option 2 一樣定義了 apikey role,請將 GET /v1/publicip/ip 加入該 role 的 routes,並傳送其 key,例如 curl -s -H "X-API-Key: myapikey" http://127.0.0.1:8000/v1/publicip/ip。
從不在相同 VPN 上的裝置開啟 http://<that address>:4567。使用行動數據連線的手機即可。若頁面顯示瀏覽器的 IP 位址與 user agent,且 port-checker 的日誌中記錄了相符的請求,即表示輸入的 TCP 流量已到達該 namespace。若發生逾時,表示流量未到達,原因位於 client 以外。使用 CTRL+C 停止工具,使用 exit 離開 shell,然後重新啟動 client。此檢查只會測試 TCP。DHT (distributed hash table) 與 uTP 流量會在相同的連接埠號碼上使用 UDP,因此不包含在此測試中。
錯誤情況與您會看到的訊息
日誌中完全沒有連接埠行列。 沒有任何項目要求連接埠。使用 docker exec gluetun printenv | grep PORT_FORWARDING 確認變數確實已傳入容器,因為將變數設在錯誤的 compose 服務中是常見原因。
Gluetun 拒絕啟動,並顯示 provider 相關錯誤。 VPN_PORT_FORWARDING_PROVIDER 會與支援的 4 個名稱比對驗證,因此拼寫錯誤會使容器停止,而不是在未轉送的情況下靜默執行。
日誌顯示 no port forwarded。 Gluetun 已提出要求,但 provider 沒有回傳任何內容。對 ProtonVPN 而言,通常表示您產生的設定未啟用 NAT-PMP,或方案不包含連接埠轉送。對 Private Internet Access 而言,通常表示選取的伺服器不提供這項功能。
已取得連接埠,但沒有任何連線進入。 使用上方的 2 個命令,比對轉送連接埠與客戶端的監聽連接埠。如果兩者相同,請確認客戶端已繫結至 tunnel 介面,且已關閉 random-port 選項,因為該選項會在每次啟動時改寫監聽連接埠。
up 命令似乎沒有作用。 在容器內執行確切命令以查看錯誤:docker exec gluetun /bin/sh -c '<your command>'。通常會得到 curl: not found,因為此映像檔只附帶 wget。
控制伺服器傳回 401 Unauthorized。 沒有任何角色涵蓋您呼叫的路由,或所有相符角色都因缺少或不正確的認證資訊而拒絕請求。已設定的 HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE 會涵蓋檔案中未列出的路由。每條路由都以方法加路徑表示,例如 GET /v1/portforward。單獨寫成 /v1/portforward 的路由不會產生 401;gluetun 會在啟動時直接失敗。
Private Internet Access 每次重新啟動後都使用不同的連接埠。 Bind mount /gluetun,讓已儲存的連接埠狀態在重新啟動後仍能保留。沒有這個 volume 時,gluetun 每次都會要求新的連接埠。
FAQ
為什麼 torrent 可以下載,卻始終沒有輸入連線?
沒有轉送的連接埠時,VPN provider 沒有 NAT 規則可將任何連接埠上的輸入封包轉送到你的 tunnel,因此從出口位址收到、但不是由你發起的連線都會被捨棄。下載仍可運作,因為用戶端會自行建立這些連線,也能連線到任何可接受連線的 peer。做種與加入 swarm 會受到影響,因為兩者都依賴其他人連入你的服務。解決方式是使用提供連接埠轉送的 provider、在 gluetun 中設定 VPN_PORT_FORWARDING=on,並將取得的連接埠套用到用戶端的監聽連接埠。
gluetun 是否支援任何 VPN provider 的連接埠轉送?
不支援。Gluetun v3.41.3 原生整合四個 provider:Private Internet Access、ProtonVPN、Perfect Privacy 與 PrivateVPN。清單以外的 provider 在驗證 VPN_PORT_FORWARDING_PROVIDER 時都會失敗,容器也會在啟動時停止。若你的 provider 透過自有控制面板提供靜態連接埠,gluetun 無法代你提出請求,但 FIREWALL_VPN_INPUT_PORTS 會允許該固定連接埠通過 gluetun 的防火牆。Provider 政策可能變更,因此購買方案前請查看目前的 provider 頁面。
每次重新連線後都必須更新連接埠嗎?
需要,而且應自動更新。轉送的連接埠隸屬於 VPN session,因此容器重新啟動、伺服器變更或租約更新失敗,都可能產生新的號碼;但用戶端仍會保留自己的設定中的舊連接埠。你可以讓 gluetun 透過 VPN_PORT_FORWARDING_UP_COMMAND 推送連接埠;該程序會在連接埠轉送啟用時立即執行。也可以執行小型程序,從 control server 讀取 GET /v1/portforward,再透過用戶端 API 將該值寫入用戶端。
如何確認轉送的連接埠確實已開放?
在 gluetun 的 network namespace 內,於該確切連接埠上執行監聽器,再從 VPN 外部連線到它。先停止 torrent 用戶端,讓連接埠處於可用狀態,然後使用 --listening-address=":<port>" 在 gluetun 容器內執行上游的 port-checker binary。從 curl -s http://127.0.0.1:8000/v1/publicip/ip 取得出口位址;若列出 GET /v1/publicip/ip 的 role 使用 auth = "apikey",請加入 -H "X-API-Key: <key>",再從使用行動數據的手機開啟 http://<address>:<port>。若 port-checker 日誌中出現請求,即可證明輸入的 TCP 流量已抵達。若逾時,表示流量未抵達,不論用戶端自己的狀態圖示顯示什麼。