Headscale 入门指南：搭建与使用详解

Headscale 入门指南：搭建与使用详解

headscale An open source, self-hosted implementation of the Tailscale control server 项目地址: https://gitcode.com/gh_mirrors/he/headscale

前言

Headscale 是一个开源的 Tailscale 控制服务器替代方案，它允许用户自建 Tailscale 的协调服务器，完全掌控自己的网络基础设施。本文将详细介绍 Headscale 的基本使用方法，帮助您快速上手这一强大的网络工具。

准备工作

在开始使用 Headscale 前，请确保已完成以下准备工作：

1. 安装部署：Headscale 已正确安装并作为系统服务运行
2. 配置调整：已完成配置文件调整，适配您的运行环境
3. 网络可达：Headscale 服务可通过互联网访问
4. 客户端准备：已在终端设备安装 Tailscale 客户端

命令行工具基础

Headscale 提供了丰富的命令行工具，可通过以下方式获取帮助信息：

原生安装方式

# 查看全局帮助
headscale help

# 查看特定命令帮助
headscale <命令> --help

容器化部署方式

# 查看全局帮助
docker exec -it headscale headscale help

# 查看特定命令帮助
docker exec -it headscale headscale <命令> --help

用户管理

在 Headscale 架构中，所有设备节点都必须归属于特定用户。一个用户可以拥有多个设备节点。

创建新用户

原生安装

headscale users create <用户名>

容器部署

docker exec -it headscale headscale users create <用户名>

查看用户列表

原生安装

headscale users list

容器部署

docker exec -it headscale headscale users list

设备注册

要将设备接入 Headscale 网络，需要先完成注册流程。以下是针对 Linux/BSD 系统的注册方法。

交互式注册

1. 在客户端设备执行：

tailscale up --login-server <您的Headscale地址>

2. 系统通常会打开浏览器窗口显示机器密钥
3. 在服务器端批准注册：

原生安装

headscale nodes register --user <用户名> --key <机器密钥>

容器部署

docker exec -it headscale headscale nodes register --user <用户名> --key <机器密钥>

使用预认证密钥（推荐）

预认证密钥方式更适合自动化部署场景。

1. 生成预认证密钥（默认1小时有效，单次使用）：

原生安装

headscale preauthkeys create --user <用户名>

容器部署

docker exec -it headscale headscale preauthkeys create --user <用户名>

2. 在客户端使用获取的密钥连接：

tailscale up --login-server <您的Headscale地址> --authkey <预认证密钥>

高级技巧

1. 密钥有效期控制：可通过 --expiration 和 --reusable 参数调整密钥的有效期和使用次数限制
2. 批量部署：预认证密钥特别适合批量部署多台设备
3. 用户隔离：通过创建不同用户实现设备分组管理

常见问题

Q：设备注册失败怎么办？ A：检查时间同步、网络连通性和密钥有效性

Q：预认证密钥可以重复使用吗？ A：默认情况下不能，但创建时可指定 --reusable 参数

Q：如何查看已注册设备？ A：使用 headscale nodes list 命令

通过本指南，您应该已经掌握了 Headscale 的基本使用方法。后续可以进一步探索 ACL 规则配置、子网路由等高级功能，构建更复杂的网络拓扑。

headscale An open source, self-hosted implementation of the Tailscale control server 项目地址: https://gitcode.com/gh_mirrors/he/headscale