From e1cfd61d46996e31e00f7d246aa715fb0276255a Mon Sep 17 00:00:00 2001 From: nc Date: Wed, 10 Jun 2026 15:38:43 +0800 Subject: [PATCH] add USAGE.md --- USAGE.md | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 USAGE.md diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 0000000..b1ada1b --- /dev/null +++ b/USAGE.md @@ -0,0 +1,149 @@ +# 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` | 是否接受其他节点发布的子网路由 | + +### `[[forward.]]` — 转发规则（Tailscale → 本地） + +将 Tailscale 上的流量转发到本地服务。`` 为自定义标签名。 + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `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.]]` — 连接规则（本地 → Tailscale） + +在本机监听端口，将接入的流量转发到 Tailnet 中的目标。`` 为自定义标签名。 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|------|------|------|--------|------| +| `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 # 可选，接受子网路由 + +# 示例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 +```