В админке: Обновления
Обновления
Как агенты нод обновляются из подписанных пакетов, как обновить ноду сейчас или по расписанию, что страхует обновление и как обновляется сама панель.
На этой странице
- Как устроено доверие
- Откуда берётся пакет
- Страница «Обновления»
- Что нового
- Каналы обновлений
- Обновление ноды
- Всё, что можно обновить, одной раскаткой
- Сейчас, вместе с идущей раскаткой или позже
- Обновление одной ноды
- Собственная страховка агента
- Пауза, продолжение, отмена
- Источники загрузки
- Откат вручную
- Старые агенты: один раз вручную
- В Cloudflare-версии
- Обновление панели
- Включить обновления для непривилегированной службы панели
- Ранние сборки и ручное обновление
- Операционная система серверов
- Обновление системы одного сервера
- Таблица ядер
- Запуск вручную на ноде
- Обновления через API и MCP
Агенты нод обновляют себя сами, но только до сборки, подписанной ключом релиза. Панель доставляет подписанный пакет на ноды, а каждый агент перед заменой себя проверяет подпись ключом, вшитым в его собственный бинарник. Сама панель ноду никогда не обновляет: вы нажимаете Обновить N нод (или Обновить в строке ноды), чтобы обновить сейчас, или назначаете обновление ноды на тихий час. Панель умеет и сама установить более новый официальный релиз со страницы «Обновления» — тоже только если подпись сходится.
Эта страница — для работы с флотом. Как сделать ключ релиза, подписать и опубликовать релиз, описано в разделе Релизы и подпись.
В подписанном пакете нод также есть таблица диапазонов IPv4 и IPv6 с названиями операторов ASN, созданная на основе iptoasn.com (PDDL 1.0). В ней указаны сетевые диапазоны, но нет адресов клиентов и записей о людях.
Как устроено доверие#
- Есть одна пара ключей Ed25519 — ключ релиза. Закрытая половина хранится офлайн у того, кто подписывает релизы; открытая вшивается в оба бинарника при сборке. В официальных бинарниках — ключ проекта. При первом запуске панель также сохраняет ключ в
<data-dir>/release.pub. - В каждом релизе два подписанных манифеста: пакет нод (
manifest.jsonсmanifest.sig) и манифест панели (panel-manifest.jsonсpanel-manifest.sig). В каждом — версия, время сборки, срок действия и для каждого бинарника имя, ОС, архитектура, размер и SHA-256. Манифест панели подписывается в отдельном контексте Ed25519, поэтому агент никогда не примет его за своё обновление, а панель не установит бинарник ноды вместо себя. - Агент проверяет по порядку: подпись — вшитым ключом, формат манифеста, срок действия, что релиз новее его самого и что в пакете есть файл под его ОС и архитектуру. Сначала он скачивает файл с панели по взаимному TLS (в Cloudflare-версии — по каналу к панели); если VPS-панель предложила GitHub агенту с нужной возможностью, после ошибки передачи он может продолжить оттуда. Агент сверяет размер и SHA-256 с подписанным манифестом. Несовпадение контрольной суммы явно завершает шаг с ошибкой: повторной загрузки из другого источника не будет. При любой ошибке установленный бинарник не трогается.
- Панель — только курьер: взломанная панель не заставит ноду запустить код, который не подписан ключом релиза.
- Релизы упорядочены по времени сборки (Unix-время коммита исходников), а не по строке версии. Релиз с тем же временем сборки, что у ноды, считается «уже актуальным»; более старый отклоняется как откат версии.
- Агент ноды, собранный без ключа релиза, не обновляется сам;
mistgate-node versionпечатает отпечаток вшитого ключа. Если ключ, вшитый в панель, иrelease.pubразличаются, панель пишет в журналrelease key mismatchи не доверяет ни одному пакету, пока новый ключ не подтверждён: см. «Смена ключа релиза» в разделе Релизы и подпись.
Откуда берётся пакет#
Пакет нод панель хранит в <data-dir>/dist. (В Cloudflare-версии такой папки нет, там свой релиз; этот раздел и строка Пакет релиза описывают панель на VPS.)
- С GitHub. Панель с ключом релиза проверяет новейший релиз
Mistgate/mistgateв канале обновлений панели при запуске и потом каждые 10 минут. Если в релизе есть пакет нод, подпись которого сходится с ключом панели и который новее пакета панели, она скачивает его, проверяет каждый файл и одним шагом заменяетdist. Релиз, подписанный другим ключом, игнорируется, иdistостаётся как был. Скачивание пакета само по себе не обновляет ни одну ноду. - Вручную. Панель, собранная со своим ключом, получает пакет, который вы подписываете и копируете в
dist: см. «Свой пакет» в разделе Релизы и подпись. Панель перечитываетdistв течение минуты; Перечитать папку читает её сразу.
Строка Пакет релиза внизу карточки флота на странице «Обновления» показывает результат (подробности — под кнопкой Подробности; они раскрываются сами, если пакет не прошёл проверку или его нет):
| Статус | Значение |
|---|---|
| Подпись проверена | Подпись сходится с ключом релиза этой панели, манифест в порядке, все файлы на месте с нужным размером и контрольной суммой. Раскатывать и использовать для установки по SSH можно только такой пакет. |
| Не прошёл проверку | Что-то не так; карточка пишет что (см. ниже). |
| Не проверен | У установки нет пригодного ключа релиза: его нет ни в сборке, ни в release.pub, или они различаются. Панель не может оценить пакет; ноды всё равно проверяют его сами. |
| Нет пакета | В <data-dir>/dist нет manifest.json. |
| Причина | Что делать |
|---|---|
| В каталоге данных панели нет пакета релиза | Дождитесь скачивания с GitHub или скопируйте свой пакет в <data-dir>/dist. |
| Нет файла подписи (manifest.sig) | Скопируйте и manifest.sig. |
| manifest.json — не манифест релиза | Подпишите заново; не правьте манифест. |
| Манифест в более новом формате, чем понимает эта панель | Сначала обновите панель. |
| Подпись не сходится с ключом релиза этой панели | Пакет подписан другим ключом или панель собрана с другим ключом. |
| Срок манифеста истёк: подпиши новый | Нужна новая подпись: мейнтейнеры продлевают её на GitHub, а свой пакет вы подписываете заново с более поздним --expires. |
| Файла из манифеста нет | Скопируйте все файлы пакета. |
| Файл не совпадает с манифестом (размер или контрольная сумма) | Копия неполная или файл изменён: скопируйте его снова. |
Файлы пакета панель отдаёт только агентам с действующим сертификатом ноды, через точку подключения агентов, не больше четырёх активных загрузок одновременно. Возобновление загрузки того же файла сразу занимает место предыдущей загрузки этой ноды; обработчик прежнего потока сам завершает запись. Учитываются только обычные файлы в dist (символьные ссылки не открываются). Пакет, сделанный вручную, меняйте целиком и за один раз; замена пакета во время раскатки ставит раскатку на паузу.
Страница «Обновления»#
Смотреть страницу могут все. Обновление, расписание, пауза, продолжение и отмена, откат ноды и Перечитать папку доступны только владельцу и требуют свежего повторного подтверждения входа (см. «Безопасность»).
На странице три слоя, для каждого вверху своя карточка: Эта панель, Агенты нод и Система серверов. Карточка говорит, в каком состоянии её слой, и несёт статус, так что все три видны, какой бы ни был открыт; выбранный слой раскрывается ниже. Страница открывается на панели, когда вышло обновление панели (панель обновляют раньше нод), иначе на агентах нод; адрес запоминает слой. В Cloudflare-версии есть первые два.
Что в слоях (карточка флота, раскатка и ноды находятся в слое Агенты нод; Система серверов описана в разделе «Операционная система серверов»):
- Эта панель: одна строка с версией, датой сборки, состоянием и кнопкой Проверить GitHub. Когда вышел подписанный релиз, карточка выделяется и в ней появляется Обновить панель. Отпечаток ключа релиза, SHA-256 и пояснение скрыты под Подробности; панель, которая не умеет обновлять себя, раскрывает шаги сама.
- Карточка флота: где стоит флот («2 из 4 нод на v0.1.24»), полоса из отрезков по одному на ноду, под ней счётчики по состояниям, и одна главная кнопка. Когда есть что обновлять, это Обновить N нод (см. ниже); пока идёт раскатка — Пауза / Продолжить / Отменить раскатку. В её нижней строке Пакет релиза: пакет в
<data-dir>/dist, вердикт проверки подписи, версия и сроки, Перечитать папку и свёрнутые подробности (файлы, причина отказа, шаги для самостоятельной сборки пакета). - Раскатка: идущая раскатка стоит сразу под карточкой флота, по этапам (канарейка, пачки) с нодами в каждом; у совместимого агента во время загрузки видны этап, ход, объём и скорость за последний интервал; последняя законченная — после списка нод, свёрнутой в одну строку (Показать этапы), если она закончилась хорошо.
- Ноды: каждая нода с версией агента и датой сборки, состоянием и последним обновлением в одну строку. Владельцу в строке доступна одна основная кнопка: Обновить (или Расписание, если обновление уже назначено); рядом меню ⋯ с Запланировать… и Откатить…. Нода, входящая в идущую раскатку, говорит об этом в строке («В очереди · пачка 2», «Обновляется…») и не имеет своего обновления и расписания; Откатить… остаётся там, где был разрешён.
| Состояние ноды | Значение |
|---|---|
| Актуальна | Её сборка не старее сборки проверенного пакета (без проверенного пакета — сборки самой панели). |
| Есть обновление | Она умеет обновляться сама и работает на более старой сборке. |
| Обновляется… | Идёт обновление этой ноды. |
| Откатилась | Последнее обновление закончилось откатом; работает прежняя сборка. |
| Обновление не удалось | Последнее обновление не удалось на ноде. |
| Обновить вручную | Её агент не умеет обновляться сам (см. «Старые агенты» ниже). |
| Не в сети | Нода не на связи; показана последняя известная сборка. |
«Нет защиты от повторных падений» под нодой значит, что в её служебном файле нет защиты от цикла падений: обновление там страхует только самооткат агента через 5 минут. Если вы видите исправление Обновить службу в разделе «Здоровье» → «Доктор», примените его там; агент перезапустится, подключения могут прерваться на несколько секунд. Если агент слишком старый и не предлагает исправление, вы можете один раз выполнить mistgate-node install с текущим бинарником.
Что нового#
Под карточкой флота и в строке панели страница показывает, что принесёт обновление, чтобы ты мог решить, обновляться сейчас или позже: описания всех стабильных релизов, которые новее самого старого агента среди нод, вплоть до пакета на панели (для панели — всех релизов между этим и тем, который она может установить). Новейшая версия показана целиком, а если она длинная, есть Показать всё; более ранние свёрнуты под «и ещё N более ранних версий». Описания выводятся на языке интерфейса (по-английски, если у релиза нет описания на нём).
Это текст описания релиза на GitHub: панель читает его по HTTPS из официального репозитория с той же периодичностью, что и проверку релиза. Он справочный и не подписан: подписаны только манифесты. Ничего, кроме одной отметки, по нему не решается. Релиз, в описании которого есть раздел Безопасность (заголовок «Security», «Безопасность» или «安全»), помечается Исправления безопасности, и карточка прямо говорит, что в обновлении есть исправления безопасности и лучше обновиться скорее. Без такого раздела о срочности страница молчит. Без доверенного пакета или если панель ещё не прочитала описания (в Cloudflare-версии это происходит, когда нажимаешь Проверить GitHub), блока просто нет.
Каналы обновлений#
Каждый релиз относится к одному каналу, и это видно по тегу: vX.Y.Z — Стабильный, vX.Y.Z-testing.N — Тестовый, vX.Y.Z-dev.N — Разработка. Панель следует одному каналу и предлагает установить новейший релиз этого канала и всех более стабильных: «Стабильный» видит стабильные релизы, «Тестовый» — тестовые и стабильные, «Разработка» — все три. Канал определяет и обновление самой панели, и пакет для нод; ноды по-прежнему обновляются, только когда вы раскатываете пакет.
| Канал | Для кого |
|---|---|
| Стабильный (по умолчанию) | Проверенные релизы, для всех панелей. |
| Тестовый | Следующий релиз раньше остальных. Возможны ошибки — сообщайте о них. |
| Разработка | Сборки из разработки: всё самое новое, может ломаться. Для своей тестовой панели. |
Канал меняет владелец на странице «Обновления»: чип рядом с версией панели открывает окно Канал обновлений. Смена требует свежего подтверждения входа, пишется в журнал аудита, и следующая проверка сразу идёт по новому каналу. При переходе на более ранний канал панель сразу предлагает его новейший релиз. При переходе на более стабильный назад ничего не ставится: панель и ноды остаются на своих версиях, пока в канале не выйдет более новая, и полоска панели об этом говорит. Что нового помечает тестовые релизы и релизы разработки. Панель, установленная с --channel testing или --channel dev (см. Установка панели), начинает с этого канала. Инструмент MCP updates_status показывает канал, но не меняет его.
Обновление ноды#
Всё, что можно обновить, одной раскаткой#
Обновить N нод в карточке флота открывает окно со всеми нодами, которые можно обновить: у каждой галочка (по умолчанию стоят все), канарейка названа — это нода, где меньше всего людей онлайн. Окно напоминает, что канарейку проверяют 5 минут, остальные идут пачками (по одной, пока к обновлению меньше пяти нод, иначе по две), а нода при отказе проверки получает прежнюю версию и раскатка встаёт на паузу. Пока вы не нажали Начать раскатку, ничего не происходит. Запрос закреплён за пакетом, который показывала страница, как и обновление одной ноды, и требует повторного подтверждения входа. Кнопки нет, пока идёт раскатка, пока нет проверенного пакета и для всех, кроме владельца; ноды, чьё обновление нужно назначить на время, обновляются по одной (см. ниже).
Сейчас, вместе с идущей раскаткой или позже#
Обновить в строке ноды открывает окно с двумя вариантами:
- Обновить сейчас сразу запускает обновление этой ноды. Пока идёт другое обновление с тем же релизом, вариант называется В текущую раскатку: нода становится следующим этапом и начнёт обновляться, когда текущий пройдёт проверку. Раскатку на паузе или с другим релизом сначала нужно продолжить, дождаться её конца или отменить.
- Выбрать дату и время сохраняет расписание. Время вводится с фиксированным смещением UTC из Настройки → Система → Часовой пояс обновлений; по умолчанию это UTC (установки, сделанные раньше, сохраняют UTC+03:00 — тогдашнее значение по умолчанию). При смене настройки уже сохранённые расписания не сдвигаются: каждое хранит точный момент и смещение, показанные при сохранении. Самое раннее время — через минуту от текущего; Отменить расписание удаляет его.
Каждое обновление закреплено за релизом:
- Обновление «сейчас» закреплено за версией пакета, которую показывала страница (план MCP — за версией плана): если проверенный пакет за это время заменился, панель откажет и попросит посмотреть новую версию.
- Расписание закреплено за подписанной версией, выбранной при сохранении, и не может быть позже срока действия этого пакета. Если в выбранное время обновление начать нельзя (нода отключена, идёт другое обновление), панель пытается ещё два часа; после этого строка покажет, что расписание пропущено, и само оно уже не начнётся — обновление, рассчитанное на тихий час, не запустится, когда нода вернётся. Запланируйте заново или отмените. Если пакет к этому моменту заменился, панель не подменит версию: проверьте новую и запланируйте заново.
Обновление одной ноды#
- Панель отправляет подписанный манифест. Агент проверяет его, скачивает свой файл, сохраняет текущий бинарник как
<бинарник>.prev, ставит новый на его место и перезапускает себя на месте (systemd ничего не замечает). Нода пропадает на несколько секунд; админка показывает это как обновление, а не как сбой. - Для агентов с
update-timeout/1панель даёт настроенное время на загрузку (по умолчанию 30 минут; изменить его можно в Настройки → Система → Тайм-аут загрузки); окно фиксируется при отправке команды, а если 90 секунд нет данных, загрузка продолжается с места обрыва, до трёх раз, в пределах окна. Панель всегда предлагает свой пакет первым, а GitHub — следующим, если источник включён и проверен для этого релиза, агенту сupdate-sources/1. Изменение настройки действует для следующих шагов. Старые агенты сохраняют встроенный лимит 10 минут. После ответа агента панель ждёт до 3 минут возвращения ноды с новой сборкой. - Проверка после обновления идёт до 5 минут после возвращения ноды. Она пройдена, когда выполнено всё сразу:
- новая сборка закрепилась: подключилась и применила конфигурацию без упавшего профиля;
- нода применила ту же конфигурацию, что у панели;
- не упал ни один профиль, который работал до обновления (профиль, который не работает 30 секунд, сразу проваливает проверку);
- каждый профиль, который панель умеет проверять, прошёл проверку глазами клиента после возвращения ноды (панель сразу запускает круг). Cloudflare-версия это условие пропускает.
- на ноде с включённым профилем, который выходит через WARP, туннель WARP поднят с момента возвращения ноды.
- Если проверка пройдена, шаг завершён. Проваленная проверка называет невыполненное условие: новая сборка не подтвердила обновление, нода не применила конфигурацию, панель не смогла прочитать профили ноды, упал профиль или не поднялся WARP. Если нет, панель отправляет ноде откат (возвращается прежний бинарник), шаг заканчивается как «откачена», раскатка встаёт на паузу.
Когда теряет пакеты только собственный путь панели. Сразу после перезагрузки или обновления путь от панели до ноды может терять пакеты, хотя сама нода в порядке и другие ноды до неё достают. Проверки глазами клиента тогда упираются в тайм-аут, и проверка провалила бы здоровую ноду. И для обновлений агента, и для обновлений ОС у проверки есть второй путь к успеху, и только когда не выполнено одно это условие, проверка глазами клиента: каждый проваленный раунд был тайм-аутом (отказ в соединении, ошибка авторизации и ошибка TLS не считаются), и сбои длятся не меньше минуты; нода сообщает о себе, что здорова (задание завершено или новая сборка подтвердилась, каждый включённый профиль работает, а собственная проверка резолвера на ноде прошла после её возвращения); и проверка портов, начатая после возвращения ноды с другой ноды (не с панели и не с самой ноды), увидела, что каждый UDP-порт доставляет пакеты, а каждый TCP- и TLS-порт отвечает эта нода. Тогда шаг проходит с пометкой «Собственный путь панели до ноды теряет пакеты», а в Истории ноды появляется информационное событие panel_path_lossy. Если другая нода тоже не видит порты или проверить некому, проверка проваливается как раньше, и пометка говорит, какой из двух случаев. Это доказательство доступности (и TLS-слушателей) вместе с собственным отчётом ноды, а не полное клиентское соединение через туннель. Синтетические алерты панели остаются как есть и могут оставаться красными, пока путь панели не восстановится.
Собственная страховка агента#
Агент не полагается на панель, чтобы отменить плохое обновление:
- Новая сборка, которая за 5 минут после запуска не подключилась и не применила конфигурацию, возвращает прежний бинарник и перезапускается (
not_committed). - Новая сборка, у которой собственное время сборки отличается от манифеста, откатывается сразу (
built_mismatch). - Служебный файл считает запуски, пока обновление не закреплено; на третьем запуске подряд он возвращает прежний бинарник ещё до старта агента (
crash_loop). - Прежняя сборка сообщает итог, когда снова подключается.
Пауза, продолжение, отмена#
Идущее обновление показывает ход в верхней части страницы, а владельцу — кнопки Пауза, Продолжить и Отменить раскатку.
- Пауза: новые шаги не начинаются. Шаг, который уже идёт, доходит до конца и проходит свою проверку. Уже обновлённые ноды остаются обновлёнными.
- Продолжить: оставшиеся ждущие шаги идут дальше. Неудачные и откаченные шаги остаются как есть; обновите эти ноды снова, когда устраните причину. Если пакет на диске сменился, продолжить нельзя: отмените раскатку и начните заново.
- Отменить раскатку: ждущие ноды пропускаются; нода, которую обновляют сейчас, заканчивает и проходит проверку; обновлённые ноды остаются на новой версии.
Раскатка встаёт на паузу и сама:
| Причина паузы | Что случилось |
|---|---|
| нода не приняла обновление | Она отклонила обновление (причина показана). |
| нода не прошла проверку после обновления | Она провалила проверку или не вернулась; где получилось, ей вернули прежнюю версию. |
| пакет релиза сменился | В <data-dir>/dist теперь другой релиз. Отмените раскатку и начните заново. |
| панель перезапустилась во время шага | Панель не знает, чем закончился шаг. Проверьте ноду, затем продолжите или отмените. |
Первая, вторая и четвёртая причины ещё и открывают алерт «Обновление ноды остановилось» — до тех пор, пока раскатку не продолжат, не отменят или не запустят новое обновление.
Законченная раскатка получает статус Готово, Отменена или Закончилась с проблемами (хотя бы одна нода не обновилась или откатилась). Страница показывает идущую раскатку или последнюю. Законченные раскатки хранятся: последние 20 — всегда, более старые — 90 дней.
Частые ошибки шагов:
| Ошибка | Значение |
|---|---|
| Нода отвергла подпись | Агент ноды доверяет другому ключу релиза. |
| Агент этой ноды собран без ключа релиза | Обновите его вручную. |
| Релиз старее того, что уже работает на ноде | Нужна более новая подписанная сборка. |
| В пакете нет файла для системы и архитектуры этой ноды | В пакете нет бинарника под её архитектуру (например, arm64). |
| Нода не смогла скачать файл с панели | Проверьте связь ноды с панелью. |
| Нода не смогла скачать файл ни из одного предложенного источника | В деталях шага указаны sources_failed, например panel:stalled,github:http_404; проверьте связь ноды с панелью и доступ к GitHub. |
| Нода не может писать рядом со своей программой | Проверьте диск ноды; примените Обновить службу в разделе «Здоровье» → «Доктор», если исправление доступно, или вы можете один раз выполнить mistgate-node install с текущим бинарником. |
| Нода не ответила на команду обновления в отведённое время загрузки (по умолчанию 30 минут; у старых агентов 10 минут) | Посмотрите на ноду и ход загрузки. |
| Нода не вернулась за 3 минуты | Посмотрите на ноду и её логи. |
| Проверка глазами клиента после обновления не прошла | См. «Здоровье»; нода уже на прежней версии. |
Источники загрузки#
На панели VPS запасной источник GitHub включён по умолчанию в Настройки → Система → Источники загрузки. Панель всегда идёт первой, отключить её нельзя; сейчас доступен только дополнительный источник GitHub. Панель предлагает GitHub, только если её ключ релиза проверяет подписанный манифест именно для этого тега и в нём перечислены те же файлы, что и в пакете раскатки. Подписанный заново манифест с более поздним сроком действия подходит, если список файлов не изменился. Самодельные пакеты и пакеты панели с другим ключом не предлагаются через GitHub. В Cloudflare-версии такой настройки нет.
Если панель занята, передаёт слишком медленно или передача с панели не удалась, нода может напрямую запросить бинарник релиза у GitHub. GitHub увидит публичный IP ноды, тег релиза, имя бинарника и User-Agent: Mistgate-Update/1, в котором указано название программы. Запрос не содержит идентификатор ноды, адрес панели, заголовок авторизации или токен панели. На странице «Обновления» у совместимого агента показывается текущий источник; при смене между опросами значение меняется. В ошибке загрузки перечислены только источники и короткие коды, например panel:stalled,github:http_404.
Откат вручную#
Откатить… в меню ⋯ строки ноды (и, как раньше, с подтверждением, в котором названа версия, к которой нода вернётся) возвращает прежний бинарник ноды (<бинарник>.prev) и перезапускает агента. Работает и вне раскатки. У ноды, которую ни разу не обновляли, прежней версии нет, и она откажет. Если нода участвует в идущей раскатке, её шаг помечается как «откачена», и раскатка встаёт на паузу.
Столбец Последнее обновление показывает, кто откатил ноду: «Откачено тобой», «Панель вернула прошлую версию: …» (проверка после обновления) или «Прошлую версию вернули командой панели».
Старые агенты: один раз вручную#
Нода показывает Обновить вручную, когда её агент не умеет обновляться сам: он появился раньше самообновления, собран без ключа релиза или работает под первой версией служебного файла (где каталог программы только для чтения). Как обновить в её строке даёт две команды, например:
scp /var/lib/mistgate/dist/mistgate-node-linux-amd64 root@de1.example.com:/root/mistgate-node
ssh root@de1.example.com 'chmod +x /root/mistgate-node && /root/mistgate-node install'install копирует бинарник в /usr/local/bin/mistgate-node, пишет актуальный защищённый служебный файл (с защитой от цикла падений) и перезапускает агента. После этого нода обновляется со страницы «Обновления». Если пакета на панели нет, возьмите mistgate-node из того же релиза, что и панель. В Cloudflare-версии две команды другие: см. ниже.
Старые агенты продолжают работать с более новой панелью: изменения протокола агента только добавляют новое. Если старому агенту чего-то не хватает, там, где это нужно, админка пишет «агент слишком старый».
В Cloudflare-версии#
Панель в Cloudflare-версии обновляет ноды с этой же страницы, и канарейка, пачки, проверка после обновления, пауза, продолжение, отмена, ручной откат и обновления по расписанию работают так, как описано выше. Отличается вот что:
- Релиз — собственный релиз панели. Панель предлагает подписанный релиз нод той версии, из которой развёрнута, сверяет его вшитым ключом и более новый не ищет. Чтобы перевести ноды на новый релиз, сначала разверни его на панели, потом нажми здесь Обновить. Если панель собрана не из релиза или не смогла получить свой релиз с GitHub, карточка флота говорит почему (панель повторяет попытку в течение минуты), а раскатку не начать. Если развернуть другую версию во время раскатки и в ней ещё есть ждущие ноды, раскатка встанет на паузу («пакет релиза сменился»). Папки
distнет, поэтому строки Пакет релиза и кнопки Перечитать папку не видно. - Нода скачивает через панель. Команда обновления несёт токен, который годится на один шаг. Агент запрашивает
<адрес канала>/update/<id ноды>/<файл>с этим токеном, а Worker панели отдаёт файл потоком из релиза на GitHub: нода с GitHub не соединяется, ей достаточно дотянуться до панели. Оборванная загрузка продолжается с того места, где остановилась. Перед заменой агент сверяет размер и SHA-256 с подписанным манифестом. Токен годится только для этой ноды, пока её шаг ждёт ответа, и только для файлов того манифеста, с которым началась раскатка. - В проверке после обновления нет проверки глазами клиента. Панель пока не запускает в этой версии проверки глазами клиента, поэтому проверка после обновления это условие пропускает, а окно и карточка раскатки об этом говорят. Остальное она требует: новая сборка закрепилась, нода применила конфигурацию панели, ни один профиль, работавший раньше, не упал, а у профиля с выходом через WARP поднят WARP. Сборка, у которой профили остаются запущенными, но туннели ломаются, такую проверку пройдёт; ущерб ограничивают канарейка и пачки.
- Шаги идут по минутам. Плановая задача версии двигает раскатку раз в минуту, поэтому решение может прийти на минуту позже, чем на панели с VPS. Пределы ожидания те же.
- Саму панель обновляют со своего компьютера, а не с этой страницы:
mistgate edge deploy --host panel.example.com --version vX.Y.Z, а--rollbackвозвращает прежнюю версию (см. Обновление и Откат). Строка панели показывает это вместо Обновить панель. После деплоя у нод появляется Есть обновление.
Агент версии v0.1.49 или более ранней пока не умеет скачивать по каналу, поэтому в его строке написано Обновить вручную. Как обновить даёт две команды, которые нужно один раз выполнить на ноде от root; страница сама подставляет версию, файл под архитектуру ноды и его SHA-256 из подписанного манифеста:
curl -fL -o /root/mistgate-node.new https://github.com/Mistgate/mistgate/releases/download/vX.Y.Z/mistgate-node-linux-amd64 && echo "<sha256> /root/mistgate-node.new" | sha256sum -c -
chmod +x /root/mistgate-node.new && mv /root/mistgate-node.new /root/mistgate-node && /root/mistgate-node installВторую команду запускай, когда первая напечатала OK. Это единственный раз, когда ноде нужен GitHub; если он недоступен, положи файл в /root/mistgate-node.new сам, выполни проверку и вторую команду. install сохраняет личность ноды и её канал к панели, пишет актуальный служебный файл и перезапускает агента. После этого нода обновляется с этой страницы. Если нода не сообщила архитектуру, подставляется файл для amd64; на ARM-сервере возьми файл arm64 и его SHA-256 из manifest.json релиза.
Обновление панели#
Этот раздел — про панель на VPS. Панель в Cloudflare-версии обновляется командой mistgate edge deploy.
Страница «Обновления» проверяет новейший релиз Mistgate/mistgate в канале обновлений панели при запуске и каждые десять минут (в том же темпе, что и пакет для нод). Когда выходит новая подписанная версия, владелец видит на каждой странице, кроме «Обновлений», небольшую карточку с номером версии. Её можно свернуть в плашку или закрыть до следующей версии. Проверить GitHub проверяет сразу (на проверку, сделанную за последние три минуты, панель отвечает из памяти и бережёт анонимную квоту GitHub для скачивания пакета).
Обновить панель сначала открывает окно: что произойдёт (панель перезапустится примерно на минуту; ноды и подключения людей продолжают работать; если новая версия не запустится, панель сама вернётся к текущей) и резервная копия. Если бэкапы в Cloudflare R2 настроены, окно показывает последний и предлагает Сделать сейчас; если нет — ссылку, где их настроить. Файл на компьютер скачивает зашифрованный бэкап с именем mistgate-backup-<панель>-<версия>-<дата>.tar.gz.age: на ваш ключ восстановления, если он есть, иначе с паролем, который вы придумываете для этого файла. Обновить не ждёт бэкапа, кроме уже идущего бэкапа в R2.
Установить можно только релиз, в котором есть panel-manifest.json и panel-manifest.sig, подпись проходит проверку ключом релиза, вшитым в эту панель (release.pub не считается: его может изменить пользователь службы панели), срок манифеста не истёк, а время сборки новее, чем у этой панели. Релизы упорядочены по этому времени сборки, а не по строке версии: панель, собранная из коммита после тега (например, v0.1.6-3-gabc1234), никогда не увидит v0.1.6 как обновление, и ей не предложат откат на базу, которую она уже обновила. Релиз без такого манифеста показывается как «не подписана ключом релиза этой панели: установить её нельзя»; релиз с истёкшим манифестом — как истёкший, пока его не подпишут заново. Карточка показывает дату сборки релиза и SHA-256 бинарника для этого сервера. Обновить панель отправляет именно эти версию и SHA-256, и панель откажет, если к тому времени последним подписанным релизом стал другой.
Автоматическая установка доступна панели от root под systemd. Панель с непривилегированным пользователем службы, например mistgate, может использовать отдельный фиксированный root-helper ниже; HTTP-панель при этом остаётся непривилегированной. В обоих случаях владелец подтверждает действие свежим повторным подтверждением входа, а идущая раскатка нод должна закончиться. Панель записывает выбранный канал, подтверждённые версию и SHA-256 в <data-dir>/panel-update.request и запускает helper (временный unit systemd mistgate-panel-update-<время>.service для панели от root, иначе mistgate-panel-update.service). Этот запрос может только сузить то, что helper установит. Helper сам проверяет манифест панели в релизе ключом, вшитым в установленный бинарник, требует, чтобы он называл ровно подтверждённые версию и SHA-256 и сборку новее его собственной, скачивает бинарник и сверяет размер, SHA-256 и архитектуру ELF. Только после этого он останавливает панель, сохраняет каталог данных, заменяет бинарник и запускает службу.
Разрешённый helper канал релизов читает из принадлежащего root файла /etc/mistgate/panel-update-channel. Новая установка создаёт его из --channel установщика (по умолчанию stable), только если файла политики ещё нет. Если файла нет, helper использует stable, поэтому существующие стабильные установки не требуют миграции. Выбор канала на странице «Обновления» хранится в базе панели; повторное подтверждение защищает эту настройку, но не даёт процессу mistgate права менять root-файл. Панель записывает выбранный канал, подтверждённые версию и SHA-256 в panel-update.request. Если выбранный канал отличается от разрешённого, страница один раз сообщает об этом как о состоянии карточки панели вместе с root-командой для изменения разрешённого канала (кнопки «Обновить» нет, поток ошибок не создаётся), а helper сам отказывает с кодом panel_update_channel_not_allowed. Файл должен быть обычным файлом root, недоступным для записи группе и остальным, с одним словом (stable, testing или dev), в каталоге root, куда остальные не могут писать; всё остальное, включая символическую ссылку, отклоняется с кодом panel_update_channel_config_invalid, и страница показывает команду, которая заменяет файл. Установки на Testing или Development не переключаются незаметно: их обновление ждёт, пока владелец не выполнит эту команду, а существующая стабильная установка продолжает обновляться без действий.
Новая панель должна проработать 45 секунд без перезапусков со стороны systemd (при Restart=on-failure падение через несколько секунд после старта видно только как перезапуск). Иначе helper останавливает её, возвращает прежний бинарник и копию данных с исходными владельцами файлов и запускает прежнюю панель. После успеха предыдущий бинарник хранится как <бинарник>.prev, а копия данных — рядом с каталогом данных: <data-dir>.panel-update-backup.tar.gz. Если helper завершился, не заменив панель (не прошла проверка или скачивание), страница «Обновления» в течение нескольких секунд покажет, что обновление не завершилось, и раскатку или новое обновление снова можно запускать; причину покажет journalctl -u 'mistgate-panel-update*'.
Копия данных делается, пока панель остановлена, до первого запуска нового бинарника. Если новая панель не прошла 45-секундную проверку, базу, которую она, возможно, уже мигрировала вперёд, заменяет эта копия, поэтому прежний бинарник никогда не работает со схемой, которой не знает; всё, что новая панель успела записать за эти секунды, теряется. Чтобы вернуться позже вручную, остановите панель, восстановите каталог данных из <data-dir>.panel-update-backup.tar.gz, верните <бинарник>.prev и запустите; всё, что изменилось после обновления, будет потеряно.
Включить обновления для непривилегированной службы панели#
Для systemd-службы панели с User=mistgate установите root-owned unit helper и узкое правило PolicyKit. Правило разрешает этой учётной записи запускать только mistgate-panel-update.service; оно не даёт общего доступа к systemd и не открывает root shell. В unit панели можно оставить NoNewPrivileges=yes. Unit helper обновляет только стандартную раскладку: бинарь /usr/local/bin/mistgate, каталог данных /var/lib/mistgate и служба mistgate.service. Панель без root, установленная иначе, откажет в Обновить панель с ошибкой, где названы эти пути; обновляйте её вручную.
Чтобы сознательно разрешить другой канал, выполните от root команду, показанную панелью. Например, эта команда разрешает Development:
sudo sh -c 'install -d -o root -g root -m 0755 /etc/mistgate && tmp=$(mktemp /etc/mistgate/.panel-update-channel.XXXXXX) && printf "%s\n" dev > "$tmp" && chmod 0644 "$tmp" && mv -f "$tmp" /etc/mistgate/panel-update-channel'install -o root -g root -m 0644 deploy/systemd/mistgate-panel-update.service /etc/systemd/system/mistgate-panel-update.service
install -o root -g root -m 0644 deploy/polkit/60-mistgate-panel-update.rules /etc/polkit-1/rules.d/60-mistgate-panel-update.rulesПроверьте unit helper перед загрузкой. В ExecStart должны быть указаны установленный бинарник, каталог данных и unit панели. По умолчанию используется mistgate.service; если имя отличается, укажите одинаковое значение в --update-service панели и --service helper. В ReadWritePaths укажите родительский каталог данных и каталог бинарника: для отката helper должен атомарно переименовать каталог данных. Если служба работает от другого пользователя, замените subject.user в правиле PolicyKit на точное имя этой учётной записи. Оба файла должны принадлежать root и быть недоступны для записи пользователю панели.
systemctl daemon-reload
systemctl show --property=LoadState --value mistgate-panel-update.serviceПоследняя команда должна вывести loaded. На сервере также должен быть установлен PolicyKit и работать его служба авторизации, чтобы пользователь панели мог запустить helper. Helper запускается по запросу панели; включать или запускать его вручную не нужно. Если панель сообщает, что не удалось запланировать обновление, проверьте журнал командой journalctl -u mistgate-panel-update.service.
Ранние сборки и ручное обновление#
Ранние сборки с хешем коммита, например 0.1.0-<commit>, появились до самообновления панели: они показывают релиз, но не могут его установить. Один раз замените такой бинарник на подходящий файл текущего стабильного релиза из GitHub Releases, следуя ручным шагам ниже. Более новые сборки обновляются в разделе Настройки → Система: нажмите Проверить GitHub, затем Обновить панель, когда появится новая версия.
Для установки без systemd, панели, собранной со своим ключом, или ручного обновления:
- Берите бинарник с тем же ключом релиза. Панель, чей вшитый ключ отличается от
<data-dir>/release.pub, не доверяет ни одному пакету, пока вы не выполнитеmistgate release trust-key(см. Релизы и подпись); сборка без ключа продолжает проверять пакеты ключом изrelease.pub, но не может устанавливать релизы панели. - Не обновляйте панель во время раскатки: поставьте её на паузу или дождитесь конца. Перезапуск посреди шага ставит раскатку на паузу («панель перезапустилась во время шага»).
- Скопируйте новый бинарник рядом с установленным, затем остановите панель, сделайте копию каталога данных, замените бинарник и запустите панель снова. Здесь бинарник —
/usr/local/bin/mistgate, а unit systemd —mistgate.service, как в «Установке панели»; подставьте свои имена:
scp mistgate-linux-amd64 panel.example.com:/usr/local/bin/mistgate.new
# на сервере панели, от root
systemctl stop mistgate
tar czf /root/mistgate-backup-$(date +%F).tgz -C /var/lib mistgate
mv /usr/local/bin/mistgate.new /usr/local/bin/mistgate
chmod 0755 /usr/local/bin/mistgate
systemctl start mistgate
journalctl -u mistgate -n 50- База данных мигрирует при запуске панели, больше ничего не нужно. Новую версию покажут строка журнала
mistgate starting, карточка Эта панель на странице «Обновления» иmistgate version.
Что происходит вокруг перезапуска:
- Агенты нод переподключаются сами (повторяют попытки с растущей паузой от 1 до 60 секунд). Пока панели нет, их профили продолжают работать.
- Первые 90 секунд после запуска панель не открывает алерт «Нода недоступна».
- Сессии админки переживают перезапуск.
Миграции идут только вперёд. Старый бинарник панели не обязан работать с базой, которую уже обновил новый. Чтобы вернуться, остановите панель, восстановите каталог данных из копии, сделанной перед обновлением, верните старый бинарник и запустите. Всё, что изменилось после копии, будет потеряно.
Операционная система серверов#
Слой Система серверов на странице «Обновления» показывает операционную систему каждого сервера: сначала сервер самой панели, затем каждую ноду. Он отвечает, какие серверы ждут нового ядра, перезагрузки или обновлений безопасности, без входа на каждый из них.
| Колонка | Что показывает |
|---|---|
| Сервер | Нода (или Сервер этой панели) и сколько людей на ней сейчас в сети. |
| Система | Дистрибутив и его версия. |
| Ядро | Работающее ядро и, если установлено более новое, то, которое запустится после перезагрузки. |
| Обновления | Сколько пакетов ждёт и сколько из них — обновления безопасности, а также насколько стары списки пакетов на сервере. Если обновлений безопасности нет, в колонке написано Обновлений безопасности нет, а рядом, тихой строкой, — сколько обычных обновлений ждёт («18 обычных обновлений»). |
| Состояние | Безопасность в порядке (зелёный), Обновления безопасности (янтарный), Нужна перезагрузка (янтарный), Обновление не удалось (красный), Обновляется…, Не в сети, Недоступно или Ещё не прочитано. |
Состояние говорит о безопасности и перезагрузке. Сервер, на котором нет ожидающих обновлений безопасности и не нужна перезагрузка, зелёный: Безопасность в порядке (Актуальна, если не ждёт вообще ничего), даже когда ждут обычные пакеты (всё, что не обновления безопасности): они — заметка рядом с числом, а не состояние, поэтому страница может выглядеть «всё хорошо». Янтарный — для ожидающих обновлений безопасности и для нужной перезагрузки, красный — для сбоя. Строка над таблицей считает так же: сколько серверов ждут перезагрузки, у скольких есть обновления безопасности, или «Безопасность в порядке на всех серверах» с числом серверов, где ждут обычные обновления.
Под строкой страница называет то, что требует внимания: почему нужна перезагрузка (новое ядро или пакеты, которые её просят), удерживаемые пакеты, прерванные установки, выключенные или не установленные автоматические обновления безопасности, работающий в этот момент другой менеджер пакетов и новое ядро, для которого ещё не собран модуль AmneziaWG. В контейнере ядро принадлежит провайдеру, и строка говорит об этом.
Как это читается:
- Агент ноды читает всё на самом сервере: из списков пакетов, которые уже лежат на диске, и пробным обновлением (
apt-get -s). Он не обращается к зеркалам пакетов, не запускаетapt updateи ничего не меняет на сервере. Поэтому числа свежи настолько, насколько свежи списки: «списки: 9 дней назад» значит, что сервер не обновлял их девять дней, а сервер совсем без списков просит один раз выполнитьapt updateвручную. - Агент читает всё заново раз в шесть часов и раньше, если на сервере что-то изменилось (установлен пакет, обновлены списки, была перезагрузка); результат он отправляет при подключении. Подключённая нода, чьё последнее чтение старше 18 часов, показывает Ещё не прочитано.
- Работает на Debian и Ubuntu с systemd. Другие системы и ноды с агентом старше этой функции показывают Недоступно с причиной.
- Сервер самой панели читается, только когда панель работает от root; иначе строка просит проверить его вручную.
В статусе перечислены до 32 ожидающих обновлений безопасности; если такие пакеты остаются больше двух дней при включённых автоматических обновлениях, они отмечаются отдельно. После unattended-upgrade нода повторно проверяет собственную симуляцию и устанавливает оставшиеся пакеты безопасности вместе с нужными новыми зависимостями; неудачная попытка отмечается в результате, но не делает задание неуспешным. Если apt занят, статус показывает имя процесса-владельца блокировки и время его запуска.
Из этого слоя панель может установить обновления безопасности или все пакеты, а также перезагрузить одну ноду; см. Обновление системы одного сервера. Раскатка ОС обрабатывает от 1 до 20 нод: канарейка выбирается по наименьшему числу людей онлайн, затем inbound; следующие пакеты содержат от 1 до 5 нод (по умолчанию 1). Обычные пакеты устанавливаются в режиме all; сервер самой панели остаётся вне области этой функции и обновляется вручную. В Cloudflare-версии этого слоя нет. MCP-инструмент os_updates_status возвращает те же сохранённые данные и последнее обновление ОС; к ноде он не обращается.
Обновление системы одного сервера#
Владелец может из панели поставить обновления безопасности на одном сервере или перезагрузить его: на вкладке Сервер ноды (карточка Операционная система) или в строке ноды в слое Системы серверов. Сначала панель просит свежее подтверждение, как для любого изменения, которое выполняется на ноде от root.
| Кнопка | Что делает |
|---|---|
| Установить обновления безопасности… | Ставит то, что дистрибутив называет обновлениями безопасности (unattended-upgrade). С выбором Перезагрузить, если потребуется (рекомендуется) потом перезагружает сервер, если нужна перезагрузка; с Не перезагружать только ставит, и сервер показывает Нужна перезагрузка, пока вы его не перезагрузите. |
| Перезагрузить… | Перезагружает сервер, ничего не устанавливая. |
| Проверить обновления | Обновляет списки пакетов сервера (apt-get update), чтобы счётчики были свежими. Ничего не ставит и не перезагружает. Один раз на сервер за 30 минут, по три сервера одновременно. |
Окно подтверждения говорит, что произойдёт: сколько пакетов ждёт и сколько из них обновления безопасности, ждёт ли новое ядро, нужна ли уже перезагрузка, сколько людей онлайн на сервере и что при перезагрузке они отключатся (обычно примерно на две минуты) и подключатся снова сами. Оно предупреждает о том, из-за чего сервер откажется: unattended-upgrades настроен перезагружать сервер сам, модуль AmneziaWG не собран под новое ядро, пакеты остались недоустановленными. Старые ядра остаются установленными.
Что происходит дальше, в строке сервера:
- Панель даёт заданию новый id и отправляет его агенту ноды; агент запускает его отдельной системной службой, поэтому перезапуск агента его не обрывает. В строке видна фаза: проверка сервера, ожидание другого менеджера пакетов (до 15 минут), починка прерванных пакетов, проверка обновлений, установка обновлений, сборка модуля AmneziaWG под новое ядро, проверка перед перезагрузкой, перезагрузка.
- После перезагрузки панель ждёт до 15 минут, пока сервер вернётся с новой загрузкой. Нода проверяет, что стартовала на установленном ядре, что модуль AmneziaWG загружен там, где он использовался, и что её профили подняты.
- Затем панель делает ту же проверку, что после обновления агента: настройки применены, ни один работавший прежде профиль не сломан, WARP поднят там, где профиль выходит через него, и проверки панели «глазами клиента» проходят (до 8 минут). Пока идёт ожидание, строка говорит, чего именно ждут: названия профилей, которые ещё не прошли (первые пять, затем «и ещё N»), а если дело не в профиле — что панель применяет настройки к ноде, что запускается WARP или что нода заканчивает собственную проверку; и сколько уже прошло из максимума. Панель засчитывает сервер, только когда знает, чем кончилось задание: сервер, найденный на новой загрузке без вестей о задании, ждёт его собственного отчёта. Если сервер пропадает во время этой проверки, а перезагрузки не было, обновление останавливается с пометкой «сервер потерян». После этого в строке написано Готово, с числом установленных пакетов и новым ядром.
Слишком ранняя перезагрузка не предлагается. Нода отказывается перезагружаться раньше чем через 10 минут после загрузки (too_soon), а по заданию панели — чаще одного раза в час и трёх раз за сутки (reboot_limit). Панель знает и то и другое: время загрузки ноды и перезагрузки своих обновлений ОС. В данных ноды она сообщает время, с которого перезагрузка снова возможна (позднее из двух ограничений), и Перезагрузить… остаётся выключенной до этого момента, а под ней написано «Перезагрузка возможна через 12 мин» (минуты округляются вверх и обновляются вместе со страницей). Установку это не задерживает; окно при этом заранее выбирает Не перезагружать и объясняет почему: перезагрузка, которую нода удержала после установки, останавливает обновление. План MCP на перезагрузку раньше этого времени отклоняется с той же причиной (reboot_wait).
Безопасна ли перезагрузка, решает нода, и обойти её ответ из панели нельзя: кнопки «перезагрузить всё равно» нет. Если нода отказывается, установленные ею обновления остаются (запуск Перезагрузить… ничего не устанавливает и говорит только, что сервер не перезагружен), задание завершается как неудачное с удержанной перезагрузкой (held), а строка говорит, почему и что делать. Одни и те же фразы стоят у каждого отказа и сбоя задания:
| Код | Что это значит и что делать |
|---|---|
busy |
На сервере уже идёт другое задание: дождитесь его конца. |
too_soon |
Сервер перезагружался меньше 10 минут назад, поэтому повторно его не перезагрузили. |
reboot_limit |
Панель уже перезагружала этот сервер в последний час или трижды за сутки, поэтому пока не будет делать это снова. |
boot_entry_missing |
В /boot/grub/grub.cfg нет пункта для новейшего ядра, перезагрузка не запустила бы его, поэтому ноду не перезагрузили: выполните update-grub на сервере или перезагрузите из панели провайдера. |
boot_default_custom |
Меню загрузки (GRUB) настроено на выбранный или сохранённый пункт, а не на новейшее ядро, поэтому ноду не перезагрузили: поставьте GRUB_DEFAULT=0 или перезагрузите из панели провайдера. |
awg_module_missing |
Модуль AmneziaWG не собран под новое ядро, поэтому ноду не перезагрузили: сначала соберите модуль. |
awg_module_build_failed |
Модуль AmneziaWG не собрался под новое ядро; ноду не перезагрузили, загруженный модуль работает: сначала исправьте сборку. |
kernel_unknown |
Не удалось определить, какое ядро загрузится, поэтому сервер не перезагрузили. |
kernel_older |
При следующей загрузке запустилось бы ядро старше текущего, поэтому ноду не перезагрузили: проверьте меню загрузки (GRUB). |
initramfs_missing |
Нет файлов для запуска нового ядра, поэтому ноду не перезагрузили: переустановите пакет ядра. |
boot_full |
Раздел /boot слишком заполнен для нового ядра: удалите старые ядра. |
apt_lock |
Другой менеджер пакетов слишком долго держал блокировку: повторите через несколько минут. |
dpkg_interrupted |
Установка пакета была прервана: выполните на сервере sudo dpkg --configure -a. |
dpkg_broken |
База пакетов повреждена: выполните на сервере sudo dpkg --configure -a. |
disk_full |
Диск слишком заполнен: освободите место. |
security_source_failed |
Сервер не достучался до источника обновлений безопасности: проверьте его зеркало и сеть. |
refresh_failed |
Списки пакетов не обновились: проверьте сеть и зеркала сервера. |
install_failed |
Установка обновлений не удалась: смотрите журнал задания на сервере (journalctl -u mistgate-os-update). |
auto_reboot_conflict |
Unattended-upgrades настроен перезагружать сервер сам, это обошло бы проверки: выключите Automatic-Reboot. |
reboot_failed |
Команда перезагрузки отклонена или сервер не выключился: перезагрузите его из панели провайдера. |
kernel_not_switched |
Сервер загрузился на другом ядре, чем установленное: проверьте меню загрузки (GRUB). |
awg_module_not_loaded |
После перезагрузки модуль AmneziaWG не загрузился: пересоберите его или переключите бэкенд на Auto. |
inbound_failed |
После перезагрузки часть профилей не запустилась: смотрите вкладку «Профили» ноды. |
unsupported_os |
Эту систему нельзя обновить из панели: обновите её вручную. |
no_systemd |
На сервере нет systemd: обновите его вручную. |
bad_request |
Нода не приняла запрос: обновите агент ноды. |
launch_failed |
Задание не удалось запустить: проверьте диск ноды и журнал агента. |
timeout |
Задание шло слишком долго и было остановлено. |
interrupted |
Задание оборвалось без результата: проверьте сервер. |
cancelled |
Задание отменили, ничего не изменив. |
unknown |
Нода сообщила о проблеме, которой панель не знает: смотрите её историю событий. |
Недоступно (кнопки серые, причина под ними), когда: сервер не на связи; его агент слишком старый для заданий (обновите агент на странице «Обновления»); система не Debian 12 или 13 и не Ubuntu 22.04, 24.04 или 26.04 с systemd; это сервер самой панели (его перезагрузка уронила бы панель, обновите его вручную); на нём уже идёт другое задание (обновление, сборка модуля AmneziaWG, обновление агента); с него ещё ничего не прочитано; нет обновлений безопасности (используйте Перезагрузить… или Проверить обновления); или идёт другое обновление: обновление ОС другой ноды (идущее, или остановленное и ещё не закрытое), раскатка агентов, обновление панели или установка пакета релиза. Одновременно только одно, чтобы две перезагрузки или два менеджера пакетов не пересекались. В обратную сторону: пока идёт обновление ОС, раскатки агентов, обновление панели, установка пакета релиза и запланированные обновления нод ждут его; остановленное обновление ОС держит только следующее обновление ОС.
Если нода отказывает по причине, допускающей повтор (busy, apt_lock, too_soon, reboot_limit), шаг ждёт и повторяется до двух часов; затем он получает статус Пропущен (try_later), и раскатка продолжается. Жёсткая блокировка, например не готовое ядро, пропускается сразу с указанием причины. Реальная ошибка (ошибка задания, нода не вернулась или вторая проверка не прошла) ставит на паузу всю раскатку; следующие ноды не запускаются, пока владелец не продолжит или не отменит её. Продолжение повторяет неудачный шаг один раз либо помечает его пропущенным при skip_failed. Уже выполняющееся на ноде задание не прерывается паузой или отменой. Если сервер не вернулся за 15 минут после перезагрузки, откройте консоль хостера: если он завис, выберите прежнее ядро в Advanced options меню GRUB (обновление никогда не удаляет старые ядра).
Панель хранит запуск и его шаги в базе и после перезапуска продолжает по сохранённому состоянию. События ноды os_update_started, os_update_done, os_update_failed и os_reboot_started и панельные os_step_passed и os_step_failed видны на вкладке История ноды; в журнале аудита записаны os_rollout_start, os_rollout_pause, os_rollout_resume, os_rollout_cancel и os_refresh.
Таблица ядер#
Карточка «Операционная система» ноды (Нода → Сервер) перечисляет установленные ядра, новейшее первым, не больше 8. Строка — одно ядро, у него пять маленьких отметок: можно ли с него загрузиться:
- Загрузка: образ ядра лежит в
/boot, а initramfs не меньше 1 МиБ. - GRUB:
/boot/grub/grub.cfgназывает это ядро. - Заголовки: есть
/usr/src/linux-headers-<ядро>. - Модуль: модуль AmneziaWG собран под это ядро. Серая отметка: AmneziaWG не использует модуль ядра, либо агент не видит сборку (обычная сборка на Debian).
- Пакеты: пакеты
linux-*этого ядра полностью настроены.
Строка под заголовком — «Следующая загрузка: всё готово» или «Перезагрузка будет отклонена: …» с первой причиной (initramfs_missing, boot_entry_missing, awg_module_missing, dpkg_interrupted, kernel_older или boot_default_custom, те же коды, что у задания перезагрузки ниже). В таблице «Обновления» блок появляется, раскрытым, только у такой ноды. Пока перезагрузку отклонили бы, кнопка Перезагрузить… выключена с той же причиной. Агент читает эти файлы в своей песочнице и ничего не меняет; задание перезагрузки проверяет заново от root и решает само, так что таблица — предварительный взгляд, а не обещание. Агент старее этой версии показывает «Обнови агент, чтобы увидеть таблицу ядер».
Проверка «Обновления безопасности» в разделе «Здоровье» также предупреждает, если у unattended-upgrades включён Automatic-Reboot, а AmneziaWG работает на модуле ядра: такая перезагрузка идёт мимо проверок агента и может попасть на ядро без модуля. Выключите Automatic-Reboot.
Запуск вручную на ноде#
То же задание панель запускает для одной ноды (см. Обновление системы одного сервера). Нода умеет выполнить задание и сама, и владелец может запустить его на одном сервере по SSH (от root; Debian 12 или 13, Ubuntu 22.04, 24.04 или 26.04 с systemd):
mistgate-node host os-update --action upgrade --mode security --reboot if-required # печатает план, ничего не запускает
systemd-run --unit=mistgate-os-update --collect --property=KillMode=mixed --property=TimeoutStopSec=600 \
mistgate-node host os-update --yes --action upgrade --mode security --reboot if-required| Параметр | Значения |
|---|---|
--action |
refresh (только обновить списки пакетов), upgrade (установить обновления; по умолчанию), reboot (без изменения пакетов, только перезагрузка). |
--mode |
security (то, что ставит unattended-upgrade; по умолчанию) или all (apt-get upgrade --with-new-pkgs). Только вместе с upgrade. |
--reboot |
never (по умолчанию), if-required (только если перезагрузка нужна) или always. С refresh допустим never, с upgrade — never или if-required, с reboot — if-required или always. |
--awg-required |
Считать модуль ядра AmneziaWG нужным. Команда считает его нужным и без флага, пока модуль загружен. |
Без --yes команда только печатает план. Запускайте её отдельным юнитом, как во второй строке: так оборванная SSH-сессия не прервёт dpkg. Что она делает, по порядку: проверяет систему и свободное место; ждёт до 15 минут другой менеджер пакетов; доводит до конца прерванные установки (dpkg --configure -a), если они есть; запускает apt-get update; ставит обновления; на Ubuntu собирает модуль AmneziaWG (DKMS) под только что установленное ядро; и только последним шагом и только по просьбе перезагружает сервер.
Перед перезагрузкой команда проверяет и отказывается, ничего не перезагружая и завершаясь ошибкой с перезагрузкой в состоянии удержана, если:
- apt или
dpkgзаняты (apt_lock); - установка пакета была прервана, пакет наполовину установлен или настроен (
dpkg_interrupted, пакеты названы); - ядро, которое запустится при следующей загрузке, определить не удалось (
kernel_unknown) или оно старше работающего (kernel_older); - модуль AmneziaWG загружен (или указан
--awg-required) и не собран под каждое ядро, на котором может оказаться меню загрузки: самое новое из установленных и каждое более низкое, не старше работающего (awg_module_missing); - образ или initramfs одного из этих ядер отсутствует или обрезан (
initramfs_missing), либо при смене ядра в/bootсвободно меньше 50 МБ (boot_full); - GRUB может не запустить первый пункт: нет
/boot/grub/grub.cfg,GRUB_DEFAULTв/etc/default/grubили/etc/default/grub.d/*.cfgзадан не как0,grub-editenv listпоказываетsaved_entryилиnext_entry, либоgrub-editenvне читается (boot_default_custom); /boot/grub/grub.cfgесть, но в нём нетvmlinuz-<ядро>для новейшего установленного ядра (boot_entry_missing);- сервер загружен меньше 10 минут назад (
too_soon): ноду не перезагружают по кругу; - для задания от панели (идентификатор начинается с
osj_): нода уже перезагружалась таким заданием меньше часа назад или три раза за сутки, либо история перезагрузок рядом сos-update.jsonне читается или опережает часы (reboot_limit). Команды, запущенные вручную, не ограничиваются.
Когда проверки пройдены, команда берёт замок dpkg и держит его до перезагрузки, чтобы между ними не запустился другой менеджер пакетов.
--reboot always пропускает только вопрос «нужна ли перезагрузка», но не эти проверки. Пакеты AmneziaWG команда никогда не удаляет и не ставит для модуля никаких пакетов, даже заголовки ядра. Если собственная сборка DKMS модуля не удалась, команда останавливается с awg_module_build_failed, называя ядро и пакет linux-headers-<ядро>, настройка которого запускает сборку: ничего не удалено, ничего больше не установлено, перезагрузка (если её просили) удержана, а загруженный модуль работает до следующей загрузки. Исправьте сборку (её make.log лежит в /var/lib/dkms/amneziawg) до любой перезагрузки. Сборка DKMS, не удавшаяся по другой причине, например потому что не установлены заголовки нового ядра, лишь оставляет модуль несобранным под это ядро и удерживает перезагрузку (awg_module_missing). Другие отказы: unsupported_os (любая система вне списка выше), no_systemd, disk_full, security_source_failed (не удалось обновить источник пакетов безопасности; остальные источники, которые не отвечают, лишь перечисляются), install_failed (с именем пакета), auto_reboot_conflict (unattended-upgrades настроен перезагружать сервер сам, и это обошло бы проверки: выключите Automatic-Reboot или используйте --mode all), busy (идёт другое задание ОС, обновление агента или сборка модуля).
Состояние хранится в os-update.json в каталоге состояния агента (по умолчанию /var/lib/mistgate-node), поэтому переживает перезапуск агента и саму перезагрузку. После неё агент находит файл и проверяет, что сервер вернулся на ожидаемом ядре, что модуль AmneziaWG снова загружен там, где он использовался, и что входы ноды подняты; итог — одно событие во вкладке «История» ноды (os_update_done или os_update_failed с кодом). Вывод apt остаётся в журнале юнита (journalctl -u mistgate-os-update), урезанный и без адресов. Отменить до начала установки можно командой systemctl stop mistgate-os-update: при KillMode=mixed сигнал получает только сама команда, а уже начавшийся apt дают доработать (до TimeoutStopSec). Тот же идентификатор задания, присланный агенту повторно, получает результат этого задания и ничего не запускает; после отказа или сбоя панель присылает следующую попытку под новым идентификатором.
Чего команда не делает: не правит источники пакетов, не запускает dist-upgrade и autoremove (старые ядра остаются), не переходит на новый релиз, не меняет настройку бэкенда AmneziaWG на ноде и не трогает бинарник самого агента. У ноды с агентом старше этого релиза такой команды нет.
Обновления через API и MCP#
Любой профиль API-токена может читать страницу обновлений (GetUpdates). Рискованные действия через обычный API запрещены; MCP-агент с профилем admin может только составить план, который владелец одобряет в админке. MCP-инструмент rollout_start обновляет от 1 до 20 выбранных нод поэтапно в порядке канарейки. План раскатки ОС (os_rollout_start) закрепляет id нод, режим, политику перезагрузки и размер пакета и показывает порядок, пакеты, ядро, перезагрузку, онлайн-пользователей и блокировки. Пауза, продолжение и отмена доступны как планы с одобрением владельца; обновление списков пакетов (RefreshOsUpdates) остаётся действием владельца в админке. См. API и MCP.