Docker 容器透過 VPN 路由:連接埠消失怎麼辦
使用 Gluetun sidecar 搭配 network_mode: service:gluetun 時,連接埠與服務名稱會消失。了解共享 network namespace 的原因,以及可正常運作的 Compose 設定。
透過 VPN 路由 Docker 容器時,連接埠為何會消失
若要透過 VPN 路由 Docker 容器,請先讓其中一個容器建立 tunnel,再使用 network_mode: "service:gluetun" 將其他容器連接到它的 network namespace。這個連接方式最容易造成誤解。被連接的容器不再擁有自己的 network,因此原本發佈的連接埠與 Docker service name 也會一併消失。請改在 VPN 容器上發佈連接埠,其他容器則透過 VPN 容器的名稱存取該應用程式。
若在被連接的容器上保留 ports: 區塊,Docker 會拒絕建立該容器:
Error response from daemon: conflicting options: port publishing and the container type network mode此處使用的工具是 Gluetun。這是一個可透過 WireGuard 或 OpenVPN 連線至商業 VPN(virtual private network)供應商,並具備自身 firewall 的容器。截至 October 2026,目前版本為 v3.41.3。範例使用 WireGuard 搭配 Mullvad,因此需要向供應商取得帳戶與 key。若希望在自有硬體上終止 tunnel,可使用 在 VPS 上執行自有的 WireGuard server 建立另一端,再使用 Docker 中的 wg-easy 提供 web interface。
network_mode: "service:gluetun" 的實際作用
每個 Docker 容器通常都有自己的 network namespace,包括自己的網路介面、路由表、防火牆規則與監聽中的 socket。service: 模式會略過這個步驟,改為在 gluetun 的 namespace 中啟動容器。使用同一個 namespace 就代表共用同一個 IP address,這會造成 6 項變化。
- 應用程式沒有自己的 address,而是使用 gluetun 的 address。
- 應用程式不會連接至任何 Docker network,因此不會註冊服務名稱,也無法解析服務名稱。其他容器必須使用
gluetun。 - namespace 內的容器會透過
localhost彼此連線。 - 同一個 namespace 中的 2 個容器無法監聽相同的 port。Gluetun 文件對此說明得很直接:沒有替代解法。
- capabilities 屬於容器,而不是 namespace。Gluetun 會持有
NET_ADMIN與/dev/net/tun,因為它負責建立 tunnel interface。附加的容器不會繼承這些 capabilities。 - 如果某個 service 同時設定
network_mode與networks,Compose 會拒絕該檔案。請將 gluetun 連接至各個 network,應用程式就會一併使用這些 network。
重新啟動 gluetun 會中斷所有附加至它的容器。這是文件記載的行為,也是 gluetun 在連線失敗時,選擇在容器內重新啟動 VPN process,而不是直接結束的原因。若自行重新啟動或重新建立 gluetun,請一併重新啟動附加至它的容器。
可正常運作的 compose 檔案
services:
gluetun:
image: qmcgaw/gluetun:v3
container_name: gluetun
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
- VPN_SERVICE_PROVIDER=mullvad
- VPN_TYPE=wireguard
- SERVER_CITIES=Amsterdam
- TZ=Europe/Amsterdam
env_file:
- ./gluetun.env
volumes:
- ./gluetun:/gluetun
ports:
- 127.0.0.1:8080:8080/tcp
restart: unless-stopped
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest
container_name: qbittorrent
network_mode: "service:gluetun"
environment:
- PUID=1000
- PGID=1000
- TZ=Europe/Amsterdam
- WEBUI_PORT=8080
volumes:
- ./qbittorrent:/config
- ./downloads:/downloads
depends_on:
gluetun:
condition: service_healthy
restart: unless-stopped:v3 標籤是 v3 系列最新的穩定版本。:latest 標籤指向 master 分支的最後一次 commit,也就是開發中的 edge 版本。因此,若不想在週二進行除錯,請在該機器上固定使用 :v3。
WEBUI_PORT=8080 必須與已發布的連接埠一致,因為 qBittorrent 會在 gluetun 的 namespace 內繫結,而 publish 規則會將主機流量轉送到其中的 8080 連接埠。兩者只要有一個數字不同,該連接埠就不會回應。127.0.0.1:8080:8080 會讓 Web 介面只監聽主機的 loopback 位址。單獨使用 8080:8080 會在所有介面上發布連接埠,並自行寫入防火牆規則,這正是 Docker 發布的連接埠直接繞過 ufw 的原因。
啟動服務,然後依照以下順序檢查:
docker compose up -d
docker compose ps
docker compose logs gluetun | tail -30docker compose ps 應顯示 gluetun 為 healthy,qbittorrent 為 running。接著從該 namespace 內確認出口位址;這項檢查會決定其餘所有結果:
docker run --rm --network=container:gluetun alpine:3.22 sh -c "apk add wget && wget -qO- https://ipinfo.io"該 JSON 中的 ip 欄位應為 VPN provider 的位址。若顯示的是伺服器本身的位址,表示應用程式未位於 tunnel 內,後續行為都不會如本文所述。
避免將金鑰放入 compose 檔案
gluetun.env 儲存認證資訊,且不會納入 git:
WIREGUARD_PRIVATE_KEY=wOEI9rqqbDwnN8/Bpp22sVz48T71vJ4fYmFWujulwUU=
WIREGUARD_ADDRESSES=10.64.222.21/32這兩個值都來自您在供應商帳戶區域產生的 WireGuard 設定檔。將檔案權限設為 600。請正確認識這項做法的效果:金鑰不會出現在您的儲存庫中,但任何能連線至 Docker socket 的人,仍可透過 docker inspect gluetun 列印所有環境變數。Docker Compose 中的環境檔案與 secret 說明更強的選項。
隧道外部的容器如何與隧道內部的容器通訊
兩個方向都可運作,但各自使用不同的名稱。兩個容器需要共用 Docker network,也就是 gluetun 的 network,因為附加的容器本身沒有獨立的 network。Docker Compose network 的連接方式說明了預設設定。
從外部連入內部時,使用 gluetun 的名稱,以及應用程式監聽的連接埠。反向代理容器可透過 gluetun:8080 存取 qBittorrent Web 介面。這不需要 ports: 設定,因為容器之間的流量會留在 Docker network 上,不會經過主機連接埠。
從內部連到外部時,使用另一個容器的服務名稱,例如 postgres:5432。自 v3.41 起,Gluetun 可在自己的 namespace 內解析其他容器的名稱。因此,如果名稱無法解析,請固定使用該版本或更新版本。
Gluetun 的防火牆會決定哪些來源可以向它建立連線。來自 gluetun 自有 Docker network 的流量會獲准通過。若用戶端位於不同的子網路,例如 LAN 上的筆電或獨立 bridge network 上的容器,則必須讓 gluetun 的防火牆與路由允許回程路徑:
FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24文件中的定義很明確:這是以逗號分隔的子網路,Gluetun 及共用其 network stack 的容器可存取這些子網路。
來自網際網路的入站連線是另一個問題。torrent client 的對等端會從 VPN 端連入,因此在主機上發布 6881 連接埠對這些連線沒有作用。你需要由服務供應商提供的轉送連接埠,並將該連接埠列在 FIREWALL_VPN_INPUT_PORTS 中,這會允許來自 VPN server 端的連接埠。此範例使用的 Mullvad 不支援 port forwarding,因此必須改用支援此功能的服務供應商。這是許多以 Docker Compose 建置的 媒體服務堆疊最常遺漏的部分。
Tunnel 斷線時的 kill switch:會發生什麼事
這種架構的複雜度在故障時才真正發揮作用。附加的容器會共用 Gluetun 的介面與路由表。Gluetun 的防火牆會封鎖 tunnel 外的一般網際網路流量,但允許連往 VPN 伺服器端點的流量、本機 Docker 流量,以及已設定的例外。正是這道防火牆,防止 tunnel 斷線時回退到一般介面。用戶端重新連線期間,不會出現封包從一般介面洩漏的時間窗口。
Gluetun 會監控自身的連線。每分鐘,它會對 HEALTH_ICMP_TARGET_IPS 中的位址傳送 ICMP echo(ping);預設值為 1.1.1.1,8.8.8.8。如果不允許 ICMP,這項小型檢查會改用明文 UDP DNS 查詢。每五分鐘,它會對 HEALTH_TARGET_ADDRESSES 建立完整的 TCP 與 TLS(傳輸層安全性)連線;預設值為 cloudflare.com:443,github.com:443。這些檢查失敗時,它會在容器內重新啟動 VPN,並記錄下列訊息:
WARN [vpn] restarting VPN because it failed to pass the healthcheck: periodic check: dialing: dial tcp4: lookup cloudflare.com: i/o timeout請依照這個順序閱讀附加容器的日誌。應用程式內出現的 connection refused、operation not permitted 與 i/o timeout 等行,是 tunnel 中斷的結果,不是原因。Gluetun 文件也明確說明這點,因為使用者常回報這些結果,並花上數小時追查錯誤方向。
HEALTH_RESTART_VPN=on 是預設值,應保持啟用。只有在偵錯特定故障時才暫時關閉,因為關閉後,已中斷的 tunnel 會持續維持中斷狀態。
排序:在 tunnel 就緒前避免啟動 stack
此 image 內建 Docker healthcheck:
HEALTHCHECK --interval=5s --timeout=5s --start-period=10s --retries=3 CMD /gluetun-entrypoint healthcheck該命令會啟動另一個執行時間很短的 gluetun 副本,並查詢執行中 gluetun 在 http://127.0.0.1:9999/ 提供的 health server。tunnel 正常時會回應 200 OK。tunnel 故障時會回應 500 Internal server error 並附上錯誤字串;連續 3 次檢查失敗後,Docker 會將 container 標記為 unhealthy。
condition: service_healthy 會等待這個條件。單純使用 depends_on: [gluetun] 只會等待 container 啟動。container 通常會在 handshake 完成前數秒啟動,因此應用程式可能會在網路尚未連通時啟動,並經常在第一次連線嘗試時直接放棄。Docker Compose 中的 healthcheck 說明語法與計時欄位。
有一項限制容易被忽略。Compose 只會在啟動 stack 時評估這個條件。如果 gluetun 之後變成 unhealthy,Compose 不會停止或重新啟動應用程式。這種情況由 gluetun 的內部自動修復機制處理。因此它會重新啟動 VPN process,而不是重新啟動 container。
確認 DNS 是否洩漏,再信任此設定
DNS(domain name system)是即使通道設定正確仍可能洩漏的項目。Gluetun 會在 namespace 內執行自己的 resolver,並預設透過 DoT(DNS over TLS)將查詢轉送至 Cloudflare:DNS_UPSTREAM_RESOLVER_TYPE=dot 和 DNS_UPSTREAM_RESOLVERS=cloudflare。保留這兩項設定,查詢就會加密,並經由通道傳送。
將本機 resolver 指定為解析器時,會破壞這項設定的選項是 DNS_UPSTREAM_PLAIN_ADDRESSES。當名稱無法解析時,有些人會啟用這項設定,改由路由器或網際網路服務提供者的 resolver 回應。Gluetun 文件警告,傳送至 Docker bridge 或 LAN 上 resolver 的查詢,會洩漏到 VPN 通道之外。公開的明文 resolver 仍會透過通道接收查詢,但 VPN 提供者可以讀取並修改這些查詢。WireGuard 中相同的錯誤,請參閱 WireGuard 通道上的 DNS 停止解析。
若要測試,請在 gluetun 上設定 SHADOWSOCKS=on 和 SHADOWSOCKS_PASSWORD,發布 8388:8388/tcp 和 8388:8388/udp,然後使用設定為透過通道傳送 UDP DNS 的 Shadowsocks client 連線,並載入 DNS leak test。結果應顯示您的提供者或 Cloudflare,不能顯示家用路由器。Gluetun 自己的文件警告,部分 leak test 可能會回報異常結果,因為 namespace 內的 resolver 是本機快取中介,而不是最後提供回應的伺服器。請將顯示錯誤國家或您自己的 ISP resolver 視為真正的洩漏訊號。
在 VPN sidecar 旁加入 Tailscale,以及哪一個會優先
Tailscale 是建構在 WireGuard 上的 overlay network,用來連線到自己的機器。許多人會讓它與 provider VPN 並行,以保留進入整個服務堆疊的管理路徑。共用 namespace 也代表共用防火牆規則,因此兩者必須使用相容的防火牆與路由設定。Tailscale 文件說明其預設行為:它會作為 overlay network,只在執行 Tailscale 的裝置之間路由流量,不會處理公共網際網路流量。
因此,答案取決於一項設定。
- Tailscale 使用自己的容器與預設設定:它完全看不到應用程式的對外流量。所有流量都由 Gluetun 傳送。Tailscale 容器中的程序可透過共用 Docker network,在
gluetun:8080存取應用程式;若要讓 tailnet 用戶端存取該連線,必須設定轉送或 proxy。 - Tailscale 使用
network_mode: "service:gluetun"連接至 gluetun 的 namespace:在預設的 userspace networking 模式中,TS_USERSPACE已啟用。tailscaled 完全不建立介面,而是作為 SOCKS5 或 HTTP proxy 運作,因此無法變更路由。除非應用程式明確使用該 proxy,否則一般對外流量仍由 Gluetun 傳送。 - 使用相同設定,但指定
TS_USERSPACE=false:Tailscale 需要自己的/dev/net/tun裝置與 capabilities,因為 namespace 不會提供這些項目。tailscaled 會建立 tunnel device;在 Linux 上,通常會為各個 IPv4 peer 安裝個別的 /32 路由,而不是為100.64.0.0/10安裝單一路由。單獨設定TS_USERSPACE=false不會啟用 aggregate route。只有透過TS_EXTRA_ARGS傳入--accept-routes時,才會安裝其他節點的 subnet routes。TS_ROUTES的方向相反:它會將此容器可存取的子網路通告給 tailnet 其他成員,相當於tailscale set --advertise-routes=,但不會在此處新增路由。公共流量仍會經由 gluetun 離開。 - 在 gluetun 的 namespace 中使用 kernel networking,並選取 exit node,
sudo tailscale set --exit-node=<exit-node-ip>:Tailscale 會在該 namespace 中安裝 default routes,但 Gluetun 的防火牆可能會封鎖這條路徑。在獨立容器中選取 exit node 不會變更應用程式的路由,而 userspace 模式只會傳送明確交給其 proxy 的流量。不要在 gluetun 的 namespace 中同時設定互相競爭的 default routes。一條 default route,只能有一個管理者。
如果重點是這些通告的路由,而且你希望能存取整個位於該主機後方的私有網路,而不只是該主機本身,請參閱 在 VPS 上執行 Tailscale subnet router。其中涵蓋路由核准、IP forwarding,以及 TS_ROUTES 單獨不會完成的用戶端 flag 設定。
如果使用 Tailscale 的目的是提供管理 URL,而不是路由,tailscale serve 與 tailscale funnel 可在本機 HTTP 服務前方加入 HTTPS;只有 funnel 會將其開放至公共網際網路。Tailscale Serve 的文件只支援將 http://127.0.0.1 作為 HTTP proxy 目標。共用 Docker network 不會讓 http://gluetun:8080 成為受支援的目標。請讓 network_mode: "service:gluetun" 共用 gluetun 的 network namespace,並將目標設為 http://127.0.0.1:8080。
Tailscale 在 tunnel 內執行時,會出現一項可觀察到的副作用。其 peer 看到的是 VPN provider 的位址,因此更常退回使用 relay。發生這種情況時,tailscale status 會在 peer 旁顯示 relay "...",而不是 direct。連線仍可運作,但速度較慢。如果你實際需要的只有 overlay,請先閱讀純 WireGuard 與 Tailscale 的差異。
會失效的項目與您會看到的訊息
Docker 拒絕建立 app 容器。 Error response from daemon: conflicting options: port publishing and the container type network mode 表示連接的服務上仍存在 ports: 區塊。請將它移至 gluetun。
Compose 拒絕整個檔案。 服務不能同時設定 network_mode 和 networks。請將網路設定放在 gluetun 上。
其他容器無法解析 app。 curl: (6) Could not resolve host: qbittorrent 屬於正常行為,因為連接的容器未加入任何網路,也未註冊名稱。請使用 gluetun 和連接埠。
第二個連接的容器無法啟動。 同一個 namespace 中的兩個程序不能繫結相同的連接埠。後啟動的程序會回報位址已在使用中。請變更 app 的內部連接埠,或再執行一個 gluetun。
變更 gluetun 後,app 沒有網路。 重新啟動或重新建立 gluetun 會中斷所有連接至它的容器。請重新啟動這些容器。
小型頁面可以載入,大型頁面則停滯。 這是 MTU(maximum transmission unit)問題。通道會增加額外負荷,而路徑中的某個元件會丟棄過大的封包,卻不會回傳錯誤。請檢查 WIREGUARD_MTU。v3.41.3 的預設值為 1320;若路徑需要較小的封包,請降低此值。開發映像在未設定此值時,會使用 path MTU discovery。
Gluetun 始終無法達到 healthy 狀態。 啟動檢查會指出最先應檢查的項目:WARN [vpn] restarting VPN because it failed to pass the healthcheck: startup check: dialing: dial tcp4: lookup cloudflare.com: i/o timeout。請先確認 key 尚未過期,再確認伺服器清單沒有過時,最後確認主機防火牆未封鎖輸出的 UDP。
FAQ
為什麼我的容器透過 Gluetun 發布的連接埠停止運作?
因為 network_mode: "service:gluetun" 會將容器放入 gluetun 的 network namespace,而一個 namespace 只有一個 IP 位址和一組監聽中的連接埠。應用程式仍會持續監聽,但發布規則必須設定在擁有該 namespace 的容器上。將 ports: 清單移至 gluetun 服務。如果仍將它設定在附加的服務上,Docker 甚至不會建立該規則:Error response from daemon: conflicting options: port publishing and the container type network mode。
如何從 VPN tunnel 外部的容器連線到 VPN tunnel 內部的容器?
使用 gluetun 的服務名稱,以及應用程式監聽的連接埠,例如 gluetun:8080。附加的容器不屬於任何 Docker network,因此無法解析自己的名稱。容器之間的流量不需要設定發布規則。反過來,在 Gluetun v3.41 或更新版本中,namespace 內的容器可透過外部容器的服務名稱連線,例如 postgres:5432。位於不同子網路的用戶端,例如 LAN 上的筆記型電腦,則需要由 gluetun 的防火牆與路由允許回程路徑;將該子網路加入 FIREWALL_OUTBOUND_SUBNETS。
VPN 中斷時,Gluetun 是否能作為 kill switch?
可以,但必須啟用其防火牆。附加的容器會共用 Gluetun 的介面與路由。防火牆會阻擋 tunnel 外的一般網際網路流量,同時允許 VPN 伺服器 endpoint、本機 Docker 流量及已設定的例外。接著 Gluetun 會在內部重新啟動 VPN,並記錄 WARN [vpn] restarting VPN because it failed to pass the healthcheck,而不是結束程序,因為 gluetun 本身重新啟動時,所有附加的容器都會失去網路連線。
在同一個 stack 中使用 Tailscale 和 Gluetun:哪一個會承載對外流量?
除非明確透過 Tailscale 傳送,否則一般對外流量會由 Gluetun 承載。Tailscale 預設只會在 tailnet 中的裝置之間路由流量,不會處理公開網路流量。在容器映像的預設 userspace mode 中,Tailscale 根本不會建立介面,因此無法影響路由。使用 TS_USERSPACE=false 時,Linux 通常會為各個 IPv4 peer 建立個別的 /32 路由,而不是彙總的 100.64.0.0/10 路由;只有透過 --accept-routes 和 TS_EXTRA_ARGS 加入後,才會包含其他節點的子網路路由。TS_ROUTES 會將此容器的子網路通告給 tailnet,但不會加入本機路由。使用 sudo tailscale set --exit-node=<exit-node-ip> 選取 exit node 時,只有採用 Tailscale kernel networking 的 namespace 會安裝預設路由;獨立的容器不會改變應用程式的路由,而 userspace mode 只會承載經其 proxy 傳送的流量。請選擇一個產品管理預設路由,不要同時疊加兩者。