Files
buryan-infra/docs/vpn-clients.md
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

27 KiB
Raw Permalink Blame History

Подключение к VPN — рабочий способ

Обновлено 17.10.2026. Рабочий канал — VLESS + TLS на порту 10443 с отпечатком firefox. Проверено с внешнего адреса: трафик реально выходит через VPS.

Для семьи — отдельный простой документ: 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).

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). Если держать их вместе с точкой отсчёта, они затираются на каждом круге — так и случилось при разработке.

Проверка

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в. Проверка встроенной проверки

# запустить только новую проверку, не весь цикл наблюдения
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 ops/vpn/vpn-backup-config.sh

Скрипт забирает боевую конфигурацию, шифрует её, кладёт обезличенную копию и проверяет восстановление: расшифровывает обратно и сверяет содержимое — входящие, клиентов, ключи и настройки. Если что-то не сойдётся, он об этом скажет, а не оставит «копию», которую нельзя использовать.

Восстановление

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.

Свободные ключи кончились — добавить новый:

# 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. Как закрыть доступ одному человеку

Удалить его клиента из всех трёх входящих и перезапустить:

systemctl restart xray

Остальные не пострадают — в этом смысл отдельных ключей.

8. Возврат, если что-то пошло не так

Перед каждой правкой конфиг копируется. Вернуться:

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. Диагностика

# служба и порты
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 и как откатить