客户端配置参考

client.toml 所有字段的完整参考。

---

顶层字段

字段	类型	默认值	描述
server_address	string	"wss://localhost:443/api/v1/ws"	服务器的完整 WebSocket URL。必须包含协议 (wss://)、主机名、端口和路径。
sni_hostname	string	(来自 URL)	覆盖握手时发送的 TLS SNI 主机名。通过 IP 地址或 CDN 连接时有用。
identity_key_file	path	"identity.key"	客户端身份密钥的路径。通过 rvpn keygen 生成。
prekey_bundle	path	(none)	服务器 prekey-bundle.json 的路径。首次设置时必需。
server_public_key	string	(none)	十六进制编码的服务器公钥。当你只有原始密钥时可作为 prekey_bundle 的替代。
tls_fingerprint	string	"chrome"	要模拟的 TLS ClientHello 指纹。选项："chrome"、"firefox"、"safari"、"none"。为获得最佳 DPI 抗性，请使用 "chrome"。
data_dir	path	(平台默认)	运行时数据目录（已知主机、统计）。默认在 Linux 上为 ~/.local/share/rvpn/，在 macOS 上为 ~/Library/Application Support/rvpn/。

---

[socks5]

SOCKS5 代理设置。仅在 SOCKS5 模式（默认）下运行时生效。

字段	类型	默认值	描述
listen_address	string	"127.0.0.1:1080"	接受 SOCKS5 连接的地址和端口。使用 "0.0.0.0:1080" 可与网络内其他设备共享代理。
udp_associate	bool	true	启用 SOCKS5 UDP ASSOCIATE 命令（用于基于 UDP 的应用）。
auth_enabled	bool	false	要求 SOCKS5 客户端进行用户名/密码身份验证。
auth_username	string	(none)	当 auth_enabled = true 时的用户名。
auth_password	string	(none)	当 auth_enabled = true 时的密码。
multiplex	bool	false	为所有连接使用单个多路复用 WebSocket。启用时使用 0-RTT 流创建以降低延迟。默认 false——每连接一个 WebSocket 的流量模式与正常浏览混合。参见 连接模式。
mux_path	string	(auto)	覆盖 mux WebSocket 端点路径。仅在 multiplex = true 时使用。默认为 {server_path}/mux。

[socks5]
listen_address = "127.0.0.1:1080"
auth_enabled   = true
auth_username  = "alice"
auth_password  = "hunter2"

---

[http_proxy]

在 SOCKS5 代理旁运行的 HTTP/HTTPS 代理。默认关闭。启用后可使用 HTTP_PROXY/HTTPS_PROXY 环境变量实现系统范围或按工具的 VPN 路由。两个代理共享同一连接池——同时运行不会带来额外开销。

处理两种请求类型：

• HTTP CONNECT — 用于 HTTPS。客户端发送 CONNECT host:443 HTTP/1.1，代理与目标建立加密隧道。
• 明文 HTTP 转发 — 用于未加密的 HTTP。代理连接目标主机并转发请求。

两条路径均支持分流，并与 SOCKS5 使用相同的多路复用 WebSocket 隧道。

字段	类型	默认值	描述
enabled	bool	false	与 SOCKS5 代理一起启动 HTTP 代理。
listen_address	string	"127.0.0.1:8118"	接受 HTTP 代理连接的地址和端口。
auth_enabled	bool	false	要求 HTTP 代理客户端进行 Basic 身份验证。
auth_username	string	(none)	当 auth_enabled = true 时的用户名。
auth_password	string	(none)	当 auth_enabled = true 时的密码。
multiplex	bool	false	使用单个多路复用 WebSocket。推荐默认值 false——参见 连接模式。
mux_path	string	(auto)	覆盖 mux WebSocket 端点路径。仅在 multiplex = true 时使用。默认为 {server_path}/mux。

[http_proxy]
enabled        = true
listen_address = "127.0.0.1:8118"

带身份验证：

[http_proxy]
enabled        = true
listen_address = "127.0.0.1:8118"
auth_enabled   = true
auth_username  = "user"
auth_password  = "changeme"

请参见 HTTP 代理设置 了解如何配合环境变量和按应用配置使用。

---

[dns_proxy]

将 DNS 查询通过加密隧道路由，以防止 SOCKS5 模式下的 DNS 泄漏。默认关闭。

启用后，客户端在 listen_address 上监听 UDP DNS 查询，并使用与常规流量相同的 X3DH + Double Ratchet 加密将它们转发到服务器的 /dns WebSocket 端点。分流规则会被遵守：绕过域名在本地解析，被拦截的广告/跟踪域名立即返回 NXDOMAIN。

字段	类型	默认值	描述
enabled	bool	false	与 SOCKS5 代理一起启动本地 DNS 代理。
listen_address	string	"127.0.0.1:5353"	DNS 代理的 UDP 地址和端口。使用端口 53 可与系统范围兼容（需要 root 或 CAP_NET_BIND_SERVICE）。
nameservers	list	["223.5.5.5:53", "1.1.1.1:53", "8.8.8.8:53"]	用于绕过域名的公共 DNS 服务器。查询通过 UDP 直接发送以避免循环回到 DNS 代理自身。中国用户应将本地 DNS 放在前面（例如 119.29.29.29:53）。

[dns_proxy]
enabled        = true
listen_address = "127.0.0.1:53"
nameservers    = ["223.5.5.5:53", "1.1.1.1:53", "8.8.8.8:53"]

请参见 DNS 代理设置 了解如何将系统 DNS 指向此地址。

---

[tun]

TUN 接口设置。设置 enabled = true 即启用 TUN 模式。客户端 IP 地址、网关 IP 和 DNS 服务器由服务器通过 VirtualIp 消息动态分配——请勿手动设置。

字段	类型	默认值	描述
enabled	bool	false	启用全隧道（TUN）模式。所有 IP 流量都通过 VPN 路由。
interface_name	string	(自动)	TUN 接口名。留空则由操作系统分配——通常在 macOS 上为 utun0，在 Linux/FreeBSD 上为 tun0。若为防火墙规则需要指定名称，请设为具体值。
routes	list	["0.0.0.0/0"]	通过隧道发送的路由。默认路由所有流量。若要分流路由，请指定具体 CIDR。
mtu	integer	1420	TUN 接口的 MTU。较低值可减少高延迟链路上的分片。

[tun]
enabled = true
# interface_name = "vpn0"  # optional, defaults to OS-assigned name
mtu     = 1420
routes  = ["0.0.0.0/0"]

---

[split_tunnel]

控制哪些流量绕过 VPN 以及哪些被强制通过。

字段	类型	默认值	描述
enabled	bool	false	启用分流。其他分流设置必须在此为 true 时才会生效。
builtin_bypass_countries	list	["CN"]	自动绕过其 IP 范围的国家代码。使用 APNIC 数据。支持："CN"、"HK"、"TW"、"RU" 等。设为 [] 可禁用。
bypass_networks_file	path	(none)	CIDR 网络列表文件（每行一个）的路径，其中的网络直连，绕过 VPN。
bypass_domains_file	path	(none)	域名列表文件（每行一个）的路径，其中的域名直连。
tunnel_networks_file	path	(none)	强制通过 VPN 的 CIDR 网络列表文件的路径（覆盖绕过规则）。
tunnel_domains_file	path	(none)	强制通过 VPN 的域名列表文件的路径。
bypass_networks	list	[]	内联的绕过 CIDR 网络列表。与 bypass_networks_file 相同，但直接在配置中定义。
auto_reload_interval	integer	86400	重新加载绕过/隧道文件的频率（秒）。设为 0 可禁用自动重载。
block_ads	bool	false	在 DNS 层面拦截已知广告和跟踪域名。不向被拦截域名发送任何字节。
ad_block_file	path	(none)	自定义广告拦截列表（每行一个域名）的路径。当 block_ads = true 时与内置列表一起使用。

[split_tunnel]
enabled                  = true
builtin_bypass_countries = ["CN"]
block_ads                = true
bypass_networks_file     = "~/.config/rvpn/bypass-networks.txt"

---

[network]

客户端网络行为。

字段	类型	默认值	描述
ipv6_enabled	bool	true	启用通过代理的 IPv6 连接。
prefer_ipv4	bool	true	当同时可用 IPv4 和 IPv6 时，优先 IPv4。在大多数网络上可降低延迟。
dns_cache_enabled	bool	true	缓存 DNS 响应以减少重复查询。
dns_cache_ttl	integer	14400	DNS 条目的缓存时长（秒）。默认 4 小时。
dns_cache_size	integer	1000	DNS 缓存中的最大条目数。
dns_servers	list	[]	用于解析绕过域名（直连）的自定义上游 DNS 服务器。查询通过 UDP 直接发送到这些服务器，完全绕过系统解析器。留空则使用系统默认。当系统解析器不可靠或你想为中国流量使用特定 DNS 提供商时有用。

[network]
prefer_ipv4       = true
dns_cache_enabled = true
dns_cache_ttl     = 14400
dns_servers       = ["223.5.5.5", "223.6.6.6"]  # Alibaba DNS for CN bypass domains

---

[server_identity]

以 SSH 风格的 TOFU 固定服务器 Ed25519 身份密钥，一旦服务器出示不同的密钥即拒绝连接。完整模型（含运营方轮换仪式）请参考 服务器身份固定。

字段	类型	默认值	描述
fingerprint	string	(none)	采用规范 ik:1:<base32> 形式的期望固定值（例如 ik:1:d4rgmp5b7ta6qmxi2mccwkjq4qxopfxzr7qivbfgu4wjycmuxnla）。若设置，客户端会拒绝身份不匹配的连接。旧版 32 字符十六进制值仍会被读取并在保存时重写。
trust_on_first_use	bool	true	在首次连接时接受任意服务器身份并固定，供未来验证。
known_hosts_file	path	"known_hosts.json"	存储已固定服务器身份的位置。保存时会把遗留的十六进制条目迁移为 ik:1:…，并保留原有的 first_seen 时间戳。
strict	bool	true	若为 true，在不匹配时中止连接。若为 false，仅记录警告并继续。
strict_mode	bool	false	严格 TOFU。若为 true，即使在首次连接时也拒绝未知的服务器身份——你必须在首次连接前显式设置 fingerprint。默认 false 会在首次使用时接受并固定。

[server_identity]
trust_on_first_use = true
strict             = true

---

多服务器路由

CLI 客户端可以维护一个小型服务器池,并根据目标主机名或 IP 将每个 SOCKS5 流分发到其中一个服务器。典型场景:所有流量默认走香港,但 google.com(和相关域名)走新加坡,以便地理定位内容在新加坡侧正确解析。

此功能仅限 SOCKS5。TUN 模式将整个网络栈封装在单个隧道中,无法进行按流路由;在 TUN 模式下启用多服务器配置会以明确错误拒绝。多路复用 SOCKS5(socks5.multiplex = true)也会被拒绝,因为共享的多路复用隧道是单服务器的。

客户端的 identity_key_file 在所有服务器之间共享(SSH 模型 — 一个客户端密钥,多个主机)。每个服务器都有自己的 prekey bundle。

[[server]]

可以用 [[server]] 块声明零个或多个额外服务器。顶层的 server_address + prekey_bundle 仍是隐式的 "default" 服务器,因此现有的单服务器配置无需任何更改即可继续工作。

字段	类型	必填	描述
name	string	是	用于 [routing.<name>] 的符号名。必须唯一;"default" 是保留名。
address	string	是	WebSocket URL(wss://...)。
prekey_bundle	path	是	该服务器的 X3DH prekey bundle JSON 文件路径。
sni_hostname	string	否	TLS SNI 覆盖。默认使用 URL 中的主机名。
fingerprint	string	否	该服务器的固定 ik:1:... 身份。覆盖顶层的 [server_identity] 设置。

[routing.<name>]

按服务器 name 索引的路由规则。如果 SOCKS5 请求匹配任一 domains 或 ips,则分发到该命名服务器;否则走默认服务器。

字段	类型	描述
domains	array of strings	主机名模式 — 详见下方匹配规则。不区分大小写。
ips	array of strings	字面 IP(8.8.8.8)或 CIDR 块(1.1.1.0/24、2606:4700::/32)。

域名模式匹配

支持三种形式。google.com 和 *.google.com 的区别很重要 — 它们做的事情不同。

模式	匹配	不匹配	使用场景
google.com	google.com 以及 mail.google.com、www.google.com、…	notgoogle.com	需要覆盖顶级域名和所有子域名(常见情况)。
*.google.com	mail.google.com、www.google.com	google.com 本身 — 顶级域名被有意排除	只需要子域名,例如顶级域名要走另一条规则。
google.com.(带尾点)	仅精确匹配 google.com	任何子域名	需要严格的单主机匹配。

除了前导 *. 之外的通配符会在启动时被拒绝 — google.* 或 *.google.* 都是无效的。

常见陷阱: 如果你写了 *.google.com,然后访问 https://google.com,请求会走默认服务器,而不是路由服务器。使用不带 *. 的 google.com 形式来同时覆盖顶级域名和子域名。

匹配顺序为优先主机名,IP 作为回退。带 ATYP = 0x03(domain)的 SOCKS5 请求携带原始主机名;客户端将该主机名未解析地发送到所选服务器,因此 DNS 在服务器端完成 — 地理 DNS 查询会返回所选出口本地的答案。

如果你的 SOCKS5 客户端在本地做 DNS 解析(例如 curl -x socks5://… 而不是 socks5h://…,或系统级代理设置),请求会以 ATYP = 0x01 送达 — 一个字面 IP — 此时域名规则无法匹配。要么将客户端切换到主机名透传模式(socks5h://),要么把目标 IP 段加到 ips 里。

server_address    = "wss://hk.example.com"
identity_key_file = "identity.key"
prekey_bundle     = "hk.bundle.json"

[[server]]
name          = "sg"
address       = "wss://sg.example.com"
prekey_bundle = "sg.bundle.json"

[routing.sg]
domains = ["google.com", "*.google.com", "youtube.com"]
ips     = ["8.8.8.8/32", "1.1.1.1"]

使用此配置,curl -x socks5h://127.0.0.1:1080 https://google.com 会打开到 SG 服务器的 WebSocket,并让 SG 解析 google.com;其他所有流量继续走 HK。

如果所选服务器无法连接,SOCKS5 请求会失败 — 客户端不会静默回退到默认服务器。这是有意为之:错误区域返回的地理路由流量比明确失败更糟。

---

[performance]

用于高吞吐或资源受限环境的调优。

字段	类型	默认值	描述
worker_threads	integer	4	异步工作线程数。在高核心数服务器上可增加。
recv_buffer_size	integer	262144	TCP 接收缓冲区大小（字节，256 KB）。
send_buffer_size	integer	262144	TCP 发送缓冲区大小（字节，256 KB）。
crypto_worker_count	integer	4	专用于加/解密的线程数。较高值可提高高并发负载下的吞吐量。

[performance]
worker_threads     = 4
crypto_worker_count = 4

---

完整示例

server_address    = "wss://your.server.com/api/v1/ws"
identity_key_file = "~/.config/rvpn/identity.key"
prekey_bundle     = "~/.config/rvpn/prekey-bundle.json"
tls_fingerprint   = "chrome"

[socks5]
listen_address = "127.0.0.1:1080"

[http_proxy]
enabled        = true
listen_address = "127.0.0.1:8118"

[tun]
enabled = true
mtu     = 1420
routes  = ["0.0.0.0/0"]

[dns_proxy]
enabled        = true
listen_address = "127.0.0.1:53"
nameservers    = ["223.5.5.5:53", "1.1.1.1:53", "8.8.8.8:53"]

[split_tunnel]
enabled                  = true
builtin_bypass_countries = ["CN"]
block_ads                = true

[network]
prefer_ipv4       = true
dns_cache_enabled = true

[server_identity]
trust_on_first_use = true
strict             = true