Skip to content

📦 适配 Tailscale 的 Headscale 容器服务配置文件（新手友好版）

Headscale 是 Tailscale 的 自建控制服务器（替代官方控制台），以下配置可与你的 Tailscale 容器无缝适配，实现 “自建控制 + 节点互联” 的完整私有虚拟网络。配置包含 Headscale 核心服务与依赖的 PostgreSQL 数据库（Headscale 需数据库存储节点 / 网络数据），所有参数均带详细注释，新手可按步骤直接使用。

一、Headscale 容器配置文件（docker-compose.yml）

version: "3.8"  # 兼容主流 Docker Compose 版本

# 自定义网络：让 Headscale 与数据库在同一网络内通信，避免端口暴露风险
networks:
  headscale-network:
    driver: bridge  # 桥接模式，适合容器间内部通信

services:
  # 1. PostgreSQL 数据库服务（Headscale 依赖，存储节点/网络/ACL 数据）
  headscale-db:
    image: postgres:16-alpine  # 轻量版 PostgreSQL，适合容器部署
    container_name: headscale-db  # 容器名，便于管理
    restart: unless-stopped  # 容器退出自动重启，保障数据服务稳定
    environment:
      # 数据库核心配置（新手建议修改 POSTGRES_PASSWORD 为强密码，如 HeadscaleDB@2024!）
      - POSTGRES_USER=headscale  # 数据库用户名（需与 Headscale 配置一致）
      - POSTGRES_PASSWORD=headscale123  # 数据库密码（重要！生产环境务必修改）
      - POSTGRES_DB=headscale  # 数据库名（需与 Headscale 配置一致）
      - PGDATA=/var/lib/postgresql/data/headscale  # 数据库数据存储路径
    volumes:
      # 数据持久化：本地目录 → 容器目录，避免容器删除后数据丢失
      - ./headscale/db:/var/lib/postgresql/data/headscale
    networks:
      - headscale-network  # 加入自定义网络，仅与 Headscale 通信
    healthcheck:
      # 健康检查：确保数据库启动成功后，Headscale 再启动（避免连接失败）
      test: ["CMD-SHELL", "pg_isready -U headscale -d headscale"]
      interval: 10s
      timeout: 5s
      retries: 5

  # 2. Headscale 控制服务器服务（核心，适配你的 Tailscale 容器）
  headscale:
    image: headscale/headscale:latest  # Headscale 官方最新镜像，功能同步更新
    container_name: headscale  # 容器名，便于管理
    restart: unless-stopped  # 容器退出自动重启，保障控制服务稳定
    depends_on:
      headscale-db:
        condition: service_healthy  # 等待数据库健康检查通过后再启动
    environment:
      # 1. 数据库连接配置（需与上方 PostgreSQL 配置完全一致）
      - HEADSCALE_DB_HOST=headscale-db  # 数据库地址：直接用数据库容器名（同一网络内可解析）
      - HEADSCALE_DB_USER=headscale  # 数据库用户名
      - HEADSCALE_DB_PASS=headscale123  # 数据库密码（与上方 POSTGRES_PASSWORD 一致）
      - HEADSCALE_DB_NAME=headscale  # 数据库名
      - HEADSCALE_DB_TYPE=postgres  # 数据库类型（固定为 postgres）

      # 2. Headscale 核心配置（新手无需修改，按注释理解即可）
      - HEADSCALE_ADDR=0.0.0.0:8080  # Headscale 控制端口（容器内端口，固定 8080）
      - HEADSCALE_BASE_PATH_URL=http://192.168.10.100:8080  # 关键！替换为你的 Headscale 服务器 IP:8080（Tailscale 需连接此地址）
      - HEADSCALE_LOG_LEVEL=info  # 日志级别（info 适合新手，排错时可改为 debug）
      - HEADSCALE_SERVER_URL=http://headscale:8080  # 容器内自我访问地址（固定，无需修改）
      - HEADSCALE_ACL_PATH=/etc/headscale/acl.yaml  # ACL 权限配置文件路径（控制节点访问权限）
    ports:
      # 端口映射：主机 8080 → 容器 8080（Tailscale 节点需访问此端口注册）
      - "8080:8080/tcp"
      # 可选：gRPC 端口（用于 Headscale 集群，单节点部署可注释）
      - "9090:9090/tcp"
    volumes:
      # 1. 配置文件挂载：本地目录存储 Headscale 核心配置（需手动创建 acl.yaml）
      - ./headscale/config:/etc/headscale
      # 2. 数据持久化：本地目录存储 Headscale 运行数据（如节点证书）
      - ./headscale/data:/var/lib/headscale
    networks:
      - headscale-network  # 加入自定义网络，与数据库通信
    cap_add:
      - NET_ADMIN  # 赋予网络管理权限（Headscale 需配置节点路由）

二、关键适配说明（与你的 Tailscale 容器联动）

你的 Tailscale 容器需修改 1 处配置，才能连接到自建 Headscale（而非官方控制台），步骤如下：

1.打开你的 Tailscale docker-compose.yml； 2.修改 TS_EXTRA_ARGS 环境变量，添加 --login-server 指向 Headscale 地址：

    environment:
      # 原配置保留，新增 --login-server 参数（替换为你的 Headscale 服务器 IP:8080）
      - TS_EXTRA_ARGS: --advertise-exit-node --login-server=http://192.168.10.100:8080

3.重启 Tailscale 容器生效：docker compose restart。

三、新手必做：准备 Headscale 配置文件（acl.yaml）

Headscale 需 acl.yaml 文件控制节点访问权限（默认允许所有节点互通，新手可直接用模板）：

1.在 Headscale 部署目录创建配置目录：

    # 假设 Headscale 部署目录为 /opt/headscale（可自定义）
    mkdir -p /opt/headscale/headscale/config

2.在 ./headscale/config 目录创建 acl.yaml，粘贴以下内容：

    # 新手友好版 ACL：允许所有节点互通（无权限限制）
    acls:
      - action: accept
        src: ["*"]  # 源节点（* 表示所有节点）
        dst: ["*:*"]  # 目标节点:端口（*:* 表示所有节点的所有端口）

四、部署步骤（新手按顺序执行）

1. 准备目录与权限

# 1. 创建 Headscale 部署主目录（示例：/opt/headscale）
mkdir -p /opt/headscale && cd /opt/headscale

# 2. 创建 Headscale 数据/配置目录（与配置文件中的 volumes 对应）
mkdir -p headscale/db headscale/config headscale/data

# 3. 赋予目录读写权限（避免容器无法写入数据）
sudo chmod -R 777 headscale

2. 启动 Headscale 服务

# 在 /opt/headscale 目录执行（确保 docker-compose.yml 已放在此目录）
docker compose up -d

3. 初始化 Headscale（创建第一个网络）

Headscale 启动后，需手动创建一个 “网络”（Tailscale 节点需加入此网络）：

# 进入 Headscale 容器
docker exec -it headscale /bin/sh

# 创建网络（示例网络名：my-private-net，可自定义）
headscale networks create my-private-net

# 查看网络（确认创建成功，会显示网络 ID 和名称）
headscale networks list

# 退出容器
exit

4. Tailscale 节点加入 Headscale 网络

1.查看 Tailscale 节点的 “注册命令”（在 Headscale 容器内执行）：

    docker exec -it headscale headscale nodes register --user 0 --network my-private-net
    # 输出示例：sudo tailscale up --login-server=http://192.168.10.100:8080 --authkey=abc123...

2.复制上述输出的 --authkey=abc123... 部分； 3.给你的 Tailscale 容器添加 TS_AUTHKEY 环境变量（替换为复制的 authkey）：

    environment:
      - TS_AUTHKEY: abc123...  # 替换为 Headscale 生成的 authkey

4.重启 Tailscale 容器，完成注册：docker compose restart。

五、验证适配结果

1.在 Headscale 容器内查看已注册的 Tailscale 节点：

    docker exec -it headscale headscale nodes list

2.若显示你的 Tailscale 节点（名称为 centos7，与你配置一致），状态为 online，则适配成功； 3.此时你的 Tailscale 节点已通过自建 Headscale 互联，可正常使用 “出口节点”“内网路由” 功能。

六、新手注意事项

  1. Headscale 地址修改：HEADSCALE_BASE_PATH_URL 必须填写 Headscale 服务器的 实际 IP（如公网 IP 或内网 IP），不可用 localhost 或 127.0.0.1；
  2. 数据库密码安全：POSTGRES_PASSWORD 和 HEADSCALE_DB_PASS 务必修改为强密码（如 Headscale@2024!），避免默认密码被破解；
  3. 端口开放：若 Tailscale 节点在外部网络（如公网），需开放 Headscale 服务器的 8080 端口（防火墙 / 安全组）；
  4. 日志排错：若 Tailscale 无法连接 Headscale，查看日志：
    • Headscale 日志：docker compose logs -f headscale
    • Tailscale 日志：docker compose logs -f tailscale。