pyxray/README.md

pyxray 使用手册

pyxray 是一个轻量级 Xray 控制面板。它负责下载 Xray 运行资源、导入代理节点、生成 Xray 配置、启动/停止 Xray，并可在 Linux/Docker 环境下为宿主机提供透明代理。

当前实现重点：

能力	状态	说明
Xray 资源管理	已实现	下载/检查 xray、geoip.dat、geosite.dat。
节点导入	已实现	支持 vless、vmess、trojan、trojan-go、shadowsocks。
配置生成	已实现	根据选中节点和 settings.toml 生成 config.json。
Xray 运行控制	已实现	Web 内启动/停止由 pyxray 托管的 Xray 子进程。
透明代理	已实现	生成并执行 redirect / tproxy / system_proxy / tun 相关配置和脚本。
订阅	未实现	当前只支持手动导入节点链接。
登录认证	未实现	默认不要直接暴露到不可信网络。

运行机制

flowchart LR
  UI[Web UI] --> API[Flask/Gunicorn API]
  API --> Nodes[nodes.toml]
  API --> Settings[settings.toml]
  API --> Assets[download.toml + xray assets]
  API --> Gen[config.json + transparent scripts]
  Gen --> Xray[Xray process]
  API --> Runtime[TransparentRuntime]
  Runtime --> HostNet[iptables/nft/ip rule/resolv.conf]
  Xray --> Proxy[Selected outbound node]

默认数据目录：

文件/目录	作用
data/nodes.toml	保存节点列表和当前选中节点。
data/settings.toml	保存配置页设置。
data/download.toml	保存下载页设置。
data/config.json	生成给 Xray 使用的配置。
data/xray/	保存 xray / xray.exe、geoip.dat、geosite.dat。
data/transparent/	保存透明代理脚本、nftables 配置和 tinytun.yaml。
data/xray.log	保存 Xray 输出和 pyxray 运行日志。

Docker 部署

构建镜像：

sh scripts/build.sh

启动服务：

docker compose up -d --build

访问：

http://<host-ip>:8080

当前 compose.yaml 使用：

配置	作用
network_mode: host	让容器直接使用宿主机网络，透明代理规则作用于宿主机网络栈。
privileged: true	允许执行 iptables、nft、ip rule、写 /proc/sys/net/...。
./data:/config	持久化 pyxray 数据和 Xray 资源。
/etc/resolv.conf:/etc/resolv.conf	允许 DNS 劫持脚本修改宿主机 DNS。
/lib/modules:/lib/modules:ro	读取宿主机内核模块信息。

Web 使用流程

1. 打开 Web 控制台。
2. 在“下载”页检查或下载 Xray 资源。
3. 在“节点”页导入节点链接。
4. 选择一个当前节点。
5. 在“配置”页调整入站、路由、DNS、透明代理。
6. 保存设置。
7. 点击“启动 Xray”。
8. 在“日志”页确认 Xray 和透明代理脚本执行结果。

CLI

启动 Web 控制台：

pyxray web --host 127.0.0.1 --port 3309 --xray-dir data/xray

查看配置文件：

pyxray configs --download
pyxray configs --settings

清理配置/下载资源：

pyxray clear --download
pyxray clear --all

直接下载或补齐 Xray 资源：

pyxray download --target all --directory data/xray --force
pyxray download --target geoip --geoip-url https://example.invalid/geoip.dat

透明代理建议

场景	建议
只代理本机 TCP 流量	transparent.mode = proxy，transparent.type = redirect。
国内直连、国外代理	transparent.mode = whitelist，transparent.type = redirect。
需要 UDP/TProxy	使用 transparent.type = tproxy，确认宿主机内核和防火墙支持。
只想给应用显式设置代理	使用 system_proxy 或普通 rule HTTP/SOCKS 入站。
Docker 容器流量也要透明代理	开启 docker_transparent 并确认 docker_transparent_cidrs 覆盖实际 Docker 网段。

注意事项

项目	说明
端口冲突	启动 Xray 前会检查生成配置里的入站端口是否可用。
透明代理权限	Docker 透明代理部署需要 network_mode: host 和 privileged: true。
DNS 劫持	redirect + local_dns_listen 会改写 /etc/resolv.conf。
多 worker	不要把 Gunicorn 改成多 worker；当前内存任务表和 Xray 子进程状态不能跨进程共享。
Web 暴露	当前没有认证，建议只在可信局域网使用。
自动订阅	当前不支持订阅更新，节点需要手动导入。

阅读和修改代码

路径	职责
pyxray/cli.py	CLI 入口，默认启动 Web。
pyxray/web/server.py	Flask app 装配。
pyxray/web/*.py	Web API：节点、下载、配置生成、服务控制。
pyxray/web/templates/	Web UI 模板。
pyxray/web/static/	前端交互逻辑和样式。
pyxray/libs/nodes/	节点链接解析、标准化、持久化。
pyxray/libs/xray_config/	Xray JSON、透明代理脚本、TinyTun 配置生成。
pyxray/libs/xray_runtime.py	Xray 子进程生命周期和日志转发。
pyxray/libs/xray_transparent_runtime.py	透明代理脚本执行、回滚和本地 CIDR watcher。
tests/	单元测试和 Web API 测试。

详细结构和调用时序见 docs/infra.md。

配置文档

配置总览见 docs/config.md。

按分类阅读：

分类	文档
核心	docs/config/core.md
入站	docs/config/inbounds.md
路由	docs/config/routing.md
DNS	docs/config/dns.md
透明代理	docs/config/transparent.md
透明代理 iptables 排查	docs/transparent-iptables.md
出站和自动更新	docs/config/outbounds-auto-update.md
Xray 资源下载	docs/config/assets.md