From fafcc34f031aa25219b9b18da7560b477580085b Mon Sep 17 00:00:00 2001 From: Sergey Antropoff Date: Sun, 26 Apr 2026 07:36:46 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=BE=D0=B1=D0=BD=D0=BE=D0=B2=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82?= =?UTF-8?q?=D0=B0=D1=86=D0=B8=D1=8E=20=E2=80=94=20=D0=B4=D0=BE=D0=B1=D0=B0?= =?UTF-8?q?=D0=B2=D0=B8=D1=82=D1=8C=20splitgw,=20ingress-proxypass,=20hyst?= =?UTF-8?q?eria2-server?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/networking.md: - Раздел ingress-proxypass: архитектура, пример конфигурации с TLS и auth - Раздел splitgw: TPROXY-маршрутизация, systemd и k8s режимы, пример TV - Раздел hysteria2-server: установка на VPS, SSH-пароль, URL для клиентов docs/make-reference.md: - addon-mediaserver (с флагом без Hysteria2) - addon-hysteria2-server (SSH-ключ и интерактивный пароль -k) - addon-splitgw (systemd и k8s DaemonSet) - addon-ingress-proxypass docs/troubleshooting.md: - Строки таблицы: 502/503/404 для ingress-proxypass, TPROXY для splitgw, firewall/TLS для hysteria2-server, Prowlarr sidecar для mediaserver - Разделы диагностики: ingress-proxypass, splitgw, hysteria2-server с конкретными командами kubectl/systemctl/iptables --- docs/make-reference.md | 13 ++++++ docs/networking.md | 96 +++++++++++++++++++++++++++++++++++++++++ docs/troubleshooting.md | 62 ++++++++++++++++++++++++++ 3 files changed, 171 insertions(+) diff --git a/docs/make-reference.md b/docs/make-reference.md index 7c54246..df52ca2 100644 --- a/docs/make-reference.md +++ b/docs/make-reference.md @@ -68,6 +68,19 @@ make addon-ingress-nginx make addon-cert-manager make addon-metrics-server make addon-kubernetes-dashboard + +# Медиасервер и VPN: +make addon-mediaserver +make addon-mediaserver ARGS="-e mediaserver_hysteria2_enabled=false" # без Hysteria2 + +make addon-hysteria2-server # по SSH-ключу +make addon-hysteria2-server ARGS="-k" # ввод SSH-пароля интерактивно + +make addon-splitgw # systemd на хосте +make addon-splitgw ARGS="-e splitgw_deploy_mode=k8s" # K8s DaemonSet + +make addon-ingress-proxypass +make addon-ingress-proxypass ARGS="-e ingress_proxypass_vip=192.168.1.x" ``` ## Управление нодами diff --git a/docs/networking.md b/docs/networking.md index ce14073..ba5c972 100644 --- a/docs/networking.md +++ b/docs/networking.md @@ -127,6 +127,102 @@ netbird up --management-url grpc://netbird.example.com:80 --- +## ingress-proxypass — проксировать внешние сервисы + +Позволяет открыть по домену любой сервис, работающий **вне кластера** (роутер, NAS, Plex на отдельной машине и т.д.), через тот же ingress-nginx VIP. Для каждой записи создаётся: `Service (ClusterIP, без selector)` + `Endpoints` + `Ingress`. Подробнее: [addons/ingress-proxypass/README.md](../addons/ingress-proxypass/README.md). + +```yaml +# group_vars/all/addons.yml +addon_ingress_proxypass: true + +ingress_proxypass_proxies: + - name: router + hosts: [router.home.ru] + ips: [192.168.1.1] + port: 8080 + + - name: nas + hosts: [nas.home.ru] + ips: [192.168.1.20] + port: 5000 + tls: + enabled: true + secretName: wildcard-tls + + - name: grafana-ext + hosts: [grafana.home.ru] + ips: [192.168.1.60] + port: 3000 + auth: + enabled: true + username: admin + password: "{{ vault_proxy_password }}" # хэш генерируется автоматически +``` + +```bash +make addon-ingress-proxypass +``` + +Маршрут трафика: `kube-vip VIP → ingress-nginx → Service → Endpoints → внешний IP:PORT` + +--- + +## splitgw — прозрачный split-tunnel gateway + +Устанавливает `sing-box` с TPROXY-перехватом на хосте или K3S DaemonSet. Трафик с указанных устройств (Smart TV и т.п.) маршрутизируется по правилам: YouTube/Google → Hysteria2 VPN, RU-сервисы и частные сети → прямой маршрут. Подробнее: [addons/splitgw/README.md](../addons/splitgw/README.md). + +```yaml +# group_vars/all/addons.yml (+ group [splitgw] в inventory) +addon_splitgw: true + +splitgw_tv_sources: + - "192.168.1.100/32" # Smart TV + +splitgw_router_ip: "192.168.1.1" +# vault_hysteria2_url задаётся в vault.yml +``` + +```bash +# Режим systemd на хосте (по умолчанию): +make addon-splitgw + +# Режим K8s DaemonSet: +make addon-splitgw ARGS="-e splitgw_deploy_mode=k8s" +``` + +Маршрут: `Smart TV → шлюз splitgw (TPROXY:7893) → sing-box → YouTube/Google: Hysteria2 VPN | остальное: прямой` + +--- + +## hysteria2-server — VPN-сервер на удалённом VPS + +Устанавливает Hysteria2-сервер на внешний VPS (не часть кластера). Сервер нужен для `splitgw` и `mediaserver` (Prowlarr sidecar). Подробнее: [addons/hysteria2-server/README.md](../addons/hysteria2-server/README.md). + +```yaml +# inventory/hosts.ini +[hysteria2_server] +myvps ansible_host=1.2.3.4 ansible_user=root + +# group_vars/all/vault.yml +vault_hysteria2_server_password: "мойпароль" +``` + +```bash +# По SSH-ключу: +make addon-hysteria2-server + +# По SSH-паролю (интерактивный ввод): +make addon-hysteria2-server ARGS="-k" +``` + +После установки выводится готовая URL-строка для Shadowrocket / NekoBox / Hiddify: + +``` +hysteria2://пароль@1.2.3.4:443?insecure=1#MyVPS +``` + +--- + ## kube-vip LoadBalancer kube-vip обрабатывает все `LoadBalancer` сервисы — каждый сервис с `type: LoadBalancer` автоматически получает IP из подсети кластера. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index abb091c..f3db236 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -27,6 +27,15 @@ | NetBird: клиент не подключается | DNS не настроен | Настрой A-записи для Management, Signal, Coturn LB IPs | | MinIO: distributed не поднимается | Мало нод | Distributed требует минимум 4 реплики/ноды | | Nextcloud: redirect loop | HTTP→HTTPS конфликт | Добавь `TRUSTED_PROXIES` в конфиг Nextcloud | +| ingress-proxypass: 502 Bad Gateway | Кластер не достигает внешний IP | `curl -v http://:` с ноды кластера; проверь файрвол на внешнем хосте | +| ingress-proxypass: 503 | Endpoints пустой | `kubectl -n ingress-proxypass get endpoints` — должны быть адреса | +| ingress-proxypass: 404 | Имя хоста не совпадает | `kubectl -n ingress-proxypass describe ingress ` — хост должен совпасть точно | +| splitgw: трафик не перехватывается | TPROXY mark не применён | `iptables -t mangle -L SPLITGW -v -n` — должны быть правила; `journalctl -u splitgw-rules -f` | +| splitgw: sing-box не стартует | Ошибка конфига | `journalctl -u singbox -f`; `sing-box check --config /etc/sing-box/config.json` | +| splitgw: YouTube всё равно без VPN | DNS утечка | DNS-запросы должны идти через TPROXY; `nslookup youtube.com 8.8.8.8` с устройства | +| hysteria2-server: порт закрыт | Файрвол VPS | `ufw allow 443/udp` или `firewall-cmd --add-port=443/udp --permanent` | +| hysteria2-server: клиент не подключается | Самоподписанный сертификат | Добавь `insecure=1` в URL или установи `tls_mode: acme` | +| mediaserver: Prowlarr не видит индексеры | Hysteria2 sidecar упал | `kubectl -n mediaserver logs -c hysteria2` | ## Подробный вывод @@ -125,6 +134,59 @@ kubectl describe certificate -n kubectl logs -n cert-manager deployment/cert-manager -f ``` +## Диагностика ingress-proxypass + +```bash +# Ресурсы namespace +kubectl -n ingress-proxypass get all,ingress,endpoints + +# Проверить Endpoints заполнены (Addresses не должен быть ) +kubectl -n ingress-proxypass describe endpoints + +# Тест изнутри кластера +kubectl run curl --rm -it --image=curlimages/curl -- \ + curl -v http://.ingress-proxypass.svc.cluster.local: + +# Проверить что nginx подхватил правила +kubectl -n ingress-nginx logs -l app.kubernetes.io/name=ingress-nginx --tail=50 +``` + +## Диагностика splitgw + +```bash +# Статус сервисов на хосте gateway +systemctl status singbox splitgw-rules +journalctl -u singbox -f +journalctl -u splitgw-rules -f + +# Проверить TPROXY-правила iptables +iptables -t mangle -L SPLITGW -v -n +iptables -t mangle -L PREROUTING -v -n + +# Проверить sing-box конфиг +sing-box check --config /etc/sing-box/config.json + +# Диагностика DNS (с устройства-источника) +nslookup youtube.com +nslookup vk.com +``` + +## Диагностика hysteria2-server + +```bash +# Статус на VPS +systemctl status hysteria2 +journalctl -u hysteria2 -f + +# Проверить порт открыт (UDP) +ss -ulnp | grep 443 +# С клиентской машины: +nc -u 443 + +# Тест подключения +curl -v --proxy hysteria2://pass@:443?insecure=1 https://example.com +``` + ## Типичные Molecule ошибки | Ошибка | Решение |