xtun

xtun 是一个 CLI 优先的端口转发 / 内网穿透工具。

它适合这种场景:你有一台公网机器,想把内网机器上的 TCP/UDP 端口安全地转给自己或临时访客使用。xtun 自带 Web 后台、客户端审核、临时 token、流量统计和帧级 AES-256-GCM 加密。

不适合:HTTP 反代、P2P 打洞、一键 GUI。HTTP 反代建议用 Caddy/Nginx;P2P 在 CGNAT 环境下成功率不可控。

安装

需要 Node.js 18 或更高版本。

npm 包名是 @xiabl/xtun,安装后的命令名是 xtun。

npm install -g @xiabl/xtun
xtun --help

也可以不安装,直接临时运行:

npx @xiabl/xtun --help

升级:

npm install -g @xiabl/xtun@latest

快速开始

下面例子把家里 NAS 的 192.168.1.10:5000 暴露给办公室,办公室访问 localhost:5000 就能连到 NAS。

1. 在公网机器启动 server

xtun server --port 8443

第一次启动会打印后台地址、用户名和密码,只显示一次:

xtun server initialized (first run)
admin URL : http://localhost:8443/aB3xK9mP/
username  : admin
password  : amber-falcon-7421

生产环境建议放到 Caddy/Nginx 后面,用 HTTPS 访问后台。

2. 内网机器连接 server

家里 NAS 所在机器:

xtun client --server http://公网IP:8443 --alias home

办公室机器:

xtun client --server http://公网IP:8443 --alias office

新 client 第一次连接会进入待审核状态。

3. 在 Web 后台批准 client

打开首次启动时打印的后台地址,登录后在“客户端”页批准 home 和 office。

批准后 client 会保存身份,以后重启不需要重复审核。

4. 新建转发规则

在 Web 后台“规则”页新建:

fromAlias = office
fromPort  = 5000
toAlias   = home
toHost    = 192.168.1.10
toPort    = 5000
protocol  = tcp

含义是:在 office 机器上监听 5000,流量经过公网 server 中继到 home,再由 home 连接 192.168.1.10:5000。

之后办公室机器访问:

curl http://127.0.0.1:5000

UDP 规则同理,把 protocol 选成 udp。

临时访客 token

如果只是临时给别人一个入口,不用让对方机器加入 client 列表。

在 Web 后台新建规则时选择 token 模式:

• toAlias / toHost / toPort:目标服务
• protocol:tcp 或 udp
• 要求审核:开启后,每台新访客设备第一次连接仍需要管理员批准
• 有效期:forever / 1d / 7d / 30d / 自定义时间

后台会生成一条 xtun connect ... 命令。对方安装后运行:

npm install -g @xiabl/xtun
xtun connect \
  --server http://公网IP:8443 \
  --token xtun_v_AbC123XyZ... \
  --local-port 25565

然后对方连接自己的 127.0.0.1:25565 即可。

同一台机器可以用同一个 token 同时启动多个入口,只要 --local-port 不同即可;管理员审批一次后,这台机器上的其他同 token 入口会复用审批状态。

token 泄露后任何人都可能使用。泄露时请在后台 rotate token 或删除规则。

常用命令

xtun server  [--port 8443] [--bind 0.0.0.0] [--data-dir DIR] [--host HOST]
xtun client  --server URL [--alias NAME] [--data-dir DIR] [--insecure-tls]
xtun connect --server URL --token TOKEN --local-port PORT
xtun admin   <subcommand>
xtun reset   <server|client> [--data-dir DIR] [--yes]
xtun --version

常用 admin 命令:

xtun admin login --server http://公网IP:8443/<slug> --user admin
xtun admin clients
xtun admin approve <hardwareId>
xtun admin rules
xtun admin audit

日常管理更推荐直接用 Web 后台。

数据目录

默认数据目录:

| 系统 | 路径 | |---|---| | macOS | ~/Library/Application Support/xtun | | Linux | ~/.local/share/xtun | | Windows | %APPDATA%\xtun |

可以用 --data-dir 或环境变量 XTUN_DATA_DIR 覆盖。

常见操作:

xtun reset server    # 重置 server 数据,后台 slug 和密码会重新生成
xtun reset client    # 清掉本机 client 身份,下次连接重新审核

升级 npm 包不会删除这些数据。

部署与安全提示

• 后台地址里的随机 slug 和管理员密码都要保存好。
• 生产环境建议用 Caddy/Nginx 提供 HTTPS,并把 xtun 绑定到 127.0.0.1。
• Web 后台的 Security 页可以配置管理后台 IP 白名单、查看登录历史、解锁失败登录锁定。
• xtun 0.4 起会加密转发的数据帧,但 server 作为中继仍然能看到明文。不要把 server 部署在你不信任的机器上。
• 在 Web 后台吊销 client 后,该设备会进入黑名单;如需让它重新接入,先删除这条客户端记录,再让对方重新连接并审批。
• 目标服务看到的来源 IP 通常是 127.0.0.1,不要在目标机器上依赖来源 IP 做安全策略。
• SSH 经 xtun 转发时,目标端 fail2ban 可能把 127.0.0.1 封掉导致自锁。建议关闭目标端 fail2ban 或加入 ignoreip = 127.0.0.1。
• 管理后台和 token 不要截图发到公开聊天、Issue 或日志里。

更多文档

• 协议说明