🚀 使用 Docker Compose 部署 Headscale 控制服务器

下面我将为您提供一个与您现有 Tailscale 客户端容器完美适配的 Headscale 服务端配置方案。这个方案采用 Docker Compose 部署，包含 Web 管理界面，特别适合新手使用。

📦 基础服务配置

创建 docker-compose.yml 文件：

version: '3.9'

services:
  headscale:
    image: headscale/headscale:0.23.0-alpha5
    container_name: headscale
    volumes:
      - ./headscale/config:/etc/headscale
      - ./headscale/data:/var/lib/headscale
      - ./headscale/run:/var/run/headscale
    ports:
      - 8080:8080
      - 9090:9090  # 监控指标端口
      - 3478:3478/udp  # STUN 服务端口
    command: serve  # 新版本使用 serve 命令
    restart: unless-stopped
    networks:
      - tailscale-network

  headscale-admin:
    image: goodieshq/headscale-admin:latest
    container_name: headscale-admin
    ports:
      - 8000:80
    depends_on:
      - headscale
    restart: unless-stopped
    networks:
      - tailscale-network

networks:
  tailscale-network:
    driver: bridge

⚙️ 配置文件设置

创建目录和配置文件

# 创建配置目录
mkdir -p headscale/{config,data,run}

# 下载官方配置文件模板
cd headscale/config
wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
# 或使用 curl
curl https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml -o config.yaml

修改关键配置项

编辑 headscale/config/config.yaml，重点关注以下配置：

# 服务器 URL（重要：改为你的域名或服务器 IP）
server_url: http://your-server-ip:8080

# 监听地址
listen_addr: 0.0.0.0:8080

# 监控指标地址
metrics_listen_addr: 0.0.0.0:9090

# gRPC 监听地址
grpc_listen_addr: 0.0.0.0:50443

# 启用 MagicDNS
magic_dns: true
base_domain: your-base-domain.com

# 随机化客户端端口
randomize_client_port: true

# 数据库路径
db_path: /var/lib/headscale/db.sqlite

# DERP 配置
derp:
  server:
    enabled: true
    region_id: 999
    region_code: "selfhosted"
    region_name: "Self Hosted DERP"
    stun_listen_addr: ":3478"

🚀 启动与验证

启动服务

# 在 docker-compose.yml 所在目录执行
docker compose up -d

验证服务状态

检查容器运行状态 bash docker compose ps 应该看到 headscale 和 headscale-admin 容器都处于 Up 状态
查看服务日志 bash docker compose logs -f headscale
验证服务可达性 bash curl http://localhost:9090/metrics

🔧 初始化设置

创建用户和命名空间

# 进入 headscale 容器
docker exec -it headscale headscale users create myfirstuser

# 或使用命名空间（新版本）
docker exec -it headscale headscale namespaces create myfirstnamespace

生成认证密钥

# 创建可重用的认证密钥（有效期24小时）
docker exec -it headscale headscale preauthkeys create --user myfirstuser --reusable --expiration 24h

保存输出的认证密钥，后续客户端注册时会用到。

🌐 Web 管理界面配置

获取 API 密钥

# 在 Headscale 服务端生成 API 密钥
docker exec -it headscale headscale apikeys create

配置管理界面

访问 http://your-server-ip:8000
输入 Headscale 服务器地址：http://headscale:8080
填入上一步生成的 API 密钥
点击保存，出现左侧菜单即表示成功

🔗 客户端连接配置

修改 Tailscale 客户端配置

在您现有的 Tailscale 容器配置中，修改环境变量：

environment:
  # 使用自建 Headscale 服务器
  TS_AUTHKEY: your-generated-authkey  # 替换为实际生成的密钥
  TS_EXTRA_ARGS: --login-server=http://your-headscale-ip:8080 --advertise-exit-node
  TS_ROUTES: 192.168.10.0/24
  TS_STATE_DIR: /var/lib/tailscale
  TS_HOSTNAME: centos7

客户端注册方式

方法一：使用认证密钥（推荐）

# 客户端直接使用预生成密钥注册
tailscale up --login-server=http://your-headscale-ip:8080 --authkey=your-authkey

方法二：手动注册 1. 客户端执行注册命令 bash tailscale up --login-server=http://your-headscale-ip:8080 2. 在 Headscale 管理界面或命令行中批准设备注册

🛠️ 高级配置

反向代理配置（可选）

如果需要通过域名访问，可以配置 Nginx 反向代理：

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /admin {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

子网路由配置

如果客户端需要发布子网路由：

# 在客户端启用路由通告
tailscale up --advertise-routes=192.168.10.0/24 --login-server=http://your-headscale-ip:8080

# 在 Headscale 服务端启用路由
docker exec -it headscale headscale routes enable -r <route-id>

🔍 故障排查

常见问题解决

客户端连接失败
检查 server_url 配置是否正确
确认防火墙开放了 8080、9090、3478 端口
验证认证密钥是否有效且未过期
Web 管理界面无法连接
确认 API 密钥是否正确
检查 Headscale 服务是否正常运行
查看容器日志：docker compose logs headscale
DERP 服务异常
确保 3478 UDP 端口已开放
检查 DERP 配置是否正确启用

日志查看

# 查看 Headscale 详细日志
docker compose logs -f headscale

# 查看特定时间段的日志
docker compose logs --tail=50 headscale

这个配置方案与您现有的 Tailscale 客户端完全兼容，提供了完整的控制服务器功能，同时通过 Web 管理界面大大简化了管理操作。部署完成后，您就拥有了一个完全自托管的 Tailscale 网络环境。