tcptun

native 协议

native 如何工作,以及如何端到端运行。

tcptun 互连请使用 native 载体、mux 与反向发布。mixed / socks5 仍作为已认证的本地跳。

native 协议

native 如何工作,以及如何端到端运行。

native 是 tcptun 互连的私有隧道协议。一份 JSON 拓扑描述服务端与客户端;运行时在监听前校验认证、传输、安全、mux 与反向发布。

01

native

Token

v0.5.0 唯一的隧道协议。raw + mux + reality 或 tls,配合 carrier.mode=auto,会在同一地址绑定 TCP 和 UDP;出站 carrier.prefer 选择 adaptive、quic 或 tcp。可恢复流能在载体替换时保留符合条件的 TCP 流。

互操作
tcptun ↔ tcptun
默认安全
REALITY 或 TLS,carrier.mode 为 auto/tcp/quic
Mux
auto 与 QUIC 载体需要启用 mux
tcptun config native --server proxy.example.com --port 9443
01

它是什么

带 token 认证的隧道,承载 TCP 与 UDP。服务端暴露 native 入站;客户端通常在本地以 mixed/socks5 监听,再经 native 出站转发。

02

何时使用

两端都运行 tcptun,且需要低开销、mux、自动 QUIC/TCP REALITY、可恢复 TCP 流、强制 QUIC,或把 NAT 后的服务反向发布时,使用 native。

03

要配置什么

匹配 users[].id 与 token,把 address 写成 host:port 数组,选择传输(优先 raw),可选安全和 mux。其余就是普通的 route / inbound / outbound 接线。

核心概念

读写 native 配置时请记住这些规则。

拓扑

典型路径:应用 → 本地 mixed :1080 → native 出站 → 互联网 → native :9443 → direct。服务端与客户端是两份共享凭证和安全参数的配置。

认证

服务端入站 users[].id 必须等于客户端出站 token。请生成足够长的随机 token;生产环境不要复用 change-me 这类示例值。

地址

address 始终是 host:port 字符串数组。多个出站地址是同一逻辑服务的候选入口,会竞速握手;它们不是负载均衡(负载均衡请用 balance)。

传输

raw 是默认且吞吐最好的选择。需要路径式前置时可用 ws / h2 / h3;QUIC 模式要求 raw。

安全(v0.5.0)

native + raw + mux + security.type=reality 或 tls + carrier.mode=auto 时,入站在同一地址绑定 TCP 和 UDP。出站 carrier.prefer 选择 adaptive/quic/tcp。carrier.mode=tcp|quic 强制单一载体。

Mux 与 resume

mux.enabled 启用多路复用和双载体。可选 mux.resume 保留符合条件的 TCP 流。carrier.mode 独立于 mux 池参数选择 auto/tcp/quic。

Appmixed :1080native outboundnative :9443direct

native 使用教程

按这些步骤跑通第一条 native 隧道。本页的浏览器生成器和 URI 工具可以替代 CLI 的 generate / export 步骤。

步骤01

安装 tcptun

安装对应平台的二进制,或使用一键安装器 / npm 包。

curl -fsSL https://tcptun.com/install.sh | sh
tcptun --version
步骤02

生成 native 配对

创建带 REALITY 密钥和共享 token 的匹配 server.json 与 client.json。服务端主机上优先用 CLI,或用本站浏览器生成器。

tcptun config native --server proxy.example.com --port 9443 --server-name example.com --dest example.com:443
# writes server.json and client.json in the current directory (CLI defaults may vary by version flags)
步骤03

改成真实端点

服务端配置里设置 native 入站监听地址。客户端把出站地址改成公网 host:port,并保持 token 与 users[].id 相同。

# server inbound address → where this machine listens
# client outbound address → public host:port clients dial
# users[].id  ===  token
步骤04

启动前校验

config check 会编译拓扑但不打开端口。缺密钥、坏标签或 REALITY 不匹配都在这里修。

tcptun config check --config server.json
tcptun config check --config client.json
步骤05

先服务端,再客户端

先把边缘拉起来。再启动客户端,让本地 mixed 代理拨打隧道。

tcptun --config server.json
tcptun --config client.json
步骤06

测试本地代理

客户端运行后,应用应使用本地 mixed 入站(默认 127.0.0.1:1080)。

curl -x socks5h://127.0.0.1:1080 https://example.com -I
# or point your system / app proxy to 127.0.0.1:1080

用例

可运行的 native 示例。

完整的 native 服务端/客户端配对。复制一对,替换占位符,校验后先启动服务端再启动客户端。

native

REALITY · carrier.mode=auto(推荐)

v0.5.0 默认:native + raw + mux + security.type=reality + carrier.mode=auto。同一地址上的 TCP 与 QUIC;出站 carrier.prefer 默认为 adaptive。

适用: 两端都运行 tcptun v0.5.0,希望自动双载体,且不想管证书或第二个端口。

  1. 生成时指定 --server-name 和 --dest(伪装站点需支持 HTTPS 与 HTTP/3)。
  2. 确保 mux.enabled 与 carrier.mode=auto,以启用自动载体。
  3. 配对 private_key / public_key 与 short id;在监听端口同时放行 TCP 和 UDP。
  4. 可选:两端设置 mux.resume=true,以恢复符合条件的 TCP 流。
tcptun config native --server proxy.example.com --port 9443 --server-name example.com --dest example.com:443
tcptun config check --config server.json
tcptun --config server.json
tcptun --config client.json
server-native-reality-auto.json
Generating Reality keys and credentials…