Cara Pasang Headscale Sendiri di VPS

Apakah itu headscale

Headscale ialah implementasi pelayan kawalan Tailscale yang dihoskan sendiri, jadi mesin yang menyelaraskan rangkaian peribadi anda ialah VPS milik anda sendiri. Ini merupakan projek komuniti dan tidak dikendalikan oleh Tailscale Inc. Setiap mesin masih menjalankan klien rasmi tailscale, yang dihalakan ke pelayan anda dengan satu flag, --login-server.

Pelayan kawalan ialah bahagian yang mengetahui siapa yang tergolong dalam rangkaian tersebut. Ia memberikan setiap nod alamat daripada 100.64.0.0/10, mengedarkan kunci awam, dan memberitahu nod di mana untuk mencari satu sama lain. Terowong kekal menggunakan WireGuard, yang dibina dari nod ke nod. Trafik antara dua mesin anda tidak melalui kotak headscale, melainkan laluan terus tidak dapat dibina dan nod terpaksa menggunakan relay.

Headscale menyediakan satu tailnet (satu rangkaian Tailscale) bagi setiap instans, yang disifatkan oleh projek tersebut sebagai sesuai untuk kegunaan peribadi atau organisasi kecil. Dengan tiga atau empat mesin, VPN WireGuard biasa pada VPS milik anda melibatkan perisian yang lebih sedikit untuk dijalankan dan kurang risiko kerosakan. Headscale berbaloi digunakan apabila anda tidak lagi mahu menulis blok [Peer] secara manual untuk setiap komputer riba baharu. Jika anda mahukan satah kawalan yang dihoskan sendiri tetapi lebih suka mempunyai klien sendiri dan antara muka web untuk mengurus peer berbanding pengganti terus bagi Tailscale, NetBird pada satu VPS ialah alternatif yang wajar dipertimbangkan. Untuk perbandingan yang lebih meluas antara kedua-dua model ini, lihat perbezaan antara WireGuard dan Tailscale.

Keperluan sebelum pemasangan

• Sebuah VPS yang menjalankan Ubuntu 24.04 dengan alamat IPv4 awam dan akses sudo. Jika pelayan tersebut baharu, selesaikan sepuluh minit pertama pada VPS baharu terlebih dahulu.
• Satu DNS A record yang menghala ke alamat tersebut. Panduan ini menggunakan headscale.example.com.
• Domain kedua atau subdomain untuk MagicDNS. Panduan ini menggunakan tailnet.example.net. Ia tidak boleh menjadi domain yang sama seperti yang digunakan dalam server_url.
• Satu mesin klien untuk disambungkan, yang menjalankan Linux, macOS, Windows, Android atau iOS.

Pasang headscale daripada .deb rasmi

Projek ini menerbitkan pakej .deb pada halaman GitHub releases mereka. Setakat Julai 2026, keluaran semasa ialah 0.29.3. Semak seni bina sistem anda terlebih dahulu, kerana nama fail mengandungi maklumat tersebut.

sudo apt update
sudo apt install -y wget
dpkg --print-architecture

Perintah itu mencetak amd64 pada VPS x86 biasa dan arm64 pada pelan jenis Ampere atau Graviton. Masukkan jawapan tersebut ke dalam pemboleh ubah di bawah.

HEADSCALE_VERSION="0.29.3"
HEADSCALE_ARCH="amd64"
wget --output-document=headscale.deb \\
  "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
sudo apt install -y ./headscale.deb
headscale version

Tanda ./ di hadapan nama fail adalah wajib. Tanpanya, apt akan mencari pakej bernama headscale.deb dalam repositori anda dan gagal.

Pakej ini mencipta pengguna sistem headscale, menulis /etc/headscale/config.yaml lalai, dan memasang unit systemd. Ia tidak memulakan servis tersebut, dan itu adalah urutan yang betul. Konfigurasi yang dibekalkan menghalakan server_url ke http://127.0.0.1:8080, yang bukan merupakan alamat yang boleh dicapai oleh mana-mana klien anda, jadi servis yang dimulakan sekarang adalah salah walaupun ia berjaya berjalan. Menjalankan sudo systemctl is-active headscale pada tahap ini akan mencetak inactive. Itu adalah perkara yang dijangkakan, bukan satu ralat.

Konfigurasikan server_url sebelum anda memulakan servis

Sunting /etc/headscale/config.yaml menggunakan sudo nano /etc/headscale/config.yaml, atau gunakan tiga perubahan yang sama dengan sed. Simpan salinan asal, kerana fail tersebut panjang dan mempunyai banyak ulasan, serta ia merupakan rujukan terbaik yang anda miliki untuk tetapan selebihnya.

sudo cp /etc/headscale/config.yaml /etc/headscale/config.yaml.orig
sudo sed -i 's|^server_url:.*|server_url: https://headscale.example.com|' /etc/headscale/config.yaml
sudo sed -i 's|^listen_addr:.*|listen_addr: 127.0.0.1:8080|' /etc/headscale/config.yaml
sudo sed -i 's|^  base_domain:.*|  base_domain: tailnet.example.net|' /etc/headscale/config.yaml
sudo grep -E '^(server_url|listen_addr):|^  base_domain:' /etc/headscale/config.yaml

server_url ialah alamat yang ditulis oleh headscale ke dalam setiap pendaftaran klien. Klien akan mendail rentetan tepat tersebut selama-lamanya selepas itu, jadi ia mestilah nama awam dengan https:// di hadapan, bukan 127.0.0.1.

listen_addr ialah tempat proses tersebut terikat (bind). Biarkan ia pada loopback. Reverse proxy pada mesin yang sama menamatkan TLS (transport layer security) dan menghalakan trafik kepadanya, jadi tiada apa-apa di luar pelayan perlu mencapai port 8080.

base_domain ialah akhiran MagicDNS, iaitu domain yang digunakan untuk nama nod anda. Ia mestilah nama domain yang layak sepenuhnya (FQDN) tanpa titik di hujung, dan ia mestilah domain yang berbeza daripada domain dalam server_url, kerana ruang nama kedua-duanya akan bertembung jika tidak.

Biarkan bahagian pangkalan data seperti sedia ada. Tetapan lalai ialah SQLite pada /var/lib/headscale/db.sqlite, dalam direktori yang dicipta dan dimiliki oleh pakej tersebut, dan SQLite sudah memadai untuk tailnet sebesar ini.

Mulakan headscale dan sahkan ia sedang berjalan

sudo systemctl enable --now headscale
sudo systemctl is-active headscale
curl -sS -o /dev/null -w '%{http_code}\\n' http://127.0.0.1:8080/health

is-active mencetak active dan curl mencetak 200. enable --now melakukan kedua-dua bahagian tugas tersebut: ia memulakan servis dan menandakannya untuk bermula selepas but semula.

Jika is-active mencetak failed, baca jurnal dengan sudo journalctl -u headscale -n 50 --no-pager. Kegagalan pada peringkat ini hampir selalu berpunca daripada fail konfigurasi, kerana headscale menghuraikan keseluruhan fail sebelum ia membuka soket. Oleh itu, indentasi yang salah atau kunci yang tidak dikenali akan menghentikan proses sebelum sebarang port mendengar. Betulkan fail tersebut, kemudian jalankan sudo systemctl restart headscale. Setiap perubahan konfigurasi seterusnya memerlukan langkah mulakan semula yang sama. Pelanggan akan menyambung semula secara automatik selepas itu. Jika unit systemd adalah perkara baharu bagi anda, menjalankan servis dan pemasa anda sendiri dengan systemd merangkumi arahan yang digunakan di sini.

Semak fail status semasa anda berada dalam shell:

stat -c '%U %n' /var/lib/headscale/db.sqlite /var/lib/headscale/noise_private.key

Kedua-dua baris bermula dengan headscale, pengguna tanpa keistimewaan yang dicipta oleh pakej tersebut. noise_private.key ialah identiti pelayan kepada pelanggannya. Simpan fail ini. Jika anda memadamkannya, headscale akan menjana identiti baharu dan setiap nod perlu mendaftar semula.

Meletakkan TLS di hadapan headscale

Pelanggan mesti mencapai server_url melalui HTTPS. Caddy ialah laluan terpantas kerana ia meminta dan memperbaharui sijil secara automatik.

sudo apt install -y caddy

Gantikan /etc/caddy/Caddyfile dengan blok daripada dokumentasi headscale:

headscale.example.com {
    reverse_proxy 127.0.0.1:8080 {
        header_up True-Client-IP {remote_host}
        header_up X-Real-IP {remote_host}
    }
}

sudo caddy validate --adapter caddyfile --config /etc/caddy/Caddyfile
sudo systemctl restart caddy
sudo systemctl is-active caddy

validate akan memaparkan adapted config to JSON apabila fail tersebut diurai. Amaran bahawa fail tidak diformatkan hanyalah isu kosmetik. Dari komputer riba anda, curl -sS -o /dev/null -w '%{http_code}\\n' https://headscale.example.com/health juga sepatutnya memaparkan 200. Semakan tunggal itu membuktikan bahawa DNS, firewall, sijil dan proksi semuanya berfungsi bersama.

Berikut ialah perincian proksi yang sering memakan masa pengguna. Sambungan kawalan Tailscale ialah HTTP upgrade, ia dimulakan dengan POST dan bukannya GET, dan nilai pengepala Upgrade ialah tailscale-control-protocol. Caddy melalukan perkara ini tanpa konfigurasi tambahan. nginx tidak melakukannya, jadi bahagian hadapan nginx memerlukan peta upgrade:

map $http_upgrade $connection_upgrade {
    default keep-alive;
    ''      close;
}

server {
    listen 443 ssl;
    server_name headscale.example.com;
    location / {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_buffering off;
        proxy_pass http://127.0.0.1:8080;
    }
}

Jika baris tersebut ditinggalkan, permintaan biasa masih berjaya, itulah sebabnya /health mengembalikan 200 dan segala-galanya kelihatan baik, sedangkan sambungan kawalan jangka panjang tidak pernah terbentuk dan nod anda mendaftar tetapi kekal di luar talian. Jika anda memilih laluan nginx, Certbot pada Ubuntu 24.04 dengan nginx merangkumi bahagian sijil.

Port yang perlu dibuka dalam UFW

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Port 443 membawa setiap perbualan klien. Port 80 hanya digunakan untuk cabaran HTTP ACME (automatic certificate management environment) dan pengalihan ke HTTPS, dan Caddy memerlukannya untuk mendapatkan sijil.

Port 8080 perlu kekal tertutup. listen_addr adalah 127.0.0.1:8080, jadi proksi mencapai headscale melalui antara muka loopback dan tiada peraturan firewall yang terlibat. Membuka 8080 kepada internet memberikan klien saluran kawalan teks jelas dan tidak memberikan sebarang manfaat. Perlu diingat bahawa kebanyakan penyedia menjalankan firewall kedua dalam panel kawalan mereka, berasingan daripada UFW, jadi port boleh dibuka pada pelayan tetapi masih tertutup di peringkat edge. Asas firewall UFW pada VPS membincangkan sintaks peraturan dengan lebih terperinci.

Cipta pengguna dan kunci pra-pengesahan

sudo headscale users create alice
sudo headscale users list

Perintah headscale ialah klien. Ia berhubung dengan daemon yang sedang berjalan melalui soket unix di /var/run/headscale/headscale.sock, yang mempunyai mod 0770 dan dimiliki oleh kumpulan headscale. Dua perkara terhasil daripada keadaan ini. Perintah tersebut gagal apabila servis dihentikan, yang merupakan sebab lain mengapa urutan dalam panduan ini penting, dan ia memerlukan sudo melainkan anda menambah akaun anda sendiri ke dalam kumpulan headscale.

users list mencetak ID bersebelahan setiap nama. Anda memerlukan nombor tersebut kerana perintah kunci memerlukan ID pengguna berangka dan bukannya nama.

sudo headscale preauthkeys create --user 1 --expiration 24h

Kunci tersebut dicetak sekali sahaja. Salin kunci itu sekarang. Kunci pra-pengesahan adalah untuk kegunaan sekali sahaja dan sah selama satu jam melainkan anda menetapkan sebaliknya, jadi --expiration 24h berbaloi untuk ditetapkan semasa anda masih dalam fasa ujian. Tambahkan --reusable untuk kunci yang mendaftarkan beberapa mesin, dan kendalikan kunci tersebut seperti kata laluan, kerana sesiapa yang memegangnya boleh menyertai rangkaian anda.

Sambungkan klien pertama anda dengan --login-server

Pada mesin yang ingin anda sertakan:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --login-server https://headscale.example.com --auth-key 'hskey-auth-PASTE-YOUR-KEY-HERE'
tailscale status
tailscale ip -4

tailscale ip -4 akan memaparkan alamat yang diberikan oleh headscale, contohnya seperti 100.64.0.1. Kembali ke pelayan, sudo headscale nodes list akan menunjukkan nod tersebut berserta ID, pengguna, dan status dalam taliannya.

Nilai --login-server mestilah sepadan dengan server_url sepenuhnya, termasuk skema dan tanpa garis miring (trailing slash) di hujungnya. Nilai ini dibandingkan sebagai rentetan, dan ketidakpadanan bermakna klien mendaftar pada satu alamat tetapi kemudian diarahkan untuk berhubung dengan alamat yang lain.

Mesin yang sebelum ini telah dilog masuk ke perkhidmatan hos Tailscale akan mengekalkan log masuk tersebut. Jalankan sudo tailscale logout pada mesin itu terlebih dahulu, kemudian jalankan tailscale up dengan --login-server.

Jika anda tidak menyertakan --auth-key, klien akan memaparkan URL. Buka URL tersebut dan halaman itu akan menunjukkan pengecam bagi percubaan pendaftaran tersebut, yang perlu anda luluskan pada pelayan:

sudo headscale auth register --user alice --auth-id PASTE-THE-ID-FROM-THE-PAGE

Borang tersebut lebih mudah digunakan untuk komputer riba anda sendiri. Kunci pra-pengesahan (preauth keys) adalah lebih baik untuk sebarang skrip, kerana tiada manusia yang perlu memantau proses tersebut. Sebaik sahaja VPS itu sendiri menjadi nod, ia juga boleh membawa trafik internet mesin anda yang lain, iaitu melalui persediaan exit node, dengan satu perbezaan iaitu anda meluluskan laluan yang diiklankan pada pelayan menggunakan arahan headscale dan bukannya melalui konsol pentadbir yang dihoskan.

DERP, dan perkara yang menyalurkan trafik apabila laluan terus gagal

DERP (designated encrypted relay for packets) ialah laluan sandaran. Apabila dua nod tidak dapat membuka sambungan WireGuard secara terus, biasanya kerana kedua-duanya berada di sebalik NAT (network address translation) yang ketat, nod tersebut akan menghantar paket melalui relay sebagai ganti. Relay tidak memegang sebarang kunci, jadi ia tidak boleh membaca trafik anda. Ia hanya melihat nod mana yang sedang berhubung dan berapa banyak data yang dipindahkan.

Fahami dengan jelas tindakan konfigurasi lalai. Headscale dihantar dengan menunjuk kepada https://controlplane.tailscale.com/derpmap/default menggunakan auto_update_enabled: true dan update_frequency: 3h, jadi satah kawalan (control plane) adalah milik anda manakala relay adalah milik Tailscale. Bagi kebanyakan pengguna, ini adalah pertukaran yang adil. Jika tidak, jalankan relay anda sendiri.

Untuk menjalankan relay anda sendiri, tetapkan enabled: true di bawah derp.server dalam config.yaml, mulakan semula headscale, dan buka port STUN (session traversal utilities for NAT) dengan sudo ufw allow 3478/udp. Fail konfigurasi menyatakan keperluan tersebut dengan jelas: server_url mesti menggunakan https, kerana DERP memerlukan TLS. Mengosongkan senarai derp.urls akan membuang relay Tailscale daripada peta, dan jika anda melakukan perkara itu tanpa relay terbenam (embedded relay) yang berfungsi, mana-mana pasangan nod yang tidak dapat bersambung secara terus tidak akan dapat bersambung langsung.

Daripada klien, tailscale netcheck memaparkan kependaman ke setiap rantau relay yang diketahuinya, manakala tailscale status menandakan setiap peer sebagai sama ada direct dengan alamat atau relay dengan kod rantau. Peer yang tersekat pada relay ialah masalah NAT, bukan masalah headscale. Peer yang berada dalam keadaan direct tetapi masih perlahan ialah isu yang berbeza, dan jawapan lazimnya ialah MTU, bukan terowong itu sendiri.

Mengapa nod dipaparkan sebagai luar talian?

Proksi menggugurkan naik taraf. Ini adalah punca yang biasa, dan tandanya ialah segala-galanya kelihatan sihat: /health mengembalikan 200, headscale nodes list menunjukkan nod tersebut, namun nod tidak pernah menjadi dalam talian. Sambungan kawalan ialah POST yang membawa Upgrade: tailscale-control-protocol, dan proksi yang tidak memajukannya akan mematikan satu-satunya saluran yang melaporkan status nod. Bandingkan konfigurasi nginx anda dengan blok map di atas, atau tukar kepada Caddy untuk memastikan proksi bukan puncanya.

server_url berubah selepas nod didaftarkan. Nod terus mendail nilai yang diberikan semasa pendaftaran. Jika anda telah mengubahnya, jalankan sudo tailscale up --login-server https://headscale.example.com --force-reauth pada setiap nod.

Klien tidak berjalan. Pada nod, jalankan sudo systemctl is-active tailscaled dan sudo journalctl -u tailscaled -n 50 --no-pager. Klien yang tidak dapat menyelesaikan atau mencapai domain anda akan merekodkan percubaan semula di sana.

Kunci telah tamat tempoh. Dibincangkan dalam bahagian seterusnya.

Untuk memantau bahagian pelayan semasa anda menguji, jalankan sudo journalctl -u headscale -f pada VPS dan mulakan semula tailscaled pada klien. Nod yang mencapai headscale akan menghasilkan baris log serta-merta. Keadaan senyap bermakna permintaan tidak sampai, jadi periksa DNS, firewall dan proksi sebelum anda memeriksa headscale.

Tamat tempoh kunci, dan nod yang berhenti berfungsi beberapa minggu kemudian

Terdapat dua jenis tamat tempoh yang berbeza, dan kekeliruan antara keduanya akan membuang masa.

Kunci preauth tamat tempoh dengan cepat mengikut reka bentuknya. Nilai lalai ialah satu jam dan satu kegunaan. Jika tailscale up menolak kunci tersebut, jana kunci baharu pada pelayan dan bukannya menyunting apa-apa pada klien.

Kunci nod adalah bahagian yang mempunyai jangka hayat panjang. Bahagian node dalam config.yaml menetapkan expiry: 0, dan 0 bermaksud tiada tamat tempoh lalai: nod yang didaftarkan kekal sah sehingga anda menamatkan tempohnya. Nod yang ditag tidak akan tamat tempoh walau apa pun. Tetapkan expiry: 180d jika anda mahu pendaftaran mempunyai tempoh luput, dan fahami apa yang anda minta: setiap nod yang tidak ditag kemudiannya memerlukan sudo tailscale up --login-server https://headscale.example.com --force-reauth mengikut jadual tersebut, dan pelayan tanpa kepala yang tidak diautentikasi semula oleh sesiapa akan terkeluar daripada rangkaian dengan sendirinya.

Lakukan secara manual apabila seseorang kehilangan komputer riba. sudo headscale nodes list memberikan anda ID tersebut, kemudian sudo headscale nodes expire -i 3 melog keluar nod itu, dan sudo headscale nodes delete -i 3 membuangnya daripada rangkaian sepenuhnya.

Sandaran dan naik taraf

/var/lib/headscale dan /etc/headscale secara keseluruhannya membentuk keseluruhan pelayan. Hentikan servis sebelum anda menyalin fail tersebut, kerana SQLite mungkin sedang melakukan penulisan dan pangkalan data yang disalin semasa beban kerja boleh menjadi tidak konsisten.

sudo systemctl stop headscale
sudo tar czf /root/headscale-state.tgz -C /var/lib headscale
sudo tar czf /root/headscale-config.tgz -C /etc headscale
sudo systemctl start headscale
sudo chmod 600 /root/headscale-*.tgz

Alihkan kedua-dua fail tersebut keluar dari pelayan. Fail ini mengandungi kunci peribadi dan setiap pendaftaran, jadi ia memerlukan penjagaan yang sama seperti pelayan itu sendiri. sandaran restic daripada VPS merangkumi cara melakukan perkara ini mengikut jadual dan dalam bentuk terenkripsi.

Naik taraf mengulangi proses pemasangan: muat turun .deb dan sudo apt install ./headscale.deb yang baharu, kemudian mulakan semula dan jalankan semula semakan is-active dan /health. Sejak versi 0.29, laluan naik taraf adalah ketat. Melangkau versi minor adalah disekat, begitu juga dengan menurunkan taraf kepada versi minor yang lebih lama. Lakukan naik taraf satu versi minor pada satu masa, ambil sandaran sebelum setiap langkah, dan baca nota keluaran versi tersebut terlebih dahulu, kerana keluaran yang sama telah mengubah tingkah laku polisi ACL dan memindahkan beberapa kunci konfigurasi.

FAQ

Mengapa headscale gagal bermula sejurus selepas saya memasang .deb?

Pakej tersebut memasang unit tetapi membiarkan servis dalam keadaan berhenti, dan /etc/headscale/config.yaml lalai hanyalah templat dan bukannya konfigurasi yang berfungsi. Edit server_url, listen_addr dan base_domain terlebih dahulu, kemudian jalankan sudo systemctl enable --now headscale dan sahkan dengan sudo systemctl is-active headscale. Jika ia masih gagal, sudo journalctl -u headscale -n 50 --no-pager akan menamakan masalah tersebut, dan pada peringkat ini ia hampir selalu merupakan ralat YAML, kerana headscale menghuraikan keseluruhan fail sebelum ia mengikat port.

Adakah saya masih perlu memasang klien Tailscale biasa pada mesin saya?

Ya. Headscale hanya menggantikan pelayan kawalan. Setiap nod menjalankan klien rasmi daripada Tailscale, dan anda menghalakannya ke pelayan anda dengan sudo tailscale up --login-server https://headscale.example.com. Flag tersebut wujud dalam klien standard, jadi tiada apa-apa yang perlu ditampal atau dibina semula.

Adakah trafik saya melalui pelayan headscale?

Biasanya tidak. Headscale menyelaraskan rangkaian serta mengagihkan kunci dan alamat, manakala laluan data adalah WireGuard secara terus antara nod anda. Trafik hanya mengambil lencongan apabila dua nod tidak dapat mencapai satu sama lain secara terus dan kembali kepada relay DERP, dan dengan konfigurasi yang dibekalkan, relay tersebut adalah relay awam milik Tailscale. Jalankan tailscale status pada nod untuk melihat sama ada peer tertentu adalah direct atau pada relay.

Mengapa nod saya kekal luar talian selepas ia mendaftar?

Nod yang muncul dalam headscale nodes list tetapi tidak pernah dalam talian biasanya telah kehilangan sambungan kawalannya pada reverse proxy. Sambungan itu adalah HTTP upgrade yang dihantar sebagai POST dengan header Upgrade: tailscale-control-protocol, dan nginx akan menggugurkannya melainkan anda menambah blok map $http_upgrade $connection_upgrade dan baris proxy_set_header yang sepadan. Caddy menghantarnya tanpa konfigurasi tambahan, yang menjadikannya cara pantas untuk menguji sama ada proxy menjadi punca masalah.

Adakah saya memerlukan nama domain dan TLS untuk headscale?

Secara praktikalnya, ya. Klien menyambung kepada apa jua rentetan yang anda letakkan dalam server_url, sijil dikeluarkan untuk nama dan bukannya untuk alamat IP kosong, dan fail konfigurasi menyatakan bahawa DERP memerlukan TLS. Domain berserta Caddy mengambil masa kira-kira lima minit dan memberikan anda titik akhir HTTPS yang memperbaharui dirinya sendiri. Menjalankan pelayan kawalan melalui HTTP biasa bermakna setiap perbualan klien dengannya merentasi internet dalam bentuk teks jelas.