原文链接： headscale多租户改造，ACL、路由、DNS等全隔离

改造目标​

原始 headscale 默认是单实例、单 tailnet。多租户化的关键是把下面能力全部按租户隔离：

• tailnet 地址空间
• ACL 规则
• 路由配置
• MagicDNS 命名空间
• CLI 管理入口
• 中继服务策略

关键点​

tailnet​

• 每个租户独立 tailnet。
• 地址池可保持默认 10.64.0.0/10，也可以按租户自定义（例如 192.168.6.0/24）。
• 保留 default 租户，兼容原有单租户使用习惯。

ACL / 路由​

• ACL 按租户独立维护。
• 路由按租户独立配置与生效。

MagicDNS​

• FQDN 格式：hostname.<tenant_key>.<dns.base_domain>。
• default 租户使用 default 子域名。

CLI​

• 命令行增加租户参数（例如 -t 指定租户）。

中继服务器​

• 可选择共享中继。
• 也可为租户分配独立中继，实现更强隔离。

示例截图​

本文已同步到 Larktun 博客，原始内容与更新请以原文为准： headscale多租户改造，ACL、路由、DNS等全隔离

原文链接： headscale-系列：Headscale-SaaS-环境下的用户无缝切换实战

架构回顾​

• 用户域名（如 hsa.demo.com）统一解析到 Traefik。
• Traefik 按域名把流量转发到对应 headscale 节点。
• 后端通过 cluster_id 维度做数据隔离与迁移。

迁移难点​

即使热更新反向代理路由，已经建立的 TCP 长连接通常不会立刻切换到新后端。

实战迁移步骤​

1) 迁移用户数据​

# 从旧节点导出用户相关数据
pg_dump -h node3-db -U headscale -t nodes -t ip_addresses \
  --where="user_id = (SELECT id FROM users WHERE name = 'hsa')" \
  > hsa_data.sql

# 修改 cluster_id 并导入新节点
sed -i 's/cluster_id: 3/cluster_id: 4/g' hsa_data.sql
psql -h node4-db -U headscale -d headscale < hsa_data.sql

2) 热更新 Traefik 路由​

http:
  routers:
    hsa-router:
      rule: "Host(`hsa.demo.com`)"
      service: "headscale-cluster4"
      entryPoints: ["https"]

curl -X POST http://traefik/api/providers/file?dynamic=true

3) 在旧节点精准中断目标连接​

ss -K "dport = 7890 and src 203.0.113.5"

客户端通常会在数秒内自动重连到新节点，继续沿用 node key，不需要重新认证。

迁移效果（原文实测）​

• 迁移总时长：通常小于 15 秒
• 客户端中断：通常 1-5 秒
• 重新认证率：接近 0%

本文已同步到 Larktun 博客，原始内容与更新请以原文为准： headscale-系列：Headscale-SaaS-环境下的用户无缝切换实战

原文链接： headscale 系列：组建 headscale 集群，把设备接入能力做成“无限接近无限”

核心结论​

通过以下组合，可以把 headscale 逐步改造成接近 SaaS 形态的控制面：

• cluster_id 逻辑分片
• 共享 PG/PG 集群
• 接入控制程序（ACS）做分配与黏住
• DAO/ORM 层强制查询隔离
• netmap 计算从全量转为增量

架构要点​

1. 多个 headscale 节点并行运行，每个节点绑定独立 cluster_id。
2. 所有节点共享数据库，但查询必须显式包含 cluster_id。
3. ACS 负责首次接入分配、配额策略、区域与负载选择、租户黏住。
4. 配合 LISTEN/NOTIFY + 去抖合并，让 netmap 重建聚焦到受影响范围。

启动示例​

CLUSTER_ID=A \
PG_DSN="postgres://..." \
DERP_MAP_URL="https://derp.example.com/map.json" \
./headscale --config ./config.yaml

数据与查询隔离示例​

ALTER TABLE nodes ADD COLUMN cluster_id TEXT NOT NULL DEFAULT 'default';
CREATE INDEX idx_nodes_cluster_id ON nodes(cluster_id);

func (c *ClusterDB) Scoped() *gorm.DB {
  return c.db.Where("cluster_id = ?", c.clusterID)
}

netmap 增量化思路​

• 变更写入后触发 NOTIFY netmap_dirty(cluster_id, scope_key)。
• 节点只消费本 cluster_id 事件。
• 按 scope_key（用户、tag、路由域）做增量重建与推送。
• 引入缓存与版本号，避免重复全量构建。

演示截图​

相关链接​

• 项目地址： OwnDing/headscale-saas

本文已同步到 Larktun 博客，原始内容与更新请以原文为准： headscale 系列：组建 headscale 集群，把设备接入能力做成“无限接近无限”

原文链接： headscale系列：headsale压力测试

压测脚本​

• 脚本仓库： OwnDing/headscale-test-scripts

快速使用流程​

# 1) 准备配置
cp .env.example .env

# 2) 环境检查
bash scripts/00_check_env.sh

# 3) 拉起客户端（默认 200）
bash scripts/01_bootstrap_up.sh

# 4) 导出节点列表
bash scripts/02_list_nodes.sh

# 5) 抖动测试（终端 A）
bash scripts/03_churn.sh

# 6) 流量抽样（终端 B）
watch -n 20 'bash scripts/04_traffic_round.sh'

# 7) 清理
bash scripts/99_cleanup.sh

关键环境变量​

HEADSCALE_URL=https://headscale.example.com
TS_AUTHKEY=tskey-auth-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

REPLICAS=200
CHURN_INTERVAL=30
CHURN_BATCH_PERCENT=10
TRAFFIC_PAIR_COUNT=30
TRAFFIC_TCP_DURATION=10
TRAFFIC_TCP_PARALLEL=4
TRAFFIC_UDP_DURATION=10
TRAFFIC_UDP_BW=50M

推荐机器规格（200 设备）​

• 发压端：16 vCPU / 32 GB / 100 GB NVMe
• 被测 headscale：4 vCPU / 8 GB / 100 GB
• 可选 DERP：2-4 vCPU / 2-4 GB

脚本职责速览​

• 00_check_env.sh：检查 docker/compose/tun 并预拉镜像。
• 01_bootstrap_up.sh：按 REPLICAS 启动客户端容器。
• 02_list_nodes.sh：导出 nodes.tsv（容器名与 Tailnet IPv4）。
• 03_churn.sh：周期性随机 up/down/restart，模拟不稳定网络与节点波动。
• 04_traffic_round.sh：随机成对做 TCP/UDP 压力抽样。
• 99_cleanup.sh：停止并清理测试容器与 sidecar。

测试结果截图​

本文已同步到 Larktun 博客，原始内容与更新请以原文为准： headscale系列：headsale压力测试

原文链接： headscale系列：如何在headscale中使用MagicDNS

场景说明​

• 客户端登录后，除了用 IP 访问设备，也可以直接用主机名。
• 在 Windows 客户端中，tailscale 会把设备主机信息写入 hosts 文件。
• 当开启 4via6 等能力时，用自定义 DNS 名称映射会明显更省心。

开启 MagicDNS​

在 config.yaml 中开启 DNS 相关配置（下面是核心项）：

dns:
  magic_dns: true
  base_domain: example.com
  override_local_dns: false

  nameservers:
    global:
      - 1.1.1.1
      - 1.0.0.1

  search_domains: []
  extra_records_path: /var/lib/headscale/extra-records.json

建议使用 extra_records_path 指向外部 JSON 文件，便于后续动态维护记录。

extra-records.json 示例​

[
  {
    "name": "192-168-6-1-via-7",
    "type": "AAAA",
    "value": "fd7a:115c:a1e0:b1a:0:7:c0a8:601"
  }
]

• type 支持 A（IPv4）和 AAAA（IPv6）。
• 首次把配置从 extra_records 切换为 extra_records_path 时，建议重启一次 headscale。
• 后续只改 extra-records.json，通常不需要每次重启。

使用示例​

客户端上线后，可以通过自定义记录名直接访问目标设备服务。

本文已同步到 Larktun 博客，原始内容与更新请以原文为准： headscale系列：如何在headscale中使用MagicDNS

这篇文章记录一个更贴近官方体积的做法：使用 ko 构建 Headscale 容器镜像，而不是手写 Dockerfile。

原文链接： headscale系列：如何将源码编译的headscale打包成docker镜像

为什么使用 ko​

ko 是一个用于构建和打包 Go 应用的轻量工具，适合容器化场景（Docker / Kubernetes）。它可以直接把 Go 项目打包成镜像，省去 Dockerfile 维护成本。

ko 安装​

在普通用户环境下安装 ko：

go install github.com/google/ko@latest

安装后可在 ~/go/bin/ko 找到可执行文件。

使用 ko 打包 headscale​

在 Headscale 源码目录执行：

# --local 表示不推送镜像到仓库
/home/djc/go/bin/ko build --local ./cmd/headscale

构建完成后，会生成 ko.local/... 命名的本地镜像。可用 docker images 查看：

REPOSITORY                                            TAG                                                                IMAGE ID       CREATED      SIZE
headscale                                             v0.26.1-r                                                          bf66da388ca1   6 days ago   87.5MB
ko.local/headscale-f40b3d8640713cd381403459ebd67e78   38aefca56cab7d9b11692c61968915fb59fdf1dce134e52fed02ae2fa3a0e871   bf66da388ca1   6 days ago   87.5MB
ko.local/headscale-f40b3d8640713cd381403459ebd67e78   latest                                                             bf66da388ca1   6 days ago   87.5MB
ghcr.io/juanfont/headscale                            v0.26.1                                                            b9e7b75fd3b0   N/A          80.8MB

后续可通过 docker tag 给镜像重命名。

镜像运行要点​

运行时需要：

• config.yaml 配置文件
• /var/run/headscale/、/var/lib/headscale/ 的读写权限

可在 config.yaml 中把：

unix_socket: /var/run/headscale/headscale.sock

改成：

unix_socket: /var/lib/headscale/headscale.sock

这样运行容器时只挂载 /var/lib/headscale/ 即可：

docker run -d \
  -v ./headscale/config.yaml:/etc/headscale/config.yaml \
  -v ./doc:/var/lib/headscale \
  --name headscale \
  -p 8080:8080 \
  -p 9090:9090 \
  headscale:v0.26.1-r serve

参考​

• 源码编译文章： 使用 Headscale 源码自行编译打包

本文已同步到 Larktun 博客，原始内容与更新请以原文为准： headscale系列：如何将源码编译的headscale打包成docker镜像

原文链接： 使用Headscale源码自行编译打包

说明​

• 操作系统：Windows 11 + WSL2 Ubuntu 24.04 LTS
• 示例版本：Headscale v0.26.1
• 源码仓库：github.com/juanfont/headscale
• 建议使用 Git 克隆源码，不要直接下载压缩包

环境准备​

1) 下载源码​

git clone https://github.com/juanfont/headscale.git

# 使用 v0.26.1 的 tag
git checkout -b release-v0.26.1 v0.26.1

然后复制根目录下的 config-example.yaml 并重命名为 config.yaml。

2) WSL 配置​

在 Windows 用户目录（例如 C:\Users\XXX）创建 .wslconfig：

[wsl2]
nestedVirtualization=true
ipv6=true

[experimental]
autoMemoryReclaim=gradual
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

重启 WSL 后再继续编译流程。

3) 安装 Nix（Multi-user）​

sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon

参考：nixos.org/download

编译步骤​

编译时请使用普通用户（不要用 root 运行 make build）：

# 进入源码目录（WSL 中 Windows 盘通常在 /mnt/c 下）
cd /mnt/c/Users/XXX/Documents/develop/0me/headscale

# 进入构建环境
nix develop

make generate
make test
make build

# 查看产物
ls -la result/
cd result/bin
./headscale version

构建成功后会出现 result 目录。

运行说明​

将编译出的 headscale 二进制复制到目标服务器后，建议先检查依赖：

ldd headscale
file headscale

如果提示解释器路径依赖 Nix store，需要按实际提示补齐对应目录和链接器文件；另外确保 config.yaml、/root/.headscale/、/var/lib/headscale/ 等路径存在且权限正确。

打包为 Docker 镜像​

若你希望将源码编译结果打包成 Docker 镜像，可参考： headscale系列：如何将源码编译的headscale打包成docker镜像

编译异常汇总​

问题 1：dirtyShortRev missing​

make build 报错 attribute 'dirtyShortRev' missing 时，可在 flake.nix 中为版本号补充兜底：

headscaleVersion = if self ? shortRev
                  then self.shortRev
                  else if self ? dirtyShortRev
                  then self.dirtyShortRev
                  else "v0.26.1";

问题 2：测试阶段找不到 config.yaml​

当 make build 在测试阶段失败时，可先准备配置再构建：

cp config-example.yaml config.yaml
go mod tidy
go build -o headscale ./cmd/headscale

问题 3：nix-command 被禁用​

echo 'experimental-features = nix-command flakes' >> /etc/nix/nix.conf

请使用 root 用户执行上面的配置命令。

问题 4：找不到 flake.nix​

出现 could not find a flake.nix file 时，先 cd 到 Headscale 源码目录，再执行 nix develop。

问题 5：initdb 不能以 root 运行​

make build 中涉及 PostgreSQL 初始化时，不要用 root 用户运行构建与测试流程。

手动安装相关依赖​

# 安装 Buf
go install github.com/bufbuild/buf/cmd/buf@v1.55.1

# 安装 Protobuf
sudo apt update
sudo apt install protobuf-compiler

本文已同步至 Larktun 博客，原始内容与后续更新请以原文为准： 使用Headscale源码自行编译打包