diff --git a/config/config.yaml b/config/config.yaml index e6221ad..ffb0e92 100644 --- a/config/config.yaml +++ b/config/config.yaml @@ -5,293 +5,192 @@ # - `~/.headscale` # - current working directory -# The url clients will connect to. -# Typically this will be a domain like: -# -# https://myheadscale.example.com:443 -# +# server_url: 給客戶端連線用的網址 # server_url: http://127.0.0.1:8080 server_url: https://headscale.lotimmy.com -# Address to listen to / bind to on the server -# -# For production: -listen_addr: 0.0.0.0:8080 +# listen_addr: Headscale 綁定在哪個 IP:Port 等待連線 # listen_addr: 127.0.0.1:8080 +listen_addr: 0.0.0.0:8080 -# Address to listen to /metrics and /debug, you may want -# to keep this endpoint private to your internal network +# metrics_listen_addr: 提供 Prometheus 或其他監控系統抓取 metrics 的位址 # metrics_listen_addr: 127.0.0.1:9090 metrics_listen_addr: 0.0.0.0:9090 -# Address to listen for gRPC. -# gRPC is used for controlling a headscale server -# remotely with the CLI -# Note: Remote access _only_ works if you have -# valid certificates. -# -# For production: +# grpc_listen_addr: Headscale 提供 gRPC API 的服務位址，通常給內部或管理工具使用 grpc_listen_addr: 0.0.0.0:50443 # grpc_listen_addr: 127.0.0.1:50443 -# Allow the gRPC admin interface to run in INSECURE -# mode. This is not recommended as the traffic will -# be unencrypted. Only enable if you know what you -# are doing. +# grpc_allow_insecure: 是否允許 gRPC 使用未加密連線（建議保持 false 確保安全） grpc_allow_insecure: false -# The Noise section includes specific configuration for the -# TS2021 Noise protocol +# noise: Headscale 使用 Noise 協議加密與客戶端的流量 noise: - # The Noise private key is used to encrypt the traffic between headscale and - # Tailscale clients when using the new Noise-based protocol. A missing key - # will be automatically generated. + # private_key_path: Noise 私鑰路徑，缺少時會自動生成 private_key_path: /var/lib/headscale/noise_private.key -# List of IP prefixes to allocate tailaddresses from. -# Each prefix consists of either an IPv4 or IPv6 address, -# and the associated prefix length, delimited by a slash. -# It must be within IP ranges supported by the Tailscale -# client - i.e., subnets of 100.64.0.0/10 and fd7a:115c:a1e0::/48. -# See below: -# IPv6: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#LL81C52-L81C71 -# IPv4: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#L33 -# Any other range is NOT supported, and it will cause unexpected issues. +# 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 - # Strategy used for allocation of IPs to nodes, available options: - # - sequential (default): assigns the next free IP from the previous given IP. - # - random: assigns the next free IP from a pseudo-random IP generator (crypto/rand). + # allocation: IP 分配策略（sequential 依序分配，random 隨機分配） allocation: sequential -# DERP is a relay system that Tailscale uses when a direct -# connection cannot be established. -# https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp -# -# headscale needs a list of DERP servers that can be presented -# to the clients. +# derp: DERP 是 Tailscale 用來在無法直連時的中繼伺服器設定 derp: + # server: 內建的 DERP 伺服器設定 server: - # If enabled, runs the embedded DERP server and merges it into the rest of the DERP config - # The Headscale server_url defined above MUST be using https, DERP requires TLS to be in place + # enabled: 是否啟用內建 DERP（需要 https/TLS） enabled: false - # Region ID to use for the embedded DERP server. - # The local DERP prevails if the region ID collides with other region ID coming from - # the regular DERP config. + # region_id: 內建 DERP 的區域 ID（避免與其他 DERP 衝突） region_id: 999 - # Region code and name are displayed in the Tailscale UI to identify a DERP region + # region_code: 區域代碼（會顯示在 Tailscale UI） region_code: "headscale" + # region_name: 區域名稱（會顯示在 Tailscale UI） region_name: "Headscale Embedded DERP" - # Listens over UDP at the configured address for STUN connections - to help with NAT traversal. - # When the embedded DERP server is enabled stun_listen_addr MUST be defined. - # - # For more details on how this works, check this great article: https://tailscale.com/blog/how-tailscale-works/ + # stun_listen_addr: STUN 服務的監聽位址（協助 NAT 穿透） stun_listen_addr: "0.0.0.0:3478" - # Private key used to encrypt the traffic between headscale DERP and - # Tailscale clients. A missing key will be automatically generated. + # private_key_path: 內建 DERP 使用的私鑰路徑，沒有會自動生成 private_key_path: /var/lib/headscale/derp_server_private.key - # This flag can be used, so the DERP map entry for the embedded DERP server is not written automatically, - # it enables the creation of your very own DERP map entry using a locally available file with the parameter DERP.paths - # If you enable the DERP server and set this to false, it is required to add the DERP server to the DERP map using DERP.paths + # automatically_add_embedded_derp_region: 是否自動把內建 DERP 加進 DERP map automatically_add_embedded_derp_region: true - # For better connection stability (especially when using an Exit-Node and DNS is not working), - # it is possible to optionally add the public IPv4 and IPv6 address to the Derp-Map using: + # ipv4: 可選，將公開 IPv4 加入 DERP map（改善 Exit-Node 或 DNS 問題時的連線穩定性） ipv4: 1.2.3.4 + # ipv6: 可選，將公開 IPv6 加入 DERP map ipv6: 2001:db8::1 - # List of externally available DERP maps encoded in JSON + # urls: 外部可用的 DERP map JSON 清單 urls: - https://controlplane.tailscale.com/derpmap/default - # Locally available DERP map files encoded in YAML - # - # This option is mostly interesting for people hosting - # their own DERP servers: - # https://tailscale.com/kb/1118/custom-derp-servers/ - # - # paths: - # - /etc/headscale/derp-example.yaml + # paths: 本地的 DERP map YAML 檔路徑（通常用在自建 DERP 伺服器） paths: [] - # If enabled, a worker will be set up to periodically - # refresh the given sources and update the derpmap - # will be set up. + # auto_update_enabled: 是否自動定期更新 DERP map auto_update_enabled: true - # How often should we check for DERP updates? + # update_frequency: DERP map 更新檢查頻率 update_frequency: 24h -# Disables the automatic check for headscale updates on startup +# disable_check_updates: 是否停用 Headscale 啟動時自動檢查更新 disable_check_updates: false -# Time before an inactive ephemeral node is deleted? +# ephemeral_node_inactivity_timeout: 臨時節點（ephemeral node）多久沒活動就自動刪除 ephemeral_node_inactivity_timeout: 30m database: - # Database type. Available options: sqlite, postgres - # Please note that using Postgres is highly discouraged as it is only supported for legacy reasons. - # All new development, testing and optimisations are done with SQLite in mind. + # type: 資料庫類型（可選 sqlite 或 postgres，建議用 sqlite） type: sqlite - # Enable debug mode. This setting requires the log.level to be set to "debug" or "trace". + # debug: 是否啟用資料庫偵錯（需搭配 log.level=debug/trace） debug: false - # GORM configuration settings. gorm: - # Enable prepared statements. + # prepare_stmt: 是否啟用 prepared statements prepare_stmt: true - # Enable parameterized queries. + # parameterized_queries: 是否啟用參數化查詢（提升安全性與效能） parameterized_queries: true - # Skip logging "record not found" errors. + # skip_err_record_not_found: 是否略過「record not found」錯誤訊息 skip_err_record_not_found: true - # Threshold for slow queries in milliseconds. + # slow_threshold: 慢查詢閾值（毫秒） slow_threshold: 1000 - # SQLite config sqlite: + # path: SQLite 資料庫檔案的存放路徑 path: /var/lib/headscale/db.sqlite - # Enable WAL mode for SQLite. This is recommended for production environments. - # https://www.sqlite.org/wal.html + # write_ahead_log: 是否啟用 WAL 模式（建議正式環境開啟，效能與穩定性更好） write_ahead_log: true - # Maximum number of WAL file frames before the WAL file is automatically checkpointed. - # https://www.sqlite.org/c3ref/wal_autocheckpoint.html - # Set to 0 to disable automatic checkpointing. + # wal_autocheckpoint: WAL 自動 checkpoint 閾值（單位 frame，0 代表停用自動 checkpoint） wal_autocheckpoint: 1000 - # # Postgres config - # Please note that using Postgres is highly discouraged as it is only supported for legacy reasons. - # See database.type for more information. - # postgres: - # # If using a Unix socket to connect to Postgres, set the socket path in the 'host' field and leave 'port' blank. - # host: localhost - # port: 5432 - # name: headscale - # user: foo - # pass: bar - # max_open_conns: 10 - # max_idle_conns: 10 - # conn_max_idle_time_secs: 3600 - - # # If other 'sslmode' is required instead of 'require(true)' and 'disabled(false)', set the 'sslmode' you need - # # in the 'ssl' field. Refers to https://www.postgresql.org/docs/current/libpq-ssl.html Table 34.1. - # ssl: false - -### TLS configuration -# -## Let's encrypt / ACME -# -# headscale supports automatically requesting and setting up -# TLS for a domain with Let's Encrypt. -# -# URL to ACME directory +# acme_url: ACME 伺服器 URL（預設使用 Let's Encrypt） acme_url: https://acme-v02.api.letsencrypt.org/directory -# Email to register with ACME provider +# acme_email: 註冊 ACME 憑證時的聯絡 email acme_email: "" -# Domain name to request a TLS certificate for: +# tls_letsencrypt_hostname: 要申請憑證的網域名稱 tls_letsencrypt_hostname: "" -# Path to store certificates and metadata needed by -# letsencrypt -# For production: +# tls_letsencrypt_cache_dir: 存放憑證與 metadata 的路徑 tls_letsencrypt_cache_dir: /var/lib/headscale/cache -# Type of ACME challenge to use, currently supported types: -# HTTP-01 or TLS-ALPN-01 -# See: docs/ref/tls.md for more information +# tls_letsencrypt_challenge_type: ACME 驗證方式（支援 HTTP-01 或 TLS-ALPN-01） tls_letsencrypt_challenge_type: HTTP-01 -# When HTTP-01 challenge is chosen, letsencrypt must set up a -# verification endpoint, and it will be listening on: -# :http = port 80 +# tls_letsencrypt_listen: HTTP-01 驗證時使用的監聽位址（預設 80 port） tls_letsencrypt_listen: ":http" -## Use already defined certificates: +# tls_cert_path: 已有憑證的檔案路徑（選填，不用 Let's Encrypt 時使用） tls_cert_path: "" +# tls_key_path: 已有私鑰的檔案路徑（選填，不用 Let's Encrypt 時使用） tls_key_path: "" log: - # Output formatting for logs: text or json + # format: 日誌輸出格式（text 或 json） format: text + # level: 日誌等級（常見有 debug、info、warn、error） level: info -## Policy -# headscale supports Tailscale's ACL policies. -# Please have a look to their KB to better -# understand the concepts: https://tailscale.com/kb/1018/acls/ policy: - # The mode can be "file" or "database" that defines - # where the ACL policies are stored and read from. + # mode: ACL 政策儲存方式（可選 file 或 database） mode: file - # If the mode is set to "file", the path to a - # HuJSON file containing ACL policies. + # path: 當 mode=file 時，ACL HuJSON 檔案的路徑 path: "" -## DNS -# -# headscale supports Tailscale's DNS configuration and MagicDNS. -# Please have a look to their KB to better understand the concepts: -# -# - https://tailscale.com/kb/1054/dns/ -# - https://tailscale.com/kb/1081/magicdns/ -# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/ -# -# Please note that for the DNS configuration to have any effect, -# clients must have the `--accept-dns=true` option enabled. This is the -# default for the Tailscale client. This option is enabled by default -# in the Tailscale client. -# -# Setting _any_ of the configuration and `--accept-dns=true` on the -# clients will integrate with the DNS manager on the client or -# overwrite /etc/resolv.conf. -# https://tailscale.com/kb/1235/resolv-conf -# -# If you want stop Headscale from managing the DNS configuration -# all the fields under `dns` should be set to empty values. dns: - # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/). + # 啟用 MagicDNS，讓節點自動有 hostname magic_dns: true - # Defines the base domain to create the hostnames for MagicDNS. - # This domain _must_ be different from the server_url domain. - # `base_domain` must be a FQDN, without the trailing dot. - # The FQDN of the hosts will be - # `hostname.base_domain` (e.g., _myhost.example.com_). + # 要確定和 headscale server_url 不同網域，例如： # base_domain: example.com base_domain: internal.lotimmy.com - # Whether to use the local DNS settings of a node (default) or override the - # local DNS settings and force the use of Headscale's DNS configuration. - override_local_dns: false + # override_local_dns: 是否強制使用 Headscale 的 DNS，覆蓋本地設定 + # 如果希望 tailnet 裡所有節點都「強制」走這組 DNS，建議改成 true + # 若你還想保留各節點自己的 DNS（例如公司 VPN、家裡路由器內網），就維持 false + override_local_dns: true - # List of DNS servers to expose to clients. + # nameservers.global: 全域 DNS 伺服器清單 nameservers: global: - - 1.1.1.1 - - 1.0.0.1 - - 2606:4700:4700::1111 - - 2606:4700:4700::1001 - # NextDNS (see https://tailscale.com/kb/1218/nextdns/). - # "abc123" is example NextDNS ID, replace with yours. - # - https://dns.nextdns.io/abc123 + # NextDNS（你的專屬 DoH Profile） + - https://dns.nextdns.io/9c7b19 # NextDNS DoH：完整支援你的個人設定、封鎖清單、過濾規則 - # Split DNS (see https://tailscale.com/kb/1054/dns/), - # a map of domains and which DNS server to use for each. + # 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: @@ -300,110 +199,31 @@ dns: # - 1.1.1.1 # - 8.8.8.8 - # Set custom DNS search domains. With MagicDNS enabled, - # your tailnet base_domain is always the first search domain. + # 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" - # - # # you can also put it in one line # - { name: "prometheus.myvpn.example.com", type: "A", value: "100.64.0.3" } - # - # Alternatively, extra DNS records can be loaded from a JSON file. - # Headscale processes this file on each change. + + # extra_records_path: 額外 DNS 紀錄的 JSON 檔路徑（檔案變更時會自動載入） # extra_records_path: /var/lib/headscale/extra-records.json -# Unix socket used for the CLI to connect without authentication -# Note: for production you will want to set this to something like: +# unix_socket: Headscale 提供本地 UNIX Socket 的路徑 unix_socket: /var/run/headscale/headscale.sock +# unix_socket_permission: UNIX Socket 的權限設定（例如 0770） unix_socket_permission: "0770" -# -# headscale supports experimental OpenID connect support, -# it is still being tested and might have some bugs, please -# help us test it. -# OpenID Connect -# oidc: -# only_start_if_oidc_is_available: true -# issuer: "https://your-oidc.issuer.com/path" -# client_id: "your-oidc-client-id" -# client_secret: "your-oidc-client-secret" -# # Alternatively, set `client_secret_path` to read the secret from the file. -# # It resolves environment variables, making integration to systemd's -# # `LoadCredential` straightforward: -# client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret" -# # client_secret and client_secret_path are mutually exclusive. -# -# # The amount of time from a node is authenticated with OpenID until it -# # expires and needs to reauthenticate. -# # Setting the value to "0" will mean no expiry. -# expiry: 180d -# -# # Use the expiry from the token received from OpenID when the user logged -# # in, this will typically lead to frequent need to reauthenticate and should -# # only been enabled if you know what you are doing. -# # Note: enabling this will cause `oidc.expiry` to be ignored. -# use_expiry_from_token: false -# -# # Customize the scopes used in the OIDC flow, defaults to "openid", "profile" and "email" and add custom query -# # parameters to the Authorize Endpoint request. Scopes default to "openid", "profile" and "email". -# -# scope: ["openid", "profile", "email", "custom"] -# extra_params: -# domain_hint: example.com -# -# # List allowed principal domains and/or users. If an authenticated user's domain is not in this list, the -# # authentication request will be rejected. -# -# allowed_domains: -# - example.com -# # Note: Groups from keycloak have a leading '/' -# allowed_groups: -# - /headscale -# allowed_users: -# - alice@example.com -# -# # Optional: PKCE (Proof Key for Code Exchange) configuration -# # PKCE adds an additional layer of security to the OAuth 2.0 authorization code flow -# # by preventing authorization code interception attacks -# # See https://datatracker.ietf.org/doc/html/rfc7636 -# pkce: -# # Enable or disable PKCE support (default: false) -# enabled: false -# # PKCE method to use: -# # - plain: Use plain code verifier -# # - S256: Use SHA256 hashed code verifier (default, recommended) -# method: S256 -# -# # Map legacy users from pre-0.24.0 versions of headscale to the new OIDC users -# # by taking the username from the legacy user and matching it with the username -# # provided by the OIDC. This is useful when migrating from legacy users to OIDC -# # to force them using the unique identifier from the OIDC and to give them a -# # proper display name and picture if available. -# # Note that this will only work if the username from the legacy user is the same -# # and there is a possibility for account takeover should a username have changed -# # with the provider. -# # When this feature is disabled, it will cause all new logins to be created as new users. -# # Note this option will be removed in the future and should be set to false -# # on all new installations, or when all users have logged in with OIDC once. -# map_legacy_users: false -# Logtail configuration -# Logtail is Tailscales logging and auditing infrastructure, it allows the control panel -# to instruct tailscale nodes to log their activity to a remote server. logtail: - # Enable logtail for this headscales clients. - # As there is currently no support for overriding the log server in headscale, this is - # disabled by default. Enabling this will make your clients send logs to Tailscale Inc. + # enabled: 是否啟用 Logtail，把 client 日誌送到 Tailscale 官方伺服器（預設關閉） enabled: false -# Enabling this option makes devices prefer a random port for WireGuard traffic over the -# default static port 41641. This option is intended as a workaround for some buggy -# firewall devices. See https://tailscale.com/kb/1181/firewalls/ for more information. +# randomize_client_port: 是否隨機使用 WireGuard port（預設 41641，開啟後會隨機挑 port，主要解決防火牆相容問題） # randomize_client_port: false randomize_client_port: true