🛠️ 新设备接入自建 Headscale 服务器操作指南

📝 版本说明：本指南适用于自建 Headscale 服务器环境。文中所有涉及隐私及网络敏感信息的字段（如域名、IP、密钥、特定业务端口等）均已按规范进行脱敏处理，请在实际操作中替换为你的具体配置。

📋 一、前置准备与环境确认

在开始接入前，请确保以下基础环境已部署完毕，这将避免绝大多数连接失败的问题。

  • 域名解析：拥有一个公网域名（如 your-domain.com），并已解析至服务器公网 IP。
  • 端口开放：服务器防火墙及路由器已放行 TCP 5001 端口（Headscale HTTPS 入口）。
  • 服务状态：Headscale 服务端容器处于运行状态。
  • 用户存在：Headscale 服务端已创建对应用户（User），通常为 home 或数字 ID 1。

💡 专业注释：

  • 关于 User ID：Headscale v0.29+ 版本开始，命令行参数 --user 可能要求传入数字 ID（如 1）而非用户名字符串。若遇报错，请先执行 headscale users list 查询准确 ID。
  • 关于端口：5001 为示例 HTTPS 端口，若你使用的是标准 443 端口或其他自定义端口，请同步修改客户端命令。

🔑 二、核心接入方式速览

根据使用场景的不同，推荐采用以下两种接入策略：

接入方式 适用场景 操作复杂度 审批机制
预授权密钥 (推荐) 批量部署、生产环境、自动化脚本 ⭐ (一步到位) 无需审批 (自动注册)
交互式注册 测试设备、临时接入、密钥管理受限 ⭐⭐ (需二次操作) 需手动批准 (服务端确认)

🚀 三、方式一：预授权密钥自动注册 (推荐)

此方式通过在服务端预先生成密钥，客户端携带密钥直连，无需人工干预，适合长期稳定的设备接入。

1. 服务端：生成预授权密钥
进入 Headscale 项目目录，执行密钥生成命令。

1
2
3
4
5
6
7
8
9
# 1. 进入服务目录
cd ~/headscape-stack

# 2. 生成长期有效、可重复使用的密钥 (推荐)
# 注：若提示 user 错误，请将 --user home 替换为 --user 1 (具体ID请查询)
docker compose exec headscale headscale preauthkeys create \
  --user home \
  --reusable \
  --expiration 3650d

📌 操作要点：

  • 执行后终端会输出一串密钥（格式如 hskey-auth-zoBISQsExOQv...），请立即复制并妥善保管。
  • 参数 --reusable 允许该密钥被多次使用，非常适合批量添加设备。

2. 客户端：执行接入命令
根据客户端操作系统，选择对应的接入指令。

  • Linux / macOS (终端执行)

    1
    2
    3
    4
    sudo tailscale up \
      --login-server=https://headscale.your-domain.com:5001 \
      --auth-key=hskey-auth-zoBISQsExOQv... \
      --accept-routes=true

  • OpenWrt (SSH 命令行)

    1
    2
    3
    4
    5
    tailscale up \
      --login-server=https://headscale.your-domain.com:5001 \
      --auth-key=hskey-auth-zoBISQsExOQv... \
      --accept-routes=true \
      --insecure # 仅限自签名证书或内网环境使用，跳过证书验证

  • OpenWrt (Web 管理界面)

    1. 进入 **服务 (Services) → Tailscale → 附加设置 (Advanced Settings)**。
    2. **服务器地址 (Server Address)**：填入 https://headscale.your-domain.com:5001。
    3. **认证密钥 (Auth Key)**：粘贴刚才复制的密钥。
    4. 点击 **保存并应用 (Save & Apply)**。

3. 验证状态
在服务端执行以下命令，确认新节点已出现在列表中且状态为 active。

1
docker compose exec headscale headscale nodes list

🔄 四、方式二：交互式注册 (手动审批)

当客户端无法预先获取密钥时，可使用此方式。客户端发起请求后，需管理员在服务端手动批准。

1. 客户端：发起连接请求
在客户端执行不带密钥的命令。

1
tailscale up --login-server=https://headscale.your-domain.com:5001
  • 终端反馈：命令执行后，终端会提示类似 Run the command below in the headscale server... 的信息。
  • 提取 ID：请复制提示信息中 --auth-id 后面的值（例如 hskey-authreq-xxxxxx）。

2. 服务端：批准注册请求
在 Headscale 服务器上执行批准命令。

1
2
3
4
cd ~/headscale-stack
docker compose exec headscale headscale auth register \
  --auth-id hskey-authreq-xxxxxx \
  --user home # 注意 User ID 兼容性

3. (可选) 清理过期请求
若待审批列表积压过多，可执行以下命令清理：

1
2
3
4
5
# 查看所有待审批请求
docker compose exec headscale headscale auth list

# 撤销指定的请求 (支持前缀匹配)
docker compose exec headscale headscale auth expire --auth-id hskey-authreq-xxx

🛠️ 五、运维管理与故障排查

1. OpenWrt 常用维护命令速查

操作目的 命令示例
首次接入/重连 tailscale up ... (携带完整参数)
查看连接状态 tailscale status
查看虚拟 IP ip addr show tailscale0
退出登录 tailscale logout
断开并重置 tailscale down 后重新 up

2. 接入验证清单 (Checklist)
请按顺序排查以下环节：

  • 服务端状态：docker compose ps 确认 headscale 容器为 Up。
  • 密钥有效性：预授权密钥未过期，且已正确复制。
  • 网络连通性：客户端能 ping 通域名，且能 telnet headscale.your-domain.com 5001。
  • 节点列表：服务端 nodes list 中已显示新设备。
  • IP 分配：客户端网卡 tailscale0 已获取到 Tailscale 虚拟 IP。

3. 常见问题与解决方案

问题现象 可能原因与解决方案
x509 证书错误 服务端使用了自签名证书。解决：客户端命令添加 --insecure 参数。
密钥无效/已过期 密钥有效期短或为一次性密钥。解决：重新生成带有 --reusable 参数的长期密钥。
连接超时 (Timeout) 网络不通。解决：检查防火墙、安全组是否放行 5001 端口，确认公网 IP 映射正确。
Web 界面配置失效 OpenWrt LuCI 插件版本兼容性问题。解决：优先使用 SSH 命令行方式进行配置。
Auth-ID 无效 请求已过期。解决：交互式请求有效期较短，需在提示后立即在服务端执行批准命令。

📝 六、总结

本指南覆盖了从环境准备到故障排查的全链路操作。建议在生产环境中优先使用“预授权密钥”方式，以确保接入的自动化与安全性。