Files
buryan-infra/ops/runbooks/update-manager.md
T

207 lines
8.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Runbook: система обновлений
**Относится к:** F6-1 (ядро), F6-3 (обнаружение версий), F6-4 (одобрение), F6-5 (откат)
**Расположение:** pve, `/root/buryan-infra/ops/update-manager/`
---
## 1. Как это устроено
```
version-watch.sh (cron каждые 6 часов)
│ находит новые версии образов
▼
Gitea issue + сообщение в Telegram с кнопками
│ человек нажимает «Обновить сейчас»
▼
comms-agent (CT 108) пишет решение в таблицу update_queue
│
▼
update-runner.sh (cron каждую минуту на pve)
│ забирает одобренную задачу
▼
safe-update.sh <сервис>
│ снимок → обновление → проверка здоровья → проверка образа
▼
успех: версия в реестр, снимок удалён, коммит в Git
провал: откат из снимка, задача в Gitea с меткой sev:1
```
**Кнопки нажимает бот `@Adm_buryans_bot`** — тот, который опрашивает Telegram.
Кнопки работают только у того бота, который получает обновления.
---
## 2. Ежедневное использование
Ничего делать не нужно. При появлении новой версии придёт сообщение с кнопками.
### Посмотреть очередь
```bash
psql -h 192.168.1.151 -U buryan_monitor -d buryan_monitoring \
-c 'SELECT id, service, action, status, requested_by FROM update_queue ORDER BY id;'
```
Состояния: `pending` → `approved` → `running` → `done` / `failed` / `cancelled` / `deferred`.
### Обновить сервис вручную
```bash
/root/buryan-infra/ops/update-manager/safe-update.sh <сервис>
```
Список сервисов: `yq -r '.services | keys[]' /root/buryan-infra/ops/update-manager/services.yaml`
### Посмотреть журнал
```bash
tail -30 /root/buryan-infra/ops/update-manager/runner.log # решения и результаты
tail -30 /root/buryan-infra/ops/update-manager/update.log # что делал исполнитель
```
---
## 3. Проверка, что система жива
```bash
# раннер в расписании
crontab -l | grep update-runner
# задача выполняется, а не висит
psql -h 192.168.1.151 -U buryan_monitor -d buryan_monitoring \
-c "SELECT * FROM update_queue_summary;"
# ночной отчёт приходил (в Telegram в 03:05)
tail -3 /root/buryan-infra/ops/update-manager/runner.log
```
---
## 4. Что ломается и как это выглядит
Все случаи ниже реально происходили 14.10.2026. Общая черта — **система
сообщала об успехе, ничего не сделав**.
### Кнопка нажата, ничего не происходит
**Причина:** у бота нет прав на таблицу `update_queue`. Бот ходит под
пользователем `n8n`, а таблицу создаёт `buryan_monitor`.
```bash
pct exec 108 -- docker logs --tail 50 tg-admin-bot | grep -i 'решение\|privilege'
# лечится:
psql -h 192.168.1.151 -U buryan_monitor -d buryan_monitoring <<'SQL'
GRANT SELECT, INSERT, UPDATE ON update_queue TO n8n;
GRANT USAGE, SELECT ON SEQUENCE update_queue_id_seq TO n8n;
SQL
```
**Запомнить:** новая таблица в базе — это не только `CREATE TABLE`. Нужно
сразу выдать права тем, кто с ней работает.
### Задача висит в состоянии running
Признак того, что исполнитель упал между началом и записью результата.
```bash
psql -h 192.168.1.151 -U buryan_monitor -d buryan_monitoring \
-c "UPDATE update_queue SET status='failed', finished_at=now(), result='прервано' WHERE status='running';"
```
### В журнале «обновлено», а версия не изменилась
**Причина:** контейнер перезапущен, но не пересоздан. `docker restart`
поднимает тот же контейнер из **старого** образа.
```bash
# проверить: образ контейнера против скачанного
pct exec <CT> -- docker inspect <контейнер> --format '{{.Image}}'
pct exec <CT> -- docker images --no-trunc --format '{{.ID}}' <образ>:latest
```
Если различаются — обновление не применилось. Причины и лечение:
| Причина | Признак | Лечение |
|---|---|---|
| Нет файла compose | `compose_path` в реестре ведёт в пустоту | составить compose-файл |
| **Нет плагина compose** | `docker: unknown command: docker compose` | `apt-get install -y docker-compose-v2` |
| Контейнер создан через `docker run` | нет меток `com.docker.compose.*` | составить compose-файл |
| AppArmor мешает старту | `docker-default profile could not be loaded` | `security_opt: [apparmor:unconfined]` |
Здоровый прогон содержит строку `✅ Контейнер работает из актуального образа`.
### Задача в Gitea не создаётся при откате
Две ловушки разом: Gitea принимает метки **только по номеру** (передача имени
даёт `422`), а `curl` возвращает код 0 даже при ошибке сервера. Поэтому
проверяется код ответа HTTP, а номер метки запрашивается заранее.
### Уведомление об обновлении приходит, но не о том сервисе
Проверить соответствие имён:
```bash
bash /root/buryan-infra/ops/update-manager/map-containers.sh
```
Уведомления приходят с именами контейнеров, реестр оперирует именами сервисов.
Соответствие хранится в поле `container`. Автоподбор по вхождению ошибается:
для `dashy` он находил `oauth2-proxy-dashy`.
---
## 5. Отложенные обновления
Кнопка «Отложить до 03:00» ставит статус `deferred`. Раннер переводит такие
задачи в `approved`, когда наступает час `DEFER_HOUR` (по умолчанию 03).
Проверить механику, не дожидаясь ночи:
```bash
DEFER_HOUR=$(date +%H) bash /root/buryan-infra/ops/update-manager/update-runner.sh
```
Ночной отчёт приходит в Telegram в 03:05 и показывает, сколько отложенных
дождалось своего часа.
---
## 6. Проверка отката
Сценарий намеренно ломает обновление тестового сервиса и смотрит, что откат
сработал за 5 минут:
```bash
bash /root/buryan-infra/ops/update-manager/rollback-drill.sh
```
Скрипт подставляет в реестр сервис с нерабочим адресом проверки здоровья,
ждёт результат, проверяет отсутствие снимков и прибирает за собой.
Использует контейнер CT 160, который никому не нужен.
**Результат 14.10.2026:** откат за 90 секунд, задача в Gitea с меткой `sev:1`.
---
## 7. Важное про снимки
`safe-update.sh` снимает снимок контейнера перед обновлением и **обязан его
удалить**. В версии до 14.10.2026 снимок не удалялся никогда — так накопились
два снимка на 14 ГБ, которые заполнили пул томов.
Проверить, не осталось ли лишних:
```bash
for id in $(pct list | awk 'NR>1{print $1}'); do
pct listsnapshot "$id" | grep pre-update && echo " ^ CT $id"
done
```
Если исполнитель отказался от обновления, снимок удаляется тоже.
Если снимок остался после провала — удалить вручную:
```bash
pct delsnapshot <CT> <имя-снимка>
```