pyxray/docs/config.md

pyxray 配置说明

本文档说明当前 Web UI 已整理的配置项：核心配置、入站端口、路由、透明代理、DNS。

当前 UI 没有展示的配置项，如果本文明确写了隐藏默认值，表示保存配置时会按该默认值写入 settings.toml。

配置页使用改动确认模式：

• 修改任意配置项后，右下角会出现两个圆形按钮。
• ✓ 表示保存设置。
• × 表示撤回当前未保存修改，恢复到页面加载时的配置值。

核心配置

日志等级

控制生成的 Xray log.loglevel。

可选值：

• trace
• debug
• info
• warn
• warning
• error

默认值：

info

注意事项：

• trace / debug 适合排查问题，但日志量更大。
• 日常使用建议保持 info。
• 只想看错误时可以改成 error。

Mux 并发数

控制 Xray outbound 的 mux 设置。

UI 可选值：

0, 1, 2, 4, 8, 16, 32, 64

含义：

• 0 表示关闭 Mux。
• 非 0 表示启用 Mux，并把该值作为 mux.concurrency。

默认值：

0

保存后的实际含义：

0  -> mux_enabled = false
8  -> mux_enabled = true, mux_concurrency = 8
16 -> mux_enabled = true, mux_concurrency = 16

注意事项：

• Mux 会把多个连接复用到更少的底层连接中。
• 某些节点或网络环境下 Mux 可能提升体验，也可能导致兼容性问题。
• 不确定时建议用 0 关闭。

隐藏默认项

当前 UI 不显示 TCP Fast Open。

保存时固定为：

tcp_fast_open = "default"

含义：

• default 表示不主动覆盖 Xray / 系统默认行为。
• TCP Fast Open 是 TCP 握手阶段携带首包数据的优化，是否有效取决于系统和网络路径。

入站端口

入站端口表示 Xray 在本机监听哪些入口，让应用把流量交给 Xray。

当前 UI 只保留“规则代理入口”，普通 SOCKS/HTTP、VMess、API、自定义入站都隐藏。

监听地址

控制规则代理入口监听在哪个地址。

可选值：

127.0.0.1
0.0.0.0

含义：

• 127.0.0.1 只允许本机访问。
• 0.0.0.0 允许局域网设备访问。

默认值：

127.0.0.1

注意事项：

• 如果只给本机程序使用，建议选择 127.0.0.1。
• 如果要让其它设备连接这台机器的代理端口，才选择 0.0.0.0。
• 选择 0.0.0.0 时需要注意防火墙和局域网安全。

规则 SOCKS 端口

生成带路由规则的 SOCKS5 入站。

默认值：

20170

含义：

• 应用连接该 SOCKS5 端口后，流量会按路由配置决定走 proxy、direct 或 block。
• 端口设为 0 表示不生成该入站。

规则 HTTP 端口

生成带路由规则的 HTTP 代理入站。

默认值：

20172

含义：

• 应用连接该 HTTP 代理端口后，流量会按路由配置决定走 proxy、direct 或 block。
• 端口设为 0 表示不生成该入站。

Sniffing

控制 Xray 是否从连接中识别目标域名。

可选值：

disable
http,tls
http,tls,quic

默认值：

http,tls,quic

含义：

• disable 表示关闭嗅探。
• http,tls 表示识别 HTTP Host 和 TLS SNI。
• http,tls,quic 表示额外识别 QUIC。

注意事项：

• 路由规则经常依赖域名匹配，开启 Sniffing 后更容易按域名正确分流。
• 如果遇到特定服务兼容性问题，可以尝试降低到 http,tls 或关闭。

Sniffing 仅用于路由

控制嗅探结果是否只用于路由判断。

可选值：

关闭
开启

默认值：

关闭

含义：

• 开启 表示嗅探出的域名只用于路由，不改写实际连接目标。
• 关闭 表示按 Xray 默认 sniffing 行为处理。

注意事项：

• 开启 通常更保守，兼容性更好。
• 如果只希望 Sniffing 帮助规则匹配，可以开启。

隐藏默认项

当前 UI 隐藏以下入站设置，并在保存时固定为默认值：

socks_port = 0
http_port = 0
vmess_port = 0
api.port = 0
port_sharing = false
domains_excluded = ""
custom = []

含义：

• 普通 SOCKS/HTTP 入站不生成，只生成规则 SOCKS/HTTP 入站。
• VMess 入站不生成。
• Xray API 入站不生成。
• 端口共享开关不再单独存在，是否允许局域网访问由“监听地址”决定。
• 排除嗅探域名暂不开放 UI。
• 自定义入站暂不开放 UI。

路由

路由决定进入规则代理端口或透明代理入口的流量最终走哪个 outbound。

当前执行顺序：

1. 先匹配自定义规则
2. 再匹配路由模式
3. 最后默认走 proxy

路由模式

可选值：

whitelist
gfwlist
proxy
direct
block

默认值：

whitelist

含义：

• whitelist 表示白名单模式，常见目标是国内和私有地址直连，其它走代理。
• gfwlist 表示 GFWList 模式，命中规则的目标走代理，其它直连。
• proxy 表示全部走代理。
• direct 表示全部直连。
• block 表示全部阻断。

注意事项：

• 想简单全部走代理，选择 proxy。
• 想国内直连、国外代理，选择 whitelist。
• 想更保守地只代理规则命中的目标，选择 gfwlist。

自定义规则

自定义规则会优先于路由模式匹配。

语法：

domain(...)->proxy
domain(...)->direct
domain(...)->block
ip(...)->proxy
ip(...)->direct
ip(...)->block

示例：

domain(domain:example.com)->direct
domain(geosite:google)->proxy
ip(geoip:cn)->direct

含义：

• domain(...) 表示按域名规则匹配。
• ip(...) 表示按 IP 规则匹配。
• ->proxy 表示命中后走代理。
• ->direct 表示命中后直连。
• ->block 表示命中后阻断。

注意事项：

• 一行一条规则。
• 空行和以 # 开头的行会被忽略。
• 自定义规则只负责前置匹配，不再支持 default:。
• 默认兜底固定为 proxy，不在 UI 中显示。

隐藏默认项

当前 UI 不显示默认规则。

保存时固定为：

default_rule = "proxy"

含义：

• 自定义规则和路由模式都没有命中时，最终走 proxy。

当前 UI 也不显示旧的 custom / routingA 模式。

DNS

DNS 设置控制 Xray 内置 DNS 模块如何解析域名，以及是否提供本地 DNS 入口。

查询策略

控制生成的 Xray dns.queryStrategy。

可选值：

默认
UseIP
UseIPv4
UseIPv6

默认值：

UseIPv4

含义：

• 默认 表示不写入 queryStrategy，交给 Xray 默认行为。
• UseIP 表示允许返回 IP，具体 IPv4 / IPv6 由 Xray 和系统环境决定。
• UseIPv4 表示优先使用 IPv4 解析结果。
• UseIPv6 表示优先使用 IPv6 解析结果。

注意事项：

• 当前 pyxray 默认使用 UseIPv4，避免 IPv6 网络不可用时出现连接失败。
• 如果运行环境明确支持 IPv6，可以改成 UseIP 或 UseIPv6。

防污染模式

当前 UI 保留该字段，但 pyxray 暂未把它接入 Xray JSON 生成逻辑。 交叉核对当前 .v2rayA 后，旧的 antiPollution.GetExternalDNS 和 DropSpoofing.GetSetupCommands 已不在透明代理 setup 路径中生效，因此这里先保持为保存项，不生成额外规则。

可选值：

closed
none
dnsforward
doh
advanced

默认值：

closed

含义：

• closed 表示关闭防污染策略。
• none 表示不使用额外防污染策略。
• dnsforward 表示预期转发 DNS 请求，由程序接收 DNS 后再按规则转发到上游。
• doh 表示预期使用 DNS-over-HTTPS，减少传统 UDP DNS 被劫持或污染的概率。
• advanced 表示预留高级自定义 DNS 防污染策略。

注意事项：

• 当前阶段该字段只保存到 settings.toml。
• 真正生效的是下方 DNS 规则、查询策略、禁用 fallback、本地 DNS 监听。

特殊模式

当前 UI 保留该字段，但 pyxray 暂未把它接入 Xray JSON 生成逻辑。 当前 .v2rayA 代码里原 specialMode 的 supervisor / fakedns 相关逻辑已经移除，只保留 redirect 透明代理所需的本地 DNS 监听辅助函数。

可选值：

none
supervisor
fakedns

默认值：

none

含义：

• none 表示不启用特殊 DNS 模式。
• supervisor 表示预期监控 DNS 污染，并结合 sniffing 识别出的域名修正连接行为。
• fakedns 表示预期使用 FakeDNS，为域名返回保留网段假 IP，再由代理反查假 IP 对应的原始域名。

注意事项：

• fakedns 通常需要配套 FakeDNS 地址池、透明代理或 TUN 路由逻辑。
• 因为当前 .v2rayA 已移除 supervisor / fakedns 生成路径，pyxray 也不会为这些选项生成额外配置。

禁用 fallback

控制是否生成 Xray dns.disableFallback。

可选值：

关闭
开启

默认值：

关闭

含义：

• 关闭 表示允许 Xray 在需要时使用 fallback DNS。
• 开启 表示生成 disableFallback = true，DNS 解析更严格地按配置规则执行。

注意事项：

• 开启后 DNS 行为更可控。
• 如果某个 DNS 服务器解析失败，可能不会自动退到其它 DNS，容错更低。

监听本地 DNS

控制是否生成本地 UDP 53 DNS 入站。

可选值：

关闭
开启

默认值：

开启

含义：

• 开启 时允许生成 dns-in，让本机 DNS 请求交给 Xray。
• 关闭 时 Xray 仍可在内部解析域名，但不会额外提供本地 DNS 入口。

注意事项：

• 本地 DNS 监听只有在透明代理开启且类型为 redirect 时才生成；透明代理关闭、tproxy、system_proxy、tun 都不会生成。
• 非局域网共享时监听 127.2.0.17:53/udp；启用局域网共享时，会额外保留 0.0.0.0:53/udp 给局域网设备使用，并增加 dns-in-local 处理本机 DNS。
• 监听 53 端口可能需要权限，且端口不能被其它 DNS 服务占用。

DNS 规则

DNS 规则一行一条，格式：

server|domains|outbound

默认值：

localhost|geosite:private|direct
223.5.5.5|geosite:cn|direct
8.8.8.8||proxy

含义：

• server 表示 DNS 服务器，例如 localhost、223.5.5.5、8.8.8.8、https://dns.google/dns-query。
• domains 表示该 DNS 服务器负责解析哪些域名规则，空表示默认 DNS。
• outbound 表示访问该 DNS 服务器本身时走哪个出口，常用 direct 或 proxy。

默认规则含义：

私有域名 -> localhost -> direct
国内域名 -> 223.5.5.5 -> direct
其它域名 -> 8.8.8.8 -> proxy

隐藏默认项

当前 UI 不显示 DNS hosts。

保存和生成配置时保留默认值：

hosts."courier.push.apple.com" = ["1-courier.push.apple.com"]

含义：

• hosts 类似 /etc/hosts，用于在 DNS 模块里固定或改写某些域名解析结果。
• 当前保留该默认项主要用于兼容 Apple Push 相关域名。

当前 UI 也不显示出站组与自动更新设置。

保存时固定为：

outbounds.0.tag = "proxy"
outbounds.0.probe_url = "https://www.gstatic.com/generate_204"
outbounds.0.probe_interval = "60s"
outbounds.0.type = "leastping"
auto_update.gfwlist_auto_update_mode = "none"
auto_update.gfwlist_auto_update_interval_hour = 0
auto_update.subscription_auto_update_mode = "none"
auto_update.subscription_auto_update_interval_hour = 0
auto_update.proxy_mode_when_subscribe = "direct"

含义：

• 当前 pyxray 只使用手动导入并选中的节点生成 proxy outbound。
• GFWList 资源更新由“下载”页面负责，不在配置页提供自动更新策略。
• 当前不关注订阅相关设置和逻辑。

透明代理

透明代理由两部分组成：

Xray transparent inbound + 系统流量劫持规则

当前 pyxray 已经能生成 Xray transparent inbound，并能生成宿主机透明代理系统规则脚本。

系统规则脚本当前覆盖：

• redirect 的 legacy iptables 规则。
• redirect 的 nftables 表配置和加载命令。
• tproxy 的 legacy iptables 规则。
• tproxy 的 nftables 表配置和加载命令。
• system_proxy 的 HTTP/SOCKS 代理入口说明脚本。

注意事项：

• 当前只生成脚本，不自动执行系统命令。
• 生成规则参考 .v2rayA/service/core/iptables 的链名、mark、路由表和端口语义。
• 点击“生成配置”时，会在 config.json 同级目录下生成 transparent/ 目录。
• transparent/ip-forward-apply.sh 用于按配置打开或关闭 Linux IP Forward。
• transparent/resolv-hijack-setup.sh 用于把 /etc/resolv.conf 指向 127.2.0.17。
• transparent/resolv-hijack-cleanup.sh 用于恢复 v2rayA 风格的兜底 DNS。
• transparent/transparent-iptables-setup.sh 用于安装 legacy iptables 规则。
• transparent/transparent-iptables-cleanup.sh 用于清理 legacy iptables 规则。
• transparent/transparent-nft-setup.sh 用于加载 nftables 规则。
• transparent/transparent-nft-cleanup.sh 用于清理 nftables 规则。
• transparent/v2raya.nft 是 nftables 表配置；仅在当前透明代理类型需要 nftables 表时生成。
• transparent/tinytun.yaml 是 TinyTun 配置；仅在 type = tun 且透明代理未关闭时生成。

模式

控制透明代理入口进来的流量怎么走路由。

可选值：

close
proxy
whitelist
gfwlist
pac

默认值：

close

含义：

• close 表示关闭透明代理，不生成 transparent inbound。
• proxy 表示透明代理流量全部走代理。
• whitelist 表示透明代理流量按白名单模式分流。
• gfwlist 表示透明代理流量按 GFWList 模式分流。
• pac 表示透明代理流量跟随“路由”配置中的路由模式。

类型

控制透明代理用哪种方式接收系统转发来的流量。

可选值：

redirect
tproxy
system_proxy
tun

默认值：

redirect

含义：

• redirect 使用 NAT REDIRECT，适合 TCP，Docker 友好。
• tproxy 使用 TPROXY + fwmark + policy routing，支持 TCP/UDP，但规则复杂且 Docker 不友好。
• system_proxy 生成 HTTP/SOCKS 代理入口，给系统代理或应用显式使用，不是真正的内核透明代理。
• tun 表示生成 TinyTun 配置，由 TinyTun 创建 TUN 设备和系统路由。

注意事项：

• 当前建议优先使用 redirect。
• 如果需要 UDP 能力，后续可以考虑 tproxy，但要接受更复杂的系统规则。
• Docker 容器透明代理优先考虑 redirect。

透明代理端口

默认值：

52345

含义：

• redirect / tproxy 时，系统规则会把流量导到这个端口，Xray 的 dokodemo-door 在这里接收流量。
• system_proxy 时，这个端口作为 HTTP 代理端口。
• tun 时，当前 pyxray 里仍是占位性质。

注意事项：

• 应用通常不会主动连接这个端口，除非是 system_proxy。
• 该端口不能被其它进程占用。

系统代理 SOCKS 端口

默认值：

52306

含义：

• 只有 type = system_proxy 时有意义。
• 用作显式 SOCKS5 代理入口。

示例：

应用 -> 127.0.0.1:52306 SOCKS -> Xray -> proxy/direct

启用 IP Forward

控制是否预期打开 Linux IP 转发能力。

默认值：

关闭

含义：

• 开启后，这台机器才能作为网关转发其它设备或容器的流量。
• 如果只代理本机程序，一般不需要开启。

注意事项：

• 当前 pyxray 只保存该字段，还没有执行系统命令打开 IP Forward。
• 后续实现系统规则时，可能对应 net.ipv4.ip_forward=1。

TUN 自动路由

控制 TUN 模式下是否预期自动添加系统路由。

默认值：

开启

含义：

• 开启后，程序应自动添加路由，把系统流量导入 TUN 虚拟网卡。
• 关闭后，需要用户自己配置路由。

注意事项：

• 当前 pyxray 会把该字段写入 tinytun.yaml 的 tun.auto_route。
• 生成的 TinyTun 默认 TUN 地址参考 v2rayA：198.18.0.1/32 和 fd00::1/128。
• 生成的 TinyTun SOCKS5 上游固定为 127.0.0.1:52345，对应 Xray 为 TUN 流量准备的本地 SOCKS 入站。
• 当前 pyxray 只生成 tinytun.yaml，不会自动启动 TinyTun 进程。

TPROXY 排除接口

默认值：

docker*,veth*,wg*,ppp*,br-*

含义：

• 只对 type = tproxy 有意义。
• 生成 TPROXY 系统规则时，这些接口进来的流量会被跳过。
• 常用于避免 Docker、veth、WireGuard、PPP、bridge 接口被错误劫持。

注意事项：

• 当前 UI 在 type != tproxy 时会禁用该输入。
• 生成 TPROXY 系统规则脚本时会使用该字段。

当前阶段限制

当前透明代理配置能生成 Xray JSON 侧的 inbound / routing，也能生成 IP Forward、DNS 劫持、redirect / tproxy 系统规则脚本。

尚未实现：

• TUN 设备创建。
• TUN 进程启动和生命周期管理。
• Docker 容器透明代理规则。
• 根据宿主机环境自动选择 iptables-legacy / iptables-nft。
• 自动执行或回滚生成的系统规则脚本。