add USAGE.md
This commit is contained in:
nc
@@ -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.<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 # 可选，接受子网路由
|
||||
|
||||
# 示例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
|
||||
```
|
||||
Reference in New Issue
Block a user