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：互补的开源克隆
- 由 Kristoffer Dalby 演讲
Fosdem 2023（视频）：Headscale：我们如何使用集成测试重新实现 Tailscale
- 由 Juan Font Alonso 和 Kristoffer Dalby 演讲

免责声明

本项目与 Tailscale Inc. 无关。

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

维护者共同制定项目方向。基本原则是服务自托管者、爱好者和业余爱好者社区，同时保持项目的可持续性。

贡献

请阅读 CONTRIBUTING.md 文件。

要求

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

我们建议使用 Nix 来设置开发环境。可以通过 nix develop 完成，它将安装工具并为你提供一个 shell。这保证你的开发环境与 headscale 维护者相同。

代码风格

为了确保随着贡献数量的增长保持一致性，本项目采用了代码检查及风格/格式化规则：

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

Proto 代码使用 buf 进行代码检查，并使用 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 查看所有可用目标。

贡献者

Made with contrib.rocks.