168 lines
6.0 KiB
Markdown
168 lines
6.0 KiB
Markdown
# 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` 相关配置和脚本。 |
|
||
| 订阅 | 未实现 | 当前只支持手动导入节点链接。 |
|
||
| 登录认证 | 未实现 | 默认不要直接暴露到不可信网络。 |
|
||
|
||
## 运行机制
|
||
|
||
```mermaid
|
||
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 部署
|
||
|
||
构建镜像：
|
||
|
||
```bash
|
||
sh scripts/build.sh
|
||
```
|
||
|
||
启动服务：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
访问：
|
||
|
||
```text
|
||
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 控制台：
|
||
|
||
```bash
|
||
pyxray web --host 127.0.0.1 --port 3309 --xray-dir data/xray
|
||
```
|
||
|
||
查看配置文件：
|
||
|
||
```bash
|
||
pyxray configs --download
|
||
pyxray configs --settings
|
||
```
|
||
|
||
清理配置/下载资源：
|
||
|
||
```bash
|
||
pyxray clear --download
|
||
pyxray clear --all
|
||
```
|
||
|
||
直接下载或补齐 Xray 资源：
|
||
|
||
```bash
|
||
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/infra.md)。
|
||
|
||
## 配置文档
|
||
|
||
配置总览见 [docs/config.md](docs/config.md)。
|
||
|
||
按分类阅读：
|
||
|
||
| 分类 | 文档 |
|
||
| --- | --- |
|
||
| 核心 | [docs/config/core.md](docs/config/core.md) |
|
||
| 入站 | [docs/config/inbounds.md](docs/config/inbounds.md) |
|
||
| 路由 | [docs/config/routing.md](docs/config/routing.md) |
|
||
| DNS | [docs/config/dns.md](docs/config/dns.md) |
|
||
| 透明代理 | [docs/config/transparent.md](docs/config/transparent.md) |
|
||
| 透明代理 iptables 排查 | [docs/transparent-iptables.md](docs/transparent-iptables.md) |
|
||
| 出站和自动更新 | [docs/config/outbounds-auto-update.md](docs/config/outbounds-auto-update.md) |
|
||
| Xray 资源下载 | [docs/config/assets.md](docs/config/assets.md) |
|