pyxray/docs/infra.md

项目结构和调用时序

目录结构

路径	职责
pyxray/cli.py	命令行入口。默认启动 Web。
pyxray/web/server.py	创建 Flask app，注册各 API 和生命周期清理。
pyxray/web/dashboard.py	渲染首页。
pyxray/web/jobs.py	内存任务表，当前用于下载任务轮询。
pyxray/web/nodes.py	节点 API。
pyxray/web/xray_assets.py	Xray 资源下载 API。
pyxray/web/xray_config.py	配置保存和生成 API。
pyxray/web/xray_service.py	Xray 启停和日志 API。
pyxray/web/templates/	Jinja 页面和配置表单。
pyxray/web/static/	前端 JS/CSS。
pyxray/libs/nodes/	节点链接解析、标准化、TOML 存储。
pyxray/libs/xray_assets.py	下载和检查 xray、geoip.dat、geosite.dat。
pyxray/libs/xray_asset_settings.py	download.toml 读写。
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/	使用和配置文档。
scripts/build.sh	Docker 镜像构建脚本。
compose.yaml	Docker 透明代理部署。

数据文件

文件	创建方	读写时机
nodes.toml	NodeStore	导入、选择、删除节点。
settings.toml	XrayConfigSettingsStore	保存配置页设置、生成配置、启动 Xray。
download.toml	XrayAssetSettingsStore	保存下载页设置、启动下载任务。
config.json	generate_current_xray_config	生成配置、启动 Xray 前。
xray.log	XrayServiceManager / TransparentRuntime	启停 Xray、转发 Xray 输出、透明代理脚本日志。
transparent/*	write_transparent_rule_files	生成配置、启动 Xray 前。

Web App 装配

flowchart TD
  CLI[pyxray cli] --> RunWeb[run_web]
  RunWeb --> CreateApp[create_app]
  CreateApp --> Jobs[init_job_store]
  CreateApp --> Assets[register_xray_assets]
  CreateApp --> Nodes[register_nodes]
  CreateApp --> Config[register_xray_config]
  CreateApp --> Service[register_xray_service]
  CreateApp --> Lifecycle[_bind_xray_lifecycle]
  CreateApp --> Dashboard[register_dashboard]

首页渲染

sequenceDiagram
  participant B as Browser
  participant D as dashboard.index
  participant A as AssetSettingsStore
  participant N as NodeManager
  participant C as XrayConfigSettingsStore
  participant S as XrayServiceManager

  B->>D: GET /
  D->>A: load download.toml
  D->>N: list_nodes + selected_id
  D->>C: load settings.toml
  D->>S: status
  D-->>B: render index.html

资源下载

sequenceDiagram
  participant B as Browser
  participant API as /api/xray/assets/ensure
  participant Store as XrayAssetSettingsStore
  participant Jobs as JobStore
  participant Worker as _run_asset_job
  participant Assets as ensure_xray_assets

  B->>API: POST form
  API->>Store: save download.toml
  API->>Jobs: start worker
  API-->>B: job_id
  Worker->>Assets: check/download/extract
  Worker->>Jobs: update steps/status
  B->>Jobs: GET job status
  Jobs-->>B: progress/result

节点导入和选择

sequenceDiagram
  participant B as Browser
  participant API as nodes API
  participant M as NodeManager
  participant P as parse_node_link
  participant S as NodeStore

  B->>API: POST /api/nodes/import
  API->>M: import_links
  M->>P: parse + normalize
  M->>S: save nodes.toml
  API-->>B: import results
  B->>API: POST /api/nodes/select
  API->>M: select_node
  M->>S: save selected_id
  API-->>B: selected node

配置生成

sequenceDiagram
  participant B as Browser
  participant API as /api/xray/config/generate
  participant N as NodeManager
  participant S as SettingsStore
  participant G as generate_xray_config
  participant T as write_transparent_rule_files
  participant U as write_tinytun_config_file
  participant FS as data directory

  B->>API: POST generate
  API->>N: get_selected_node
  API->>S: load settings.toml
  API->>G: node + settings
  G-->>API: config dict
  API->>FS: write config.json
  API->>T: write transparent scripts
  API->>U: write tinytun.yaml if needed
  API-->>B: config + paths

启动 Xray 和透明代理

sequenceDiagram
  participant B as Browser
  participant API as /api/xray/service/start
  participant G as generate_current_xray_config
  participant X as XrayServiceManager
  participant R as TransparentRuntime
  participant OS as Host network

  B->>API: POST start
  API->>G: regenerate config and scripts
  API->>X: status
  API->>X: start xray
  X->>X: check inbound ports
  X->>OS: Popen xray run -config config.json
  X->>X: forward stdout/stderr to xray.log
  API->>R: setup settings
  R->>R: cleanup old rules best-effort
  R->>OS: run ip-forward script
  R->>OS: run iptables setup, fallback nft
  R->>OS: run resolv setup
  R->>R: start local CIDR watcher
  API-->>B: running status

停止和清理

sequenceDiagram
  participant B as Browser
  participant API as /api/xray/service/stop
  participant X as XrayServiceManager
  participant R as TransparentRuntime
  participant OS as Host network

  B->>API: POST stop
  API->>X: stop
  X->>R: before_stop cleanup
  R->>R: stop local CIDR watcher
  R->>OS: run resolv cleanup
  R->>OS: run transparent backend cleanup
  X->>OS: terminate xray process
  API-->>B: stopped status

Docker 透明代理部署

flowchart TD
  Compose["docker compose"] --> Container["pyxray container"]
  Container --> HostNet["host network namespace"]
  Container --> ConfigVol["data volume mounted to config"]
  Container --> Resolv["resolv.conf bind mount"]
  Container --> Modules["lib modules read-only mount"]
  HostNet --> XrayPorts["Xray listens on host ports"]
  HostNet --> Rules["iptables nft ip rule affect host"]
  Resolv --> DNS["host DNS hijack when enabled"]

关键点：

Compose 配置	原因
network_mode: host	Xray 端口和透明代理规则直接作用于宿主机。
privileged: true	允许改防火墙、策略路由、procfs。
./data:/config	容器重建后状态不丢。
/etc/resolv.conf:/etc/resolv.conf	redirect DNS 劫持修改宿主机 DNS。
/lib/modules:/lib/modules:ro	读取宿主机内核模块信息。

修改建议

目标	优先修改位置
增加节点协议	pyxray/libs/nodes/parsers/、pyxray/libs/xray_config/outbound.py。
增加配置字段	settings.py、store.py、配置模板、generator.py。
改 Web API	pyxray/web/*.py。
改配置生成	pyxray/libs/xray_config/generator.py。
改透明代理规则	transparent_rules.py。
改规则执行/回滚	xray_transparent_runtime.py。
改 Docker 部署	Dockerfile、compose.yaml、scripts/build.sh。