feat: 基础功能实现

2026-05-27 00:57:55 +08:00
commit 90e1e9a725
61 changed files with 7880 additions and 0 deletions
@@ -0,0 +1,754 @@
+# 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。
+- 自动执行或回滚生成的系统规则脚本。