Headscale VPN 完整操作手册

# 下载并安装Headscale curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/jammy.noarmor.gpg | sudo tee /usr/share/keyrings/tailscale-archive-keyring.gpg >/dev/null curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/jammy.tailscale-keyring.list | sudo tee /etc/apt/sources.list.d/tailscale.list sudo apt update sudo apt install headscale

# 创建配置目录 sudo mkdir -p /etc/headscale # 复制配置文件 sudo cp /usr/share/headscale/config-example.yaml /etc/headscale/config.yaml # 编辑配置文件 sudo nano /etc/headscale/config.yaml

# 主要配置项 server_url: http://38.54.100.175:8080 listen_addr: 0.0.0.0:8080 grpc_listen_addr: 0.0.0.0:50443 grpc_allow_insecure: false # DERP服务器配置 derp: server: enabled: true region_id: 999 region_code: "headscale" region_name: "Headscale Embedded DERP" stun_listen_addr: "0.0.0.0:3478" ipv4: 38.54.100.175 # 数据库配置 database: type: sqlite sqlite: path: /var/lib/headscale/db.sqlite write_ahead_log: true # DNS配置 dns: magic_dns: true base_domain: headscale.local nameservers: global: - 1.1.1.1 - 1.0.0.1

# 安装Caddy curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list sudo apt update sudo apt install caddy # 配置Caddy sudo nano /etc/caddy/Caddyfile

# 域名配置 - 使用自签名证书 qywbip.qumai8.cn { reverse_proxy localhost:8080 tls internal log { output file /var/log/caddy/headscale.log } } # IP地址配置 - 使用自签名证书 38.54.100.175 { reverse_proxy localhost:8080 tls internal log { output file /var/log/caddy/headscale.log } } # HTTP重定向到HTTPS :80 { redir https://{host}{uri} permanent }

# 创建必要目录 sudo mkdir -p /var/lib/headscale sudo mkdir -p /var/run/headscale # 设置权限 sudo chown -R headscale:headscale /var/lib/headscale sudo chown -R headscale:headscale /var/run/headscale # 启动服务 sudo systemctl enable headscale sudo systemctl start headscale sudo systemctl enable caddy sudo systemctl start caddy # 检查服务状态 sudo systemctl status headscale sudo systemctl status caddy

# 开放必要端口 sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw allow 8080/tcp sudo ufw allow 50443/tcp sudo ufw allow 3478/udp sudo ufw allow ssh # 启用防火墙 sudo ufw enable # 检查防火墙状态 sudo ufw status

# 生成预授权密钥 headscale preauthkeys create --user=1 --reusable --expiration 24h # 查看生成的密钥 headscale preauthkeys list --user=1 # 构建一键连接URL（示例） # https://38.54.100.175?authkey=tskey-auth-xxxxx-xxxxxxxxxxxx

# 创建用户 headscale users create default # 生成预授权密钥 headscale preauthkeys create --user=1 --reusable --expiration 24h # 查看生成的密钥 headscale preauthkeys list --user=1

# 查看所有预授权密钥 headscale preauthkeys list --user=1 # 查看特定密钥详情 headscale preauthkeys list --user=1 --output json # 生成新的预授权密钥（可重用，24小时过期） headscale preauthkeys create --user=1 --reusable --expiration 24h # 生成一次性密钥（使用后自动失效） headscale preauthkeys create --user=1 --reusable=false --expiration 1h # 生成长期有效的密钥（7天） headscale preauthkeys create --user=1 --reusable --expiration 168h # 删除/使密钥过期 headscale preauthkeys expire --user=1 KEY_ID # 查看密钥使用情况 headscale preauthkeys list --user=1 --output json | jq '.[] | {id, key, created, expiration, used, reusable}'

# 退出当前连接（如果有） tailscale logout # 使用HTTP连接（推荐） tailscale up --login-server=http://38.54.100.175:8080 --authkey=YOUR_AUTH_KEY # 或者使用HTTPS连接（需要处理证书问题） tailscale up --login-server=https://38.54.100.175 --authkey=YOUR_AUTH_KEY

# 检查连接状态 tailscale status # 查看分配的IP tailscale ip # 测试网络连接 ping 100.64.0.1

# 查看连接的节点 headscale nodes list # 查看节点详情 headscale nodes list --output json # 实时监控 watch -n 2 'headscale nodes list'

# 检查服务状态 sudo systemctl status headscale sudo systemctl status caddy # 查看日志 sudo journalctl -u headscale -f sudo journalctl -u caddy -f # 检查端口监听 sudo ss -tlnp | grep -E "(8080|443|50443)" # 测试本地连接 curl http://localhost:8080/health curl -k https://localhost/health

# 创建用户 headscale users create username # 列出用户 headscale users list # 删除用户 headscale users destroy username

# 列出所有节点 headscale nodes list # 查看节点详情 headscale nodes list --output json # 删除节点 headscale nodes destroy NODE_ID # 重命名节点 headscale nodes rename NODE_ID new-name

# 生成新密钥 headscale preauthkeys create --user=1 --reusable --expiration 24h # 列出密钥 headscale preauthkeys list --user=1 # 删除密钥 headscale preauthkeys expire --user=1 KEY_ID

# 启用子网路由 headscale nodes enable-routes --node NODE_ID --routes 192.168.1.0/24 # 查看路由 headscale nodes list --output json | grep -A 5 -B 5 "routes"

# Headscale配置文件 (config.yaml) server_url: http://38.54.100.175:8080 listen_addr: 0.0.0.0:8080 grpc_listen_addr: 0.0.0.0:50443 grpc_allow_insecure: false noise: private_key_path: /var/lib/headscale/noise_private.key prefixes: v4: 100.64.0.0/10 v6: fd7a:115c:a1e0::/48 allocation: sequential derp: server: enabled: true region_id: 999 region_code: "headscale" region_name: "Headscale Embedded DERP" stun_listen_addr: "0.0.0.0:3478" private_key_path: /var/lib/headscale/derp_server_private.key automatically_add_embedded_derp_region: true ipv4: 38.54.100.175 urls: - https://controlplane.tailscale.com/derpmap/default paths: [] auto_update_enabled: true update_frequency: 24h disable_check_updates: false ephemeral_node_inactivity_timeout: 30m database: type: sqlite debug: false gorm: prepare_stmt: true parameterized_queries: true skip_err_record_not_found: true slow_threshold: 1000 sqlite: path: /var/lib/headscale/db.sqlite write_ahead_log: true wal_autocheckpoint: 1000 acme_url: https://acme-v02.api.letsencrypt.org/directory acme_email: "" tls_letsencrypt_hostname: "" tls_letsencrypt_cache_dir: /var/lib/headscale/cache tls_letsencrypt_challenge_type: HTTP-01 tls_letsencrypt_listen: ":http" tls_cert_path: "" tls_key_path: "" log: format: text level: info policy: mode: file path: "" dns: magic_dns: true base_domain: headscale.local override_local_dns: false nameservers: global: - 1.1.1.1 - 1.0.0.1 - 2606:4700:4700::1111 - 2606:4700:4700::1001 split: {} search_domains: [] extra_records: [] unix_socket: /var/run/headscale/headscale.sock unix_socket_permission: "0770" logtail: enabled: false randomize_client_port: false