docs(F6-7): ранбуки систем, ретроспектива спринта, закрытие чек-листа
This commit is contained in:
1 parent
b9d69958de
commit
93011330ab
5 files changed
+686
-2
No files matched your search
@@ -0,0 +1,159 @@
|
||||
# Ретроспектива спринта F6
|
||||
|
||||
**Дата:** 2026-10-14
|
||||
**Спринт:** F6 — «Автоматизация обновлений и наблюдаемость»
|
||||
**Итог:** задачи F6-1…F6-7 выполнены. Версия зафиксирована тегом **v1.4**
|
||||
|
||||
---
|
||||
|
||||
## 1. Что планировалось и что получилось
|
||||
|
||||
| Задача | План | Факт |
|
||||
|---|---|---|
|
||||
| F6-1 | Ядро менеджера обновлений | Было сломано, переписано заново |
|
||||
| F6-2 | Самостоятельная регистрация | Работает, описано в ранбуке |
|
||||
| F6-3 | Слежение за версиями | Работает, найдены ложные срабатывания, исправлено |
|
||||
| F6-4 | Поток одобрения обновлений | Собран с нуля, проверен живым нажатием кнопки |
|
||||
| F6-5 | Проверка отката | Проведена: откат за 90 секунд, задача sev:1 создана |
|
||||
| F6-6 | Проактивный мониторинг | Сделан, попутно починен сбор метрик |
|
||||
| F6-7 | Ретроспектива и ранбуки | Этот документ и четыре ранбука |
|
||||
|
||||
---
|
||||
|
||||
## 2. Главное открытие спринта
|
||||
|
||||
**Система трижды сообщала об успехе, ничего не сделав.** Это не три разных
|
||||
случая, а одна закономерность в трёх формах:
|
||||
|
||||
| Форма | Как выглядело | Что было на самом деле |
|
||||
|---|---|---|
|
||||
| Код возврата `curl` | В журнале «задача в Gitea создана» | Gitea вернула `422`, задачи нет |
|
||||
| Проверка здоровья | «Проверка пройдена, обновлено» | Контейнер работал из старого образа |
|
||||
| Запись в журнале | «ГОТОВО! Сервис обновлён» | Образ скачан, контейнер не пересоздан |
|
||||
|
||||
Отсюда правило, которое стоит перенести на всю дальнейшую работу:
|
||||
**проверять надо результат, а не факт выполнения команды.**
|
||||
|
||||
У каждой проверки теперь есть подтверждение: образ работающего контейнера
|
||||
сравнивается со скачанным, факт записи в базу проверяется, состояние фиксируется.
|
||||
|
||||
---
|
||||
|
||||
## 3. Что нашлось сломанным (и это ценнее, чем сделанное)
|
||||
|
||||
### Данные были под угрозой
|
||||
|
||||
- **Резервные копии контейнеров не создавались две недели.** Скрипт ротации
|
||||
падал каждое воскресенье из-за синтаксической ошибки, копии копились,
|
||||
том копий заполнился на 100%. При заполнении пула ломаются не копии,
|
||||
а данные.
|
||||
- **Контроль пула всё это время писал `CRITICAL` каждые 5 минут** — 15 677
|
||||
записей — и никого не уведомлял. Скрипт умел только писать в базу.
|
||||
|
||||
### Обновления не работали нигде
|
||||
|
||||
- Gitea не обновлялась с июля: «обновление» 9 октября свелось к скачиванию
|
||||
образа. Три независимые причины: нет файла compose, **нет плагина compose**
|
||||
(в 12 контейнерах из 26!), AppArmor мешает запуску нового контейнера.
|
||||
- Медиа-сервисы, Prometheus, Syncthing, Linkwarden — та же история с плагином.
|
||||
|
||||
### Наблюдаемость отсутствовала
|
||||
|
||||
- **28 сборщиков метрик работали, а Prometheus читал данные с себя одного.**
|
||||
Диски, процессор и память гостей не собирались вообще.
|
||||
- Диски никто не контролировал: контейнеры стояли на 86–89%, узнали случайно.
|
||||
- Сроки сертификатов никто не проверял.
|
||||
|
||||
### Мелкое, но показательное
|
||||
|
||||
- `yq` версии 4 не понимает `empty` — реестр сервисов не читался бы вовсе.
|
||||
- В расписании копирования был несуществующий контейнер CT 131.
|
||||
- Кнопка «Обновить» в Telegram была нарисована, а обработчика под ней
|
||||
не существовало никогда.
|
||||
|
||||
---
|
||||
|
||||
## 4. Наши собственные ошибки
|
||||
|
||||
Честный раздел: часть проблем спринта создали мы сами.
|
||||
|
||||
| Ошибка | Как проявилась | Вывод |
|
||||
|---|---|---|
|
||||
| Заменил `docker compose up -d` на `docker restart` при переписывании | Обновления перестали применяться, отчёт говорил «обновлено» | Регрессию поймал владелец вопросом «а точно обновилось?» |
|
||||
| Создал таблицу и не выдал права боту | Кнопка одобрения молча не работала | Новая таблица — это не только `CREATE TABLE` |
|
||||
| Проверял успех `curl` по коду возврата | Ложные записи об успехе | Проверять код ответа HTTP |
|
||||
| Проверка контейнера по вхождению имени | Для `dashy` находился `oauth2-proxy-dashy` | Сначала точное соответствие, потом догадки |
|
||||
| Считал, что `docker restart` перезапускает сервис | Версия не менялась | Перезапуск ≠ пересоздание |
|
||||
| Отложил уборку снимков «на потом» | Два снимка на 14 ГБ заполнили пул | Убирать сразу, а не когда-нибудь |
|
||||
|
||||
Общее у всех: **проверка «команда выполнилась» вместо «результат достигнут».**
|
||||
|
||||
---
|
||||
|
||||
## 5. Что сделано в цифрах
|
||||
|
||||
| Показатель | Было | Стало |
|
||||
|---|---|---|
|
||||
| Пул томов | **80,65%** | **46%** |
|
||||
| Том резервных копий | 100%, 0 байт свободно | 38% |
|
||||
| Резервные копии | не создавались 2 недели | работают, проверены |
|
||||
| Целей в Prometheus | 1 | **29** |
|
||||
| Плагин compose | 14 из 26 | **26 из 26** |
|
||||
| Gitea | 1.25.4, не обновлялась | **28.1.0**, управляется через compose |
|
||||
| Контроль дисков | нет | ежечасно, 30 точек |
|
||||
| Контроль сертификатов | нет | ежедневно, 14 доменов |
|
||||
| Кнопка одобрения обновлений | не работала | проверена живым нажатием |
|
||||
|
||||
Освобождено места: **63 ГБ** копий, **~18 ГБ** логов, **14 ГБ** снимков.
|
||||
|
||||
Коммитов за день: **40**.
|
||||
|
||||
---
|
||||
|
||||
## 6. Что осталось и почему это осознанно
|
||||
|
||||
| Что | Почему не сейчас |
|
||||
|---|---|
|
||||
| Ротация секретов | Требует карты зависимостей и отдельного окна. План готов: `docs/SECRETS-ROTATION-PLAN.md` |
|
||||
| Миграция SQLite на PostgreSQL | Отдельное направление, затрагивает все сервисы |
|
||||
| Графики в Grafana | Данные собираются, панелей нет — работа отдельная |
|
||||
| Alertmanager | Пока уведомления шлют скрипты, этого достаточно |
|
||||
| 13 задач-артефактов в Gitea | Закрыты как следы прежней версии workflow |
|
||||
|
||||
**Компромиссы, принятые сознательно:**
|
||||
|
||||
- `security_opt: apparmor:unconfined` для Gitea — контейнер и так работал в этом
|
||||
режиме, менять не стали;
|
||||
- права на таблицы выдаются пользователю `n8n`, под которым ходят и бот, и n8n, —
|
||||
разграничение между ними отсутствует и требует отдельной работы;
|
||||
- снимок и старый контейнер Gitea оставлены на сутки для отката — их **надо
|
||||
удалить**, иначе повторится история с заполненным пулом.
|
||||
|
||||
---
|
||||
|
||||
## 7. Правила, которые стоит унести в следующие спринты
|
||||
|
||||
1. **Проверять результат, а не факт выполнения.** Признак успеха должен быть
|
||||
наблюдаемым: запись в базе, совпадение версий, файл состояния.
|
||||
2. **Убирать за собой сразу.** Снимки, старые контейнеры, временные файлы.
|
||||
Отложенная уборка уже дважды за день привела к нехватке места.
|
||||
3. **Новая таблица — это права.** Сразу выдавать тому, кто с ней работает.
|
||||
4. **Компромисс записывать.** «Временно» и «пока сойдёт» должны быть в документе
|
||||
с причиной, иначе через месяц никто не вспомнит, почему так.
|
||||
5. **Проверять на живом сервисе.** Три из четырёх дефектов нашлись только при
|
||||
реальном прогоне, чтение кода их не показывало.
|
||||
6. **Одна роль — одно место хранения секрета.** Уже применено к ботам,
|
||||
распространить на остальное.
|
||||
|
||||
---
|
||||
|
||||
## 8. Связанные документы
|
||||
|
||||
- `docs/SECRETS-ROTATION-PLAN.md` — план смены секретов
|
||||
- `ops/runbooks/update-manager.md` — система обновлений
|
||||
- `ops/runbooks/user-provisioning.md` — выдача доступов
|
||||
- `ops/runbooks/monitoring.md` — наблюдение за инфраструктурой
|
||||
- `ops/audit/F6-4-update-flow-report.md` — отчёт по потоку обновлений
|
||||
- `ops/audit/F6-6-monitoring-report.md` — отчёт по мониторингу
|
||||
- `ops/audit/GITEA-COMPOSE-MIGRATION.md` — перенос Gitea на compose
|
||||
- `ops/audit/SPRINT-F6-PLAN-v2.md` — план спринта
|
||||
@@ -66,7 +66,7 @@ Version Watch (cron 6ч) → Gitea issue (label: update-available) + Telegram
|
||||
Grafana rules: диск >85% (node_exporter); cert-check.sh: TLS <14 дней → алерт.
|
||||
Приёмка: тестовые алерты по диску и сертификату получены в Telegram.
|
||||
|
||||
- [ ] F6-7: Ретроспектива + runbook'и + baseline v1.4
|
||||
- [x] F6-7: Ретроспектива + runbook'и + baseline v1.4
|
||||
Runbook'и: update-manager, user-provisioning. Закрытие чек-листа.
|
||||
Приёмка: тег v1.4 в Gitea, документация в репо.
|
||||
|
||||
|
||||
@@ -0,0 +1,176 @@
|
||||
# Runbook: наблюдение за инфраструктурой
|
||||
|
||||
**Относится к:** F6-6 (проактивный мониторинг), контроль пула томов
|
||||
**Расположение:** pve, `/opt/buryan-hub/scripts/`, расписания в `/etc/cron.d/`
|
||||
|
||||
---
|
||||
|
||||
## 1. Что и как часто проверяется
|
||||
|
||||
| Проверка | Скрипт | Как часто | Порог |
|
||||
|---|---|---|---|
|
||||
| Пул томов | `check_thin_pool.py` | каждые 5 минут | 75% предупреждение |
|
||||
| Диски гостей и хоста | `check_disk.py` | ежечасно | 85% / 92% |
|
||||
| Сроки сертификатов | `check_certs.py` | ежедневно в 08:30 | 14 / 7 дней |
|
||||
| Ночной отчёт об обновлениях | `nightly-report.sh` | ежедневно в 03:05 | — |
|
||||
|
||||
Расписания: `/etc/cron.d/buryan-monitor` и `/etc/cron.d/buryan-monitoring`.
|
||||
Пароль базы — в `/root/.buryan-monitor.env` (права 600), **не в файлах расписания**.
|
||||
|
||||
Уведомления шлёт бот аварий `@Buryans_AlertBot` в чат владельца.
|
||||
|
||||
---
|
||||
|
||||
## 2. Как устроены уведомления
|
||||
|
||||
- **Переход через порог** — сообщение.
|
||||
- **Возврат в норму** — сообщение о восстановлении.
|
||||
- **Повтор в том же состоянии** — молчание до суток, чтобы не заваливать чат.
|
||||
- Если порог перешли несколько точек, приходит **одно сообщение со списком**,
|
||||
а не по сообщению на каждую.
|
||||
|
||||
Состояние хранится в `/var/lib/buryan-monitor/`:
|
||||
|
||||
```
|
||||
disk-state.json cert-state.json last-alert.json
|
||||
```
|
||||
|
||||
Удаление файла состояния сбрасывает память: следующая тревога придёт сразу.
|
||||
Это полезно при проверке, но не делайте так без причины.
|
||||
|
||||
---
|
||||
|
||||
## 3. Проверка, что оповещения работают
|
||||
|
||||
Запустить с заниженным порогом — тревога должна прийти в Telegram:
|
||||
|
||||
```bash
|
||||
. /root/.buryan-monitor.env
|
||||
|
||||
# диски: тревога по всем, кто выше 50%
|
||||
THRESH_WARN=50 python3 /opt/buryan-hub/scripts/check_disk.py
|
||||
|
||||
# сертификаты: тревога по всем, у кого меньше 90 дней
|
||||
THRESH_WARN_DAYS=90 python3 /opt/buryan-hub/scripts/check_certs.py
|
||||
|
||||
# вернуть нормальные пороги и сбросить память о ложной тревоге
|
||||
rm -f /var/lib/buryan-monitor/disk-state.json /var/lib/buryan-monitor/cert-state.json
|
||||
python3 /opt/buryan-hub/scripts/check_disk.py
|
||||
python3 /opt/buryan-hub/scripts/check_certs.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Сбор метрик
|
||||
|
||||
Prometheus (CT 134) собирает данные со сборщиков `node_exporter` во всех гостях.
|
||||
|
||||
```bash
|
||||
# сколько целей и все ли отвечают
|
||||
curl -s 'http://192.168.1.134:9090/api/v1/targets?state=active' \
|
||||
| jq -r '[.data.activeTargets[] | .health] | group_by(.) | map({(.[0]): length}) | add'
|
||||
# ожидается: {"up": 29}
|
||||
```
|
||||
|
||||
**14.10.2026 выяснилось, что Prometheus собирал данные только с себя** — одна
|
||||
цель из двадцати девяти, при том что сборщики работали везде. Конфигурация
|
||||
пересобирается скриптом:
|
||||
|
||||
```bash
|
||||
bash /opt/buryan-hub/scripts/prometheus-targets.sh
|
||||
```
|
||||
|
||||
Запускать после добавления или удаления гостя: список адресов берётся из живых
|
||||
контейнеров.
|
||||
|
||||
**Важно:** Prometheus сам уведомления не отправляет — для этого нужен
|
||||
Alertmanager, которого нет. Уведомления шлют скрипты. Prometheus даёт историю
|
||||
и графики.
|
||||
|
||||
---
|
||||
|
||||
## 5. История замеров
|
||||
|
||||
```bash
|
||||
psql -h 192.168.1.151 -U buryan_monitor -d buryan_monitoring <<'SQL'
|
||||
-- что растёт быстрее всего
|
||||
SELECT guest_key, guest_title, now_pct, day_ago_pct,
|
||||
now_pct - day_ago_pct AS рост
|
||||
FROM disk_growth
|
||||
ORDER BY рост DESC NULLS LAST
|
||||
LIMIT 10;
|
||||
|
||||
-- сколько осталось сертификатам
|
||||
SELECT domain, days_left FROM cert_metrics
|
||||
WHERE collected_at > now() - interval '2 days'
|
||||
ORDER BY days_left LIMIT 10;
|
||||
SQL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Что делать при срабатывании
|
||||
|
||||
### Диск заполнен
|
||||
|
||||
Порядок действий — от самого частого к самому редкому:
|
||||
|
||||
```bash
|
||||
# 1. разросшиеся логи контейнеров (самая частая причина)
|
||||
bash /opt/buryan-hub/scripts/fix-logs.sh
|
||||
|
||||
# 2. старые образы Docker
|
||||
pct exec <CT> -- docker system prune -a
|
||||
|
||||
# 3. расширить диск, если данные действительно нужны
|
||||
pct resize <CT> rootfs +4G
|
||||
```
|
||||
|
||||
**14.10.2026:** в CT 110 один лог контейнера разросся до 3,9 ГБ и заполнил диск
|
||||
на 87%. Причина — в `daemon.json` не были заданы ограничения на размер логов.
|
||||
Ограничения прописаны во всех 26 контейнерах, ежедневная уборка поставлена
|
||||
в `/etc/cron.d/buryan-log-hygiene`.
|
||||
|
||||
### Пул томов заполнен
|
||||
|
||||
```bash
|
||||
lvs -o lv_name,data_percent | grep data
|
||||
fstrim -v /mnt/backups
|
||||
for id in $(pct list | awk 'NR>1{print $1}'); do pct fstrim $id; done
|
||||
```
|
||||
|
||||
Проверить, не осталось ли снимков от обновлений — они занимают место и должны
|
||||
удаляться сами:
|
||||
|
||||
```bash
|
||||
for id in $(pct list | awk 'NR>1{print $1}'); do
|
||||
pct listsnapshot "$id" | grep pre-update && echo " ^ CT $id"
|
||||
done
|
||||
```
|
||||
|
||||
### Сертификат истекает
|
||||
|
||||
Продлением занимается обратный прокси (CT 101, контейнер `npm-app-1`):
|
||||
|
||||
```bash
|
||||
pct exec 101 -- docker exec npm-app-1 certbot renew --dry-run
|
||||
```
|
||||
|
||||
Проверка читает **настоящий сертификат, отдаваемый по домену**, а не файл на
|
||||
диске — поэтому ловит случай, когда файл обновился, а прокси его не подхватил.
|
||||
|
||||
---
|
||||
|
||||
## 7. Принцип, который дорого дался
|
||||
|
||||
**Проверять надо результат, а не факт выполнения команды.**
|
||||
|
||||
За один день 14.10.2026 три разных механизма сообщали об успехе, ничего не сделав:
|
||||
|
||||
- `curl` возвращает код 0 даже при ошибке сервера — запись «задача создана»
|
||||
появлялась, когда задача не создавалась;
|
||||
- проверка здоровья проходила при старом образе — сервис жив, но версия не та;
|
||||
- в журнале писалось «ГОТОВО» при отсутствии обновления.
|
||||
|
||||
Поэтому у каждой проверки должно быть подтверждение: новый образ совпадает
|
||||
со скачанным, в базе появилась запись, файл состояния изменился.
|
||||
@@ -1 +1,206 @@
|
||||
✅ F6-1 полностью закрыт и задокументирован!cat
|
||||
# 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> <имя-снимка>
|
||||
```
|
||||
@@ -0,0 +1,144 @@
|
||||
# Runbook: выдача доступов новому пользователю
|
||||
|
||||
**Относится к:** F6-2 (Self-Service Registration)
|
||||
**Расположение:** n8n (CT 108), workflow `F6-2: Self-Service Registration` (id `dDhihSKtoZ4EE9jV`)
|
||||
|
||||
---
|
||||
|
||||
## 1. Как это устроено
|
||||
|
||||
```
|
||||
Заявка (форма) ──POST──▶ /webhook/register-request
|
||||
│
|
||||
▼
|
||||
уведомление владельцу в Telegram
|
||||
через бота доступов @Auth_buryans_bot
|
||||
│
|
||||
владелец нажимает «Одобрить» / «Отклонить»
|
||||
│
|
||||
▼
|
||||
/webhook/tg-callback (вебхук того же бота)
|
||||
│
|
||||
┌─────────┴─────────┐
|
||||
▼ ▼
|
||||
Одобрено: создаём Отклонено: сообщаем
|
||||
пользователя в Authentik владельцу
|
||||
+ ссылка на вход (24 ч)
|
||||
```
|
||||
|
||||
**Ключевая деталь:** заявку обрабатывает **бот доступов**, потому что именно он
|
||||
отправляет уведомление. Кнопки работают только у того бота, который получает
|
||||
обновления. У `@Auth_buryans_bot` стоит вебхук:
|
||||
|
||||
```
|
||||
https://n8n.buryans.ru/webhook/tg-callback
|
||||
```
|
||||
|
||||
Если этот вебхук слетит — кнопки одобрения перестанут работать, при этом форма
|
||||
продолжит принимать заявки.
|
||||
|
||||
---
|
||||
|
||||
## 2. Порядок действий владельца
|
||||
|
||||
1. Пользователь заполняет форму заявки.
|
||||
2. Владельцу приходит сообщение в Telegram от `@Auth_buryans_bot`.
|
||||
3. Владелец нажимает «Одобрить».
|
||||
4. В Authentik создаётся пользователь, приходит ссылка на вход (действует 24 часа).
|
||||
5. Владелец передаёт ссылку пользователю.
|
||||
6. Создаётся задача в Gitea с записью о выдаче доступа.
|
||||
|
||||
---
|
||||
|
||||
## 3. Проверка, что система жива
|
||||
|
||||
```bash
|
||||
# workflow существует и включён
|
||||
pct exec 108 -- docker exec n8n n8n list:workflow | grep 'F6-2'
|
||||
|
||||
# вебхук бота доступов на месте
|
||||
AUTH=$(grep -m1 AUTH_TOKEN /root/bots-tokens.env | cut -d= -f2)
|
||||
curl -s -x http://192.168.1.10:10888 \
|
||||
"https://api.telegram.org/bot${AUTH}/getWebhookInfo" | jq -r '.result.url'
|
||||
# ожидается: https://n8n.buryans.ru/webhook/tg-callback
|
||||
|
||||
# сам вебхук отвечает (не 404)
|
||||
curl -s -o /dev/null -w '%{http_code}\n' -X POST \
|
||||
https://n8n.buryans.ru/webhook/tg-callback -d '{}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Что ломается
|
||||
|
||||
### Кнопки одобрения не работают
|
||||
|
||||
**Причина первая:** вебхук снят с бота доступов. Проверить командой выше.
|
||||
Вернуть:
|
||||
|
||||
```bash
|
||||
AUTH=$(grep -m1 AUTH_TOKEN /root/bots-tokens.env | cut -d= -f2)
|
||||
curl -s -x http://192.168.1.10:10888 -X POST \
|
||||
"https://api.telegram.org/bot${AUTH}/setWebhook" \
|
||||
-d 'url=https://n8n.buryans.ru/webhook/tg-callback' \
|
||||
-d 'allowed_updates=["message","callback_query"]'
|
||||
```
|
||||
|
||||
**Причина вторая:** бот доступов начали опрашивать вместо вебхука.
|
||||
Опрос и вебхук несовместимы — Telegram отдаёт обновления только одним способом.
|
||||
Проверить, кто опрашивает:
|
||||
|
||||
```bash
|
||||
pct exec 108 -- docker logs --tail 100 tg-admin-bot | grep -i 'polling\|Бот @'
|
||||
```
|
||||
|
||||
Бот `@Adm_buryans_bot` (администратор) опрашивается намеренно, у него вебхука
|
||||
быть не должно. Бот доступов — наоборот: только вебхук.
|
||||
|
||||
**Причина третья:** ошибка `TelegramConflictError: terminated by other getUpdates`.
|
||||
Значит, один и тот же бот и опрашивается, и имеет вебхук.
|
||||
|
||||
### Форма принимает заявку, но уведомление не приходит
|
||||
|
||||
Проверить журнал n8n:
|
||||
|
||||
```bash
|
||||
pct exec 108 -- docker exec n8n n8n list:workflow | grep F6-2
|
||||
pct exec 108 -- docker logs --tail 50 n8n | grep -i 'register-request'
|
||||
```
|
||||
|
||||
### Пользователь создан, но войти не может
|
||||
|
||||
Ссылка на вход действует **24 часа**. Если истекла — создать заново:
|
||||
|
||||
```bash
|
||||
# в Authentik: Directory → Users → <пользователь> → Set password / Enrollment
|
||||
# либо через API, тем же способом, что и workflow
|
||||
```
|
||||
|
||||
Проверить, что пользователь есть и в нужных группах:
|
||||
|
||||
```bash
|
||||
curl -s -H "Authorization: Bearer <токен Authentik>" \
|
||||
'http://192.168.1.114:9000/api/v3/core/users/?search=<логин>' | jq
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Учётные записи и роли
|
||||
|
||||
Боты и их назначение — в `docs/BOTS.md`. Там же правило: **один бот — одна роль —
|
||||
одно место хранения токена.** Токены лежат в `/root/bots-tokens.env` (права 600)
|
||||
и в `D:\Buryans Hub\bots\` на закрытом компьютере. В Git токены не попадают.
|
||||
|
||||
Учётные данные Authentik для workflow — в самом n8n, а не в файлах репозитория.
|
||||
Действующий токен, записанный прямо в теле workflow, — это утечка, такие случаи
|
||||
перечислены в `docs/SECRETS-ROTATION-PLAN.md`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Связанные документы
|
||||
|
||||
- `docs/BOTS.md` — роли ботов и правила хранения токенов
|
||||
- `docs/SECRETS-ROTATION-PLAN.md` — план смены секретов
|
||||
- `ops/runbooks/update-manager.md` — система обновлений
|
||||
Reference in new issue
Block a user