headscale/config/config.yaml

---
# headscale will look for a configuration file named `config.yaml` (or `config.json`) in the following order:
#
# - `/etc/headscale`
# - `~/.headscale`
# - current working directory

# server_url: 給客戶端連線用的網址
# server_url: http://127.0.0.1:8080
server_url: https://headscale.lotimmy.com

# listen_addr: Headscale 綁定在哪個 IP:Port 等待連線
# listen_addr: 127.0.0.1:8080
listen_addr: 0.0.0.0:8080

# metrics_listen_addr: 提供 Prometheus 或其他監控系統抓取 metrics 的位址
# metrics_listen_addr: 127.0.0.1:9090
metrics_listen_addr: 0.0.0.0:9090

# grpc_listen_addr: Headscale 提供 gRPC API 的服務位址，通常給內部或管理工具使用
grpc_listen_addr: 0.0.0.0:50443
# grpc_listen_addr: 127.0.0.1:50443

# grpc_allow_insecure: 是否允許 gRPC 使用未加密連線（建議保持 false 確保安全）
grpc_allow_insecure: false

# noise: Headscale 使用 Noise 協議加密與客戶端的流量
noise:
  # private_key_path: Noise 私鑰路徑，缺少時會自動生成
  private_key_path: /var/lib/headscale/noise_private.key

# prefixes: 設定分配給節點的 IP 範圍（必須在 Tailscale 支援的範圍內）
prefixes:
  # v4: IPv4 分配範圍（預設 100.64.0.0/10）
  v4: 100.64.0.0/10
  # v6: IPv6 分配範圍（預設 fd7a:115c:a1e0::/48）
  v6: fd7a:115c:a1e0::/48

  # allocation: IP 分配策略（sequential 依序分配，random 隨機分配）
  allocation: sequential

# derp: DERP 是 Tailscale 用來在無法直連時的中繼伺服器設定
derp:
  # server: 內建的 DERP 伺服器設定
  server:
    # enabled: 是否啟用內建 DERP（需要 https/TLS）
    enabled: false

    # region_id: 內建 DERP 的區域 ID（避免與其他 DERP 衝突）
    region_id: 999

    # region_code: 區域代碼（會顯示在 Tailscale UI）
    region_code: "headscale"
    # region_name: 區域名稱（會顯示在 Tailscale UI）
    region_name: "Headscale Embedded DERP"

    # stun_listen_addr: STUN 服務的監聽位址（協助 NAT 穿透）
    stun_listen_addr: "0.0.0.0:3478"

    # private_key_path: 內建 DERP 使用的私鑰路徑，沒有會自動生成
    private_key_path: /var/lib/headscale/derp_server_private.key

    # automatically_add_embedded_derp_region: 是否自動把內建 DERP 加進 DERP map
    automatically_add_embedded_derp_region: true

    # ipv4: 可選，將公開 IPv4 加入 DERP map（改善 Exit-Node 或 DNS 問題時的連線穩定性）
    ipv4: 1.2.3.4
    # ipv6: 可選，將公開 IPv6 加入 DERP map
    ipv6: 2001:db8::1

  # urls: 外部可用的 DERP map JSON 清單
  urls:
    - https://controlplane.tailscale.com/derpmap/default

  # paths: 本地的 DERP map YAML 檔路徑（通常用在自建 DERP 伺服器）
  paths: []

  # auto_update_enabled: 是否自動定期更新 DERP map
  auto_update_enabled: true

  # update_frequency: DERP map 更新檢查頻率
  update_frequency: 24h

# disable_check_updates: 是否停用 Headscale 啟動時自動檢查更新
disable_check_updates: false

# ephemeral_node_inactivity_timeout: 臨時節點（ephemeral node）多久沒活動就自動刪除
ephemeral_node_inactivity_timeout: 30m

database:
  # type: 資料庫類型（可選 sqlite 或 postgres，建議用 sqlite）
  type: sqlite

  # debug: 是否啟用資料庫偵錯（需搭配 log.level=debug/trace）
  debug: false

  gorm:
    # prepare_stmt: 是否啟用 prepared statements
    prepare_stmt: true

    # parameterized_queries: 是否啟用參數化查詢（提升安全性與效能）
    parameterized_queries: true

    # skip_err_record_not_found: 是否略過「record not found」錯誤訊息
    skip_err_record_not_found: true

    # slow_threshold: 慢查詢閾值（毫秒）
    slow_threshold: 1000

  sqlite:
    # path: SQLite 資料庫檔案的存放路徑
    path: /var/lib/headscale/db.sqlite

    # write_ahead_log: 是否啟用 WAL 模式（建議正式環境開啟，效能與穩定性更好）
    write_ahead_log: true

    # wal_autocheckpoint: WAL 自動 checkpoint 閾值（單位 frame，0 代表停用自動 checkpoint）
    wal_autocheckpoint: 1000

# acme_url: ACME 伺服器 URL（預設使用 Let's Encrypt）
acme_url: https://acme-v02.api.letsencrypt.org/directory

# acme_email: 註冊 ACME 憑證時的聯絡 email
acme_email: ""

# tls_letsencrypt_hostname: 要申請憑證的網域名稱
tls_letsencrypt_hostname: ""

# tls_letsencrypt_cache_dir: 存放憑證與 metadata 的路徑
tls_letsencrypt_cache_dir: /var/lib/headscale/cache

# tls_letsencrypt_challenge_type: ACME 驗證方式（支援 HTTP-01 或 TLS-ALPN-01）
tls_letsencrypt_challenge_type: HTTP-01
# tls_letsencrypt_listen: HTTP-01 驗證時使用的監聽位址（預設 80 port）
tls_letsencrypt_listen: ":http"

# tls_cert_path: 已有憑證的檔案路徑（選填，不用 Let's Encrypt 時使用）
tls_cert_path: ""
# tls_key_path: 已有私鑰的檔案路徑（選填，不用 Let's Encrypt 時使用）
tls_key_path: ""

log:
  # format: 日誌輸出格式（text 或 json）
  format: text
  # level: 日誌等級（常見有 debug、info、warn、error）
  level: info

policy:
  # mode: ACL 政策儲存方式（可選 file 或 database）
  mode: file
  # path: 當 mode=file 時，ACL HuJSON 檔案的路徑
  path: ""


dns:
  # 啟用 MagicDNS，讓節點自動有 hostname
  magic_dns: true

  # 要確定和 headscale server_url 不同網域，例如：
  # base_domain: example.com
  base_domain: internal.lotimmy.com

  # override_local_dns: 是否強制使用 Headscale 的 DNS，覆蓋本地設定
  # 如果希望 tailnet 裡所有節點都「強制」走這組 DNS，建議改成 true
  # 若你還想保留各節點自己的 DNS（例如公司 VPN、家裡路由器內網），就維持 false
  override_local_dns: true

  # nameservers.global: 全域 DNS 伺服器清單
  nameservers:
    global:

      # NextDNS（你的專屬 DoH Profile）
      - https://dns.nextdns.io/9c7b19   # NextDNS DoH：完整支援你的個人設定、封鎖清單、過濾規則

      # NextDNS IPv4 傳統 DNS（可作 fallback）
      - 45.90.28.37                     # NextDNS IPv4 主 DNS
      - 45.90.30.37                     # NextDNS IPv4 副 DNS


      # Cloudflare DNS（快速＋穩定）
      - 1.1.1.1                         # Cloudflare IPv4 主 DNS（fallback）
      - 1.0.0.1                         # Cloudflare IPv4 副 DNS
      - 2606:4700:4700::1111            # Cloudflare IPv6 主 DNS
      - 2606:4700:4700::1001            # Cloudflare IPv6 副 DNS
      - https://cloudflare-dns.com/dns-query   # Cloudflare DoH：快速＋加密

      # Google DNS（可靠但不做安全過濾）
      - https://dns.google/dns-query    # Google DoH：高穩定度 fallback

      # Quad9 DNS（帶惡意網站安全過濾）
      - https://dns.quad9.net/dns-query # Quad9 DoH：側重惡意網站與安全防護

    # nameservers.split: Split DNS，每個網域指定不同 DNS 伺服器
    split:
      {}
      # foo.bar.com:
      #   - 1.1.1.1
      # darp.headscale.net:
      #   - 1.1.1.1
      #   - 8.8.8.8

  # search_domains: 自訂搜尋網域（啟用 MagicDNS 時，base_domain 會自動加在最前面）
  search_domains: []

  # Extra DNS records
  # so far only A and AAAA records are supported (on the tailscale side)
  # See: docs/ref/dns.md
  # extra_records: 額外的 DNS 紀錄（支援 A 與 AAAA，可用檔案或直接寫在這裡）
  extra_records: []
  #   - name: "grafana.myvpn.example.com"
  #     type: "A"
  #     value: "100.64.0.3"
  #   - { name: "prometheus.myvpn.example.com", type: "A", value: "100.64.0.3" }

  # extra_records_path: 額外 DNS 紀錄的 JSON 檔路徑（檔案變更時會自動載入） 
  # extra_records_path: /var/lib/headscale/extra-records.json

# unix_socket: Headscale 提供本地 UNIX Socket 的路徑
unix_socket: /var/run/headscale/headscale.sock
# unix_socket_permission: UNIX Socket 的權限設定（例如 0770）
unix_socket_permission: "0770"

logtail:
  # enabled: 是否啟用 Logtail，把 client 日誌送到 Tailscale 官方伺服器（預設關閉）
  enabled: false

# randomize_client_port: 是否隨機使用 WireGuard port（預設 41641，開啟後會隨機挑 port，主要解決防火牆相容問題）
# randomize_client_port: false
randomize_client_port: true