Cara Setup Gluetun Port Forwarding Untuk Torrent

Mengapa tiada sambungan masuk tanpa port yang diforward

Gluetun port forwarding meminta penyedia VPN anda untuk memetakan satu port awam pada alamat keluar mereka kembali ke kontena anda, yang merupakan satu-satunya cara rakan setara (peer) lain boleh memulakan sambungan ke klien torrent anda. Tanpa pemetaan tersebut, terowong berada dalam keadaan sihat, muat turun berjalan, namun tiada apa-apa yang sampai secara sendiri. Setiap sambungan yang berfungsi adalah sambungan yang dibuka oleh klien anda terlebih dahulu.

Mekanismenya ialah NAT (network address translation). Kontena anda berkongsi alamat keluar penyedia dengan ramai pelanggan lain. Apabila klien anda membuka sambungan ke luar, penyedia merekodkan aliran tersebut dan menghantar balasan kembali ke bawah terowong anda. Sambungan masuk daripada rakan setara yang tidak dikenali tidak sepadan dengan mana-mana aliran yang direkodkan, jadi paket tersebut sampai ke alamat keluar dan digugurkan di situ. Klien anda masih boleh mencapai setiap rakan setara yang boleh disambungkan, jadi muat turun selesai dan masalah tersebut kekal tidak kelihatan. Masalah ini ketara semasa proses seeding, kerana seeder ialah mesin yang disambungkan oleh orang lain.

Port masuk yang terbuka mengubah dua perkara. Anda menyertai swarm dengan lebih pantas, kerana rakan setara yang tidak dapat menerima sambungan sendiri kini boleh mencapai anda, dan anda boleh memuat naik kepada rakan setara tersebut.

Mengapa kebanyakan penyedia VPN tidak menawarkan port yang diforward

Port yang diforward merupakan sumber terhad pada alamat IP kongsi. Penyedia menempah satu nombor port pada satu IP keluar untuk seorang pelanggan, dan kemudian bertanggungjawab atas apa jua tindakan pelanggan tersebut dengan port itu. Beberapa penyedia besar telah membuang ciri ini dan menyatakan pengendalian penyalahgunaan sebagai puncanya. Anggap sokongan sebagai soalan kategori dan bukannya kotak semak: tanya sama ada penyedia menawarkan port forwarding pada hari ini, pada pelan anda, dan pada pelayan yang boleh anda pilih.

Di mana forwarding wujud, port tersebut bersifat dinamik. Ia kepunyaan sesi VPN dan bukannya akaun anda, jadi nombornya boleh berubah selepas setiap kali penyambungan semula. Private Internet Access mengeluarkan port bertandatangan yang disegarkan oleh gluetun, dan dokumentasi huluan menyatakan anda mengekalkan port yang sama selama 60 hari selagi anda melakukan bind mount pada direktori /gluetun supaya status tersebut kekal selepas but semula. ProtonVPN memberikan port rawak melalui NAT-PMP (NAT port mapping protocol) dengan tempoh sewaan singkat yang perlu diperbaharui secara berterusan. Inilah sebabnya menetapkan port sekali dalam klien tidak akan berfungsi untuk jangka masa panjang.

Penyedia yang boleh diminta port oleh gluetun

Sehingga gluetun v3.41.3, yang dikeluarkan pada 30 Julai 2026, integrasi natif mengesahkan empat nama penyedia: Private Internet Access, ProtonVPN, Perfect Privacy dan PrivateVPN. Aktifkannya dengan VPN_PORT_FORWARDING=on, yang ditetapkan sebagai off secara lalai. Panduan lama menggunakan PORT_FORWARDING atau PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING. Kedua-duanya masih berfungsi dalam versi ini sebagai nama yang serasi dengan versi terdahulu, namun kedua-duanya akan dihentikan penggunaannya.

Dua perincian penyedia menentukan sama ada permintaan tersebut boleh berjaya atau tidak. ProtonVPN memerlukan pelan berbayar, dan NAT-PMP perlu dihidupkan: aktifkan NAT-PMP (Port Forwarding) di bawah pilihan VPN semasa anda menjana konfigurasi WireGuard, atau tambah +pmp pada nama pengguna anda apabila anda menggunakan OpenVPN. Private Internet Access pada OpenVPN mempunyai PORT_FORWARD_ONLY, yang mengehadkan pemilihan pelayan kepada pelayan yang menyokong penghantaran port, supaya anda tidak memilih pelayan yang tidak pernah menyokongnya. WireGuard dan OpenVPN berbeza dari segi cara port diminta, jadi baca halaman penyedia anda sebelum anda membuat pilihan.

Apabila gluetun menjalankan konfigurasi tersuai dan bukannya penyedia terbina dalam, VPN_PORT_FORWARDING_PROVIDER menamakan API yang perlu dipanggil oleh gluetun. Halaman Private Internet Access huluan menggandingkan pemboleh ubah tersebut dengan VPN_PORT_FORWARDING_USERNAME dan VPN_PORT_FORWARDING_PASSWORD, yang membawa kelayakan akaun yang diperlukan oleh permintaan port tersebut.

Hidupkan port forwarding gluetun dalam docker compose

Bahagian ini mengandaikan terowong sudah berfungsi. Jika belum, mulakan dengan menghalakan trafik kontena Docker melalui gluetun dan kembali semula setelah muat turun berjalan.

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

Tetapkan tag imej. qmcgaw/gluetun:latest mengikut cawangan master, di mana bahagian dalaman port forwarding sedang berubah untuk v4, jadi imej yang tidak ditetapkan tag boleh mengubah kelakuan pada docker compose pull seterusnya. Simpan kunci peribadi di luar fail compose dengan fail env untuk rahsia compose.

Lokasi gluetun menulis port yang diforward

Gluetun mendedahkan port tersebut di tiga lokasi, dan kesemuanya membawa nilai yang sama.

Ia merekodkan port tersebut sekali bagi setiap pemerolehan. Baris tersebut berbunyi port forwarded is 45678, dan no port forwarded apabila permintaan tidak menghasilkan apa-apa.

docker logs gluetun 2>&1 | grep -i "port forwarded"

Ia menulis nombor tersebut ke dalam fail yang dinamakan oleh VPN_PORT_FORWARDING_STATUS_FILE, yang secara lalai ditetapkan kepada /tmp/gluetun/forwarded_port. Fail tersebut menyimpan satu port bagi setiap baris, ditulis dengan mod 0644, dan hak milik ditukar kepada PUID dan PGID bekas tersebut. Apabila proses forwarding berhenti, gluetun mengosongkan fail tersebut dan bukannya memadamnya, supaya pengguna boleh membaca fail kosong daripada menghadapi ralat fail tiada.

docker exec gluetun cat /tmp/gluetun/forwarded_port

Ia menyediakan nilai tersebut pada pelayan kawalan, yang mendengar pada :8000 secara lalai dan ditetapkan oleh HTTP_CONTROL_SERVER_ADDRESS.

curl -s http://127.0.0.1:8000/v1/portforward

{"port":45678,"ports":[45678]}

Gluetun juga membuka port tersebut dalam firewallnya sendiri pada antaramuka VPN, jadi FIREWALL_VPN_INPUT_PORTS tidak diperlukan sementara integrasi natif melakukan kerja tersebut. Pemboleh ubah itu meliputi kes lain: pembekal yang tidak boleh disoal oleh gluetun, di mana anda diberikan port statik di luar jalur (out of band) dan perlu membenarkannya secara manual.

Salah satu daripada tiga lokasi ini adalah kekal manakala dua lagi tidak. Dokumentasi huluan menandakan fail status sebagai usang dalam v4.0.0, dan GET /v1/openvpn/portforwarded sudah pun menjawab dengan 301 Moved Permanently yang menghala ke /v1/portforward. Pembangunan baharu harus membaca pelayan kawalan.

Mengapa klien perlu dimaklumkan tentang port pada setiap sambungan semula

Klien torrent menyimpan port pendengar (listening port) dalam konfigurasinya sendiri dan mengekalkan nombor tersebut selepas but semula. Port yang diforwardkan adalah sifat bagi sesi VPN. Selepas penyambungan semula, kedua-dua nombor tersebut tidak sepadan, menyebabkan penyedia memetakan port yang tidak mendengar sebarang trafik, manakala klien pula mendengar pada port yang tidak dipetakan. Penyambungan semula bukanlah perkara luar biasa: ia boleh berlaku akibat but semula kontena, pertukaran pelayan, terputusnya tunnel yang dimulakan semula oleh pemeriksaan kesihatan gluetun, atau pajakan (lease) yang gagal diperbaharui. Hasilnya ialah persediaan yang boleh dicapai semalam tetapi tidak lagi boleh dicapai hari ini secara senyap, tanpa sebarang ralat dalam mana-mana log.

Oleh itu, port tersebut perlu digunakan pada saat gluetun memperolehnya. Terdapat dua cara untuk menyambungkannya, dan perbezaannya terletak pada proses mana yang melakukan kerja tersebut.

Pilihan 1: gluetun menolak port dengan arahan up

VPN_PORT_FORWARDING_UP_COMMAND berjalan apabila port forwarding diaktifkan, dan VPN_PORT_FORWARDING_DOWN_COMMAND berjalan apabila ia dinyahaktifkan. Gluetun menggantikan {{PORT}} (port pertama), {{PORTS}} (semua port, dipisahkan dengan koma) dan {{VPN_INTERFACE}} (nama antara muka tunnel, tun0 secara lalai) sebelum menjalankan arahan tersebut. Sintaks shell memerlukan pembalut /bin/sh -c yang eksplisit. Ini adalah contoh qBittorrent huluan, yang ditulis sebagai dua entri persekitaran 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'

Setiap medan dalam panggilan tersebut mempunyai tugas. listen_port ialah port baharu. current_network_interface mengikat qBittorrent kepada tunnel. random_port yang ditetapkan kepada false menghalang qBittorrent daripada memilih portnya sendiri pada permulaan seterusnya. upnp yang ditetapkan kepada false menghalangnya daripada cuba memetakan port melalui penghala yang tidak wujud.

Dua keperluan disertakan dengan pendekatan ini. UI web qBittorrent mesti menjawab pada 127.0.0.1:8080 dari dalam container gluetun, yang berlaku secara automatik apabila klien berkongsi ruang nama rangkaian gluetun. Dan Bypass authentication for clients on localhost (bypass_local_auth) mesti didayakan, kerana arahan tersebut tidak menghantar sebarang kelayakan. Arahan down disertakan kerana qBittorrent tidak sentiasa menetapkan semula port selepas terputus sambungan.

Arahan tersebut berjalan di dalam container gluetun, yang dibina di atas Alpine dan menyertakan wget. Tiada curl dalam imej tersebut. Arahan yang menamakan binari yang tidak dimiliki oleh imej akan gagal setiap kali forwarding diaktifkan.

Opsyen 2: proses di luar gluetun membaca port

Corak lain menjalankan proses kecil di samping gluetun yang mengambil port dan menolaknya ke dalam klien melalui API klien itu sendiri. Baca port tersebut daripada pelayan kawalan:

port=$(curl -s http://127.0.0.1:8000/v1/portforward | jq -r .port)

Atau baca fail tersebut, jika proses boleh melihatnya. /tmp/gluetun/forwarded_port berada di dalam kontena gluetun, jadi sidecar memerlukan volum kongsi yang dipasang pada /tmp/gluetun dalam kedua-dua kontena, atau anda menghalakan VPN_PORT_FORWARDING_STATUS_FILE ke laluan di bawah volum yang telah anda pasang.

Pengesahan adalah penting di sini. Dalam v3.41.3, laluan GET /v1/portforward tergolong dalam peranan lalai bernama public dengan auth = "none", jadi ia menjawab tanpa kelayakan, dan gluetun mencatatkan amaran yang bermula dengan route GET /v1/portforward is unprotected by default, please set up authentication. Pihak hulu akan menutup akses tersebut dalam keluaran akan datang. Tentukan peranan sekarang, dalam fail yang dipasang pada /gluetun/auth/config.toml:

roles = [
  { name = "qbittorrent", routes = ["GET /v1/portforward"], auth = "apikey", apikey = "myapikey" }
]

Jana kunci dengan docker run --rm qmcgaw/gluetun:v3.41.3 genkey dan hantarkannya dalam pengepala X-API-Key. HTTP_CONTROL_SERVER_AUTH_DEFAULT_ROLE melakukan tugas yang sama seperti satu pemboleh ubah persekitaran berkod JSON apabila anda tidak mahu memasang fail. Port 8000 yang diterbitkan tanpa peranan memberikan sesiapa sahaja yang boleh mencapainya kawalan ke atas status VPN, jadi tentukan dengan teliti sejauh mana ia boleh diakses apabila anda merancang cara mencapai gluetun daripada hos dan kontena lain.

Pilih arahan up apabila klien mendedahkan API yang boleh dipacu oleh satu panggilan wget, kerana ia hanya berjalan sekali bagi setiap peristiwa dan tidak memerlukan proses tambahan untuk terus berjalan. Pilih proses luaran apabila klien memerlukan aliran log masuk, penulisan semula fail konfigurasi, atau but semula. Dalam timbunan arr di belakang satu kontena gluetun, ini biasanya berakhir sebagai satu poller kecil, memandangkan hanya klien torrent yang memerlukan port tersebut.

Perangkap: berkongsi namespace tidak menetapkan port pendengar

Kegagalan ini paling banyak membuang masa. network_mode: "service:gluetun" meletakkan klien dalam network namespace milik gluetun, jadi ia mempunyai alamat VPN, laluan tunnel dan peraturan firewall gluetun. Tiada satu pun daripada perkara tersebut menetapkan port pendengar klien. Gluetun membuka port yang diforward pada antara muka VPN, paket untuk port tersebut tiba dalam namespace, dan jika klien mendengar pada port yang berbeza, kernel tidak mempunyai destinasi untuk menghantarnya. Sambungan ditolak atau tamat tempoh walaupun setiap semakan keluar kelihatan sihat. Port yang diforward dan port pendengar klien adalah dua nombor yang berasingan, dan memastikan kedua-duanya sama adalah tugas utama.

Bandingkan kedua-duanya daripada meneka. Kedua-dua arahan dijalankan terhadap namespace yang sama:

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]*'

Satu lagi tetapan menghalakan pengguna ke arah yang salah. VPN_PORT_FORWARDING_LISTENING_PORT mengubah hala trafik masuk daripada port yang diforward ke port tempatan tetap menggunakan iptables. Pihak upstream menasihatkan supaya tidak menggunakannya dengan klien torrent, kerana klien mengumumkan port pendengarnya sendiri kepada tracker dan peer, jadi swarm mempelajari nombor yang salah.

Cara membuktikan port yang diforward boleh dicapai

Penunjuk sambungan klien sendiri hanya memaparkan sambungan tracker keluar, jadi ia mungkin kelihatan hijau walaupun tiada apa-apa yang boleh mencapai anda. Uji dengan listener yang anda kawal, daripada rangkaian di luar tunnel. Pihak upstream menerbitkan alat kecil untuk tujuan ini. Hentikan klien torrent terlebih dahulu, kerana dua proses tidak boleh melakukan bind pada port yang sama.

docker stop qbittorrent
docker exec -it gluetun /bin/sh

Di dalam container, tukar amd64 kepada seni bina CPU anda dan 4567 kepada port yang anda forward:

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"

Sekarang, cari alamat keluar yang digunakan oleh gluetun. Respons tersebut adalah dalam format JSON dan alamatnya berada dalam medan public_ip.

curl -s http://127.0.0.1:8000/v1/publicip/ip

Buka http://<that address>:4567 daripada peranti yang tidak berada pada VPN yang sama. Telefon yang menggunakan data mudah alih boleh digunakan. Halaman yang memaparkan alamat IP dan user agent pelayar anda, dengan permintaan yang sepadan direkodkan oleh port-checker, bermakna TCP masuk mencapai namespace tersebut. Timeout bermakna ia tidak sampai, dan puncanya berada di atas klien. Hentikan alat tersebut dengan CTRL+C, keluar dari shell dengan exit, dan mulakan semula klien. Ujian ini hanya menguji TCP. Trafik DHT (distributed hash table) dan uTP menggunakan UDP pada nombor port yang sama, yang tidak diliputi oleh ujian ini.

Mod kegagalan dan rentetan yang akan anda lihat

Tiada baris port langsung dalam log. Tiada permintaan untuk port. Sahkan pemboleh ubah tersebut benar-benar sampai ke kontena dengan docker exec gluetun printenv | grep PORT_FORWARDING, kerana pemboleh ubah yang ditetapkan dalam servis compose yang salah adalah punca biasa.

Gluetun enggan bermula dan merungut tentang penyedia. VPN_PORT_FORWARDING_PROVIDER disahkan terhadap empat nama yang disokong, jadi kesilapan taip akan menghentikan kontena dan bukannya berjalan secara senyap tanpa pemajuan (forwarding).

Log menyatakan no port forwarded. Gluetun meminta tetapi penyedia tidak memberikan sebarang maklum balas. Pada ProtonVPN, ini biasanya bermakna NAT-PMP tidak didayakan pada konfigurasi yang anda jana, atau pelan anda tidak menyertakan pemajuan port. Pada Private Internet Access, ini biasanya bermakna pelayan yang dipilih tidak menawarkannya.

Port diterima, tetapi tiada sambungan masuk. Bandingkan port yang dimajukan dengan port mendengar (listening port) klien menggunakan dua arahan di atas. Jika ia sepadan, semak sama ada klien terikat pada antara muka tunnel dan pilihan random-port dimatikan, kerana pilihan itu menulis semula port mendengar pada setiap permulaan.

Arahan up seolah-olah tidak melakukan apa-apa. Jalankan arahan tepat di dalam kontena untuk melihat ralatnya: docker exec gluetun /bin/sh -c '<your command>'. curl: not found adalah hasil biasa, kerana imej tersebut hanya membekalkan wget.

401 Unauthorized daripada pelayan kawalan. Anda mentakrifkan konfigurasi auth dan peranan (role) tidak menyenaraikan laluan yang anda panggil. Laluan dipadankan sebagai kaedah ditambah laluan, jadi peranan yang menyenaraikan /v1/portforward sahaja tidak meliputi GET /v1/portforward.

Port berbeza pada Private Internet Access selepas setiap but semula. Lakukan bind mount pada /gluetun supaya status port yang disimpan kekal selepas but semula. Tanpa volum tersebut, gluetun akan meminta port baharu setiap kali.

FAQ

Mengapa torrent saya boleh dimuat turun tetapi tidak menerima sambungan masuk?

Tanpa port yang diforward, penyedia VPN tidak mempunyai peraturan NAT untuk menghantar paket masuk pada mana-mana port ke terowong anda, jadi sambungan yang tidak dimulakan oleh anda akan digugurkan di alamat keluar. Muat turun masih berfungsi kerana klien anda membuka sambungan tersebut sendiri, dan ia boleh mencapai mana-mana peer yang boleh disambungkan. Proses seeding dan penyertaan dalam swarm akan terjejas kerana kedua-duanya bergantung kepada orang lain untuk mencapai anda. Penyelesaiannya adalah dengan menggunakan penyedia yang menawarkan port forwarding, VPN_PORT_FORWARDING=on dalam gluetun, dan port yang terhasil digunakan pada port pendengaran klien.

Adakah gluetun berfungsi dengan port forwarding mana-mana penyedia VPN?

Tidak. Gluetun v3.41.3 mempunyai integrasi natif untuk empat penyedia: Private Internet Access, ProtonVPN, Perfect Privacy dan PrivateVPN. Mana-mana penyedia di luar senarai tersebut akan gagal dalam pengesahan untuk VPN_PORT_FORWARDING_PROVIDER, dan kontena akan berhenti semasa permulaan. Jika penyedia anda mengeluarkan port statik melalui panel kawalan mereka sendiri, gluetun tidak boleh memintanya untuk anda, tetapi FIREWALL_VPN_INPUT_PORTS akan membenarkan port tetap tersebut melalui firewall gluetun. Polisi penyedia sering berubah, jadi semak halaman penyedia semasa sebelum anda membeli pelan untuk tujuan ini.

Adakah saya perlu mengemas kini port selepas setiap kali menyambung semula?

Ya, dan kemas kini tersebut sepatutnya berlaku secara automatik. Port yang diforward adalah milik sesi VPN, jadi memulakan semula kontena, menukar pelayan atau kegagalan pembaharuan pajakan boleh menghasilkan nombor baharu, manakala klien masih menyimpan port tersebut dalam konfigurasinya sendiri. Sama ada biarkan gluetun menolaknya dengan VPN_PORT_FORWARDING_UP_COMMAND, yang berjalan sebaik sahaja forwarding aktif, atau jalankan proses kecil yang membaca GET /v1/portforward daripada pelayan kawalan dan menulis nilai tersebut ke dalam klien melalui API-nya.

Bagaimanakah cara untuk menyemak sama ada port yang diforward benar-benar terbuka?

Jalankan pendengar (listener) pada port tersebut di dalam ruang nama rangkaian gluetun dan sambung kepadanya dari luar VPN. Hentikan klien torrent terlebih dahulu supaya port tersebut bebas, kemudian jalankan binari pemeriksa port huluan di dalam kontena gluetun dengan --listening-address=":<port>". Dapatkan alamat keluar daripada curl -s http://127.0.0.1:8000/v1/publicip/ip dan buka http://<address>:<port> daripada telefon menggunakan data mudah alih. Permintaan yang muncul dalam log pemeriksa port membuktikan bahawa TCP masuk telah sampai. Jika berlaku timeout, ini bermakna ia tidak sampai, tidak kira apa yang ditunjukkan oleh ikon status klien anda sendiri.