243 lines
12 KiB
Markdown
243 lines
12 KiB
Markdown
# USAGE
|
||
|
||
## 配置文件
|
||
|
||
配置使用 [TOML](https://toml.io) 格式，支持本地文件或远程 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`） |
|
||
|
||
## 配置来源
|
||
|
||
### 本地文件
|
||
|
||
```bash
|
||
tslink -c /path/to/config.toml
|
||
```
|
||
|
||
如果指定路径的文件不存在，tslink 会自动生成一份默认配置模板。
|
||
|
||
### 远程 URL
|
||
|
||
配置可通过 HTTP(S) 远程加载，启动后不会将密钥写入磁盘：
|
||
|
||
```bash
|
||
tslink -c https://example.com/tslink.toml
|
||
```
|
||
|
||
### 构建时注入
|
||
|
||
可在编译时注入默认配置 URL，适用于分发场景：
|
||
|
||
```bash
|
||
go build -ldflags "-X tslink/core.DefaultConfigURL=https://example.com/tslink.toml"
|
||
```
|
||
|
||
当未指定 `-c` 和 `-config-url` 时，自动使用该 URL。
|
||
|
||
## 完整示例
|
||
|
||
```toml
|
||
[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`，使用前需：
|
||
|
||
1. 准备好 `config.toml` 并放在项目根目录
|
||
2. 根据配置中的 `connect` 规则，修改 `docker-compose.yml` 中的 `ports:` 映射
|
||
3. 启动：
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
也可以直接拉取镜像部署：
|
||
|
||
```bash
|
||
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](https://gioui.org) 直接绘制界面——不含 WebView、不打包浏览器，Linux / macOS / Windows 各是一个原生可执行文件（约 30 MB）。
|
||
|
||
它在自身进程内运行与无界面版**完全相同**的转发服务，因此配置文件、规则语义和行为都一致：
|
||
|
||
```bash
|
||
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 的开发头文件：
|
||
|
||
```bash
|
||
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 无法像无界面版那样交叉编译，需要在目标平台上分别构建。
|