Files
root 633f580803 VPN: сохранность ключей — зашифрованная копия и восстановление
НАЙДЕНО И ЭТО БЫЛО ОПАСНО: боевая конфигурация xray с ключами жила
ТОЛЬКО на VPS.
  * в репозитории лежала копия от 23.09: 1 клиент вместо 10;
  * в резервное копирование (restic) VPS не входит вовсе.

Значит при гибели VPS все ключи пропали бы, и пришлось бы перевыпускать
доступ всей семье заново, обходя каждого. Это дороже, чем сделать копию.

Что теперь есть:
  * ops/secrets-enc/xray-config.json — копия для восстановления,
    зашифрована SOPS + age (правило уже было настроено на этот путь);
  * vps/xray/config.json — обезличенная копия: структура без ключей,
    её можно читать кому угодно;
  * /root/xray-config-encrypted.json на VPS — вторая копия, на другой
    машине.

Копия проверена, а не просто создана: скрипт расшифровывает её обратно и
сверяет СОДЕРЖИМОЕ (входящие, клиентов, ключи, настройки). Сверка
побайтовая не годится: SOPS при расшифровке пересобирает JSON, и порядок
ключей может отличаться. Результат: содержимое совпадает полностью,
30 ключей в 3 входящих.

Восстановление: ops/vpn/vpn-restore-config.sh. Без ключа --apply ничего
не пишет — только расшифровывает и показывает. С --apply делает копию
текущего файла, пишет на VPS и проверяет, что канал после этого работает.

Отдельно записано в документе: локально проверить конфигурацию НЕЛЬЗЯ,
потому что в ней пути к файлам сертификатов, а они только на VPS. Попытка
проверить на домашнем узле даёт ложную ошибку "failed to parse
certificate", и это не признак порчи копии. Скрипт об этом предупреждает
вместо того, чтобы пугать зря.

Восстановление невозможно без ключа шифрования age
(/root/.buryan-age-key, он же в Vaultwarden и на флешке). Это и есть
правило из аудита: ключ и зашифрованные данные — в разных местах.
2026-10-16 21:31:00 +03:00

506 lines
27 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Подключение к VPN — рабочий способ
**Обновлено 17.10.2026.** Рабочий канал — **VLESS + TLS на порту 10443**
с отпечатком **firefox**. Проверено с внешнего адреса: трафик реально
выходит через VPS.
> Для семьи — отдельный простой документ: [`VPN-FOR-FAMILY.md`](VPN-FOR-FAMILY.md).
> Здесь техническая часть.
---
## 1. Что работает сейчас
| Способ | Порт | Состояние |
|---|---|---|
| **VLESS + TLS** | **10443** | ✅ основной рабочий канал |
| VLESS + Reality | 2087 | ⚠️ рукопожатие не проходит (причина не найдена) |
| VLESS + Reality | 2053 | ⚠️ то же |
| mtg (Telegram) | 9443 | ✅ работает, отдельная задача |
| WireGuard / Headscale | — | координация сети, не для выхода в интернет |
**Отпечаток `firefox` критичен.** С `chrome` не работает — проверено.
## 2. Доступы
```
Домен для маскировки (SNI): git.buryans.ru
Адрес сервера: 193.233.210.184
Порт: 10443
Отпечаток: firefox
```
Сертификат домена `git.buryans.ru` — Let's Encrypt, действует до 21.12.2026.
## 3. Ключи
**В Git ключей нет** (см. `policies/secret-policy.md`).
| Где | Что |
|---|---|
| `/root/.buryan-vpn-final` (VPS, 600) | ссылки VPN, готовые к выдаче |
| `/root/.buryan-vpn-page` (VPS, 600) | адрес и пароль страницы раздачи |
| Vaultwarden (`vault.buryans.ru`) | целевое хранилище |
**10 ключей**, у каждого своё имя `Buryan-01 … Buryan-10`.
Именование позволило раздавать доступ по одному и отзывать по одному,
не трогая остальных:
```
Buryan-01 … Buryan-05 — исходные ключи
Buryan-06 … Buryan-10 — добавлены 17.10.2026 на этом этапе
```
## 4. Ссылка для телефона (образец)
Подставляется свой UUID вместо `<UUID>`:
```
vless://<UUID>@193.233.210.184:10443?encryption=none&security=tls&sni=git.buryans.ru&fp=firefox&type=tcp#Buryan-XX
```
Параметры по частям:
| Часть | Значение | Почему так |
|---|---|---|
| `security=tls` | TLS | обычный HTTPS — не выделяется |
| `sni=git.buryans.ru` | домен | сертификат настоящий, домен уже наш |
| `fp=firefox` | отпечаток | **без этого не работает** |
| `type=tcp` | транспорт | поток без наворотов, стабильнее в РФ |
| `flow` | пусто | на сервере у ключей `flow` не задан — должно совпадать |
## 5. Приложения
| Система | Приложение |
|---|---|
| Android | **Hiddify**, v2rayNG |
| iPhone | Streisand, FoXray |
| Windows | Hiddify, v2rayN |
| macOS | Hiddify, V2Box |
Импорт: «+» → «Сканировать QR-код» либо «Импорт из ссылки».
## 5б. Раздача через Matrix
**Решение от 17.10.2026:** профили выдаются не только страницей, но и в Matrix.
Причина простая: Matrix наш, ключи не уходят на чужие серверы, и человек
получает профиль там, где он и так общается с семьёй.
**Скрипт:** `ops/vpn/matrix-distribute.py` (на хосте — `/root/matrix-distribute.py`).
```bash
python3 /root/matrix-distribute.py # план, ничего не меняет
python3 /root/matrix-distribute.py --send # отправить всем
python3 /root/matrix-distribute.py --send --only akadmin # проверить на одном
python3 /root/matrix-distribute.py --verify # проверить по факту
```
### Главное правило: комната НА КАЖДОГО
Профили **не** кладём в общую комнату «Семья». Причина: в общей комнате
ключи видны всем сразу, и тогда нельзя отозвать доступ одному человеку,
не задев остальных. Ради этого мы и делали отдельные ключи (раздел 3).
Вместо этого скрипт заводит приватную комнату `#vpn-<логин>:matrix.buryans.ru`
с названием «VPN — <имя>», приглашает туда одного человека и отправляет
ему: картинку QR, ссылку текстом (на случай, если QR не считался)
и инструкцию.
| Профиль | Кому |
|---|---|
| Buryan-01 | Роман (`akadmin`) |
| Buryan-03 | Сергей (`sergey`) |
| Buryan-04 | AlexTest (`alextest`) |
| Buryan-05 | Елена (`elena`) |
| Buryan-06 | Полина (`polina`) |
| Buryan-07 | Никита (`nikita`) |
| Buryan-02, 08, 09, 10 | запас |
Карта соответствия задаётся в самом скрипте (`RECIPIENTS`).
### Отдельный мост в Telegram
В комнате «Семья» есть участники вида `@telegram_<id>` — это люди,
пришедшие из Telegram. **Если положить профили в такую комнату, ключи
уедут в Telegram.** Поэтому раздача идёт в отдельные комнаты, куда мост
не подключён. Решение о том, нужно ли зеркало в Telegram, — за владельцем.
### Особенность этого Synapse: где лежат картинки
Старые пути `/_matrix/media/v3/download` и `/_matrix/media/r0/download`
на нашем сервере отдают **404**. Медиа доступно только по новому пути:
```
/_matrix/client/v1/media/download/<сервер>/<id>
```
Проверять доступность картинки нужно именно им — иначе получишь ложный 404
и решишь, что файл потерялся (ровно это и случилось при первой проверке).
### Шифрование
E2EE в этих комнатах не включён: ключи лежат в нашей базе в открытом виде.
База своя, это допустимо, но знать об этом надо. Для ключа VPN,
который можно перевыпустить, риск приемлемый.
## 5в. Бот: выдача профиля по запросу
**Зачем.** Человек сменил телефон, потерял сообщение, забыл ссылку — он
пишет команду и получает свой профиль заново, не дёргая владельца.
**Как устроено** (`ops/vpn/matrix-vpn-bot.py`, служба `matrix-vpn-bot`):
| Команда | Кто | Что получит |
|---|---|---|
| `!vpn` | любой | свой профиль (картинка QR + ссылка) |
| `!vpn link` | любой | только строку-ссылку, без картинки |
| `!vpn check` | любой | проверку: что на месте и что делать |
| `!vpn help` | любой | подсказку |
| `!vpn 08` | владелец | указанный ключ (в том числе запасной) |
| `!vpn 04` | не владелец | **отказ** |
Регистр не важен: `!VPN`, `!Vpn`, `!впн` работают одинаково.
`!vpn link` нужен для настройки **на самом телефоне**: QR с того же экрана
не считать, а ссылку из сообщения можно скопировать и вставить в приложение
через «Импорт из ссылки».
Ответ приходит **личным сообщением**, а не в комнату. Это не украшение,
а условие безопасности: в комнате «VPN — Сергей» сидит только Сергей
и бот, но если отвечать в комнату, то при добавлении туда кого-то
третьего он увидит чужой ключ. Ключ — это доступ.
Свой профиль человек получает **только по своему Matrix-логину**: комната
«VPN — <логин>» заранее закреплена за конкретным ключом. Спросить чужой
нельзя — иначе доступ к чужому аккаунту в Matrix означал бы доступ
к чужому VPN.
**Где слушает.** Только в комнатах выдачи («VPN — …» и личные комнаты).
В «Семье» и в тревогах бот молчит — там профилей быть не должно.
**Владельцы.** Право запросить любой ключ есть у `@akadmin` и `@comms_agent`
(единственные админы Matrix).
### Устройство, о котором стоит знать
* Бот работает циклом синхронизации (`/sync`), точка отсчёта хранится
в `/root/.buryan-vpn-bot-token.json`.
* При **первом** запуске бот только берёт точку отсчёта и старые сообщения
**не** обрабатывает. Иначе после перезапуска он увидел бы прежние команды
и разослал профили повторно.
* Личные комнаты хранятся **отдельным** файлом
(`/root/.buryan-vpn-bot-direct.json`). Если держать их вместе с точкой
отсчёта, они затираются на каждом круге — так и случилось при разработке.
### Проверка
```bash
systemctl status matrix-vpn-bot --no-pager
journalctl -u matrix-vpn-bot -n 30 --no-pager
# самопроверка: команда подаётся так, будто её прислал человек
python3 /opt/buryan-hub/scripts/matrix-vpn-bot.py --self-test --as=akadmin --command='!vpn'
python3 /opt/buryan-hub/scripts/matrix-vpn-bot.py --self-test --as=sergey --command='!vpn 04'
```
Вторая команда **обязана** дать отказ — это проверка, что чужой ключ
не утекает.
## 10б. Проверка «VPN работает» в наблюдении
**Задача 4.2 из реестра** («проверка: работает ли VPN»). Сделано 17.10.2026.
**Почему отдельная проверка.** Порт 10443 может слушать, а трафик не
проходить — именно такую картину мы уже видели, когда провайдер вмешивался
в поток после установки соединения. Открытый порт в этом случае ничего
не говорит, поэтому проверка не «порт открыт», а «трафик доходит».
**Как проверяется.** `ops/vpn/vpn-check.sh` (на VPS —
`/usr/local/bin/vpn-check.sh`) поднимает временный клиент xray прямо
на сервере, ходит через него в интернет и сверяет внешний адрес.
Совпал — канал действительно пропускает трафик. За собой убирает.
```
bash /usr/local/bin/vpn-check.sh # подробно
bash /usr/local/bin/vpn-check.sh --quiet # только итог
```
Коды возврата: `0` — работает, `1` — нет.
**Где встроено.** `/opt/buryan-hub/scripts/check-services.sh`, функция
`check_vpn`, вызывается вместе с остальными проверками каждые 5 минут
(задача в cron). Провал попадает в общую тревогу в Matrix.
**Важно:** проверяется внутренняя исправность сервера. Путь
«устройство снаружи → VPS» этим не покрывается — его проверяет владелец
со своего устройства. И порт 2087 (Reality) намеренно **не** проверяется:
он не работает и занесён в план задачами VPN-2.3, иначе тревога была бы
каждые 5 минут.
**Ключ для проверки** берётся прямо из рабочей конфигурации xray,
а не из файла со ссылками: файл со ссылками лежит на домашнем узле,
а проверка идёт на VPS (на этих граблях я уже постоял).
## 10в. Проверка встроенной проверки
```bash
# запустить только новую проверку, не весь цикл наблюдения
FUNC=$(awk '/^check_vpn\(\)/,/^}/' /opt/buryan-hub/scripts/check-services.sh)
eval "$FUNC"; check_vpn; echo "код: $?"
```
Ожидаемый результат: `код: 0` и `PASSED` увеличился на единицу.
## 5г. Выдача доступа новому человеку
**Зачем.** Владельцу нужна одна команда, чтобы выдать профиль новому
участнику — без ручной сборки QR и без пересылки ключей в мессенджерах.
```
!vpn give @логин — выдать свободный ключ
!vpn give @логин 08 — выдать конкретный ключ
!vpn list — что кому выдано и какие ключи свободны
```
Доступна **только владельцу** (`@akadmin`, `@comms_agent`). Обычному
человеку бот ответит отказом и запишет попытку в журнал.
**Как это работает.** Бот заводит личную комнату с получателем,
приглашает его и отправляет профиль **лично ему**, а не в комнату, где
сидит владелец: ключ — это доступ, в переписке с третьими лицами ему
не место. Владельцу бот отвечает, что и кому выдано, и это же
записывается в состояние (`given_by`, `key`).
**Что человек должен уже иметь.** Учётную запись в матрице —
бот заводит только комнату. Учётные записи создаёт владелец через
админский доступ Synapse: у самого бота прав серверного админа нет.
### Важная тонкость: видимость истории
Личные комнаты создаются с `history_visibility: shared`, а не `joined`.
Причина: при выдаче доступа человек в комнате ещё только **приглашён**.
С видимостью `joined` он увидел бы только то, что отправлено после его
вступления, — то есть приглашение с профилем внутри оказалось бы для
него пустым. С `shared` приглашённый видит, что ему прислали, **сразу**.
Это выяснилось проверкой, а не из документации: первый прогон создал
комнату с `joined`, и получатель не увидел ничего, хотя бот отчитался
об успешной отправке.
### Свободные ключи
```
Buryan-08, Buryan-09, Buryan-10 — свободны
Buryan-01..07 — выданы семье
```
Свободных не осталось — нужен новый: добавить клиента в конфигурацию
xray (раздел 6) и внести в `profiles.json` со своим QR.
### Проверка
Выдача проверена по-настоящему, на живом получателе: временный человек
заводился в Matrix, получал ключ, принимал приглашение и видел у себя
QR-код и ссылку. После проверки временный человек и его комнаты удалены
из базы (пользователей снова 21, событий временных комнат — 0).
## 10г. Раздельная маршрутизация и приложения, не любящие VPN
Часть приложений (банки, госуслуги, маркетплейсы) не работает, когда
весь трафик идёт через VPN: они закрывают доступ тем, кто приходит
с зарубежного адреса. Решается маршрутизацией, а не переключениями.
| Документ | О чём |
|---|---|
| `docs/VPN-APP-CONFLICTS.md` | почему ломается, что именно перестало работать, понятным языком |
| `docs/VPN-SPLIT-ROUTING.md` | как настроить: по приложениям и по доменам, с граблями |
| `ops/vpn/split-profile-android.yaml` | готовый профиль: туннель несёт только домашнее |
| `ops/vpn/gen-split-routing.py` | сборка файлов маршрутизации из одного списка доменов |
| `ops/vpn/split/` | собранные файлы: список доменов, правила, конфиг Xray |
Проверено 17.10.2026: домашний домен идёт через туннель, российский
и прочий — напрямую. Подробности и подтверждение из журнала — в
`VPN-SPLIT-ROUTING.md`.
### Самопроверка: «!vpn check»
Человек не должен угадывать, на каком шаге он застрял. Команда смотрит
со стороны сервера и отвечает коротко: что получилось, что нет и что
делать. Вот как это выглядит:
```
Проверка вашего подключения
[да] Доступ выдан, ваш ключ: Buryan-01
[да] Готовые профили пришли: vpn-akadmin.json, vpn-akadmin.yaml
[да] Сервер отвечает, связь с ним есть
Со стороны сервера всё готово. Осталось проверить на телефоне:
1. Приложение: FlClash (файл .yaml) либо Hiddify (файл .json).
2. Скачайте свой файл на странице раздачи — прямо на телефоне.
...
5. Откройте 2ip.ru — должен показаться 193.233.210.184.
```
**Чего команда НЕ делает:** не проверяет, работает ли VPN на самом
телефоне. Этого со стороны сервера не видно — поэтому последний шаг
всегда «проверьте сами», с точной ссылкой и ожидаемым адресом.
Если чего-то не хватает, команда называет причину и следующий шаг:
нет ключа — «напишите владельцу»; профилей не видно — «примите
приглашение в комнату»; сервер молчит — «повторите через пару минут».
## 11. Сохранность ключей: копия и восстановление
**Найдено 17.10.2026 и это было опасно.** Боевая конфигурация xray
с ключами жила **только на VPS**:
* в репозитории лежала копия от 23.09 — 1 клиент вместо 10;
* в резервное копирование (restic) VPS **не входит** вовсе.
То есть при гибели VPS все ключи пропали бы, и пришлось бы перевыпускать
доступ всей семье — заново, с обходом каждого. Это дороже, чем сделать
копию.
### Что теперь есть
| Что | Где | Вид |
|---|---|---|
| Копия для восстановления | `ops/secrets-enc/xray-config.json` | **зашифрована** SOPS + age |
| Копия для чтения | `vps/xray/config.json` | структура **без ключей** |
| Вторая копия | `/root/xray-config-encrypted.json` на VPS | зашифрована |
Ключи в открытом виде в Git **не попадают** — это проверяется автоматически
при копировании (`policies/secret-policy.md`).
### Копирование
```bash
bash ops/vpn/vpn-backup-config.sh
```
Скрипт забирает боевую конфигурацию, шифрует её, кладёт обезличенную
копию и **проверяет восстановление**: расшифровывает обратно и сверяет
содержимое — входящие, клиентов, ключи и настройки. Если что-то не
сойдётся, он об этом скажет, а не оставит «копию», которую нельзя
использовать.
### Восстановление
```bash
bash ops/vpn/vpn-restore-config.sh # проверка, ничего не меняет
bash ops/vpn/vpn-restore-config.sh --apply # записать на VPS
```
Без ключа `--apply` скрипт только расшифровывает и показывает, что
получилось. На сервер пишет лишь по явной команде, с копией текущего
файла и проверкой, что канал после этого работает.
**Локально проверить конфигурацию нельзя:** в ней указаны файлы
сертификатов, а они есть только на VPS. Попытка проверить на домашнем
узле даёт ложную ошибку `failed to parse certificate` — это не признак
порчи копии, и скрипт об этом предупреждает.
### Без чего восстановление невозможно
**Нужен ключ шифрования age** — `/root/.buryan-age-key`. Он также лежит
в Vaultwarden и (по поручению из аудита) на флешке.
**Правило из аудита:** ключ и зашифрованные данные — в разных местах.
Именно поэтому копия в репозитории зашифрована, а ключ лежит отдельно.
Если ключ потеряется, копия станет бесполезной — восстановить будет
нечего.
## 6. Как выдать доступ новому человеку
1. Взять свободный ключ из `/root/.buryan-vpn-final`.
2. Собрать ссылку по образцу из раздела 4.
3. Сделать QR-код.
4. Отдать человеку вместе с `VPN-FOR-FAMILY.md`.
Свободные ключи кончились — добавить новый:
```bash
# 1. новый UUID
uuidgen
# 2. добавить в три входящих (10443, 2087, 2053) в /usr/local/etc/xray/config.json
# с меткой buryan-NN@buryans.ru
# 3. ОБЯЗАТЕЛЬНО проверить до применения
xray run -test -config /usr/local/etc/xray/config.json
# 4. применить
systemctl restart xray
# 5. проверить, что слушает
ss -tlnp | grep -E '10443|2087|2053'
```
## 7. Как закрыть доступ одному человеку
Удалить **его** клиента из всех трёх входящих и перезапустить:
```bash
systemctl restart xray
```
Остальные не пострадают — в этом смысл отдельных ключей.
## 8. Возврат, если что-то пошло не так
Перед каждой правкой конфиг копируется. Вернуться:
```bash
ls -t /usr/local/etc/xray/config.json.before-* | head -1
cp "$(ls -t /usr/local/etc/xray/config.json.before-* | head -1)" /usr/local/etc/xray/config.json
xray run -test -config /usr/local/etc/xray/config.json
systemctl restart xray
```
## 9. Известная особенность этого хозяйства
**Доступ снаружи бывает непредсказуемым.** Наблюдали: с одного провайдера
работает, с другого — нет; на одном устройстве работает, на другом нет.
Причина — вмешательство провайдера в поток после установки соединения.
Поэтому:
* не делаем вывод «сломано» по одной неудаче;
* проверяем минимум на двух сетях (Wi-Fi и мобильная);
* держим несколько протоколов — это и есть Этап 2.
Замер 17.10.2026 с внешнего адреса: **10 подключений из 10 успешных**.
## 10. Диагностика
```bash
# служба и порты
systemctl status xray --no-pager
ss -tlnp | grep -E '10443|2087|2053'
# что видит сервер (самый полезный журнал)
journalctl -u xray -n 50 --no-pager
# проверка конфига до применения
xray run -test -config /usr/local/etc/xray/config.json
```
Что искать в журнале:
| Запись | Значение |
|---|---|
| `accepted tcp:...` + `email: buryan-NN@` | ключ работает, видно кто |
| `invalid request version` | до сервера дошёл не VLESS — обычно это чужой стук в порт |
| Тишина при попытке с телефона | трафик не дошёл: провайдер режет по пути |
## 11. Связанные документы
| Файл | Что внутри |
|---|---|
| `VPN-FOR-FAMILY.md` | инструкция для родных, простым языком |
| `ops/network/VPN-STATUS.md` | состояние и результаты проверок |
| `ops/network/VPN-README.md` | заметки по Reality |
| `ops/runbooks/vless-vpn.md` | runbook |
| `ops/vpn/VPN-STAGE1-IMPLEMENTATION.md` | что именно сделано 17.10.2026 и как откатить |