# 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) |