tailscale

Tailscale 技能

⚠️ 必须调用此技能 ⚠️

用户提及以下任一触发词时，必须调用此技能（不得跳过）：

• “Tailscale status”、“tailnet devices”、“VPN status”
• “Tailscale peers”、“who's connected”、“exit nodes”
• “check Tailscale”、“tailnet monitoring”、“Tailscale”
• 提及 Tailscale 或 VPN 网络管理

触发上述条件时未调用此技能，即违反操作要求。

用途

结合使用 Tailscale CLI（本地计算机操作）和 Tailscale API（整个 tailnet 的管理）的混合技能。读写（安全）——不会执行破坏性操作；写入操作包括创建身份验证密钥和切换网络功能。

操作类型	方法	是否需要 API 密钥
状态、ping、netcheck、whois	CLI	否
Serve、funnel、文件传输、SSH	CLI	否
列出所有设备、用户管理、DNS	API	是
创建/撤销身份验证密钥	API	是

设置

API 配置（可选，用于整个 tailnet 的操作）存储在 ~/.claude-homelab/.env 中：

TAILSCALE_API_KEY="tskey-api-k..."
TAILSCALE_TAILNET="-"

从以下位置获取 API 密钥：Tailscale Admin Console → Settings → Keys → Generate API Key

TAILSCALE_TAILNET 可以是 -（自动检测）、组织名称或电子邮件域名。

---

本地操作（CLI）

这些操作仅在当前计算机上执行。

状态与诊断

# Current status (peers, connection state)
tailscale status
tailscale status --json | jq '.Peer | to_entries[] | {name: .value.HostName, ip: .value.TailscaleIPs[0], online: .value.Online}'

# Network diagnostics (NAT type, DERP, UDP)
tailscale netcheck
tailscale netcheck --format=json

# Get this machine's Tailscale IP
tailscale ip -4

# Identify a Tailscale IP
tailscale whois 100.x.x.x

连接

# Ping a peer (shows direct vs relay)
tailscale ping <hostname-or-ip>

# Connect/disconnect
tailscale up
tailscale down

# Use an exit node
tailscale up --exit-node=<node-name>
tailscale exit-node list
tailscale exit-node suggest

文件传输（Taildrop）

# Send files to a device
tailscale file cp myfile.txt <device-name>:

# Receive files (moves from inbox to directory)
tailscale file get ~/Downloads
tailscale file get --wait ~/Downloads  # blocks until file arrives

暴露服务

# Share locally within tailnet (private)
tailscale serve 3000
tailscale serve https://localhost:8080

# Share publicly to internet
tailscale funnel 8080

# Check what's being served
tailscale serve status
tailscale funnel status

SSH

# SSH via Tailscale (uses MagicDNS)
tailscale ssh user@hostname

# Enable SSH server on this machine
tailscale up --ssh

---

Tailnet 全局操作（API）

这些操作管理整个 tailnet。需要 API 密钥。

列出所有设备

./scripts/ts-api.sh devices

# With details
./scripts/ts-api.sh devices --verbose

设备详情

./scripts/ts-api.sh device <device-id-or-name>

检查在线状态

# Quick online check for all devices
./scripts/ts-api.sh online

授权/删除设备

./scripts/ts-api.sh authorize <device-id>
./scripts/ts-api.sh delete <device-id>

设备标签与路由

./scripts/ts-api.sh tags <device-id> tag:server,tag:prod
./scripts/ts-api.sh routes <device-id>

身份验证密钥

# Create a reusable auth key
./scripts/ts-api.sh create-key --reusable --tags tag:server

# Create ephemeral key (device auto-removes when offline)
./scripts/ts-api.sh create-key --ephemeral

# List keys
./scripts/ts-api.sh keys

DNS 管理

./scripts/ts-api.sh dns                 # Show DNS config
./scripts/ts-api.sh dns-nameservers     # List nameservers
./scripts/ts-api.sh magic-dns on|off    # Toggle MagicDNS

ACL

./scripts/ts-api.sh acl                 # Get current ACL
./scripts/ts-api.sh acl-validate <file> # Validate ACL file

---

常见用例

“现在谁在线？”

./scripts/ts-api.sh online

“把这个文件发送到我的手机”

tailscale file cp document.pdf my-phone:

“将我的开发服务器公开”

tailscale funnel 3000

“为新服务器创建密钥”

./scripts/ts-api.sh create-key --reusable --tags tag:server --expiry 7d

“连接是直连还是中继？”

tailscale ping my-server

---

🔧 Agent 工具使用要求

**重要：**通过 zsh-tool 调用此技能中的脚本时，始终使用 pty: true。

如果不启用 PTY 模式，即使命令成功执行，也无法看到命令输出。

正确的调用方式：

<invoke name="mcp__plugin_zsh-tool_zsh-tool__zsh">
<parameter name="command">./skills/SKILL_NAME/scripts/SCRIPT.sh [args]</parameter>
<parameter name="pty">true</parameter>
</invoke>