nativeToken auth, TCP/UDP tunnel semantics, reverse publish, and resumable logical streams.
配置
在一份配置里描述入站、出站和安全。先从 native 开始,再看 REALITY 与协议选择。
v0.5.0 · native + raw + reality
native + raw + reality + carrier.mode=autoThis is the recommended automatic stack in v0.5.0: one listen address, dual Reality carriers, QUIC preferred, TCP fallback, and optional resumable TCP streams. carrier.mode selects auto/tcp/quic while security.type stays reality. Without mux, Reality remains TCP-only.
Force TCP with carrier.mode=tcp, or force QUIC with carrier.mode=quic.
nativeToken auth, TCP/UDP tunnel semantics, reverse publish, and resumable logical streams.
rawRequired base transport for automatic dual carriers. Do not stack ws / h2 / h3 in this mode.
realityCamouflage keys/SNI/dest. Pair with carrier.mode for auto, TCP-only, or QUIC-only selection.
mode=autov0.5.0 generator path: Reality or TLS with carrier.mode=auto on one address; outbound carrier.prefer is adaptive by default.
mux.enabledMux enables dual-carrier and pooling. Optional mux.resume preserves eligible TCP flows across carrier replacement.
security.reality + carrier.mode="auto" + mux.enabled
Binds TCP and UDP on one address, prefers QUIC, falls back to Reality TCP with backoff, and probes to restore QUIC preference.
carrier.mode="tcp"
Uses only the Reality TCP carrier (security.type stays reality). Choose this when UDP is intentionally unavailable.
carrier.mode="quic" + mux.enabled
Uses the dedicated QUIC pool without TCP fallback. The server listen port must be reachable over UDP.
Automatic dual carriers need type=native, transport.type=raw, mux enabled, security.type=reality, and carrier.mode=auto (default for generators). Missing mux keeps ordinary TCP-only Reality.
Set carrier.mode to auto (QUIC-first with TCP fallback), tcp, or quic. security.type remains reality in all three cases. quic and auto require mux.enabled.
The inbound binds TCP and UDP to the same host:port. Clients race the same address over both carriers without a second listen entry.
Outbounds prefer the Reality QUIC carrier. When UDP is blocked or unhealthy, they fall back to Reality TCP with jittered exponential backoff, then probe to restore QUIC preference.
Both carriers share the same REALITY keys, short IDs, SNI, and dest. The camouflage destination should support HTTPS over TCP and HTTP/3 over UDP.
TCP streams, UDP relay, and reverse carriers follow the same automatic carrier policy when carrier.mode=auto.
carrier.mode=tcp forces Reality TCP only. carrier.mode=quic forces the dedicated QUIC pool without TCP fallback. security.type remains reality.
Top-level fields include log, resources, inbounds, outbounds, route, and dns. Unknown fields are rejected; resources.resumable_buffer_budget controls the shared replay-buffer budget.
inbound.address and outbound.address are both host:port arrays. Multiple addresses race as candidate entry points; use balance for independent nodes.
Components link through tags; via chains and balance members are checked for missing refs and cycles.
Load → Validate → Compile → Start. Listening begins only after validation succeeds.
FileConfig route
route.default_outbound 必填。rules 按声明顺序执行,第一条命中的规则选定其 outbound。mixed、socks5 与平台 TUN 的每条流都走这套路由器。native 入站在 route_mode 设为 rules 之前,把已接受的流送到默认出站。
规则保持文件中的顺序。命中后停止继续查找。一条只写了 outbound 的规则会匹配剩余的全部流,并挡住后面的规则。
inbound、network、principals、app 与目的地条件组用 AND 组合。同一数组内的值是 OR。domains、domain_regexes、domain_suffixes、ips、ip_cidrs 与 ip_ranges 组成同一个目的地条件组:任一命中即可。空的条件组不增加约束。
mixed、socks5 与平台 TUN 始终使用编译后的路由器。native 入站省略 route_mode 或设为 default 时,每条已接受的流都走 default_outbound。route_mode 为 rules 时,按每条 TCP flow 和每个固定目标 UDP association 选择。应用身份由嵌入方提供,不会写入 native、mux 或 UDP 帧。带 app 的规则在缺少该身份时不匹配。
type 为 blackhole 的出站拒绝 TCP,并丢弃 UDP。该流不会继续转到 direct 或其他出站。
dns.outbound 把拦截到的 DNS 固定到一个同时支持 TCP 与 UDP 的出站,并绕过路由规则。该出站不可用时,DNS 失败即关闭。启用 dns.fake_ip.enabled 后,A 与 AAAA 使用配置的 fake-IP 范围(省略时为 198.18.0.0/15 与 fc00::/18),之后发往这些地址的流会在路由选择前还原成域名。其他 DNS 报文仍走配置的路由。dns.strategy 为 prefer_ipv4、prefer_ipv6、ipv4_only 或 ipv6_only。TUN 上 TCP 或 UDP 53 端口的 DNS 进入同一路由器,除非被固定到 dns.outbound。
未知字段会被拒绝。匹配项就是本页列出的这些数组。geosite: 与 geoip: 前缀会被拒绝。一条 URI 只携带一个隧道端点;路由规则和 via 链留在 JSON 里。via 把该出站的拨号串起来,并会做环检查。Android 应用使用 Full Tunnel,不编辑这些规则。
default_outboundrulesrules[].outboundinboundnetworkdomainsdomain_suffixesdomain_regexesipsip_cidrsip_rangesappapp.idsapp.id_prefixesapp.platformsapp.attributesusers[].principalroute_modeprincipalsclient-route-split.jsonads.example 走 blackhole,RFC1918 前缀与 internal.example 走 direct,其余流走 native 出站。运行 config check 前请换上真实的 REALITY 公钥。
{
"log": { "level": "info" },
"inbounds": [
{
"tag": "local",
"type": "mixed",
"address": ["127.0.0.1:1080"],
"network": ["tcp", "udp"]
}
],
"outbounds": [
{
"tag": "proxy",
"type": "native",
"address": ["proxy.example.com:9443"],
"token": "change-me",
"transport": { "type": "raw" },
"carrier": { "mode": "auto", "prefer": "quic", "udp_mode": "auto" },
"mux": { "enabled": true },
"security": {
"type": "reality",
"server_name": "example.com",
"public_key": "REPLACE_WITH_SERVER_PUBLIC_KEY",
"short_id": "abcd1234",
"spider_x": "/"
}
},
{ "tag": "direct", "type": "direct" },
{ "tag": "block", "type": "blackhole" }
],
"route": {
"default_outbound": "proxy",
"rules": [
{ "domain_suffixes": ["ads.example"], "outbound": "block" },
{ "ip_cidrs": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"], "outbound": "direct" },
{ "domain_suffixes": ["internal.example"], "outbound": "direct" }
]
},
"dns": {}
}client-route-app.json普通 CLI 流没有应用身份,所以两条规则都不会命中,流量走 direct。嵌入方在 Android 上返回 com.example.reader 且属性 profile=work 时选择 direct。以 com.example.game. 开头的 ID 选择 block。
{
"log": { "level": "info" },
"inbounds": [
{
"tag": "local",
"type": "mixed",
"address": ["127.0.0.1:1080"],
"network": ["tcp", "udp"]
}
],
"outbounds": [
{ "tag": "direct", "type": "direct" },
{ "tag": "block", "type": "blackhole" }
],
"route": {
"default_outbound": "direct",
"rules": [
{
"app": {
"ids": ["com.example.reader"],
"platforms": ["android"],
"attributes": { "profile": ["work"] }
},
"outbound": "direct"
},
{
"app": { "id_prefixes": ["com.example.game."] },
"outbound": "block"
}
]
},
"dns": {}
}server-route-principal.jsonremote-access 使用 route_mode rules。已认证用户 alice 可以通过 direct 打开这两个前缀上的 TCP/UDP。其余已接受的流走 deny。这里只展示路由字段,并不导出家庭局域网。
{
"log": { "level": "info" },
"inbounds": [
{
"tag": "remote-access",
"type": "native",
"address": ["0.0.0.0:9443"],
"network": ["tcp", "udp"],
"users": [{ "principal": "alice", "id": "change-me" }],
"transport": { "type": "raw" },
"mux": { "enabled": true },
"route_mode": "rules"
}
],
"outbounds": [
{ "tag": "direct", "type": "direct", "network": ["tcp", "udp"] },
{ "tag": "deny", "type": "blackhole" }
],
"route": {
"default_outbound": "deny",
"rules": [
{
"inbound": ["remote-access"],
"principals": ["alice"],
"network": ["tcp", "udp"],
"ip_cidrs": ["192.168.50.0/24", "fd12:3456:789a::/64"],
"outbound": "direct"
}
]
},
"dns": {}
}Native
Supports TCP / UDP and mux, with transport options raw / ws / h2 / h3. Server users[].id and client token must match.
users[].idtokenServer users[].id and client token must match.
address is a host:port array. Multiple addresses race as candidate entry points for the same service; they are not balance.
native + raw + mux + security.type=reality + carrier.mode=auto prefers QUIC, falls back to TCP, and shares one camouflage identity on both carriers.
mux.resume=true on both carrier.mode=auto peers can preserve an eligible TCP logical stream across carrier replacement (v0.3.0+).
Prefer native + raw + mux. Forced TLS / REALITY / ws / h2 / h3 add flexibility but cost more.
Server publish + client expose can hang NAT-side TCP/UDP services on edge listeners (requires mux).
Native QUIC
native + raw + reality + carrier.mode=quicForced QUIC is still the same layers: native is the tunnel protocol, raw is the transport, and security.type=reality stays REALITY. Select the dedicated QUIC pool with carrier.mode=quic and mux.enabled. There is no TCP fallback.
Carry TCP streams and UDP DATAGRAMs together without managing TLS certificates.
nativeHandles token auth, TCP / UDP tunnel semantics, and reverse publish.
rawRequired base transport for QUIC mode; do not stack ws / h2 / h3.
realityProtects the handshake with REALITY keys and site parameters; no cert deploy needed.
mode=quicUses a dedicated QUIC pool for streams and UDP DATAGRAMs. Requires mux.enabled.
{
"log": { "level": "info" },
"inbounds": [
{
"tag": "server",
"type": "native",
"address": ["0.0.0.0:9443"],
"network": ["tcp", "udp"],
"users": [{ "id": "change-me" }],
"transport": { "type": "raw" },
"mux": { "enabled": true }
}
],
"outbounds": [
{ "tag": "direct", "type": "direct" }
],
"route": { "default_outbound": "direct", "rules": [] },
"dns": {}
}The server exposes a native inbound; the client forwards a local mixed inbound to a native outbound. Replace the sample credentials and addresses to run.
Common field overview.
tagbothtypebothaddressbothnetworkbothtransportbothsecuritybothmuxbothaddressserverusers[].idserverpublishserversecurity.cert/keyserveraddressclienttokenclientsecurity.server_nameclientexposeclientcarrier.modebothcarrier.preferclientcarrier.udp_modeclientcarrier.*_receive_windowbothmux.max_sessionsclientmux.max_streams_per_sessionclientmux.warm_sparesclientmux.resumebothmux.resume_timeoutbothmux.resume_buffer_sizebothEnable mux for short-connection workloads. Prefer native + raw + mux for peak throughput.
Set mux.enabled=true. enabled is required and must be true; omit the mux field to disable it.
Reuses physical connections. Unreachable targets are not reported as success to the local proxy early.
native + raw + mux + security.type=reality + carrier.mode=auto prefers QUIC, falls back to Reality TCP with bounded backoff, then probes to restore QUIC preference.
mux.resume keeps eligible native TCP logical streams alive while an automatic Reality carrier is replaced. Enable matching settings on both peers.
carrier.mode=quic uses a UDP/QUIC connection pool and requires native + raw + mux.enabled; security.type may be tls or reality.
reliable uses streams; auto prefers DATAGRAM with fallback; datagram does not degrade. DATAGRAM supports fragmentation, recovery, and adaptive FEC.
"mux": {
"enabled": true,
"max_sessions": 4,
"max_streams_per_session": 128,
"warm_spares": 1
}v0.3.0 continuity
Add resume to matching carrier.mode=auto mux blocks to preserve an eligible TCP logical stream while its physical QUIC or TCP attachment is replaced.
native + raw + security.type=reality + carrier.mode=auto + mux only. UDP, reverse publish, and forced tcp/quic-only modes are not resumable.
Set mux.resume=true on both endpoints running v0.3.0+. There is no silent downgrade when only one peer enables it.
resume_timeout defaults to 15s (100ms–5m). resume_buffer_size defaults to 4 MiB (64 KiB–64 MiB).
The registry is process-local. Use one unique outbound address whose TCP and UDP paths reach the same server process.
"carrier": { "mode": "auto" },
"mux": {
"enabled": true,
"resume": true,
"resume_timeout": "15s",
"resume_buffer_size": 4194304
}Hang NAT-side TCP/UDP services on tunnel server listen ports. Configure publish on the server and expose on the client.
Only native + raw, and mux must be enabled.
Server publish and client expose service names must match, and network must match as well (default tcp).
The client local target is not sent to the server; the server can only open allowlisted services.
QUIC reverse publish needs matching TLS or REALITY plus carrier.mode=quic (or auto) on both ends; TLS servers need cert/key.
Generate → validate → start.
Writes server.json and client.json.
tcptun config native --server proxy.example.com --port 9443Does not listen; useful after editing a config.
tcptun config check --config server.jsonWrites matching REALITY configs with carrier.mode=quic and mux enabled.
tcptun config native --quic --server proxy.example.com --port 9443Start the server first, then the client.
tcptun --config server.json
tcptun --config client.jsonExports URIs from tunnel outbounds; multiple addresses become multiple URIs.
tcptun uri export --config client.json --output client.uriREALITY
Configured under security for native + raw. Pair with carrier.mode for auto, TCP-only, or QUIC-only.
transport must be raw and cannot be combined with ws / h2 / h3.
Plain reality cannot stack with security.type=tls; choose exactly one security type.
Works with native tunnel endpoints. mixed and socks5 are unsupported for URI export.
Server private_key pairs with client public_key; short_id must match on both ends.
On native + raw + mux + security.type=reality + carrier.mode=auto, dual carriers enable QUIC-first with TCP fallback. Without mux, Reality stays TCP-only.
carrier.mode=tcp forces Reality TCP only. carrier.mode=quic forces the dedicated QUIC pool (no TCP fallback).
typeprivate_keyserver_namesshort_idsdestmax_time_difftypepublic_keyserver_nameshort_idspider_x{
"log": { "level": "info" },
"inbounds": [
{
"tag": "server",
"type": "native",
"address": ["0.0.0.0:9443"],
"network": ["tcp", "udp"],
"users": [{ "id": "change-me" }],
"transport": { "type": "raw" },
"security": {
"type": "reality",
"private_key": "REPLACE_WITH_SERVER_PRIVATE_KEY",
"server_names": ["example.com"],
"short_ids": ["abcd1234"],
"dest": "example.com:443",
"max_time_diff": "30s"
},
"carrier": { "mode": "auto" },
"mux": { "enabled": true }
}
],
"outbounds": [
{ "tag": "direct", "type": "direct", "network": ["tcp", "udp"] }
],
"route": { "default_outbound": "direct", "rules": [] },
"dns": {}
}Writes paired server.json and client.json; run tcptun uri export if you need URIs.
tcptun config native --server proxy.example.com --port 9443 --server-name example.com --dest example.com:443Generates matching REALITY configs for native on both ends.
tcptun config native --server proxy.example.com --port 9443 --server-name example.com --dest example.com:443Generates matching REALITY configs with carrier.mode=quic and mux enabled.
tcptun config native --quic --server proxy.example.com --port 9443 --server-name example.com --dest example.com:443Validate keys and fields first, then start.
tcptun config check --config server.json && tcptun --config server.jsonNative + raw + mux + security.type=reality with carrier.mode=auto is automatic QUIC-first with TCP fallback. Force a single carrier with carrier.mode=tcp or carrier.mode=quic. tcptun config native --quic generates the latter. Legacy security.type=reality-quic / mux.mode=quic aliases are not the current scheme.
Compare
隧道端点是 native。mixed 与 socks5 仍用于本地代理跳。
| 协议 | 凭证 | 互操作 | 默认安全 | Mux | 适合 |
|---|---|---|---|---|---|
native | token ↔ users[].id | tcptun only | raw + REALITY | Private mux, recommended | Throughput / reverse publish |
{
"tag": "proxy",
"type": "native",
"address": ["proxy.example.com:9443"],
"token": "change-me",
"transport": { "type": "raw" },
"mux": { "enabled": true }
}tcptun config native --server … --port …