From c51e6c7ecf066204aee967b01263ba1c7055a493 Mon Sep 17 00:00:00 2001 From: findias Date: Tue, 24 Mar 2026 11:32:04 +0300 Subject: [PATCH] docs: update README for multi-role architecture and per-inbound overrides - Add nginx_frontend and relay roles to What you get list - Update Quick Start: separate secrets files per role, separate deploy commands - Update Secrets section: document raven_subscribe/defaults/secrets.yml with inbound_hosts/inbound_ports example - Update Configuration: add xray_dns_query_strategy, raven_subscribe_inbound_hosts/ports - Update Architecture: show full EU+RU server topology and client connection flow - roles/xray/README.md: remove xray_vless_default_flow (removed from templates) --- README.md | 124 ++++++++++++++++++++++++++++++++++--------- roles/xray/README.md | 1 - 2 files changed, 99 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 4e852e0..beaf54e 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ Ansible role that installs and configures [Xray-core](https://github.com/XTLS/Xr - Xray with VLESS + XTLS-Reality and XHTTP inbounds - Optional VLESS Encryption (post-quantum, mlkem768x25519plus) - Raven-subscribe — subscription server for client config distribution +- nginx TLS frontend on EU server (`nginx_frontend` role) +- nginx relay on RU server with TCP stream proxy for VLESS Reality (`relay` role) - Systemd services with auto-restart and config validation before reload - Ad/tracker blocking via geosite routing rules - BBR congestion control and kernel tuning via `srv_prepare` role @@ -24,12 +26,24 @@ Edit `roles/hosts.yml` and point `vm_my_srv` at your server. ### 2. Secrets -Create and encrypt the secrets file: +Create and encrypt secrets files for each role you deploy: ```bash +# Xray role (Reality keys, users) cp roles/xray/defaults/secrets.yml.example roles/xray/defaults/secrets.yml -# Fill in the values (see Secrets section below) ansible-vault encrypt roles/xray/defaults/secrets.yml --vault-password-file vault_password.txt + +# Raven-subscribe role (admin token, server host, per-inbound overrides) +cp roles/raven_subscribe/defaults/secrets.yml.example roles/raven_subscribe/defaults/secrets.yml +ansible-vault encrypt roles/raven_subscribe/defaults/secrets.yml --vault-password-file vault_password.txt + +# nginx_frontend role (certbot email) — EU server +cp roles/nginx_frontend/defaults/secrets.yml.example roles/nginx_frontend/defaults/secrets.yml +ansible-vault encrypt roles/nginx_frontend/defaults/secrets.yml --vault-password-file vault_password.txt + +# relay role (upstream EU IP, certbot email) — RU server +cp roles/relay/defaults/secrets.yml.example roles/relay/defaults/secrets.yml +ansible-vault encrypt roles/relay/defaults/secrets.yml --vault-password-file vault_password.txt ``` To edit later: @@ -49,22 +63,31 @@ xray x25519 ### 4. Deploy ```bash +# EU server: Xray ansible-playbook roles/role_xray.yml -i roles/hosts.yml --vault-password-file vault_password.txt + +# EU server: nginx TLS frontend +ansible-playbook roles/role_nginx_frontend.yml -i roles/nginx_frontend/inventory.ini --vault-password-file vault_password.txt + +# EU server: Raven-subscribe +ansible-playbook roles/role_raven_subscribe.yml -i roles/hosts.yml --vault-password-file vault_password.txt + +# RU server: nginx relay +ansible-playbook roles/role_relay.yml -i roles/relay/inventory.ini --vault-password-file vault_password.txt ``` Deploy only a specific component using tags: ```bash -# Update subscription server config only -ansible-playbook roles/role_xray.yml -i roles/hosts.yml --vault-password-file vault_password.txt --tags raven_subscribe - # Update inbound configs only ansible-playbook roles/role_xray.yml -i roles/hosts.yml --vault-password-file vault_password.txt --tags xray_inbounds ``` -## Secrets (`roles/xray/defaults/secrets.yml`) +## Secrets + +Each role has its own `defaults/secrets.yml` (ansible-vault encrypted). -Ansible-vault encrypted. Required fields: +**`roles/xray/defaults/secrets.yml`** — Reality keys and VLESS users: ```yaml # Reality keys — generate with: xray x25519 @@ -80,11 +103,29 @@ xray_users: - id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # UUID — generate: uuidgen flow: "xtls-rprx-vision" email: "user@example.com" +``` + +**`roles/raven_subscribe/defaults/secrets.yml`** — Raven-subscribe settings: + +```yaml +raven_subscribe_admin_token: "" # openssl rand -hex 32 +raven_subscribe_server_host: "media.zirgate.com" +raven_subscribe_base_url: "https://media.zirgate.com" + +# Per-inbound host/port overrides (optional) +# Useful when clients should connect through a relay instead of the EU server directly +raven_subscribe_inbound_hosts: + vless-reality-in: "media.zirgate.com" + vless-xhttp-in: "media.zirgate.com" +raven_subscribe_inbound_ports: + vless-reality-in: 8445 # nginx stream relay port on EU server +``` + +**`roles/relay/defaults/secrets.yml`** — RU server relay: -# Raven-subscribe -raven_subscribe_admin_token: "" # openssl rand -hex 32 -raven_subscribe_server_host: "your-server.com" -raven_subscribe_base_url: "http://your-server.com:8080" +```yaml +relay_upstream_host: "1.2.3.4" # EU server IP +relay_certbot_email: "admin@example.com" ``` ## Configuration @@ -98,29 +139,62 @@ Key variables in `roles/xray/defaults/main.yml`: | `xray_reality_server_names` | `["askubuntu.com"]` | SNI names for Reality | | `xray_xhttp.port` | `2053` | XHTTP inbound port | | `xray_dns_servers` | `tcp+local://8.8.8.8, ...` | DNS servers (no DoH — see note below) | +| `xray_dns_query_strategy` | `UseIPv4` | DNS query strategy — use `UseIPv4` if the server has no IPv6 | | `xray_vless_decryption` | `"none"` | VLESS Encryption (optional, see below) | + +Key variables in `roles/raven_subscribe/defaults/main.yml`: + +| Variable | Default | Description | +|----------|---------|-------------| | `raven_subscribe_listen_addr` | `:8080` | Raven-subscribe listen address | | `raven_subscribe_sync_interval_seconds` | `60` | User sync interval | +| `raven_subscribe_inbound_hosts` | `{}` | Per-inbound host overrides (set in secrets.yml) | +| `raven_subscribe_inbound_ports` | `{}` | Per-inbound port overrides (set in secrets.yml) | > **DNS note:** Do not use `https://` (DoH) in `xray_dns_servers` — DoH queries route through the proxy and fail. Use `tcp+local://` instead. ## Architecture ``` -roles/role_xray.yml - └── srv_prepare — system packages, BBR, sysctl tuning - └── xray — Xray + Raven-subscribe - ├── validate.yml (always) — pre-flight assertions - ├── install.yml (xray_install) — download Xray binary - ├── base.yml (xray_base) — log + stats config - ├── api.yml (xray_api) — gRPC API on 127.0.0.1:10085 - ├── inbounds.yml (xray_inbounds) — VLESS+Reality, XHTTP - ├── dns.yml (xray_dns) — DNS config - ├── outbounds.yml (xray_outbounds) — direct + block outbounds - ├── routing.yml (xray_routing) — routing rules + ad blocking - ├── service.yml (xray_service) — systemd unit - ├── grpcurl.yml (grpcurl) — installs grpcurl tool - └── raven_subscribe.yml (raven_subscribe) — subscription server +EU server + role_xray.yml + └── srv_prepare — system packages, BBR, sysctl tuning + └── xray — Xray binary + config + ├── validate.yml (always) — pre-flight assertions + ├── install.yml (xray_install) — download Xray binary + ├── base.yml (xray_base) — log + stats config + ├── api.yml (xray_api) — gRPC API on 127.0.0.1:10085 + ├── inbounds.yml (xray_inbounds) — VLESS+Reality, XHTTP + ├── dns.yml (xray_dns) — DNS config + ├── outbounds.yml (xray_outbounds) — direct + block outbounds + ├── routing.yml (xray_routing) — routing rules + ad blocking + ├── service.yml (xray_service) — systemd unit + └── grpcurl.yml (grpcurl) — installs grpcurl tool + + role_nginx_frontend.yml + └── nginx_frontend — nginx TLS proxy on media.zirgate.com + ├── listens on port 8443 (not 443, reserved by Xray Reality) + ├── proxies /sub/* → Raven-subscribe :8080 + └── stream TCP relay: port 8445 → 127.0.0.1:443 (Xray Reality) + + role_raven_subscribe.yml + └── raven_subscribe — subscription server + ├── listens on 127.0.0.1:8080 + ├── syncs users to Xray via gRPC API + └── serves client configs with per-inbound host/port overrides + +RU server + role_relay.yml + └── relay — nginx reverse proxy on zirgate.com + ├── my.zirgate.com → https://media.zirgate.com:8443 (Raven) + └── stream TCP relay: port 8444 → media.zirgate.com:8445 (Reality) +``` + +Client connection flow: +``` +VLESS Reality: client → zirgate.com:8444 (RU TCP relay) → media.zirgate.com:8445 (EU nginx stream) → 127.0.0.1:443 (Xray) +VLESS XHTTP: client → media.zirgate.com:443/path → nginx_frontend:8443 → Xray :2053 +Subscription: client → my.zirgate.com (RU relay) → media.zirgate.com:8443 → Raven-subscribe :8080 ``` Xray config is split across `/etc/xray/config.d/` — files are loaded in numeric order: diff --git a/roles/xray/README.md b/roles/xray/README.md index e55c6b9..5c3ad24 100644 --- a/roles/xray/README.md +++ b/roles/xray/README.md @@ -68,7 +68,6 @@ xray_vless_decryption: "mlkem768x25519plus.native.0rtt.100-111-1111-1111-1111-11 | `xray_reality_server_names` | `[askubuntu.com]` | SNI server names | | `xray_api.inbound.port` | `10085` | Xray gRPC API port (localhost only) | | `xray_vless_decryption` | `none` | VLESS payload decryption mode (`none` or postquantum cipher string) | -| `xray_vless_default_flow` | `xtls-rprx-vision` | `flow` для пользователя, если в `xray_users` не задан ([VLESS inbound](https://xtls.github.io/en/config/inbounds/vless.html)) | | `xray_reality.mldsa65_seed` | — | ML-DSA-65 server seed (secrets.yml only) | | `xray_reality.mldsa65_verify` | — | ML-DSA-65 public verification key (share with clients) |