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] [--debug]
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 后台。

隧道诊断

服务端默认记录每条转发的生命周期摘要,包括规则、两端、双向字节数、持续时间、关闭方和失败原因。Web 后台的“隧道诊断”页可以按失败、中断和正常关闭筛选。

需要排查偶发截断或断线时,以 Debug 模式启动:

xtun server --debug

--log debug 也会启用相同的隧道 Debug 记录。日志位于数据目录的 logs/tunnels/:

• tunnel-YYYY-MM-DD.jsonl:每条转发的摘要和失败记录
• tunnel-debug-YYYY-MM-DD.jsonl:建立、数据帧字节数和关闭事件

Debug 日志不保存转发正文、token 或密码,默认保留 7 天。逐帧元数据量较大,问题定位结束后应恢复普通模式。

服务端控制客户端升级

客户端默认允许服务端控制升级。直接运行时不需要增加额外参数:

xtun client --server https://relay.example.com

如果客户端由 systemd、PM2 或其他进程守护器负责重启,使用:

xtun client --server https://relay.example.com \
  --update-restart supervisor

登录 Web 后台的“客户端”页后,可以升级单台客户端或批量升级。服务端只会下发自身的稳定版本号;客户端从 npm 官方仓库安装 @xiabl/xtun。升级命令和状态经过会话加密,操作会写入审计日志。

• 全局 npm 安装和 npx 运行方式受支持;源码目录或未知安装方式不会自动改写。
• 如需禁止某台客户端被服务端升级,启动时添加 --no-remote-update。
• 默认的 self 模式会由当前客户端拉起新版,适合直接运行。
• supervisor 模式安装成功后退出,由外部进程守护器拉起新版,避免重复进程。
• 安装失败时旧客户端继续运行,后台显示 npm 返回的失败原因。
• 安装成功后先停止接收新隧道,最多等待 15 秒让现有 TCP 隧道结束,然后重启。
• 全局 npm 目录必须对运行客户端的系统用户可写;权限不足时升级会失败,但不会卸载旧版本。

数据目录

默认数据目录:

| 系统 | 路径 | |---|---| | 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 或日志里。

更多文档

• 协议说明