headscale v0.29.3

headscale logo

一个开源、自托管的 Tailscale 控制服务器实现。

加入我们的 Discord 服务器进行交流。

注意： 请始终选择与你所使用的发布版本相同的 GitHub 标签，以确保你拥有正确的示例配置。main 分支可能包含未发布的更改。文档提供稳定版和开发版：

什么是 Tailscale

Tailscale 是一个现代 VPN，构建于 Wireguard 之上。它像覆盖网络一样工作，在你的网络中的计算机之间建立连接——使用 NAT 穿透。

Tailscale 中的一切都是开源的，除了专有操作系统（Windows 和 macOS/iOS）的 GUI 客户端以及控制服务器。

控制服务器充当 Tailscale 网络中节点的 Wireguard 公钥交换点。它分配客户端的 IP 地址，创建每个用户之间的边界，支持用户之间共享机器，并公开节点通告的路由。

Tailscale 网络（tailnet）是 Tailscale 分配给用户（就私有用户或组织而言）的私有网络。

设计目标

Headscale 旨在实现一个自托管、开源的 Tailscale 控制服务器替代方案。Headscale 的目标是为自托管者和爱好者提供一个可用于其项目和实验环境的开源服务器。它实现了一个范围较窄的单一 Tailscale 网络（tailnet），适合个人使用或小型开源组织。

支持 Headscale

如果你喜欢 headscale 并觉得它有用，仓库中提供了赞助和捐赠按钮。

功能

请参阅文档中的“功能”。

客户端操作系统支持

请参阅文档中的“客户端和操作系统支持”。

运行 headscale

请注意，我们不支持也不鼓励使用反向代理和容器来运行 Headscale。

请查看文档。

对于 NixOS 用户，nix/ 中提供了一个模块。

从 `main` 构建

来自 main 分支的开发构建以容器镜像和二进制文件的形式提供。详情请参阅开发构建文档。

演讲

Fosdem 2026（视频）：Headscale & Tailscale: The complementary open source clone
- 由 Kristoffer Dalby 主讲
Fosdem 2023（视频）：Headscale: How we are using integration testing to reimplement Tailscale
- 由 Juan Font Alonso 和 Kristoffer Dalby 主讲

免责声明

本项目与 Tailscale Inc. 无关。

然而，Headscale 的一位活跃维护者受雇于 Tailscale，他被允许投入工作时间为本项目做贡献。该维护者的贡献由其他维护者审核。

维护者们共同为项目设定方向。基本原则是服务自托管者、爱好者和热衷者社区——同时保持项目的可持续性。

贡献

请阅读 CONTRIBUTING.md 文件。

也请查看我们的 AI_POLICY.md。

要求

要为 headscale 做贡献，你需要最新版本的 Go 和 Buf（Protobuf 生成器）。

我们推荐使用 Nix 来搭建开发环境。可以通过 nix develop 完成，它会安装所需工具并为你提供一个 shell。这能保证你的开发环境与 headscale 维护者完全一致。

代码风格

为了在贡献数量不断增长的情况下保持一致性，本项目采用了以下 lint 和风格/格式规则：

Go 代码使用 golangci-lint 进行 lint，并使用 golangci-lint 的格式化工具（gofumpt、gci、goimports）进行格式化。请配置你的编辑器在开发时运行这些工具，并确保在提交任何代码前运行 make lint 和 make fmt。

Proto 代码使用 buf 进行 lint，并使用 clang-format 进行格式化。

文档使用 mdformat 进行格式化。

其余部分（Markdown、YAML 等）使用 prettier 进行格式化。

查看 .golangci.yaml 和 Makefile 以了解具体配置。

安装开发工具

Go
Buf
Protobuf 工具

安装并激活：

nix develop

测试与构建

项目的某些部分需要从 Protobuf 生成 Go 代码（如果在 proto/ 中进行了更改），并且必须使用以下命令（重新）生成：

make generate

注意：请将 gen/ 中的更改放在单独的提交中，以便于审查。

运行测试：

make test

构建该程序：

make build

开发工作流程

我们建议使用 Nix 进行依赖管理，以确保你拥有所有必需的工具。如果你更愿意自行管理依赖，可以直接使用 Make：

使用 Nix（推荐）：

nix develop
make test
make build

使用你自己的依赖：

make test
make build

如果缺少任何必需的工具，Makefile 会向你发出警告，并建议运行 nix develop。运行 make help 可查看所有可用的目标。

贡献者

使用 contrib.rocks 制作。