12 KiB
USAGE
配置文件
配置使用 TOML 格式，支持本地文件或远程 URL。
[core] — 核心配置
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
auth_key |
string | 是 | — | Tailscale / Headscale 授权密钥（可在控制面生成） |
control_url |
string | 否 | https://controlplane.tailscale.com |
控制面地址，使用 Headscale 时改为自建实例地址 |
hostname |
string | 否 | 本机主机名 | 在 Tailnet 中的节点名称 |
ephemeral |
bool | 否 | true |
节点是否临时节点，离开 Tailnet 后自动删除 |
accept_routes |
bool | 否 | true |
是否接受其他节点发布的子网路由 |
[dns] — DNS 解析配置
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
doh_servers |
[]string | 否 | [] |
DNS-over-HTTPS（RFC 8484）回落解析器地址列表，须为 http(s):// URL |
dst_addr 中的域名默认走 Tailnet 自身的 DNS 解析器（支持 MagicDNS 与 split-DNS）。当该解析器无法解析目标（例如宿主机本身没有可用的系统 DNS，或目标不在 Tailnet 的 split-DNS 路由内）时，会依次尝试 doh_servers 中配置的 DoH 端点解析公网域名。留空则关闭此回落。仅对原始域名发起 DoH 查询（Tailnet 内部 MagicDNS 名称无法通过 DoH 解析）。
[[forward.<name>]] — 转发规则（Tailscale → 本地）
将 Tailscale 上的流量转发到本地服务。<name> 为自定义标签名。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
protocol |
string | 是 | tcp 或 udp |
tailscale_port |
int | 是 | 在 Tailscale IP 上监听的端口，1-65535 |
local_addr |
string | 是 | 本地转发目标地址，host:port 格式 |
注意事项： 容器环境下 local_addr 中的 127.0.0.1 指向容器自身；若要转发到宿主机服务，需使用桥接网络的 host.docker.internal 或 host 模式下的真实 IP。
[[connect.<name>]] — 连接规则（本地 → Tailscale）
在本机监听端口，将接入的流量转发到 Tailnet 中的目标。<name> 为自定义标签名。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
protocol |
string | 是 | — | tcp、udp 或 minecraft |
local_port |
int | 是 | — | 本地监听端口，1-65535 |
dst_addr |
string | 是 | — | Tailscale 目标地址，host:port 格式，支持 MagicDNS 主机名（如 my-server.ts.net:8080） |
local_addr |
string | 否 | 127.0.0.1 |
监听 IP 地址，设为 0.0.0.0 可暴露到局域网 |
lan_enable |
bool | 否 | minecraft 时为 true，其余为 false |
启用 LAN 多播发现（Minecraft 专用） |
lan_motd |
string | 否 | Minecraft via Tailscale |
LAN 广播的 MOTD 文本 |
Minecraft 模式说明： protocol = "minecraft" 实质为 TCP 转发，额外在多播地址 224.0.2.60:4445（IPv4）和 ff75:230::60:4445（IPv6）上发送 LAN 广播，使局域网内的 Minecraft 客户端可直接发现服务器。
命令行参数
| 参数 | 默认值 | 说明 |
|---|---|---|
-c |
config.toml |
配置文件路径或 HTTP(S) URL |
-config-url |
构建时注入 | 远程配置 URL（-c 指定 URL 时优先使用 -c） |
-level |
info |
日志级别：debug、info、warn、error |
-json-format |
false |
使用 JSON 格式输出日志 |
-diagnose |
false |
输出 tsnet 内部调试信息（需 -level debug） |
配置来源
本地文件
tslink -c /path/to/config.toml
如果指定路径的文件不存在，tslink 会自动生成一份默认配置模板。
远程 URL
配置可通过 HTTP(S) 远程加载，启动后不会将密钥写入磁盘：
tslink -c https://example.com/tslink.toml
构建时注入
可在编译时注入默认配置 URL，适用于分发场景：
go build -ldflags "-X tslink/core.DefaultConfigURL=https://example.com/tslink.toml"
当未指定 -c 和 -config-url 时，自动使用该 URL。
完整示例
[core]
auth_key = "tskey-auth-..." # 必填，Tailscale 授权密钥
control_url = "https://controlplane.tailscale.com" # 可选，Headscale 用户改为自建实例
hostname = "" # 可选，留空使用本机主机名
ephemeral = true # 可选，临时节点
accept_routes = true # 可选，接受子网路由
[dns]
# 可选，Tailnet DNS 无法解析时回落到 DoH 解析公网域名；留空关闭
doh_servers = ["https://cloudflare-dns.com/dns-query", "https://dns.google/dns-query"]
# 示例1: 将 Tailnet 上 8080 端口的请求转发到本地 9090
[[forward.web]]
protocol = "tcp"
tailscale_port = 8080
local_addr = "127.0.0.1:9090"
# 示例2: 将 Tailnet 上的 UDP 流量转发到本地
[[forward.dns_udp]]
protocol = "udp"
tailscale_port = 5353
local_addr = "127.0.0.1:53"
# 示例3: 本机监听 9000，转发到 Tailnet 中某主机的 8080
[[connect.web]]
protocol = "tcp"
local_port = 9000
local_addr = "127.0.0.1" # 可选，仅本机可访问
dst_addr = "other-host.ts.net:8080"
# 示例4: 本机监听 0.0.0.0:25565，转发到 Tailnet 中的 Minecraft 服务器
[[connect.minecraft]]
protocol = "minecraft"
local_port = 25565
dst_addr = "mc-server.ts.net:25566"
lan_enable = true # 可选，启用 LAN 多播发现
lan_motd = "Minecraft via Tailscale" # 可选，自定义 MOTD
# 示例5: UDP 转发
[[connect.udp_example]]
protocol = "udp"
local_port = 24454
dst_addr = "tailnet-game.ts.net:24454"
容器部署
项目根目录提供了 docker-compose.yml，使用前需：
- 准备好
config.toml并放在项目根目录 - 根据配置中的
connect规则，修改docker-compose.yml中的ports:映射 - 启动：
docker compose up -d
也可以直接拉取镜像部署：
docker pull ghcr.io/saltedfishclub/tslink:latest
docker run -d \
--name tslink \
-v $(pwd)/config.toml:/etc/tslink/config.toml:ro \
-p 9000:9000 \
-p 25565:25565 \
ghcr.io/saltedfishclub/tslink:latest \
-c /etc/tslink/config.toml
图形界面 tslink-gui
tslink-gui 是可选的桌面前端，使用 Gio 直接绘制界面——不含 WebView、不打包浏览器，Linux / macOS / Windows 各是一个原生可执行文件（约 30 MB）。
它在自身进程内运行与无界面版完全相同的转发服务，因此配置文件、规则语义和行为都一致：
tslink-gui -c config.toml
命令行参数
除下列参数外，-c、-config-url、-level、-json-format、-diagnose 与无界面版含义相同。
| 参数 | 默认值 | 说明 |
|---|---|---|
-light |
false |
以浅色主题启动（默认深色） |
-ipinfo-token |
$IPINFO_TOKEN |
ipinfo.io 的 API Token，可选，用于提高归属地查询的速率限制 |
-pprof |
空 | 在指定地址暴露 net/http/pprof，如 127.0.0.1:6060。仅允许回环地址 |
无论 -level 设为什么，界面内的日志缓冲区始终按 debug 级别记录最近 20000 条，所以出问题后不必重启加 -level debug 再复现一次。
界面说明
| 页面 | 内容 |
|---|---|
| 概览 | 在线节点数、局域网服务器数、规则数、运行时长，以及最近一次诊断的结论 |
| 节点 | 每个 Tailscale 节点的在线状态、链路类型、实时延迟、抖动与丢包；顶部为多节点延迟图谱（最近 20 分钟，鼠标悬停可查看某一时刻的取值，点击图例可隐藏某个节点） |
| 局域网 | 监听 224.0.2.60:4445 / [ff75:230::60]:4445 的 Minecraft LAN 广播。由 tslink 自己广播的条目会标记为「本机广播」——配置了规则却听不到自己的广播，说明隧道或组播链路有问题 |
| 网络诊断 | 见下 |
| 日志 | 按级别、来源、关键字检索，复制 / 保存 / 上传 |
| 设置 | 主题、语言、版本与配置来源 |
启动过程中，界面显示分步进度的加载动画；实时日志以半透明浮层固定在底部，因此启动卡住时直接截图就包含了排查所需的信息。服务就绪后，浮层可通过标题栏按钮随时唤出。
网络诊断
点击「开始诊断」后并行执行以下检查，整体不超过 45 秒：
| 检查项 | 说明 |
|---|---|
| NAT 类型 | 依 RFC 5780 做映射行为与过滤行为探测，并映射到常见的完全锥形 / 地址限制 / 端口限制 / 对称型命名。对称型 NAT 会导致打洞失败、连接回退到 DERP 中继 |
| UDP 连通性 | 对国内与境外 STUN 服务器分别探测 IPv4/IPv6，并识别疑似被封锁的目标端口 |
| 本机出口地址 | 列出所有接口上的 IPv4 与 IPv6 地址，标注默认出口以及 CGNAT / Tailscale / 私有 / 公网等类型 |
| 端口映射 | 自行实现的 UPnP IGD（SSDP + SOAP）、NAT-PMP（RFC 6886）与 PCP（RFC 6887）探测，能拿到路由器型号与外部地址 |
| 境外连通性 | 以 cp.cloudflare.com/generate_204 为主，辅以 gstatic / Google，并用国内基准（小米 / 百度）区分「完全没网」与「只是出不了境」 |
| 出口 IP 与归属地 | 通过 STUN（裸 UDP，绕过 HTTP 代理）、强制 IPv4、强制 IPv6、以及走系统代理四种方式分别探测，再用 ipinfo.io（失败时回退 ip-api.com / ip.sb）查询归属地 |
| Tailscale 内部状态 | 直接调用 tailscale 自己的 netcheck，取得 DERP 各区域延迟、首选中继、门户劫持判定，以及它自己看到的 UPnP/PMP/PCP 结果 |
STUN 服务器同时包含国内与境外两组（小米、B 站、腾讯、芒果 TV、Cloudflare 任播 / Google、Cloudflare、Nextcloud、BlackBerry、SipNet、StunProtocol）。这不只是为了容错：当本机启用了代理或分流工具时，不同探测路径会得到不同的公网 IP，诊断页会把这种分歧单独标出来——这通常正是「为什么对端连不上我」的答案。
归属地查询会把你的公网 IP 发送给第三方服务。不希望如此时，勾选「不查询归属地」即可跳过。
出口 IP 的「不一致」判定按 IPv4 / IPv6 分别计算，双栈主机同时拥有一个 v4 和一个 v6 出口属于正常情况，不会被误报。
导出与分享日志
日志页提供三种导出方式，都会附带一段环境信息头（版本、系统、配置来源、运行阶段、节点数），以及最近一次的完整诊断报告：
- 复制到剪贴板
- 保存到文件：写入用户主目录，文件名形如
tslink-log-20260726-084500.txt - 上传并分享：依次尝试 0x0.st、paste.rs、dpaste.org、termbin.com，成功后返回链接并自动复制
导出默认开启「隐去密钥」，会移除 auth_key 等凭据以及形如 tskey-... 的字符串。上传是公开的——任何拿到链接的人都能看到内容，其中包含你的公网 IP 与内网地址，请自行判断。
从源码构建
Windows 无需额外依赖。macOS 需要 Xcode Command Line Tools。Linux 需要 X11 / Wayland / EGL 的开发头文件：
sudo apt install -y pkg-config libwayland-dev libx11-dev libx11-xcb-dev \
libxkbcommon-dev libxkbcommon-x11-dev libgles2-mesa-dev libegl1-mesa-dev \
libffi-dev libxcursor-dev libxrandr-dev libxinerama-dev libxi-dev libxxf86vm-dev
go build -o tslink-gui ./cmd/tslink-gui
界面语言默认跟随中文字体的可用性：找不到任何中文字体时自动切换为英文，以免显示成方块（也可在设置里手动切换）。
由于 Gio 依赖 CGO，GUI 无法像无界面版那样交叉编译，需要在目标平台上分别构建。