# pyxray 配置说明 本文档说明当前 Web UI 已整理的配置项：核心配置、入站端口、路由、透明代理、DNS。 当前 UI 没有展示的配置项，如果本文明确写了隐藏默认值，表示保存配置时会按该默认值写入 `settings.toml`。 配置页使用改动确认模式： - 修改任意配置项后，右下角会出现两个圆形按钮。 - `✓` 表示保存设置。 - `×` 表示撤回当前未保存修改，恢复到页面加载时的配置值。 ## 核心配置 ### 日志等级 控制生成的 Xray `log.loglevel`。 可选值： - `trace` - `debug` - `info` - `warn` - `warning` - `error` 默认值： ```text info ``` 注意事项： - `trace` / `debug` 适合排查问题，但日志量更大。 - 日常使用建议保持 `info`。 - 只想看错误时可以改成 `error`。 ### Mux 并发数 控制 Xray outbound 的 `mux` 设置。 UI 可选值： ```text 0, 1, 2, 4, 8, 16, 32, 64 ``` 含义： - `0` 表示关闭 Mux。 - 非 `0` 表示启用 Mux，并把该值作为 `mux.concurrency`。 默认值： ```text 0 ``` 保存后的实际含义： ```text 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。 保存时固定为： ```text tcp_fast_open = "default" ``` 含义： - `default` 表示不主动覆盖 Xray / 系统默认行为。 - TCP Fast Open 是 TCP 握手阶段携带首包数据的优化，是否有效取决于系统和网络路径。 ## 入站端口 入站端口表示 Xray 在本机监听哪些入口，让应用把流量交给 Xray。 当前 UI 只保留“规则代理入口”，普通 SOCKS/HTTP、VMess、API、自定义入站都隐藏。 ### 监听地址 控制规则代理入口监听在哪个地址。 可选值： ```text 127.0.0.1 0.0.0.0 ``` 含义： - `127.0.0.1` 只允许本机访问。 - `0.0.0.0` 允许局域网设备访问。 默认值： ```text 127.0.0.1 ``` 注意事项： - 如果只给本机程序使用，建议选择 `127.0.0.1`。 - 如果要让其它设备连接这台机器的代理端口，才选择 `0.0.0.0`。 - 选择 `0.0.0.0` 时需要注意防火墙和局域网安全。 ### 规则 SOCKS 端口 生成带路由规则的 SOCKS5 入站。 默认值： ```text 20170 ``` 含义： - 应用连接该 SOCKS5 端口后，流量会按路由配置决定走 `proxy`、`direct` 或 `block`。 - 端口设为 `0` 表示不生成该入站。 ### 规则 HTTP 端口 生成带路由规则的 HTTP 代理入站。 默认值： ```text 20172 ``` 含义： - 应用连接该 HTTP 代理端口后，流量会按路由配置决定走 `proxy`、`direct` 或 `block`。 - 端口设为 `0` 表示不生成该入站。 ### Sniffing 控制 Xray 是否从连接中识别目标域名。 可选值： ```text disable http,tls http,tls,quic ``` 默认值： ```text http,tls,quic ``` 含义： - `disable` 表示关闭嗅探。 - `http,tls` 表示识别 HTTP Host 和 TLS SNI。 - `http,tls,quic` 表示额外识别 QUIC。 注意事项： - 路由规则经常依赖域名匹配，开启 Sniffing 后更容易按域名正确分流。 - 如果遇到特定服务兼容性问题，可以尝试降低到 `http,tls` 或关闭。 ### Sniffing 仅用于路由 控制嗅探结果是否只用于路由判断。 可选值： ```text 关闭 开启 ``` 默认值： ```text 关闭 ``` 含义： - `开启` 表示嗅探出的域名只用于路由，不改写实际连接目标。 - `关闭` 表示按 Xray 默认 sniffing 行为处理。 注意事项： - `开启` 通常更保守，兼容性更好。 - 如果只希望 Sniffing 帮助规则匹配，可以开启。 ### 隐藏默认项 当前 UI 隐藏以下入站设置，并在保存时固定为默认值： ```text 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。 当前执行顺序： ```text 1. 先匹配自定义规则 2. 再匹配路由模式 3. 最后默认走 proxy ``` ### 路由模式 可选值： ```text whitelist gfwlist proxy direct block ``` 默认值： ```text whitelist ``` 含义： - `whitelist` 表示白名单模式，常见目标是国内和私有地址直连，其它走代理。 - `gfwlist` 表示 GFWList 模式，命中规则的目标走代理，其它直连。 - `proxy` 表示全部走代理。 - `direct` 表示全部直连。 - `block` 表示全部阻断。 注意事项： - 想简单全部走代理，选择 `proxy`。 - 想国内直连、国外代理，选择 `whitelist`。 - 想更保守地只代理规则命中的目标，选择 `gfwlist`。 ### 自定义规则 自定义规则会优先于路由模式匹配。 语法： ```text domain(...)->proxy domain(...)->direct domain(...)->block ip(...)->proxy ip(...)->direct ip(...)->block ``` 示例： ```text domain(domain:example.com)->direct domain(geosite:google)->proxy ip(geoip:cn)->direct ``` 含义： - `domain(...)` 表示按域名规则匹配。 - `ip(...)` 表示按 IP 规则匹配。 - `->proxy` 表示命中后走代理。 - `->direct` 表示命中后直连。 - `->block` 表示命中后阻断。 注意事项： - 一行一条规则。 - 空行和以 `#` 开头的行会被忽略。 - 自定义规则只负责前置匹配，不再支持 `default:`。 - 默认兜底固定为 `proxy`，不在 UI 中显示。 ### 隐藏默认项 当前 UI 不显示默认规则。 保存时固定为： ```text default_rule = "proxy" ``` 含义： - 自定义规则和路由模式都没有命中时，最终走 `proxy`。 当前 UI 也不显示旧的 `custom` / `routingA` 模式。 ## DNS DNS 设置控制 Xray 内置 DNS 模块如何解析域名，以及是否提供本地 DNS 入口。 ### 查询策略 控制生成的 Xray `dns.queryStrategy`。 可选值： ```text 默认 UseIP UseIPv4 UseIPv6 ``` 默认值： ```text 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 路径中生效，因此这里先保持为保存项，不生成额外规则。 可选值： ```text closed none dnsforward doh advanced ``` 默认值： ```text 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 监听辅助函数。 可选值： ```text none supervisor fakedns ``` 默认值： ```text none ``` 含义： - `none` 表示不启用特殊 DNS 模式。 - `supervisor` 表示预期监控 DNS 污染，并结合 sniffing 识别出的域名修正连接行为。 - `fakedns` 表示预期使用 FakeDNS，为域名返回保留网段假 IP，再由代理反查假 IP 对应的原始域名。 注意事项： - `fakedns` 通常需要配套 FakeDNS 地址池、透明代理或 TUN 路由逻辑。 - 因为当前 `.v2rayA` 已移除 `supervisor` / `fakedns` 生成路径，pyxray 也不会为这些选项生成额外配置。 ### 禁用 fallback 控制是否生成 Xray `dns.disableFallback`。 可选值： ```text 关闭 开启 ``` 默认值： ```text 关闭 ``` 含义： - `关闭` 表示允许 Xray 在需要时使用 fallback DNS。 - `开启` 表示生成 `disableFallback = true`，DNS 解析更严格地按配置规则执行。 注意事项： - 开启后 DNS 行为更可控。 - 如果某个 DNS 服务器解析失败，可能不会自动退到其它 DNS，容错更低。 ### 监听本地 DNS 控制是否生成本地 UDP 53 DNS 入站。 可选值： ```text 关闭 开启 ``` 默认值： ```text 开启 ``` 含义： - `开启` 时允许生成 `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 规则一行一条，格式： ```text server|domains|outbound ``` 默认值： ```text 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`。 默认规则含义： ```text 私有域名 -> localhost -> direct 国内域名 -> 223.5.5.5 -> direct 其它域名 -> 8.8.8.8 -> proxy ``` ### 隐藏默认项 当前 UI 不显示 DNS hosts。 保存和生成配置时保留默认值： ```text hosts."courier.push.apple.com" = ["1-courier.push.apple.com"] ``` 含义： - `hosts` 类似 `/etc/hosts`，用于在 DNS 模块里固定或改写某些域名解析结果。 - 当前保留该默认项主要用于兼容 Apple Push 相关域名。 当前 UI 也不显示出站组与自动更新设置。 保存时固定为： ```text 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 资源更新由“下载”页面负责，不在配置页提供自动更新策略。 - 当前不关注订阅相关设置和逻辑。 ## 透明代理 透明代理由两部分组成： ```text 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` 且透明代理未关闭时生成。 ### 模式 控制透明代理入口进来的流量怎么走路由。 可选值： ```text close proxy whitelist gfwlist pac ``` 默认值： ```text close ``` 含义： - `close` 表示关闭透明代理，不生成 transparent inbound。 - `proxy` 表示透明代理流量全部走代理。 - `whitelist` 表示透明代理流量按白名单模式分流。 - `gfwlist` 表示透明代理流量按 GFWList 模式分流。 - `pac` 表示透明代理流量跟随“路由”配置中的路由模式。 ### 类型 控制透明代理用哪种方式接收系统转发来的流量。 可选值： ```text redirect tproxy system_proxy tun ``` 默认值： ```text 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`。 ### 透明代理端口 默认值： ```text 52345 ``` 含义： - `redirect` / `tproxy` 时，系统规则会把流量导到这个端口，Xray 的 `dokodemo-door` 在这里接收流量。 - `system_proxy` 时，这个端口作为 HTTP 代理端口。 - `tun` 时，当前 pyxray 里仍是占位性质。 注意事项： - 应用通常不会主动连接这个端口，除非是 `system_proxy`。 - 该端口不能被其它进程占用。 ### 系统代理 SOCKS 端口 默认值： ```text 52306 ``` 含义： - 只有 `type = system_proxy` 时有意义。 - 用作显式 SOCKS5 代理入口。 示例： ```text 应用 -> 127.0.0.1:52306 SOCKS -> Xray -> proxy/direct ``` ### 启用 IP Forward 控制是否预期打开 Linux IP 转发能力。 默认值： ```text 关闭 ``` 含义： - 开启后，这台机器才能作为网关转发其它设备或容器的流量。 - 如果只代理本机程序，一般不需要开启。 注意事项： - 当前 pyxray 只保存该字段，还没有执行系统命令打开 IP Forward。 - 后续实现系统规则时，可能对应 `net.ipv4.ip_forward=1`。 ### TUN 自动路由 控制 TUN 模式下是否预期自动添加系统路由。 默认值： ```text 开启 ``` 含义： - 开启后，程序应自动添加路由，把系统流量导入 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 排除接口 默认值： ```text 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。 - 自动执行或回滚生成的系统规则脚本。