setup-happ-subscription — мульти-кнопочная Happ-подписка (OpenGate)

Источник истины формата — .claude/knowledge/networking/_reference/happ-subscription-format.md. Прочитай его перед работой: там wire-формат, заголовки, ловушки балансира, РФ→direct, иконки, схема реестра, профиль-манифест. Этот скилл — процедура + готовый код.

Что строим

Одна статическая ссылка https://<домен>/<path>/<rnd>.json, которую Happ показывает как набор кнопок-политик. Каждая кнопка = отдельный xray-конфиг (Happ передаёт в ядро 1:1):

Роли/кнопки адаптируются под парк — это шаблон, не догма.

Предусловия

• Веб-сервер отдаёт статичный файл по HTTPS (nginx); python3 на сервере; qrencode (для QR — опц.).
• Подписка провайдера, отдающая серверы. Если она ЗАКРЫТА (HWID/шифр) — сперва /extract-subscription-servers. HWID-добыча — subscription-mirroring.md ч.1.

Процедура

Шаг 1 — добыть подписку провайдера (🟢 Green)

curl с заголовками Happ + X-Hwid (см. subscription-mirroring.md). Сохранить ответ во временный файл. Проверить, что это не заглушка (grep -c '00000000-0000' = 0). Гео-блок → запрашивать с РФ-хоста.

Шаг 2 — загрузить в реестр (🟢 Green)

python3 scripts/load.py ingest --source <provider> --db registry.db <файл-ответа>

load.py сам определит формат (JSON-массив / base64 / vless), классифицирует серверы по ролям, покажет отчёт (по ролям + «не классифицированы уверенно»). Нераспознанные роли поправить: python3 scripts/load.py override --db registry.db --match "<имя>" --role us.

Шаг 3 — сгенерировать подписку (🟢 Green, локально)

python3 scripts/generate.py --db registry.db --out sub.json          # все кнопки
python3 scripts/generate.py --db registry.db --only USA --out proto.json   # прототип одной

Генератор печатает routing-заголовок (профиль-манифест в base64) и набор add_header для nginx. Прототип сначала — проверить одну кнопку на устройстве, потом разворачивать все.

Шаг 4 — опубликовать (🟡 Yellow — брифинг + правка nginx)

Создать папку вебрута (напр. /var/www/happ/), залить sub.json под СЛУЧАЙНЫМ неугадываемым именем (внутри UUID-ключи!). Добавить в vhost location со всеми заголовками Happ (пример — в knowledge §9 и в выводе generate.py). nginx -t → reload. Бэкап конфига до правки.

⚠ Имя файла — стабильное между прогонами (рандом ОДИН раз). Заголовки ставит nginx add_header, не генератор.

Шаг 5 — крон автообновления (🟡 Yellow)

scripts/opengate-sync.sh.example → адаптировать (пути, env с SUB_URL/HWID), положить в /opt/<name>/, добавить в cron. Защита: при ошибке рабочий файл не трогать + .bak.

⚠ Грабля: переменную TARGET, которую скрипт задаёт сам, объявлять после source env.

Шаг 5.1 — обновление генератора на боевом (🟡 Yellow — регулярная операция)

После первичной установки generate.py/load.py живут на сервере копией в /opt/<name>/ (обычно НЕ под git, синхрон ручной). Source-of-truth — версия в репозитории инфры оператора. Правишь генератор (новый сервис в direct, новая кнопка, смена политики) — правка живёт у тебя, пока не доставлена на боевой; иначе крон при следующем прогоне пересоберёт подписку из старого генератора. Процедура доставки (ровно она применяется при «добавь сайт в обход/верни в VPN»):

1. Green-сверка: sha256 серверного generate.py против локального ДО правки — убедиться, что сервер не разошёлся и заливается строго твоё изменение (на macOS shasum -a 256, не sha256sum).
2. Бэкап серверного файла (cp generate.py generate.py.bak-<reason>).
3. scp нового generate.py на сервер.
4. Один прогон sync-скрипта (он сам бэкапит целевой *.json и атомарно заменяет; при ошибке генератора файл не трогает).
5. Проверить боевой *.json: число кнопок не упало, новое правило на месте (отдельным простым скриптом, не inline-heredoc через ssh '...' с вложенными кавычками — ломается на экранировании).

⚠ Под git серверную копию не держим по умолчанию → дрейф локального source-of-truth и боевого. Сверка sha256 на шаге 1 — обязательна, иначе можно затереть серверную правку, сделанную мимо репо.

Шаг 6 — проверка на устройстве

Добавить ссылку в Happ → проверить кнопки, балансир (выход не скачет — observatory, не burst), РФ-сайты открываются (РФ→direct), пинг в мс. Проверять выход через ip-api.com/whois, не 2ip.

Самопроверка (Honest verdict)

• load.py распознал формат и классифицировал (отчёт без массы needs_review).
• generate.py собрал ≥ ожидаемого числа кнопок, JSON валиден.
• Прототип одной кнопки проверен на устройстве ДО полного развёртывания.
• nginx -t прошёл, старые location не задеты, отдача 200 + заголовки на месте.
• Крон с защитой; первый прогон вручную; имя файла стабильно.
• Менял routing-политики (добавил/убрал сервис в direct, правил состав кнопок) → обновил inventory-документ подписки/VPN. Правка генератора = изменение маршрутизации на сервере → рефлекс §3.2 применяется: не обновил inventory — задача НЕ закрыта. Документа подписки/VPN ещё НЕТ (или vpn:{} пуст)? Это НЕ повод молча пропустить под C.7. Минимум: завести короткую inventory-запись о факте правки (что/когда/набор доменов) + todos/pending/ на полноценное заполнение vpn-блока и описания подписки. Полное заполнение карты с нуля — отдельная задача оператора, но факт текущей правки фиксирую сразу. «Обновлять нечего» ≠ «можно ничего не делать».

Не получилось / упал парсер — STOP, честно сказать оператору, не импровизировать суррогат.

Зоны доверия

• Шаги 1-3 (добыча, реестр, генерация локально) — 🟢 Green.
• Шаги 4-5 (nginx, крон на сервере) — 🟡 Yellow: брифинг 6 пунктов, бэкап, nginx -t, откат.
• Red тут нет (ничего необратимого; всё откатывается бэкапом + .bak). Поэтому type-to-confirm (дословная строка) здесь не нужен — это инструмент Red. Правка боевого генератора весомее обычного Yellow, но канон Yellow её закрывает: брифинг + diff до применения + бэкап + откат, подтверждение простое («ок»/«давай»). Тянуть дословную строку в Yellow = размывать сигнал Red (см. .claude/agents/references/trust-zones.md, Decision Point).