mistgate Документация
RU
316

В админке: Обновления

Релизы и подпись

Для мейнтейнеров и для тех, кто собирает Mistgate со своим ключом; ключ релиза, воспроизводимая сборка, подпись и публикация релиза, свой пакет и смена ключа.

На этой странице

Mistgate доверяет одному ключу релиза Ed25519: тот, у кого его закрытая половина, решает, что могут устанавливать агенты нод и панели. В официальные бинарники вшит ключ проекта, и мейнтейнеры подписывают им каждый релиз на GitHub. Если вы ставите официальный релиз, эта страница вам не нужна; работа с флотом описана в разделе Обновления. Эта страница — для мейнтейнеров и для тех, кто собирает бинарники со своим ключом.

Ключ релиза#

  • Закрытая половина хранится офлайн. Открытая вшивается в оба бинарника при сборке: RELEASE_KEY для make build, --key для mistgate release build и переменная репозитория MISTGATE_RELEASE_PUBLIC_KEY в workflow релиза.
  • При первом запуске панель сохраняет свой ключ в <data-dir>/release.pub. release.pub, отличающийся от вшитого ключа, никогда не принимается молча — ни в одну, ни в другую сторону: панель не доверяет ни одному пакету до mistgate release trust-key (см. «Смена ключа релиза» ниже).
  • Сборка без ключа не подписана: её агенты нод никогда не обновляются сами, а панель не может устанавливать релизы панели и не может дать установке по SSH доверенного агента.

Сделайте ключ (один раз)#

Shell
mistgate release keygen --out ~/mistgate-release.key

Команда пишет закрытый ключ в файл (режим 0600; существующий файл никогда не перезаписывается) и печатает открытый ключ и его отпечаток (первые 16 шестнадцатеричных символов его SHA-256).

Внимание

Храните файл ключа офлайн и сделайте резервную копию. Без него ни одну ноду нельзя обновить из панели: придётся сделать новый ключ, собрать с ним новые бинарники и один раз обновить вручную каждую ноду и панель.

Соберите с открытым ключом#

Shell
git checkout v0.1.4
RELEASE_KEY=<открытый ключ> VERSION=v0.1.4 make build

Через mistgate release build собираются bin/mistgate-linux-{amd64,arm64} и bin/mistgate-node-linux-{amd64,arm64}. В панель и агенты вшиваются одинаковые версия, время сборки (время коммита рабочей копии) и открытый ключ релиза; mistgate version и mistgate-node version печатают отпечаток ключа.

Выпуск официального релиза#

Для каждого стабильного тега vMAJOR.MINOR.PATCH .github/workflows/release.yml запускает четыре задания. node собирает оба Linux-агента только средствами Go (без Node.js и npm-пакетов); panel собирает SPA админки через pnpm, а затем два бинарника панели; edge собирает облачную редакцию (mistgate-edge.tar.gz, см. «Пакет edge» ниже) и загружает её в workerd. У всех трёх доступ к репозиторию только на чтение. publish — единственное задание с правом записи и единственное, которое не запускает код сборки, — создаёт черновик релиза с четырьмя бинарниками, mistgate-edge.tar.gz, BUILDINFO и SHA256SUMS. Все actions закреплены по SHA коммита. Черновик не виден панелям как последний релиз. Workflow требует переменную репозитория MISTGATE_RELEASE_PUBLIC_KEY и вшивает её во все четыре бинарника; если она не задана или некорректна, workflow завершится ошибкой и не опубликует релиз, который нельзя подписать.

Закрытый ключ в Actions не передаётся, и доверять бинарникам CI не нужно: на машине с ключом вы сами собираете релиз из тега, а mistgate release sign подписывает только те бинарники, которые ваша сборка воспроизводит байт в байт. Затем загрузите семь файлов манифестов и подписей, включая panel-manifest.sshsig и два файла edge-manifest, и опубликуйте черновик. В течение 10 минут панели скачают и проверят пакет нод (ноды останутся на своих сборках, пока владелец не обновит их или не назначит обновление), а Проверить GitHub предложит релиз панели.

Shell
VERSION=v0.1.6
git clone https://github.com/Mistgate/mistgate.git && cd mistgate   # или git fetch --tags в своей копии
git checkout "$VERSION"
(cd web && pnpm install --frozen-lockfile && pnpm build)           # бинарник панели и пакет edge содержат SPA
(cd edge/worker && pnpm install --frozen-lockfile)                  # esbuild, который собирает скрипты Worker для edge
go build -o ../mistgate-signer ./cmd/mistgate                       # подписывающий бинарник; версия любая
gh release download "$VERSION" --repo Mistgate/mistgate \
  --pattern 'mistgate-linux-*' --pattern 'mistgate-node-linux-*' --pattern 'mistgate-edge.tar.gz' --dir ../downloaded
../mistgate-signer release sign --key ~/mistgate-release.key --version "$VERSION" --expires 90d \
  ../downloaded/mistgate-node-linux-amd64 ../downloaded/mistgate-node-linux-arm64 \
  ../downloaded/mistgate-linux-amd64 ../downloaded/mistgate-linux-arm64 ../downloaded/mistgate-edge.tar.gz --out ../signed
gh release upload "$VERSION" ../signed/manifest.json ../signed/manifest.sig \
  ../signed/panel-manifest.json ../signed/panel-manifest.sig ../signed/panel-manifest.sshsig \
  ../signed/edge-manifest.json ../signed/edge-manifest.sig \
  --repo Mistgate/mistgate --clobber
gh release edit "$VERSION" --repo Mistgate/mistgate --draft=false

release sign откажется работать, если рабочая копия не стоит ровно на теге или в ней есть локальные изменения; затем пересоберёт каждый бинарник через mistgate release build с открытой половиной вашего ключа и сравнит со скачанным. Последняя команда публикует черновик: не публикуйте его, пока все семь файлов не загрузились.

Если подпись не прошла, потому что бинарник не совпал со своей пересборкой, не подписывайте: сначала выясните причину. Обычно это другой ключ в MISTGATE_RELEASE_PUBLIC_KEY, тег, перенесённый после сборки, или отличие тулчейна (см. ниже); необъяснимое отличие может означать взломанный раннер.

Каналы релизов#

Тег говорит и о канале релиза (см. Каналы обновлений): vX.Y.Z — стабильный, vX.Y.Z-testing.N — тестовый, vX.Y.Z-dev.N — разработка, где X.Y.Z — стабильная версия, к которой идёт работа, а N считается от 1. Сборка релиза принимает только эти формы. Тестовый тег и тег разработки создают пре-релиз, который никогда не становится latest на GitHub, поэтому установщик по умолчанию и старые панели по-прежнему получают стабильные релизы. Стабильный или тестовый тег должен указывать на коммит в main или в ветке release/*, иначе сборка остановится; тег разработки может указывать на любой коммит.

  • Продвигается коммит, а не main. Ставьте тег на проверенный коммит: коммит v0.1.80-testing.2 становится v0.1.80, даже если в main уже есть незаконченная работа.
  • Срочный фикс для стабильного, пока main не готов: ветка release/0.1.80 от стабильного тега, cherry-pick фикса в неё, тег v0.1.81 на этой ветке и перенос фикса обратно в main.
  • Подпись и публикация одинаковы для всех каналов; релизу разработки можно дать более короткий --expires (30d).
  • Описание: у каждого релиза описание на английском, русском и китайском, разделённое строками ---; панели показывают его в Что нового. Страница статуса называет только стабильные релизы.

Решение описано в design/adr/0011-release-channels.md.

Воспроизводимая сборка#

mistgate release build (его используют workflow, make build и проверка в release sign) даёт байт в байт одинаковые бинарники для одного тега и ключа; сборка на Linux и кросс-сборка на Windows из одного коммита проверены и совпадают. Это выполняется, когда:

  • тулчейн Go — тот, что указан в строке toolchain файла go.mod. release build запрашивает ровно эту версию; если локальный Go другой, она один раз скачивается из прокси модулей Go;
  • исходники — чистая рабочая копия тега. Неотслеживаемые файлы (собранная SPA, bin/) в бинарник не попадают (-buildvcs=false); не меняйте .gitattributes репозитория — он выдаёт все файлы с окончаниями строк LF на любой системе;
  • флаги — фиксированные, их ставит release build: CGO_ENABLED=0, -trimpath, GOAMD64=v1, GOARM64=v8.0 и -ldflags "-s -w", где заданы только Version (тег), Built (время коммита тега) и ReleaseKey;
  • для бинарников панели SPA собрана командой pnpm install --frozen-lockfile && pnpm build (Node.js 22, версия pnpm из web/package.json).

Проверка доказывает, что CI собрал именно то, что лежит в теге. Код тега и зафиксированные зависимости она не проверяет: вредоносный пакет из go.sum или pnpm-lock.yaml соберётся и у вас точно так же.

Пакет edge#

mistgate-edge.tar.gz — облачная редакция (Cloudflare): шесть скриптов Worker и SPA админки. Пять скриптов — роли панели, каждая скомпилирована под js/wasm как отдельная программа (link, provision, public, admin и jobs: <роль>.js и <роль>.wasm, с версией, временем сборки и открытым ключом релиза, как у остальных бинарников); шестой, front.js, — роутер, который держит имя хоста и не имеет wasm. Скрипты собирает esbuild из edge/worker/package.json с закреплённой версией. В архиве также SPA (assets/, загружается в public и admin) и edge.json (схема 2) со списком скриптов в порядке загрузки, их привязок, миграций Durable Objects, имён секретов, cron для jobs и маршрута для front, для mistgate edge deploy. Собирает его mistgate release build --version V --key PUBLIC mistgate-edge.tar.gz --out DIR (SPA уже собрано, а в edge/worker выполнен pnpm install --frozen-lockfile); release sign пересобирает его так же, отказывает при расхождении и пишет edge-manifest.json (версия, время сборки, срок, размер и SHA-256 архива) и edge-manifest.sig. Манифест edge подписан в собственном контексте Ed25519 тем же ключом релиза, поэтому ни он, ни подпись панели или нод не проходят как чужие. panel-manifest.json не меняется.

Архив детерминирован (записи отсортированы, режимы, владелец и время фиксированы, заголовок gzip без имени и времени). Это выполняется, когда тулчейн Go тот, что назван в go.mod, web/dist и edge/worker/node_modules получены из замороженных lock-файлов, а Go подписывающего той же версии, что и собравший архив (сжатие gzip выполняет Go подписывающего; другая версия с иным сжатием заставит release sign отказаться, но не подпишет что-то другое).

Короткий срок подписи#

--expires (по умолчанию 30d) — сколько оба манифеста можно устанавливать; перехваченный старый манифест перестаёт работать, когда срок истекает. Ставьте короткий срок, например 90d, и продлевайте его заранее: выполните ту же команду release sign для того же тега с новым --expires и снова загрузите семь файлов с --clobber. Панели обновят пакет нод того же билда без повторного обновления нод, а манифест панели читают заново при каждой проверке. Если манифест панели истёк, панель так и пишет и релиз не устанавливает; пакет нод с истёкшим сроком больше нельзя раскатывать и использовать для установки по SSH.

Свой пакет#

Панель, собранная со своим ключом, игнорирует официальные релизы на GitHub: их подписи не сходятся с её ключом. Обновления нод она получает из пакета, который вы подписываете и копируете в её каталог данных, а бинарник панели вы меняете вручную (см. «Ранние сборки и ручное обновление» в разделе Обновления).

Подпишите бинарники нод#

Shell
mistgate release sign --key ~/mistgate-release.key --version v0.1.4 --expires 90d \
  bin/mistgate-node-linux-amd64 bin/mistgate-node-linux-arm64 --out dist/
  • Запускайте её в рабочей копии тега (или укажите её в --source): команда откажется, если копия стоит не ровно на теге или в ней есть локальные изменения, пересоберёт бинарники и откажется, если какой-то не совпал.
  • Бинарники должны называться <имя>-<ос>-<архитектура>, как их называет make build. Переданные вместе с ними mistgate-linux-* попадут в panel-manifest.json.
  • Время сборки берётся из коммита тега; отличающийся --built отклоняется. Новая сборка, у которой собственное время сборки отличается от манифеста, после обновления откатывает себя сама (built_mismatch).
  • --expires — число дней (90d) или длительность в формате Go (2160h); по умолчанию 30d. Держите срок коротким и продлевайте его (см. выше).
  • Команда пишет dist/manifest.json и dist/manifest.sig, кладёт рядом копии бинарников, перечитывает результат и проверяет его, затем печатает версию, срок действия, каждый файл с размером и отпечаток ключа.

Положите пакет на панель#

Shell
scp dist/* panel.example.com:/var/lib/mistgate/dist/

Панель читает <data-dir>/dist и замечает изменения в течение минуты; Перечитать папку на странице «Обновления» читает её сразу. Учитываются только обычные файлы (символьные ссылки не открываются). Меняйте пакет целиком; замена пакета во время раскатки ставит раскатку на паузу. Сошлась ли подпись, показывает строка Пакет релиза на странице «Обновления»: см. Обновления.

Смена ключа релиза#

  1. Создайте новый ключ командой mistgate release keygen и задайте его открытую половину в MISTGATE_RELEASE_PUBLIC_KEY (или в своём RELEASE_KEY).
  2. Все установленные агенты доверяют только старому ключу: один раз обновите каждую ноду вручную агентом, собранным с новым ключом, как старый агент (см. «Старые агенты: один раз вручную» в разделе Обновления).
  3. Панель устанавливает релизы панели только под вшитым в неё ключом, а это всё ещё старый: замените бинарник панели вручную на собранный с новым ключом.
  4. Новая панель пишет в журнал release key mismatch и не доверяет ни одному пакету. На сервере панели выполните mistgate release trust-key (от root или пользователя службы панели, с --data-dir, если каталог данных не /var/lib/mistgate): команда запишет новый ключ в release.pub и напечатает старый и новый отпечатки. Перезапустите панель.

Ключ, подменённый кем-то в release.pub, никогда не заставит панель доверять другому подписанту: ключом установки может стать только ключ, вшитый в бинарник, и только через trust-key.

Править страницу на GitHub