HY2XS_flamy/CHANGELOG.md

Изменения HY2XS

Формат основан на Keep a Changelog. Проект использует семантическое версионирование.

Версия относится к самому HY2XS, а не к Hysteria: версия Hysteria выбирается на этапе сборки пакета и фиксируется в его metadata.

Unreleased

Hardening-проход перед релизом 1.0.0. Основная тема — сделать политику «только чистая установка» настоящим системным инвариантом, а не строчкой в документации.

Второй проход закрывает то, что осталось: два контракта приёмки, гарантированно ронявшие сборку на корректном коде; жизненный цикл планировщика; мёртвое состояние в таблице config; каналы утечки bootstrap-учётных данных; возраст графа зависимостей.

Третий проход — операции, которые делают не то, что обещает их имя: отзыв доступа, не переживающий перезапуск; резервная копия, молча получающаяся неполной; диагностика, обрывающая соединения; аварийный выход сборки, которым невозможно воспользоваться.

Четвёртый проход — failure path и релизные гейты: восстановление после неудачной установки, которое умело отменить само себя, два гейта сборки, проверявшие не то, что обещали, и два свойства, которые были описаны, но не обеспечены — read-only у doctor и различение отказа базы у reset-admin.

Пятый проход — нижний слой того же механизма. Верхнеуровневый откат стал надёжным раньше, чем его storage/firewall substrate: откат гарантированно запускался, но отдельные его шаги могли молча не выполнить восстановление, отчитаться успехом и уничтожить резервную копию.

Шестой проход — управление самой транзакцией, а не копированием файлов. Предыдущие проходы сделали надёжными шаги операции; здесь закрываются два допущения, на которых держалась операция целиком: что снятие защиты от отката действительно произошло и что операция на сервере ровно одна.

Исправлено — границы транзакции

• Снятие rollback guard было утверждением, а не фактом. Порядок фиксации успеха выглядел так:

  systemctl stop <unit>.timer <unit>.service || true
  -> "firewall rollback timer disarmed"
  -> phase=installed
  

  Между «мы думаем, что guard снят» и «guard действительно снят» не было ни одной проверки: || true стирал код возврата, и взведённый таймер мог вернуть прежний firewall уже ПОСЛЕ долговечной записи успеха. Просто убрать || true было нельзя — для транзиентного юнита, уже убранного systemd, systemctl stop возвращает 5, и этот исход неотличим от успеха.

  Введён маркер /run/hy2xs/rollback/<op-id>/auto-rollback-fired, который rollback-скрипт создаёт первым действием. Снятие guard стало доказательством: маркер отсутствует, ActiveState обоих юнитов равен inactive, и только после этого записывается phase: installed.

• Автоматический откат мог сработать во время успешного smoke, и операция этого не замечала. Окно guard — 45 секунд — заведомо короче худшего случая smoke, а единственной проверкой firewall в smoke был nft -c: разбор текущего файла, каким бы он ни был. Откатившийся прежний ruleset проходил её зелёным, и сервер объявлялся успешно настроенным с предыдущим firewall — особенно дорого при смене порта Hysteria, SSH или ACME.

  Лечится не увеличением окна: сработавший guard теперь запрещает фиксацию успеха независимо от результата smoke и даёт собственную причину отказа firewall_guard_fired. Дополнительно smoke сверяет эффективный firewall с конфигурацией операции — фрагмент правил, принадлежность entrypoint и фактически загруженную таблицу inet hy2xs.

• У оркестратора не было блокировки операций. Ни flock, ни mutex, ни lockfile — при том что вся архитектура отката опиралась на невысказанное допущение об одной операции за раз. install-state.json замком не является: это запись о состоянии, а не право на изменение. Два одновременных reconfigure доходили до конца каждый по-своему, и уникальные op-id не спасали — они разделяют резервные копии, но production paths общие. Дальше любая из операций могла упасть и «восстановить» состояние поверх изменений другой, отчитавшись полным успехом.

  Введён эксклюзивный замок /run/lock/hy2xs-orchestrator.lock. install/reconfigure/repair/doctor берут его и отказывают до первой мутации; status/diagnostics не берут, но сообщают об идущей операции; preflight-install отказывает до собственных проверок. Замок снимается при любом завершении держателя, включая обрыв SSH.

• Автоматический откат маскировал собственные ошибки. Внутри systemd-run оставались cp ... || true и nft -f ... || true, поэтому при частичном восстановлении юнит завершался кодом 0 — ровно в сценарии, где guard является последней линией защиты от потери SSH. Скрипт переписан: независимые стадии, накопление кода возврата, failed с диагностикой в journal.

• Откат не восстанавливал состояние nftables.service. applyFirewall выполняет systemctl enable --now nftables, но копия хранила только файлы правил. После отката неудачной первой установки сервис оставался включённым в автозапуск, хотя до неё был выключен. Состояние снимается вместе с файлами и восстанавливается стадиями, идущими до применения ruleset: у nftables.service ExecStop=nft flush ruleset, и обратный порядок стёр бы восстановленные правила.

• /etc/nftables.conf.candidate не удалялся никогда. Успешная установка оставляла его на сервере навсегда. Candidate-файлы убираются после успеха и best-effort при откате; purge-v0.sh тоже их знает.

• Скрипт автоотката собирался однострочником внутри sh -c '...'. Интерполяции проходили через shell-квотирование и подставлялись внутрь уже закавыченной строки: корректность держалась на склейке соседних кавычек и на том, что op-id не содержит пробелов. Скрипт вынесен в отдельную чистую функцию, ключ операции проверяется, а результат покрыт тестом и разбирается настоящим shell-парсером.

• Ключ операции считался в двух местах и разошёлся. install писал в маркер сырой ISO-timestamp с двоеточиями, тогда как каталог отката назывался санитизированным ключом: путь /run/hy2xs/rollback/<op_id>, который runbook предлагает открыть, на сервере не существовал.

• Стадии восстановления reconfigure были независимы по группе, а не по файлу. Отказ cp для hy2xs-admin.service отменял восстановление hysteria-server.service: внешняя стадия честно попадала в список отказавших, но принцип «восстановить максимум» на уровне файлов не выполнялся.

• Отказ записи маркера auto-rollback-fired оставался незамеченным. Инвариант фиксации — «маркера нет и юниты inactive ⇒ guard не сработал» — верен только при дополнительном условии «guard способен записать маркер». Пока rc=0 стояло ПОСЛЕ создания маркера, отказ записи (заполненный tmpfs /run, read-only ФС) не влиял ни на что: скрипт успешно восстанавливал прежний firewall, завершался кодом 0, юнит уходил в inactive, маркера не было — и операция фиксировала успех после реально сработавшего отката. Теперь у факта срабатывания два независимых канала: маркер и отказ юнита.

  Отдельно: маркер создаётся touch, а не : >file. Двоеточие — special builtin POSIX, и ошибка перенаправления на нём обязана завершить неинтерактивный shell целиком; в dash, который на Debian и есть /bin/sh, скрипт умер бы ДО восстановления firewall.

• Новая операция могла начаться, пока guard предыдущей ещё вооружён. Замок и guard вводились по отдельности и оставляли дыру на своём стыке. Замок действует, пока жив процесс-держатель; guard — отдельный объект systemd, который свой процесс переживает:

  A берёт замок -> применяет firewall -> вооружает guard на 45 секунд
  A аварийно умирает
  B берёт замок и начинает менять production paths
  guard A срабатывает и возвращает firewall, который был ДО A
  

  Случай с SIGTERM/SIGHUP при этом хуже, чем kill -9: обработчик снимает замок сам, поэтому проверка живости держателя не видит вообще ничего, а таймер остаётся. Введён барьер покоя, через который проходит каждый захват замка — и PHASE 0 установщика тоже. Условие старта стало «у предыдущей операции не осталось исполнителей, способных изменить систему».

• Восстановление UnitFileState обещало точность, которой не давало. systemctl enable --runtime не удаляет постоянную ссылку, поэтому «восстановление» состояния enabled-runtime оставляло юнит включённым в обоих scope'ах. Теперь восстанавливаются enabled и disabled — состояния, которые операция реально меняет, — а остальные явно называются оператору и не трогаются.

Исправлено — целостность отката

• Данные для отката уничтожались до фиксации успеха. Успешный install заканчивался вызовом, который снимал таймер автоотката и удалял резервные копии firewall, — и стоял этот вызов ДО долговечной записи phase: installed. Если запись падала (ENOSPC, EIO, read-only ФС), управление уходило в обработчик ошибки, обязательный откат честно запускался и сообщал no HY2XS rollback markers found. Откат нельзя было отменить, но откатывать ему было нечем — причём отказ записи маркера это ровно тот сценарий, который был специально сделан безопасным прошлым проходом.

  Операция разделена на disarmFirewallRollback (снять таймер, копии оставить) и cleanupFirewallRollback (удалить копии). Порядок теперь: smoke_ok → disarm → durable installed → cleanup best-effort. То же в reconfigure.

• Резервные копии снимались без доказательства. И firewall, и reconfigure копировали файлы как cp ... || true, поэтому отказ копирования игнорировался, а операция начинала менять систему, не имея копии, на которую рассчитывает откат. У firewall маркер prepared («данные для отката существуют») выставлялся вообще до копирования. Копирование стало строгим, факт создания проверяется, маркер ставится после.

• Копии reconfigure смешивались между операциями. Они лежали одним общим набором *.bak в /etc/hy2xs/backups, не привязанным к проходу. Если у операции B копирование падало, B всё равно менял систему, а его откат восстанавливал файлы, сохранённые операцией A: сервер возвращался не в состояние «до B», а в более старое — и это выглядело успешным откатом. Копия стала операционной: /etc/hy2xs/backups/<op-id>/ с манифестом, где отсутствие файла — записанный факт ("present": false), а не вывод из неудачи cp. Разбор манифеста строгий, включая проверку opId.

• Ошибка восстановления скрывалась, а копии после неё удалялись. rollbackFirewallNow выполняла cp и nft -f с || true, а затем безусловно удаляла /run/hy2xs/rollback/<op>. Худшая возможная комбинация: неудача восстановления не видна, стадия отчитывается успешной, а данные, по которым оператор мог бы поднять firewall вручную, уничтожены. Теперь копии удаляются только после подтверждённого успеха, иначе сохраняются с сообщением manual recovery data preserved at ….

• Команды отката глушили собственный код возврата. systemctl stop, disable, reset-failed, cp, nft -f, daemon-reload, restart — все несли || true. До появления стадийного раннера это была единственная защита от обрыва цепочки; после его появления — маскировка: стадия физически не могла сообщить, что ничего не сделала, и обещание «отказавшие стадии перечисляются» для них не выполнялось никогда. || true убран, непрерывность обеспечивает раннер, rollbackCurrentState разбита на семь независимых стадий.

• Долговечность записи каталога маркера. writeTextAtomic синхронизирует файл и каталог, в котором файл лежит, но при первой установке /var/lib/hy2xs создаётся тут же, и запись «hy2xs» в /var/lib оставалась несинхронизированной: после потери питания мог исчезнуть весь каталог вместе с маркером. ensureDir сообщает о фактическом создании и синхронизирует родителя только тогда.

Изменено — свойства, ставшие инвариантами

• doctor read-only по инварианту рантайма, а не по соглашению. Принудительный skipServiceStart закрывал ровно одну ИЗВЕСТНУЮ мутацию — рестарт сервисов. Всё остальное в smoke держалось на том, что автор правки выбрал правильный раннер, а читающие команды (test -s, grep -q, stat, sudo -u ... test, nft -c) шли через мутирующий namespace. То есть настоящая мутация, случайно добавленная в smoke, ничем бы от них не отличалась и была бы разрешена в doctor молча.

  Эти команды классифицированы честно, ожидание между попытками перестало быть подпроцессом sleep через мутирующий раннер, а сам doctor целиком выполняется под тем же read-only guard, что и PHASE 0 установки. Диагностика при этом не сузилась.

Исправлено — reset-admin

• Отказ базы трактовался как «администратора нет». Слой данных специально различает ErrAdminUserNotFound и ErrStorage, но команда восстановления доступа склеивала их обычным if err != nil { создать } else { обновить }. Опасен здесь не только нарушенный смысл sentinel'ов: при транзиентном отказе чтения («database is locked») ветка создания отрабатывала успешно, и в таблице оказывались ДВЕ учётные записи администратора. GetAdminUser берёт First() и о второй строке не сообщает — то есть на сервере оставалась вторая рабочая учётка с паролем, уже напечатанным на экран, и ни один запрос об этом не говорил.

• Ошибка хеширования пароля проглатывалась. В ветке обновления стояло hash, _ := util.HashPassword(password) внутри литерала map. При отказе bcrypt в password_hash уезжала пустая строка, а на экран печатался пароль, которым войти уже невозможно: VerifyPassword отклоняет всё, что не является bcrypt-хешем. Команда восстановления доступа умела молча его отобрать.

Исправлено — восстановление после неудачной операции

• Запись состояния отказа отменяла откат. Обработчик ошибки в install и reconfigure первым делом писал в install-state.json фазу отказа обычным await и только потом откатывался. Эта запись — mkdir, write и chown в /var/lib/hy2xs, то есть она падает ровно там, где откат нужнее всего: заполненный диск, read-only ФС, ошибка ввода-вывода. Бросок уносил управление наружу, и обязательное восстановление не выполнялось вовсе — применённый firewall и развёрнутые сервисы оставались на сервере.

  Необязательная телеметрия состояния стояла перед обязательным восстановлением. Для сбора диагностики это уже было закрыто прошлым проходом, для записи состояния — нет. Теперь запись обёрнута так же: неудача попадает в журнал строкой failed to persist failure state, continuing with the mandatory rollback, а откат продолжается.

• Откат отменял сам себя. Он был написан цепочкой await, а каждая его стадия — systemctl, cp, rm -rf или nft, то есть умеет упасть сама. Отказ первой стадии отменял все последующие. В reconfigure это означало сервер одновременно с применённым сломанным firewall и без восстановленных из /etc/hy2xs/backups конфигов — худший сценарий отказа лишался обеих половин восстановления сразу.

  Внутри rollbackCurrentState болезнь была та же: единственная команда без || true (systemctl daemon-reload) отменяла перезапуск сервисов строкой ниже, и восстановленные unit-файлы так и не применялись.

  Стадии стали независимыми: выполняются все и в объявленном порядке, отказавшие перечисляются в журнале, наружу уходит исходная ошибка операции.

• У маркера установки было два писателя с разными гарантиями. install перезаписывал файл на месте, reconfigure подставлял атомарно; слабейшая гарантия досталась команде, которая этот файл создаёт. Перезапись на месте укорачивает файл до нуля и только потом наполняет — отказ между этими моментами оставляет половину JSON, которая не разбирается: reconfigure видит такой маркер как отсутствующий, clean-host — как присутствующий, а хост к этому моменту уже изменён.

  Атомарности при этом было бы мало: rename() без fsync даёт атомарность видимости без долговечности, и после потери питания ext4 штатно отдаёт по этому пути нулевой файл. Порядок теперь: права и владелец → fsync файла → rename → fsync каталога.

• Ownership-флаг маркера отвечал не на тот вопрос. Он назывался stateWritten и взводился ПОСЛЕ успешной записи, хотя запись — это три операции. Отказ на chown оставлял файл на диске при невзведённом флаге, то есть давал классификацию fatal_pre_apply — «на сервере ничего не изменено» — при уже существующем /var/lib/hy2xs/install-state.json, который ломал следующую чистую установку. Флаг переименован в stateTouched и взводится до первой операции записи, как все остальные.

Изменено — релизные гейты сборки

• pnpm audit проверяет весь lock-граф, а не production-подграф. Гейт запускался с --prod под обоснованием «devDependencies в артефакт не попадают». Для frontend build tooling это неверно по существу: vite и rollup не копируются на сервер, но исполняются на build-машине и порождают тот самый production-бандл. Ровно такой случай и был найден в этом же релизном цикле — DOM clobbering в Rollup затрагивал генерируемый бандл, а --prod его не показывал; по всему графу тот же прогон дал 33 предупреждения против нуля. Критерий приёмки №47 в docs/11 формулировал это правильно ещё до того, как стало правдой в коде.

• Удалён SKIP_TESTS. Переменная была описана как «аварийное отключение тестов; для release-сборок недопустимо». Недопустимость держалась исключительно на этой фразе: ни metadata, ни финальная приёмка архива не проверяли, что тесты запускались, поэтому SKIP_TESTS=true ./tools/build/build.sh доходила до конца и выдавала обычный tarball с build_profile=production и dependency_security_gate=true — артефакт, по которому невозможно отличить проверенную сборку от непроверенной. Глушила она при этом не только тесты, но и tsc --noEmit с go vet.

  Выбран тот же строгий вариант, что и для проверки зависимостей: обхода нет, а готовый пакет объявляет tests_gate=true в metadata/package.env. Поле опирается на фактический прогон — write_metadata отказывается писать метаданные, если хотя бы один из двух прогонов не подтверждён. Для локальной работы обходить нечего: bun test, tsc --noEmit, go vet и go test запускаются напрямую и tarball не создают.

Исправлено — операции, не выполняющие обещанного

• Удаление bootstrap-admin-peer не было отзывом доступа. Признаком «создавать пир или нет» служило наличие строки в таблице пиров, а HY2XS_ADMIN_CON_PASS продолжает жить в /etc/hy2xs/hy2xs.env — его читает systemd-юнит. Поэтому оператор удалял пира, доступ действительно исчезал, а ближайший systemctl restart hy2xs-admin или перезагрузка сервера возвращали того же пира с тем же секретом. Молча: ни строки в журнале, в списке пиров запись просто снова есть.

  Признаком стала отметка BOOTSTRAP_PEER_SEEDED в таблице config: она отвечает на вопрос «пир КОГДА-ЛИБО создавался», а не «существует сейчас». Отметка и сам пир пишутся одной транзакцией — раздельная запись вернула бы прежнее поведение при падении процесса между двумя операциями. Удаление осталось разрешённым и стало необратимым; отключение (Disabled = 1) остаётся вторым, обратимым способом.

• Резервная копия с секретами могла молча оказаться неполной. ListExportPeer(true) проглатывала и ошибку расшифровки, и отсутствие шифртекста, отдавая пира с пустым полем secret и успешный ответ. Оператор, СПЕЦИАЛЬНО выбравший режим «копия с действующими credentials», получал файл, выглядящий полным, и узнавал о потере после импорта на новом сервере — по отвалившимся клиентам. Теперь недоступный секрет хотя бы одного пира отклоняет весь запрос с указанием имени; файл не создаётся. Безопасная выгрузка (includeSecrets=false) не изменилась.

• DecryptPeerSecret возвращала содержимое колонки как расшифрованный секрет, если оно не начиналось с v1:. Ветка досталась от поколения, где секреты пиров лежали открытым текстом; при clean-install-only политике такой строки существовать не может, а вред оставался: повреждённая колонка уходила в клиентскую ссылку и в резервную копию как учётные данные. Формат хранения теперь ровно один, всё остальное — ошибка. Тот же класс, что и удалённый SHA-224 fallback при входе.

• hy2xs-orchestrator doctor перезапускал оба сервиса. Команда собирала контекст с параметрами по умолчанию и звала общий smoke, который начинается с systemctl restart hysteria-server hy2xs-admin. То есть диагностика, которую runbook предлагает запускать при подозрении на проблему, гарантированно обрывала все живые VPN-соединения — включая случай, когда с сервисом всё в порядке. Диагностика, меняющая то, что диагностирует, отвечает не на заданный вопрос. doctor принудительно выставляет skipServiceStart; остальные проверки smoke выполняются полностью.

• Админка сама придумывала HYSTERIA2_TRAFFIC_STATS_SECRET. При пустом env и пустой базе она генерировала случайный токен, записать который в /etc/hysteria/config.yaml не может — файл принадлежит оркестратору и доступен ей только на чтение. Сервис объявлял себя здоровым, а machine auth переставал совпадать, потому что Hysteria продолжала слать прежнее значение. Тот же принцип, что уже действует для HY2XS_ADMIN_INITIAL_PASSWORD: пустой env при пустой базе — отказ старта; уже согласованный токен в базе принимается.

• Обходы проверки зависимостей существовали только на бумаге. Документированные dependency_security_gate=accepted-risk и skipped не могли произвести артефакт: финальная приёмка архива требует буквально true, поэтому сборка с ними проходила весь цикл и падала на последнем шаге. Продукт документировал операцию, которую сам же запрещал. Обе переменные удалены из сборки и документации; их отсутствие проверяется приёмкой. Контракт стал однозначным: релизный артефакт невозможно собрать с непройденной проверкой.

• UPDATE по отсутствующей строке config считался успехом. updateConfigOn смотрел только на tx.Error, а UPDATE без совпавших строк ошибкой SQL не является. Следом applyRuntimeConfigUpdates применял значение к планировщику, поэтому оператор дважды получал подтверждение изменения, которого не произошло, а перезапуск сервиса возвращал прежний cron. Решение принимается по RowsAffected — как в соседней UpsertConfigValue, где эта же ошибка уже была разобрана.

• Слой данных не отличал «записи нет» от «база не ответила». Каждый Get* возвращал свежий errors.New со строкой, поэтому отказ SQLite был неотличим от отсутствия записи, а решения на этом принимались серьёзные: «пира нет» означало «создать заново», «по auth_id не нашли» — «искать по имени и, не найдя, создать», «ошибка» в ExistPeerName — «имя свободно». При недоступной базе продукт не отказывал, а трактовал отказ как разрешение действовать. Введены sentinel-значения ErrPeerNotFound, ErrAdminUserNotFound, ErrConfigNotFound и ErrStorage.

• Алиасы /:id/client-url и /:id/qr удалены. Они были оставлены «на один миграционный релиз», которого у clean-install-only продукта не существует; дожив до 1.0.0, они стали бы частью публичного API v1.

Добавлено — контракт разработки

• apps/go.mod объявляет toolchain go1.26.7. Директива go — языковой baseline модуля, а не выбор компилятора: с ней одной локальный go build на другой минорной линии проходил успешно, хотя релизный бинарь собирается на 1.26.7 и наследует её stdlib. Разработчик и сборка проверяли разный код. Совпадение с versions.env проверяет verify_go_toolchain_contract.

• tools/dev/doctor.sh и tools/dev/doctor.ps1 сверяют Go, Node, pnpm, Bun и директиву toolchain с versions.env. Собственных значений версий у них нет — второй список неизбежно разъехался бы с контрактом. Сборка соблюдала versions.env и раньше; машина разработчика не проверялась никак, и расхождение обнаруживалось на Debian, внутри release-сборки.

Изменено — модернизация frontend

Известное ограничение «проверка типов frontend почти ничего не проверяет» закрыто и удалено из документации.

• vue-tsc стал настоящим release gate. Он был версии 0.35.0 (2022 год) и шаблоны Vue не типизировал: проверка проходила зелёной, не давая обещанной гарантии. На Vue 3.5 она к тому же ломается сама, не зная vue/jsx-runtime, — то есть пережить обновление Vue не могла в любом случае.

  Современный vue-tsc 3.3 на том же коде дал 142 ошибки, а не ~155 из прогноза, и картина оказалась однороднее: 141 × TS18048 и одна TS2322, всё в двух файлах представления Hysteria. Ожидавшегося класса «DefaultRow несовместим с PeerVo» на Element Plus 2.3 не существовало — он появился вместе с обновлением Element Plus до 2.14.

  Скрипты разделены: typecheck, build:prod, verify. Сборка запускает проверку типов до bundle; раньше vite build && vue-tsc сначала тратил время на production bundle и только потом сообщал о типовой ошибке.

• Нормализация конфига Hysteria на границе API. Все 142 ошибки — обращения к необязательным секциям конфига в шаблоне. Необязательны они правильно: так устроен upstream YAML. Инвариант «секция есть всегда» существовал, но держался на порядке присваиваний внутри компонента и типом не выражался. Введён Hysteria2ServerConfigView, выводимый из модели ответа типом, а не вторым списком полей, — вместо 141 оператора ?. или as any.

• Убраны три редактора, которые ничего не сохраняли. Outbounds, список значений и словарь «ключ — значение» на странице конфига Hysteria: страница отрисована с :disabled="true", значения передаются без v-model, маршрутов записи серверного конфига в API нет. Оператор мог добавить outbound, увидеть его в списке и уйти в уверенности, что изменил конфигурацию сервера.

  У одного цена была ещё и измеримой: vuedraggable поставляется UMD-сборкой, поэтому её require("vue") разрешался в полную сборку Vue с рантайм-компилятором — около полумегабайта в bundle ради перетаскивания тегов в недоступной для редактирования форме.

• pnpm audit по всему графу: 33 предупреждения → 0. Из них четыре затрагивали production-зависимости (vue-i18n, echarts), остальные — build-цепочку. Среди последних был rollup GHSA DOM clobbering, а он затрагивает генерируемый bundle, то есть уезжает в production: pnpm audit --prod, на который смотрит gate сборки, его не показывал.

  Обновлены: Vue 3.2 → 3.5, TypeScript 4.9 → 5.9, Element Plus 2.3 → 2.14, Vue Router 4.1 → 4.6, Pinia 2.0 → 2.3, VueUse 9 → 14, echarts 5 → 6, Vite 4.3 → 7.3, eslint 8 → 10 (с переходом на flat config), stylelint 15 → 17. Pinia 3, Vue Router 5 и Vite 8 сознательно не берутся: Vite 8 — это переезд на Rolldown, остальные не дают проекту ничего, кроме номера версии.

• vite-plugin-svg-icons заменён собственным спрайтом. Плагин не обновлялся с 2022 года и тянул svgo 2.8, postcss 5.2.18 и image-size 0.5.5, у которой advisory сообщает Patched versions: <0.0.0 — исправленной версии не существует. Проверка на реальных ассетах поймала то, что иначе уехало бы в релиз: три иконки из семнадцати не объявляют viewBox, и без его синтеза из width/height отрисовывались бы обрезанными.

• Разбор bundle через sourcemap нашёл вторую потерю: @vueuse/core собирался дважды — наш и тот, что тянет Element Plus. Версии сведены.

  Итог по размеру: 2 819 722 байта против 2 404 202 на исходной базовой линии. Рост в 17% — цена Vue 3.5, Element Plus 2.14, echarts 6 и rollup 4; промежуточное состояние до двух исправлений выше было 3 046 172.

Исправлено — сборка не собиралась

• build.sh детектировал сам себя и падал шестым шагом из четырнадцати. verify_api_namespace_contract искал возвращение legacy-пространства имён через grep -rlF '/hui' по списку каталогов, в который входили tools/build и тесты. Поиск находил два файла: apps/router/router_test.go, который ПЕРЕЧИСЛЯЕТ legacy-префикс, чтобы доказать отсутствие маршрута, и сам versions.sh, где эта строка стоит в тексте проверки. То есть добавление теста, закрепляющего очистку, ломало сборку, а до резолва Hysteria дело не доходило вовсе.

  Скан теперь идёт только по runtime production sources и по тому, что уезжает в пакет, с исключением *_test.go. Гарантия не ослабла, а переехала на слой, где она сильнее: отсутствие маршрута доказывает TestRouterHasNoLegacyNamespace на таблице маршрутов собранного роутера, и существование этого теста само стало частью контракта.

• Второй такой же контракт прятался за первым. Проверка «импорт пиров не выходит за транзакцию» брала source.slice(start) — файл от начала applyPeerImportEntry и до конца, — захватывая объявленные ниже ExistPeerName и UpdatePeerLastConnectionAt. Это обычные операции вне импорта, которым глобальное соединение положено, поэтому проверка падала на корректном коде. Замечена не была только потому, что сборка до неё не доходила. Границей тела функции теперь служит следующее объявление верхнего уровня.

  Отсюда общее правило и помощники code_without_comments / code_mentions_in в acceptance.sh: приёмка проверяет код, а не упоминания.

Исправлено — runtime

• Смена расписания сброса трафика размножала планировщики. middleware.InitCron() вызывался из runServer и на каждом вызове создавал новый cron.New(), нигде не сохраняя ссылку; cron.Stop() не вызывался нигде. При этом смена RESET_TRAFFIC_CRON выполняла StopServer(), а точка входа крутила for { runServer() } и поднимала сервис заново.

  Каждая правка добавляла целый дублирующий набор джоб — учёт трафика, сбор метрик, уборка статистики, — а старое расписание сброса продолжало работать. После двух правок на процессе висели три планировщика и три разных расписания одновременно. Плюс окно, в котором джобы старого планировщика били в уже закрытое SQLite-соединение: releaseResource() отрабатывал раньше, чем следующий runServer успевал открыть базу.

  Планировщик теперь принадлежит процессу: фиксированные джобы регистрируются один раз, расписание сброса переносится на месте по своему EntryID, HTTP-сервер к смене настройки отношения не имеет. Цикл перезапуска в точке входа удалён — перезапуском упавшего юнита занимается systemd.

• Невалидное cron-выражение принималось API и молча отключало сброс трафика. Поле в панели — el-select с allow-create, то есть строка произвольная; backend принимал её как строку до 128 символов, а ошибка AddFunc при следующем старте только логировалась. Оператор получал успех, панель работала, автоматический сброс исчезал.

  Выражение проверяется до записи в базу тем же парсером (cron.ParseStandard), которым его потом разбирает планировщик. Невалидное значение — отказ, база не меняется. Пустое значение легально и означает «сброс выключен».

• updateConfigs применял партию частично. Валидация и запись шли в одном цикле, поэтому партия «разрешённый ключ + запрещённый» применяла первый и возвращала ошибку на втором. Существовавший тест ставил запрещённый ключ первым и не смотрел в базу — поймать это он был неспособен по построению.

  Теперь: полная проверка партии → одна транзакция (dao.WithConfigTx) → применение к рантайму. Тест переписан на обратный порядок ключей и проверяет состояние базы на настоящей SQLite.

• Сервис не завершался штатно. SIGTERM от systemd убивал процесс на середине: соединения обрывались, SQLite закрывался вместе с процессом, джобы могли быть остановлены посреди записи. Добавлено штатное завершение — планировщик глушится и дожидается запущенных джоб, затем закрывается база.

• Ложные ERROR в журнале на каждой первой загрузке. Создание секретов шло по схеме «сначала INSERT, при ошибке UPDATE», а строки ключей уже существовали из seedBaseConfig: три записи duplicated key not allowed уровня error на совершенно здоровом старте. Зеркальная схема «сначала UPDATE, при ошибке INSERT» в других местах была хуже — она тихо не делала ничего, если строки не было: UPDATE без совпавших строк не ошибка, поэтому ветка INSERT не выполнялась, а вызывающий получал сгенерированный секрет как сохранённый. Для JWT_SECRET это означало бы подпись токенов ключом, которого нет в базе. Обе схемы заменены на dao.UpsertConfigValue, решающий по RowsAffected.

• Дублирующая реализация генерации ключей шифрования. В service/peer_secret.go лежали построчные копии getOrCreateConfigKey и getPeerSecretEncryptionKey из dao/sqlite.go: две функции в двух пакетах, порождающие один и тот же материал шифрования. Расхождение между ними означало бы, что секреты пиров шифруются одним ключом, а расшифровываются другим. Осталась одна реализация в dao.

Безопасность

• Bootstrap-пароль администратора писался в журнал открытым текстом. При отсутствии HY2XS_ADMIN_INITIAL_PASSWORD админка генерировала пароль сама и печатала его двумя logrus.Warnf в /var/log/hy2xs/hy2xs-admin.log — файл, который отдаётся кнопкой выгрузки и попадает в diagnostics-бандл. Такой пароль к тому же не знал никто, кроме журнала.

  Отсутствие переменной теперь отказ старта с объяснением причины. То же для HY2XS_ADMIN_CON_PASS при создании пира установщика: его секрет продублирован в /etc/hy2xs/bootstrap-admin.secret, откуда его читает проверка machine-auth, и придуманный админкой секрет разошёлся бы с файлом.

• Собственный журнал админки выгружался без санитайза, хотя чужой (журнал Hysteria) — с санитайзом. Теперь оба проходят SanitizeLogText, и во вкладке просмотра тоже.

• golang-jwt/jwt v3 в пути аутентификации. У v3.2.2 есть GO-2025-3553, у которой нет исправленной версии в ветке v3 (Fixed in: N/A), а уязвимый код достигается из ParseToken, то есть с неаутентифицированного запроса. Выполнен переход на jwt/v5.

  Заодно закрыт тихий недостаток: keyfunc возвращал ключ, не проверяя алгоритм подписи, — набор допустимых алгоритмов фактически задавал сам токен. Разбор ограничен jwt.WithValidMethods, проверяются issuer и обязательное наличие срока жизни; пустой JWT_SECRET считается повреждённым состоянием, а не ключом нулевой длины.

• Вход по несолёному SHA-224 больше невозможен. VerifyPassword принимала такой хеш как «legacy»-формат предыдущего поколения. В v1 он недостижим: миграции таблицы account удалены, установка возможна только на чистый хост, конфигурация 0.x отклоняется по схеме. Compatibility-ветка пережила слой совместимости, ради которого существовала, и осталась запасным путём проверки пароля слабым алгоритмом в обработчике логина.

• Modulo bias в генераторе секретов. util.RandomString брала остаток байта от деления на длину алфавита (62): первые восемь символов выпадали примерно на четверть чаще остальных. Через эту функцию проходят JWT_SECRET, PEER_SECRET_KEY, PEER_SECRET_ENCRYPTION_KEY, секрет trafficStats API, секреты и auth_id пиров. Добавлена отбраковка (rejection sampling).

• Пир установщика был защищён только в импорте. Обычный CRUD панели позволял переподписать или переименовать bootstrap-admin-peer, молча рассинхронизировав базу с /etc/hy2xs/bootstrap-admin.secret. Защита распространена на все пути записи; удаление и отключение остаются разрешёнными — это осознанные действия оператора, не создающие расхождения.

• Латентная паника в разборе токена. service.GetToken доставала токен через strings.SplitN(header, " ", 2)[1] и падала на заголовке без пробела. Единственный потребитель — резервная ветка GetAdminInfo, недостижимая и проверявшая меньше, чем middleware (ни статус учётной записи, ни версию токена). Оба удалены: разбор токена у продукта ровно один.

• reset-admin генерировал 6-символьные логин и пароль — нижняя граница, которую пропускает HashPassword. Увеличено до 12 и 24.

Изменено

• Toolchain переведён на поддерживаемые линии. GO_VERSION 1.21.13 → 1.26.7, NODE_VERSION 20.19.0 (EOL) → 24.20.0. Go компилирует hy2xs-admin, поэтому его stdlib целиком попадает в production-бинарь: на прежнем графе govulncheck ./... находил 21 вызываемую уязвимость, из них 17 в stdlib. После перехода и обновления зависимостей — ноль.

  Bun намеренно оставлен на 1.3.13: оркестратор собирается через bun build --compile, то есть Bun runtime входит в исполняемый файл, и смена его версии требует отдельного прохода по всей матрице проверок.

• Добавлен обязательный шаг проверки зависимостей (tools/build/lib/security.sh): govulncheck ./... для Go-графа и stdlib с анализом достижимости и pnpm audit --prod для frontend. Версия govulncheck пиньтся в versions.env, база уязвимостей подтягивается на каждом запуске. Аварийный выход — ALLOW_VULNERABLE_DEPENDENCIES=true; результат уезжает в metadata пакета полем dependency_security_gate.

• Обновлены зависимости frontend, попадающие в браузерный бандл: axios 1.3.4 → 1.20.0, плюс lodash/lodash-es через pnpm.overrides до 4.18.1. Прямые зависимости и их диапазоны не менялись — двинулся только lockfile. В production-графе не осталось уязвимостей уровня high и critical.

Удалено

• Четыре ключа таблицы config без единого потребителя — HYSTERIA2_ENABLE (жизненным циклом Hysteria владеет systemd), HYSTERIA2_CONFIG (второй источник истины рядом с /etc/hysteria/config.yaml, причём читался первым), HYSTERIA2_TRAFFIC_TIME (настройка «период учёта трафика», которую не читал никто: интервал сбора метрик задан в коде) и HYSTERIA2_CONFIG_REMARK (пустая read-only строка). Строки удаляются миграцией 006_drop_dead_config_keys.

  Настоящую замену получил только последний: имя профиля в клиентской ссылке теперь выводится из имени пира, а при его отсутствии — из публичного хоста.

  После очистки панель владеет ровно одной настройкой — RESET_TRAFFIC_CRON.

Исправлено — предыдущий проход

• Каждая чистая установка падала сразу после apt-get. Внутри install preflight() вызывался дважды, и оба раза проверял контракт чистого хоста. Ко второму вызову на диске уже лежал собственный /var/lib/hy2xs/install-state.json, записанный после первого preflight, — и он опознавался как маркер посторонней установки. Отказ приходил уже как fatal_post_apply: сервер оставался наполовину настроенным, а повторный запуск упирался в тот же маркер.

  Причина в том, что clean-host и проверка возможностей платформы ехали одним параметром, хотя отвечают на разные вопросы: чистота хоста — условие входа в операцию, а systemd-run/nftables/OpenSSL 3 проверяются уже после installDeps, то есть внутри PHASE 1. preflight() теперь принимает checkCleanHost явно и без значения по умолчанию в режиме install: любое умолчание здесь неверно, решение обязано приниматься на месте вызова.

• PHASE 1 начиналась вне зоны ответственности оркестратора. install.sh сам создавал /usr/local/lib/hy2xs, ставил туда бинарник, вешал symlink в /usr/local/bin и копировал runtime-пакет — и только потом запускал оркестратор, у которого дальше шёл собственный preflight. Если тот отказывал (сменился DNS, занялся порт, не ответил резолвер), ни один ownership-флаг не был взведён: отказ классифицировался как fatal_pre_apply, и оператор читал «на сервере ничего не изменено» при уже созданном каталоге оркестратора. Следующий запуск упирался в эти пути как в маркеры чужой установки.

  Отследить владение мутацией невозможно, пока мутируют двое. Теперь install.sh не изменяет на сервере ничего: он проверяет и передаёт управление через exec. Раскладку выполняет сам оркестратор — шаг steps/bootstrap.ts под флагом ownership.bootstrapTouched, а сами пути попадают в owned_paths install-state наравне с остальными. Сборка проверяет структурно, что в установщике не осталось ни одной мутирующей команды.

  Побочный эффект: у списка clean-host маркеров больше нет «мягкой» версии для PHASE 1. Она существовала только затем, чтобы установка не отказала на путях, которые shell создал между фазами.

• Machine token утекал в обычные логи при каждом подключении пира. Hysteria обращается к машинному endpoint'у как /internal/hysteria/auth?access_token=<секрет>, а журнал админки писал c.Request.RequestURI — то есть путь вместе с query string. Действующий токен оседал открытым текстом в /var/log/hy2xs/hy2xs-admin.log, который отдаётся оператору через ExportLog и попадает в diagnostics-бандл. Вся структурная редакция, сделанная для конфигов и env, этот канал не закрывала.

  Логируется путь; значения query-параметров не пишутся вовсе, имена — пишутся (reqQueryKeys). Поле reqUri удалено из модели журнала.

  Каналов было два: gin.Default() подключает gin.Logger(), который печатает путь вместе с query в stdout, откуда он уходит в journald, а оттуда — в diagnostics-бандл. Панель запускается через gin.New() + gin.Recovery(), и HTTP-логгер у продукта остался ровно один.

  Дополнительно: журналы внутри diagnostics-бандла (journal-admin.log, journal-hysteria.log, вывод systemctl status) больше не копируются как есть, а проходят санитайз; тот же проход применяется к журналу Hysteria, который админка отдаёт через ExportLog. Сравнение machine token переведено на subtle.ConstantTimeCompare.

• Config API позволял прочитать и подменить криптографические ключи приложения. Generic export/import таблицы config удалили, но точечный API остался прежним: getConfig/listConfig принимали произвольный ключ, а проверка записи работала denylist'ом из трёх ключей оркестратора. Запрос ?key=PEER_SECRET_ENCRYPTION_KEY отдавал master-key шифрования секретов пиров, а updateConfigs позволял подменить JWT_SECRET и оба peer-ключа.

  Доступ переведён на allowlist: наружу открыты только HYSTERIA2_TRAFFIC_TIME, RESET_TRAFFIC_CRON (чтение и запись) и HYSTERIA2_CONFIG_REMARK (только чтение). Denylist требует, чтобы автор каждого нового ключа вспомнил про этот файл; при allowlist забытый ключ закрыт. Маршрут GET /api/config/getConfig удалён целиком — потребителей у него не было ни одного, а фильтр на неиспользуемой двери остаётся дверью.

• Импорт пиров не был атомарным, вопреки собственному контракту. Партия проверялась целиком до первой записи, но применялась по одной записи, каждая своим оператором. Валидация ничего не знает о том, что уже лежит в базе: пусть есть A(auth_id=aaa, name=alice1) и B(auth_id=bbb, name=bob123), а файл несёт (auth_id=aaa, name=bob123) — поиск найдёт A по auth_id и попытается переименовать её в bob123, прямо в UNIQUE(name). Всё, что шло в файле до конфликтной строки, оставалось применённым, и откатить это оператор уже не мог.

  Применение выполняется одной транзакцией (dao.WithPeerTx). Криптоматериал считается до её открытия: digest и шифрование читают ключи из той же таблицы config, и держать на ней открытую запись во время AES по каждой из тысяч записей незачем.

• Файл импорта мог содержать хвост, который молча не применялся. json.Decoder читает первый документ и останавливается, поэтому файл вида [{...}]\n{"что-то":"ещё"} принимался целиком: оператор видел «импорт выполнен» и не узнавал, что применилась половина. После разбора проверяется io.EOF.

• Отказ сбора диагностики отменял откат. В install и reconfigure diagnosticsCollect() стояла перед rollback обычным await. Она создаёт каталог, копирует файлы и упаковывает tar — на заполненном диске падает сама, и тогда худший сценарий отказа установки гарантированно лишался единственного механизма восстановления. Диагностика — best effort, откат — обязателен.

• fatal_pre_apply мог означать «хост уже изменён». install-state.json пишется сразу после успешного preflight, до установки пакетов, но классификация отказа его не учитывала. Падение apt-get update или apt-get install объявлялось как «на сервере ничего не изменено»: откат и обработка состояния пропускались, а маркер оставался на диске и ломал следующую установку по clean-host контракту.

  Ownership-флаги переформулированы с «шаг успешно завершился» на «операция могла начать менять систему» и взводятся перед мутирующим вызовом: apt-get умеет изменить систему и упасть. fatal_pre_apply теперь недостижим ни при одном взведённом флаге, включая запись состояния.

• Экспорт в админке оставлял секреты на диске навсегда. ExportPeer и выгрузка системного конфига шли через os.Create в /var/lib/hy2xs-admin/export/, и файл там не удалялся. При ?includeSecrets=true это означало расшифрованные секреты пиров — фактические учётные данные доступа — в открытом виде, накапливающиеся с каждым нажатием кнопки. Экспорт формируется в памяти; каталога export/ больше нет.

• Generic export/import таблицы config выгружал и позволял подменить криптографические ключи приложения. Выгрузка исключала только сырой Hysteria YAML, а в той же таблице лежат JWT_SECRET, PEER_SECRET_KEY, PEER_SECRET_ENCRYPTION_KEY и HYSTERIA2_TRAFFIC_STATS_SECRET. Импорт их не блокировал: подмена PEER_SECRET_ENCRYPTION_KEY ломает расшифровку секретов уже существующих пиров. Оба маршрута и их UI удалены — production-сценария у них не было, перенос пиров делают peer-import/peer-export.

• Импорт пиров шёл мимо всей валидации. Обычное создание пира проходит через dto.PeerSaveDto, импорт JSON — нет: в базу попадало имя любой длины и с любыми символами, disabled с произвольным числом, отрицательные счётчики. Файл применялся построчно, поэтому ошибка в середине оставляла список пиров наполовину изменённым, а импорт мог перезаписать bootstrap-admin-peer, чей секрет продублирован в /etc/hy2xs/bootstrap-admin.secret. Партия теперь проверяется целиком до первой записи, неизвестные поля отклоняются, bootstrap-пир защищён.

• DNS проверялся на существование A-записи, но не на то, куда она ведёт. После принудительной смены IPv4 провайдером doctor отвечал успехом, хотя клиентская ссылка отправляла людей на чужую машину. Проверялся при этом HY2XS_DOMAIN, тогда как в hysteria2:// уезжает HY2XS_PUBLIC_HOST.

  Добавлен инвариант публичного endpoint: A-записи обязаны принадлежать множеству публичных IPv4, назначенных интерфейсам этого сервера. Проверка живёт в общем preflight, поэтому действует в install, reconfigure и doctor. Адрес определяется локально, без внешних сервисов определения IP. Строгость управляется HY2XS_PUBLIC_ENDPOINT_POLICY (strict по умолчанию).

• Read-only guard PHASE 0 можно было обойти. Guard стоял на writeText, writeTextAtomic, runVisible, runHidden и runRawVisible, но не на универсальном run, через который в коде проходили и наблюдение (ss, systemctl is-active), и настоящие мутации (useradd, install -d, mkdir, cp -a, tar). Универсального раннера больше нет: есть runReadOnly* без guard'а и runMutating* под guard'ом, а выбор — явное решение на месте вызова.

• Go-санитайзер конфига вырезал секреты из URL только у ключей url/addr. Будущее upstream-поле с другим именем (endpoint:) уносило встроенные учётные данные и access_token наружу целиком; URL внутри списков не обрабатывались вовсе. Граница определяется значением, а не именем ключа — как в TS-санитайзере оркестратора; обе реализации покрыты зеркальными тестами.

• purge-v0.sh --keep-hysteria-binary противоречил установщику. Скрипт сохранял /usr/local/bin/hysteria и сообщал «хост чист для установки HY2XS v1», хотя clean-host контракт считает этот бинарник legacy-маркером и следующая установка отказалась бы. Флаг удалён.

• clean-host не замечал часть того, что удаляет purge. /var/lib/hysteria (ACME-состояние и сертификаты Hysteria), /var/log/hy2xs, /usr/local/lib/hy2xs и /usr/local/bin/hy2xs-orchestrator не были маркерами: сервер, где остался только старый runtime-state Hysteria, проходил проверку и получал свежую установку поверх чужого состояния. Оба списка теперь описывают одну границу, и приёмка это проверяет.

• Установщик мог повредить работающий сервер до того, как откажется его трогать. install.sh переписывал /usr/local/lib/hy2xs, раскладывал runtime-пакет и перезаписывал /var/lib/hy2xs/install-state.json, и лишь потом запускал clean-host preflight. При ошибочном запуске поверх старого сервера rollback дополнительно выполнял stop и disable для работающих hysteria-server и hy2xs-admin.

  Установка разделена на две фазы с жёсткой границей: PHASE 0 — read only, PHASE 1 — mutation. Read-only проверка выполняется новой командой hy2xs-orchestrator preflight-install из распакованного архива, а граница держится runtime-guard'ом, а не соглашением.

• Отсутствие HY2XS_CONFIG_SCHEMA_VERSION считалось текущей схемой. До v1 этого поля не существовало, поэтому именно пустое значение — самый вероятный признак конфигурации 0.x. Теперь оно отклоняется как legacy с указанием на чистую установку. Тест, закреплявший прежнее поведение, инвертирован.

• reconfigure и repair работали поверх любого маркера установки. Проверялся только флаг installed, который мог остаться и от 0.x. Маркер получил идентификацию поколения (product, release_line, config_schema_version), и обе команды проверяют её до всего остального.

• Классификация отказа шла по тексту сообщения об ошибке. Ошибка preflight со словом nftables классифицировалась как отказ firewall и приводила к откату чужого ruleset. Теперь классификация опирается на то, что операция реально успела применить. systemctl stop/disable выполняется только для юнитов, развёрнутых текущей операцией, а fatal_pre_apply по определению не выполняет системный откат и не собирает diagnostics-бандл.

• Diagnostics-бандл уносил machine token наружу. Построчное правило редакции auth: подставляло маркер в заголовок mapping'а и оставляло нетронутым вложенный auth.http.url с access_token=<секрет> — тем самым, что открывает и trafficStats API, и auth-endpoint. Редакция YAML переписана структурно; в env-файлах секреты теперь вырезаются и из URL-значений (HY2_AUTH_URL не подходил ни под один маркер имени).

• quic.maxIdleTimeout не проверялся семантической проверкой конфига, хотя присутствовал в production-профиле. Заодно auth.http.url теперь сверяется целиком (host/port/path/token), а не по наличию подстроки access_token=; добавлены проверки auth.http.insecure, полей ACME и отсутствия посторонних секций верхнего уровня.

• Версия админки разъехалась с версией пакета: пакет 1.0.0 сообщал HY2XS admin version v0.0.22. Константа заменена переменной, которую проставляет сборка через ldflags из versions.env.

• Кнопки в панели, которые всегда возвращали ошибку. «Перезапустить панель» и загрузка сертификатов обращались к заглушкам. Маршруты и UI удалены.

Добавлено

• versions.env — единственный источник истины для контракта «продукт / платформа / toolchain»: версия продукта, линия релиза, схема конфигурации, целевая платформа, версии и контрольные суммы Go/Bun/Node/pnpm, политика выбора Hysteria. Прикладные зависимости и конкретная версия Hysteria сюда намеренно не переносятся: у них есть собственные lock-механизмы.

• Шаг сборки verify_versions_contract. Роняет сборку до создания tarball, если разошлись PACKAGE_VERSION, packageManager в двух package.json, схема в package/config/hy2xs.env, константы, скомпилированные в оркестратор, директива go в apps/go.mod, metadata пакета или версия, которую сообщает собранный hy2xs-admin.

• Контрольные суммы toolchain в контракте, включая обе сборки Bun (bun-linux-x64 и bun-linux-x64-baseline): артефакт выбирается по наличию AVX2, поэтому одной суммы архитектурно недостаточно. Передавать суммы через окружение больше не нужно — production-сборка запускается одной командой.

• Проверка происхождения артефакта Hysteria. Ожидаемый SHA-256 берётся из upstream-ассета hashes.txt и сверяется со скачанным бинарником до записи в HY2XS lock. Раньше сумма считалась локально от уже скачанного файла, то есть была trust-on-first-use.

• Полный clean-host контракт. Список маркеров чужой установки расширен с двух до четырнадцати: состояние, runtime-пакет, конфиги, бинарник Hysteria, фрагмент nftables, systemd-юниты, база админки и наследие 0.x. Пути установки и данных берутся из конфигурации, а не захардкожены.

• tools/legacy/purge-v0.sh и docs/14-legacy-cleanup.md — явная очистка сервера от предыдущего поколения. По умолчанию скрипт показывает план и ничего не делает; выполнение требует --apply --yes-i-know. Из установщика он не вызывается никогда: это вернуло бы destructive migration logic в путь свежей установки.

• Явный флаг --allow-partial-state для repair. Прежде согласие на работу поверх незавершённой установки подразумевалось молча.

• HY2XS_PUBLIC_ENDPOINT_POLICY (strict | warn | off, по умолчанию strict) — строгость проверки того, что публичный endpoint ведёт на этот сервер. Ослабление предназначено для топологий вне baseline: NAT, floating IP, anycast. Отсутствие A-записи фатально при любом значении.

• Раздельные API подпроцессов в оркестраторе: runReadOnly / runReadOnlySecret для наблюдения и runMutating* под read-only guard'ом.

• Сверка API namespace на сборке. Путь machine-auth и базовый префикс админского API объявлены по одной константе на компонент, а verify_versions_contract сверяет Go, фронтенд и шаблоны против значений, скомпилированных в оркестратор.

Изменено

• Пространства имён HTTP API. Операторский и auth API переехали с /hui на /api, machine-auth endpoint Hysteria — на /internal/hysteria/auth. Прежний общий префикс был наследием H UI: под ним лежали и machine-to-machine auth, и JWT-защищённый админский API, хотя middleware у них не пересекаются. Момент выбран до первого clean-install релиза: после 1.0.0 эти строки стали бы частью фактического v1 compatibility contract.

• Сетевая идентичность админки принадлежит оркестратору. Ключи H_UI_WEB_PORT, H_UI_WEB_CONTEXT, H_UI_CRT_PATH, H_UI_KEY_PATH удалены из схемы, seed и интерфейса вместе с собственным TLS-слоем панели. Раньше оркестратор передавал порт аргументом, админка записывала его в SQLite и тут же читала обратно, а UI показывал поля в disabled-виде: второй источник истины, из которого ничего нельзя было изменить. Панель всегда монтируется в /.

• HUI_DATA/HUI_LOG → HY2XS_DATA_DIR/HY2XS_LOG_DIR. Мост в systemd-юните, перекладывавший canonical env HY2XS в имена старого H UI, удалён.

• Экспорт пиров разделён на два явных режима. «Экспорт настроек» — без секретов, «Резервная копия» — с ними, через подтверждение с описанием риска.

  Кнопка была одна и всегда звала маршрут без includeSecrets, хотя документация называла эту пару механизмом переноса пиров. Записи с пустым секретом при импорте получают новые секреты, поэтому перенос обычным экспортом восстанавливал пиров, но все существующие клиентские ссылки после него переставали работать. Разница продуктовая, и оставлять её неявной нельзя.

• reconfigure/repair больше не классифицируют отказ по тексту ошибки. Записываемая фаза выбиралась регулярным выражением /firewall|nft|ssh port check failed/i по сообщению — тот же приём, который уже убрали из install. Классификация переведена на ownership-флаги, а откат firewall выполняется только если эта операция его трогала.

• Список непубличных IPv4 приведён к IANA Special-Purpose Address Registry. Функция называлась «маршрутизируемый публичный IPv4», а исключения покрывали только приватные диапазоны: 203.0.113.5 (TEST-NET-3 из RFC-примеров) считался нормальным публичным адресом сервера. Добавлены документационные (192.0.2/24, 198.51.100/24, 203.0.113/24), benchmarking (198.18/15), 6to4-anycast и IETF protocol assignments.

• Отказ DNS-резолвера отличается от отсутствия A-записи. Любая ошибка resolve4 печаталась как «has no A-record», поэтому при сломанном /etc/resolv.conf оператор шёл править запись, которая была на месте. ENODATA/ENOTFOUND/NXDOMAIN — это «нет записи», всё остальное — «резолвер не ответил», с отдельным текстом. Фатальны оба: без ответа резолвера проверка не выполнена, а не «выполнена с замечанием».

• База админки — hy2xs-admin.db вместо h_ui.db; reference-схема — apps/docs/sql/schema.sql вместо h_ui_db.sql. Совместимость сохранять не требуется: v1 ставится только с нуля. Историческое имя h_ui.db остаётся в docs/14-legacy-cleanup.md — там это имя чужого артефакта, который очистка должна найти.

• Индикатор загрузки и legacy-цвета переведены на брендовый токен. NProgress приходил со своим #29d и был единственным элементом интерфейса вне палитры HY2XS; страницы 401/404 и подсветка выбранной строки таблицы несли цвета исходного admin-шаблона. Все они привязаны к --el-color-primary, а не переписаны вторым литералом.

• Приёмка сверяет схему конфигурации с versions.env, а не с числом 2 в тексте проверки.

• E2E подключается по ссылке из production-кода. Внутри tools/test/e2e-hysteria.sh жила вторая реализация hysteria2:// URI на bash: дрейф любой из двух реализаций оставлял обе группы тестов зелёными. Теперь ссылку выдаёт service.BuildHysteria2ShareURI через apps/tools/share-uri. Единственное расхождение — insecure=1 для самоподписанного сертификата, и оно ограничено тестами с двух сторон.

• Формулировка гарантии санитайза экспорта. Вместо «любой будущий секрет будет удалён» — «известные секреты и неизвестные поля с секретоподобным именем». Список маркеров расширен (apiKey, privateKey, authorization, cookie, bearer, passphrase, signature, …) и синхронизирован между Go-админкой и оркестратором.

Удалено

• Маршруты, операциями которых продукт не владеет: POST /hysteria2ChangeVersion, GET /listRelease, POST /config/updateHysteria2Config, POST /config/importHysteria2Config, POST /config/restartServer, POST /config/uploadCertFile, GET /config/hysteria2AcmePath. Вместе с ними — соответствующие сервисы, клиентские функции фронтенда, кнопки и строки i18n.

  Маршруты удалены, а не оставлены отвечающими «feature disabled»: API-контракт не должен обещать updater, которого у продукта нет, а неиспользуемый маршрут остаётся attack surface.

• POST /config/exportConfig и POST /config/importConfig — generic-выгрузка и загрузка таблицы config вместе с криптографическими ключами приложения. Вместе с ними — кнопки Import/Export в настройках, клиентские функции и строки i18n.

• Персистентный каталог выгрузок /var/lib/hy2xs-admin/export/ и файловый helper util.ExportFile. Артефакт, который покидает сервер, не должен существовать на сервере дольше самого запроса.

• Флаг purge-v0.sh --keep-hysteria-binary.

• Мёртвые строки i18n, оставшиеся от H UI: noHttpsTip, defaultPassTip, hui*, useHysteria2Cert, invalidWebContext, mustBeInteger.

• GET /api/config/getConfig — точечное чтение произвольного ключа таблицы config. Потребителей у маршрута не было ни одного, а список ключей в этой таблице включает JWT_SECRET, PEER_SECRET_KEY и PEER_SECRET_ENCRYPTION_KEY. Вместе с ним удалены dto.ConfigDto, клиентская функция getConfigApi и её тип.

• Compatibility-слой аккаунтов предыдущего поколения: сущность entity.LegacyAccount, миграции 002_migrate_legacy_accounts и 003_archive_legacy_account, а также мёртвые helpers listSQLMigrationFiles и envInt. HY2XS v1 не мигрирует базу 0.x ни при каком сценарии, и clean-host контракт отказывает ещё до создания базы — живого пути, по которому таблица account могла бы оказаться в hy2xs-admin.db, не существует. Номера оставшихся миграций сохранены: перенумерация заставила бы их примениться повторно.

  В docs/14-legacy-cleanup.md имена предыдущего поколения остаются — там они обозначают реальные объекты, которые нужно удалить с сервера. Из остальных v1-доков этот словарь убран.

1.0.0 — 2026-08-27

Первый релиз линейки v1.

Обновление с 0.x не поддерживается. Между 0.x и 1.0.0 изменились схема конфигурации, тип обфускации по умолчанию и контракт выбора версии Hysteria. Сервер, установленный из пакета 0.x, нужно поднимать заново: очистка и установка с нуля. Подробности — в разделе «Миграция с 0.x» ниже.

Добавлено

• Разрешение версии Hysteria на этапе сборки. Builder по умолчанию сам определяет последний стабильный upstream-релиз, скачивает артефакт, вычисляет SHA-256 и замораживает version + url + sha256 в metadata пакета. Target-сервер по-прежнему скачивает конкретный неизменяемый артефакт и никогда не обращается к moving latest.
• Compatibility gate в сборке. До создания release-пакета builder рендерит канонический конфиг HY2XS тем же кодом, что и оркестратор, и запускает с ним реальный бинарник Hysteria — для обоих профилей обфускации. Несовместимый upstream ломает сборку, а не сервер оператора.
• Поддержка Gecko-обфускации (Hysteria 2.9.2+) со сквозной интеграцией: оркестратор, шаблон конфига, модель админки, генерация hysteria2:// URI, типы и формы фронтенда.
• Версия схемы конфигурации HY2XS_CONFIG_SCHEMA_VERSION=2. Пакет отказывается работать с конфигурацией неизвестной схемы вместо того, чтобы молча применить чужие значения.
• Современный серверный baseline в генерируемом конфиге: congestion.type: bbr + bbrProfile: standard, bandwidth.disableLossCompensation: false, quic.disableStatelessReset: false, а также maxIdleTimeout, maxIncomingStreams, disablePathMTUDiscovery.
• Модель современной схемы Hysteria в админке: obfs.gecko, ech, congestion, mimic, realm, tls.clientCA, quic.disableStatelessReset, bandwidth.disableLossCompensation, masquerade.proxy.xForwarded. Поля читаются и отображаются, даже если HY2XS не включает их в default-профиль.
• Тесты оркестратора (bun test): разбор env, рендер конфига, семантические инварианты профиля, резолвер upstream-релизов, release rollover.
• E2E-проверка с реальным клиентом Hysteria — tools/test/e2e-hysteria.sh: TLS и obfs handshake, HTTP auth (допуск и отказ), TCP и UDP forwarding, trafficStats, per-peer accounting, переподключение после перезапуска сервера и подключение клиента именно по сгенерированной ссылке.
• CHANGELOG.md в корне репозитория.

Изменено

• Обфускация по умолчанию для новых установок — Gecko. Salamander остаётся полностью поддержанным режимом совместимости и выбирается через HY2XS_HYSTERIA_OBFS_TYPE=salamander.
• Gecko использует upstream-defaults 512/1200 и не выносит размеры пакетов в env: официальная URI-схема не умеет их передавать, поэтому нестандартные значения сделали бы клиентскую ссылку неполной.
• Тип обфускации больше не собирается внутри статического YAML. Оркестратор формирует проверенный obfs-блок целиком, поэтому комбинация вида type: gecko рядом с блоком salamander структурно невозможна.
• Экспорт конфига Hysteria работает от исходного YAML, а не от типизированной модели: поля, о которых HY2XS ещё не знает, переживают выгрузку.
• Smoke-проверки разбирают YAML и сверяют его с production-профилем, вместо поиска подстрок.
• Канонический upstream-репозиторий — HyNetworks/hysteria (вместо устаревших ссылок на apernet).
• Реестр ACME DNS-провайдеров во фронтенде приведён к актуальному upstream: добавлены namecheap, njalla, porkbun.
• Дефолты формы Hysteria во фронтенде отражают baseline HY2XS (50/50 Mbps, Let's Encrypt, каталог ACME), а не пример из upstream-доки.
• Сборка запускает тесты оркестратора и админки до упаковки.

Исправлено

• hysteria2:// для Gecko. Генератор ссылок был завязан на Obfs.Salamander.Password, поэтому при любой другой обфускации выдавал формально корректную, но неработающую ссылку без параметров obfs.
• SNI в клиентской ссылке при файловых сертификатах. SNI брался только из ACME-блока, поэтому при HY2XS_TLS_MODE=file уходил пустым. Теперь источник — ACME-домен, затем HY2XS_DOMAIN, затем HY2XS_PUBLIC_HOST; IP-адрес в качестве SNI не используется.
• Утечка секретов в экспорте конфига. Выгружаемый оператору YAML содержал trafficStats.secret, access_token в auth-URL и пароль обфускации. Секреты вырезаются, включая поля, о которых HY2XS ещё не знает.
• Расхождение runtime-конфига с разобранным. renderRuntimeEnv печатал тип обфускации и режим auth литералами, игнорируя фактическую конфигурацию, — из-за чего запись /etc/hy2xs/hy2xs.env могла разойтись с тем, что реально применено.
• Смешение веток obfs в UI. Форма склеивала дефолт с ответом API и показывала блок обфускации, которого нет в конфиге сервера.
• namedotcom в списке ACME DNS-провайдеров. Провайдер удалён из Hysteria в 2.11.0; конфигурация с ним больше не запускается.
• Отсутствие подсказок в форме создания пира. У полей «Пир», «Комментарий» и «Секрет» не было ни примеров, ни пояснений: оператор не мог понять без документации, что секрет необязателен и генерируется автоматически.

Безопасность

• Переход на Hysteria 2.12.2 закрывает исправления, вышедшие после 2.8.2, включая обход UDP ACL, возможный OOM через sniff и обход ACL через домены с завершающей точкой (2.9.2).
• Экспорт конфига больше не выносит секреты за пределы сервера.

Миграция с 0.x

Автоматическая миграция не предусмотрена и не планируется.

Порядок перехода:

1. Выпишите с работающего сервера список пиров и их секреты.
2. Очистите сервер: tools/legacy/purge-v0.sh или ручная процедура из docs/14-legacy-cleanup.md.
3. Разверните 1.0.0 на чистом Debian 13 из release-пакета.
4. Заведите пиров заново и раздайте новые клиентские ссылки.

Установщик 1.0.0 обнаружит остатки предыдущей установки на шаге PHASE 0, откажется работать и не изменит на сервере ничего.

Клиентские ссылки 0.x в любом случае перестанут работать: смена обфускации — это изменение wire-совместимости.