Tailscale 配置参数详解

目标：系统梳理 Tailscale 的配置维度——tailscaled 守护进程参数、/etc/default/tailscaled、运行期偏好（tailscale up/set 的 --advertise-*、--accept-* 等）、TS_* 环境变量，并给出可直接落地的生产配置模板。参数含义与默认值均以实测 Tailscale 1.104.1 为准。

一、环境信息

二、前置条件

1. 已按《安装指南》或《Compose 部署指南》完成 Tailscale 安装并处于登录态（或至少告警进程就绪）。
2. 具备 root 权限查看/修改配置；tailscale CLI 参数属于运行期偏好，多数调整需登录后生效。
3. 了解 tailscale up 是「全量设置」——给任一参数即需给出它想保留的其余参数集或加 --reset；tailscale set 则只改显式指定的项（默认无默认值、更安全）。

💡 说明：本专栏三篇文章（安装 / Compose 部署 / 配置参数）面向同一 Tailscale 组件，本文专注「参数」本身，安装与部署流程见对应指南，本文不重复安装全文。

三、参数查看与修改方式

Tailscale 的配置分三层，对应三处查看/修改入口：

1. tailscaled 守护进程级（启动参数）：tailscaled --help 查看。真机在 /etc/default/tailscaled 的 FLAGS 里追加；亦可通过 TS_TAILSCALED_EXTRA_ARGS 环境变量透传。
2. 运行期网络偏好（tailscale up/set 参数）：tailscale up --help / tailscale set --help 查看。用 tailscale up 全量设置、tailscale set <单个参数> 增量设置，持久化于状态文件。
3. 系统策略 / 环境变量：/etc/tailscale/syspolicy.json；Compose 托管形态下，偏好经 TS_* 环境变量注入到官方镜像的 containerboot 入口（在 Compose 服务的 environment: 中写入，注入写法见本文「六、TS_* 环境变量」的示例；也可参考《Docker Compose 部署指南》篇）。

实测查看命令及头部回显：

tailscaled --help

Usage of tailscaled:
  -bird-socket string
        path of the bird unix socket
  -cleanup
        clean up system state and exit
  -config string
        path to config file, or 'vm:user-data' to use the VM's user-data (EC2); prefix with 'optional:' to boot unconfigured when the source is absent instead of failing
  -socket string
        path of the service unix socket (default "/var/run/tailscale/tailscaled.sock")
  -state string
        absolute path of state file; use 'kube:<secret-name>' ... or 'mem:' to not store state ...
  -statedir string
        path to directory for storage of config state, TLS certs, temporary incoming Taildrop files, etc.
  -tun string
        tunnel interface name; use "userspace-networking" (beta) to not use TUN (default "tailscale0")
  -verbose int
        log verbosity level; 0 is default, 1 or higher are increasingly verbose

⚠️ 注意：tailscaled 多数参数通常无需改动；日常调优先用 tailscale up/set。真正需要动 daemon 的场景主要是「改状态文件路径」「切用户态 TUN」「固定 UDP 端口」「调整日志级别」。

四、参数总览

4.1 tailscaled 守护进程参数（tailscaled --help 实测全量）

4.2 运行期偏好参数（tailscale up / tailscale set）

💡 说明：tailscale up 语义是「全量声明期望设置集合」：当你改了其中一个参数而未带 --reset 又缺了其他曾设过的参数时，会因默认值改变而报错。因此生产上要么用 tailscale up <当前全部参数> 每次全量给定，要么用 tailscale set 增量改单项。

五、核心参数分类详解

5.1 节点身份与命名（hostname / advertise-tags / auth-key）

• --hostname：控制组网里显示的名字，覆盖 hostname。
• --advertise-tags：申请 ACL 标签做 galore 权限管理，多数继成功需控制台允许；前缀 tag: 可省略自动补全。
• --auth-key：用认证密钥无交互登录；以 file: 开头可指向密钥文件，适合批量/无人值守部署。

sudo tailscale up --auth-key=tskey-auth-XXXXXXXXXXXXXXXXX --hostname=edge-r1
sudo tailscale up --advertise-tags=tag:eng,tag:ssh --reset

⚠️ 注意：认证密钥属敏感凭据，应经安全通道注入；命令历史/CI 日志中不要明文透传。

5.2 子网路由（advertise-routes / accept-routes / snat-subnet-routes）

• --advertise-routes=10.0.0.0/8,192.168.0.0/24：把本机可达子网广播给 tailnet，使对端经此节点访问这些网段（子网路由器）。子网前提系统要开启 IP 转发（见「七、生产配置模板」）。
• --accept-routes=true：让本机接受对端子网路由器广播的路由。
• --snat-subnet-routes：默认 true，对广播路由流量做源 NAT，避免反向路由问题。

sudo tailscale up --advertise-routes=10.0.0.0/8,192.168.0.0/24 --accept-routes=true

⚠️ 注意：广播较大子网或成为 exit node 时，控制台可能要求二次确认；确定无误可在 tailscale up 追加 --accept-risk=all 跳过确认。

5.3 出口节点（exit-node / advertise-exit-node）

• --advertise-exit-node=true：本机构为出口节点，让全网节点把上网流量经它转发。
• --exit-node=<对端节点>：本机作为客户端走指定出口节点；auto:any 表示自动挑选一个可用出口节点。
• --exit-node-allow-lan-access=true：走出口节点时仍允许访问本机所在的局域网设备。

# 本机是出口节点
sudo tailscale up --advertise-exit-node=true
# 客户端指定走该出口节点
sudo tailscale up --exit-node=edge-r1 --exit-node-allow-lan-access=true

5.4 DNS 与过滤（accept-dns / netfilter-mode / stateful-filtering）

• --accept-dns=true（默认）：接受控制台下发的 MagicDNS。若你不想让 Tailscale 接管系统 DNS，设 --accept-dns=false。
• --netfilter-mode：on（默认，tailscaled 自管 iptables/nftables）；nodivert（不接管转发）；off（完全由你自管防火墙，Compose 等托管形态常用 --netfilter-mode=off 配合 TS_TAILSCALED_EXTRA_ARGS）。
• --stateful-filtering=true：对子网路由器/出口节点的转发包做有状态过滤，提升安全性。

sudo tailscale up --accept-dns=false --netfilter-mode=on --stateful-filtering=true

5.5 安全与访问（shields-up / ssh / operator / report-posture）

• --shields-up=true：拒绝所有入站连接，出击后仅出向可用，安全默认。
• --ssh=true：启用内置 SSH，是否放行由控制台 ACL 策略决定。
• --operator=<user>：授权某普通用户无需 root 即可跑 tailscale up/status 等。
• --report-posture=true：上报设备姿态给控制台用于策略判定。

sudo tailscale set --ssh=true --shields-up=true
sudo tailscale up --operator=admin

六、TS_* 环境变量（Compose 托管形态）

在 Compose 托管形态下，Tailscale 官方镜像（tailscale/tailscale，入口 containerboot）通过 TS_* 环境变量注入上述偏好，containerboot 会据此自动代你执行 tailscale up ...，因此这些变量与真机 tailscale up 参数等价。核心映射：TS_ROUTES↔--advertise-routes、TS_EXTRA_ARGS↔tailscale up 其余参数、TS_TAILSCALED_EXTRA_ARGS↔tailscaled 参数。整理变量清单见下表，各变量在 Compose 编排里的注入写法见本节末尾示例（亦可参考《Docker Compose 部署指南》篇）。

⚠️ 注意：--tun 与 --netfilter-mode 属 tailscaled 参数，必须经 TS_TAILSCALED_EXTRA_ARGS 传递，而非影响 tailscale up 的 TS_EXTRA_ARGS。例如用户态模式设 TS_TAILSCALED_EXTRA_ARGS=--tun=userspace-networking --netfilter-mode=off。

在 Compose 编排文件里把这些 TS_* 变量写进服务的 environment:，即可在容器形态下注入上述偏好（敏感密钥经 .env 注入、不在 compose 写明文）：

services:
  tailscale:
    image: tailscale/tailscale:latest
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY}          # --auth-key 认证密钥，经 .env 注入
      - TS_STATE_DIR=/var/lib/tailscale   # --state 状态持久化目录
      - TS_HOSTNAME=edge-r1               # --hostname
      - TS_ROUTES=10.0.0.0/8,192.168.0.0/24  # --advertise-routes
      - TS_ACCEPT_DNS=true                # --accept-dns
      - TS_EXTRA_ARGS=--advertise-exit-node  # 追加给 tailscale up 的参数
      - TS_TAILSCALED_EXTRA_ARGS=--netfilter-mode=on  # 追加给 tailscaled 的参数

💡 说明：containerboot（tailscale/tailscale 镜像的入口）启动后读取上述 TS_* 变量并自动代你执行 tailscale up ...，因此这段 environment: 与真机按「七、生产配置模板」跑 tailscale up 的结果一致。${TS_AUTHKEY} 之类的敏感值不给默认值，而是放到项目根目录的 .env（示例内容：TS_AUTHKEY=tskey-auth-XXXXXXXXXXXXXXXXX），Compose 启动时自动读取该文件并注入 environment，从而避免把密钥明文写进 compose 或提交到仓库。

七、生产配置模板

模板 A：通用云端主机（子网路由器 + 出口节点）

适用场景：8GB 内存、通用 SSD 云主机，做组网边界（同时广播子网路由 + 全网出口）。开启内核 IP 转发：

sudo sysctl -w net.ipv4.ip_forward=1
echo 'net.ipv4.ip_forward=1' | sudo tee -a /etc/sysctl.conf

启动参数（全量）：

sudo tailscale up \
  --hostname=edge-r1 \
  --advertise-routes=10.0.0.0/8,192.168.0.0/24 \
  --advertise-exit-node=true \
  --accept-routes=true \
  --stateful-filtering=true \
  --accept-dns=true \
  --netfilter-mode=on

模板 B：仅需跳板访问的轻量节点（最小面）

适用场景：1GB 内存在线小机器，只回连管理，不被入站访问。配置简少、安全默认：

sudo tailscale up --hostname=bastion-n1 --shields-up=true

模板 C：可自建控制的离线环境

适用场景：内网隔离、用自建 Headscale 控制面。改控制服务器地址 + 认证密钥登录：

sudo tailscale up --login-server=https://control.internal.example.com --auth-key=tskey-auth-XXXXXXXXXXXXXXXXX --hostname=node-internal

⚠️ 注意：改 --login-server 后节点归属另一个 tailnet，原登录态会失效，需重新认证。

八、常见问题（FAQ）

Q1：tailscale up 改一个参数就报错（某设置会被改动）？ 因为 up 是全量设置。要么每次把所有期望参数都带上，要么用 tailscale set <单个参数> 增量改，或用 --reset 把其余恢复默认。

Q2：--advertise-routes 广播了但对端访问不通？ ① 确认本机已开启 net.ipv4.ip_forward=1；② 确认对端设了 --accept-routes=true；③ 排查 --snat-subnet-routes（默认 true，通常无需改）与云上安全组/宿主防火墙是否放行。

Q3：--advertise-exit-node 后网页要求二次确认？ --advertise-routes 广播大网段或 exit node 属高风险，控制台会确认。确认无误加 --accept-risk=all（或 lose-ssh）跳过，注意别在不明风险下随意加。

Q4：Compose 托管下 --netfilter-mode 怎么传？ 它是 tailscaled 参数，需写在 daemon 级入口（/etc/default/tailscaled 的 FLAGS，或环境变量 TS_TAILSCALED_EXTRA_ARGS），不能放进影响 tailscale up 的 TS_EXTRA_ARGS。

Q5：不想让 DNS 被接管怎么关？ sudo tailscale set --accept-dns=false（或 up 时带 --accept-dns=false）。关闭后 MagicDNS 不再写系统 resolver。

九、参考链接

• tailscale up / set 官方说明：https://tailscale.com/kb/1080/cli
• 子网路由器说明：https://tailscale.com/kb/1019/subnets
• 出口节点说明：https://tailscale.com/kb/1103/exit-nodes
• tailscaled 参数：tailscaled --help（实测 1.104.1）
• Compose 托管环境变量：见《Docker Compose 部署指南》篇