Files
buryan-infra/docs/NIGHT-JOURNAL.md
T

490 lines
30 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.
# Журнал ночного спринта
**Начат:** 2026-10-14
**Принцип:** «сделано» означает «проверено». Каждая запись содержит
не «команда выполнена», а **чем подтверждён результат**.
**При остановке** (лимит, ошибка, стоп-условие) состояние таково:
всё со статусом ✅ работает, всё со статусом ⬜ не тронуто.
Незавершённых «наполовину» состояний быть не должно.
---
## Статусы
| Знак | Значение |
|---|---|
| ⬜ | не начато |
| 🔄 | выполняется |
| ✅ | **проверено** — результат подтверждён |
| ⏸ | отложено (требует решения владельца) |
| ❌ | не удалось, откачено |
---
## Этап 1. Уборка безопасного
| # | Что | Статус | Подтверждение |
|---|---|---|---|
| 1.1 | Мёртвые файловые базы n8n и mealie (99 МБ) | ✅ | карантин, размеры совпали: 102998016 и 1331200 байт; источник убран |
| 1.2 | Осиротевшая база `gitea` в PostgreSQL (30 МБ) | ✅ | выгрузка 112 таблиц, база удалена |
| 1.3 | Старый кластер PostgreSQL 14 (381 МБ) | ✅ | выгрузка 14 баз / 1012 таблиц / 323688 строк проверена; все базы есть в рабочем; кластер удалён, освобождено 500 МБ |
## Этап 2. Кодировка: образец
| # | Что | Статус | Подтверждение |
|---|---|---|---|
| 2.1 | `buryan_monitoring` → UTF8 + ICU ru-RU | ✅ | длина «Привет» 6, upper ПРИВЕТ, сортировка true; права выданы явно; бот пишет |
## Этап 3. Кодировка: остальные базы
| # | База | Размер | Статус | Подтверждение |
|---|---|---|---|---|
| 3.1 | headscale | 8 МБ | ✅ | был UTF8 изначально |
| 3.2 | authentik | 8 МБ | ✅ | состав таблиц совпал, русский текст проверен |
| 3.3 | buryan_hub | 8 МБ | ✅ | состав таблиц совпал, русский текст проверен |
| 3.4 | buryan_monitor | 8 МБ | ✅ | состав таблиц совпал, русский текст проверен |
| 3.5 | authentik_db | 25 МБ | ✅ | состав таблиц совпал, русский текст проверен |
| 3.6 | gitea | 30 МБ | ⏸ | переносится на этапе 6 |
| 3.7 | firefly_db | 11 МБ | ✅ | состав таблиц совпал, русский текст проверен |
| 3.8 | mealie_db | 12 МБ | ✅ | состав таблиц совпал, русский текст проверен |
| 3.9 | nextcloud_db | 17 МБ | ✅ | состав таблиц совпал, русский текст проверен |
| 3.10 | paperless_db | 20 МБ | ✅ | состав таблиц совпал, русский текст проверен |
| 3.11 | n8n_prod | 14 МБ | ✅ | состав таблиц совпал, русский текст проверен |
| 3.12 | n8n_central | 17 МБ | ✅ | состав таблиц совпал, русский текст проверен |
| 3.13 | n8n | 87 МБ | ✅ | состав таблиц совпал, русский текст проверен |
| 3.14 | immich_db | 95 МБ | ⏸ | требует доступа к виртуальной машине либо вашего решения |
## Этап 4. Перенос файловых баз
| # | Сервис | Размер | Статус | Подтверждение |
|---|---|---|---|---|
| 4.1 | Vaultwarden | 288 КБ | ⬜ | — |
| 4.2 | Grafana | 1,5 МБ | ⬜ | — |
| 4.3 | Sonarr | 3,2 МБ | ⬜ | — |
| 4.4 | Radarr | 2,0 МБ | ⬜ | — |
| 4.5 | Prowlarr | 368 КБ | ⬜ | — |
| 4.6 | Bazarr | 364 КБ | ⬜ | — |
## Этап 5. Двойной Paperless
| # | Что | Статус | Подтверждение |
|---|---|---|---|
| 5.1 | Разбор двух развёртываний | ⬜ | — |
| 5.2 | Перенос оставшегося экземпляра | ⬜ | — |
## Этап 6. Gitea
| # | Что | Статус | Подтверждение |
|---|---|---|---|
| 6.1 | Выгрузка и снимок | ⬜ | — |
| 6.2 | Перенос базы на UTF8 | ⬜ | — |
| 6.3 | Проверка: репозитории, пользователи, вход | ⬜ | — |
## Этап 7. Uptime Kuma
| # | Что | Статус | Подтверждение |
|---|---|---|---|
| 7.1 | Перенос 160 МБ | ⬜ | — |
## Этап 8. Проверка восстановления
| # | Что | Статус | Подтверждение |
|---|---|---|---|
| 8.1 | Восстановление копии базы и сверка | ⬜ | — |
## Этап 9. Отчёт
| # | Что | Статус | Подтверждение |
|---|---|---|---|
| 9.1 | Итоговый отчёт | ⬜ | — |
---
## Журнал событий
Записи добавляются по ходу, после каждого значимого шага.
```
[начало] Аудит завершён: откат проверен по трём механизмам.
Пул 36,5%, копии целы, 28 сервисов без замечаний.
```
[19:42:29] buryan_hub ->
[19:42:42] buryan_monitor ->
[19:43:27] firefly_db ->
[19:43:43] mealie_db ->
[19:44:25] nextcloud_db -> UTF8=UTF8
[19:45:00] paperless_db -> UTF8=UTF8
[19:45:25] n8n_prod -> UTF8=UTF8
[19:45:39] n8n_central -> UTF8=UTF8
[19:45:56] n8n -> UTF8=UTF8
[19:46:45] authentik_db переведена
[19:46:56] authentik переведена
```
[19:34] Этап 1 завершён. Карантин: n8n 98 МБ, mealie 1,3 МБ, осиротевшая gitea,
выгрузка кластера 14. Освобождено 500 МБ в контейнере баз.
[19:36] ЭТАП 2, ПЕРВАЯ ПОПЫТКА — ОШИБКА.
Имя для старой базы содержало дефис, PostgreSQL прочитал его как
вычитание, переименование не произошло. Я поверил выводу команды
вместо проверки каталога, и загрузка пошла в ту же базу.
Данные НЕ пострадали (56 сообщений «уже существует»).
Урок: проверять результат по каталогу, а не по выводу команды.
[19:37] ЭТАП 2 ИСПРАВЛЕН И ЗАВЕРШЁН.
buryan_monitoring переведена: длина «Привет» 6, upper ПРИВЕТ,
сортировка true. Но обнаружено, что локаль C недостаточна:
регистр и сортировка для русского не работают. Проверены варианты
на тестовых базах, выбран ICU ru-RU.
[19:40] ОБНАРУЖЕНА ПОТЕРЯ ПРАВ У БОТА после пересоздания базы.
Восстановление по снимку information_schema оказалось неполным.
Исправлено: права выдаются ЯВНО на всю схему, а не по снимку.
[19:41-19:46] ЭТАП 3. Переведены 12 баз, каждая с проверкой состава таблиц
и русского текста. Службы останавливались на время переноса
и запускались обратно.
[19:47] ОБНАРУЖЕНО: у 10 баз потерян владелец — при пересоздании
я назначал владельцем postgres вместо роли сервиса.
Проявилось на Authentik: воркер не смог применить миграцию.
Исправлено: владельцы возвращены из копий до переноса.
[19:51] ЭТАП 3 ПРОВЕРЕН:
— 15 баз из 17 переведены на UTF8 с русской локалью;
— владельцы восстановлены у всех;
— Authentik: сервер и воркер 200;
— n8n, Nextcloud, Mealie, Paperless, Firefly работают;
— запись от исполнителя обновлений и от бота проходит;
— мониторинг: 29 из 29 целей.
Остались: immich_db (виртуалка, нужен доступ или решение владельца)
и служебная postgres.
```
## Найденные дефекты процесса
| # | Что | Как обнаружен | Исправление |
|---|---|---|---|
| 1 | Дефис в имени базы ломает переименование | сработала проверка состава таблиц | имена без дефисов + проверка по каталогу |
| 2 | Восстановление прав по снимку неполное | бот не смог записать | права выдаются явно на всю схему |
| 3 | Владелец базы теряется при пересоздании | воркер Authentik не запустился | владелец берётся из копии |
| 4 | Локаль C недостаточна для русского | проверка регистра и сортировки | ICU ru-RU |
[19:52:34] postgres переведена
[19:52:35] immich: требуется доступ к виртуалке или решение владельца
[19:52:40] проверка восстановления: таблицы 9=9, очередь 6=6 — совпало
---
## Случай: ложный успех в моей собственной проверке (Grafana)
**Что делалось.** Образец переноса файловой базы Grafana в PostgreSQL —
отработка метода на сервисе с низкой ценой ошибки.
**Точка отката была создана и сработала:**
- снимок контейнера `pre-grafana-pg-20261014_201346`;
- копия файловой базы в карантине (132 КБ, архив проверен);
- копия конфигурации до правок.
**Что произошло.** Скрипт получил список таблиц файловой базы — и он
оказался **пустым**, потому что в CT 113 не установлен `sqlite3`.
Дальше проверка полноты сравнила ноль строк с нулём строк по нулю таблиц
и **сообщила: «ПЕРЕНОС ПОЛНЫЙ, все таблицы совпадают»**.
```
таблиц: 0
таблиц загружено: 0, с ошибками: 0
совпало таблиц: 0, расхождений: 0
✅ ПЕРЕНОС ПОЛНЫЙ
```
**Это тот же ложный успех, который мы весь день ищем** — только теперь
в моём собственном коде: проверка проходит, когда проверять нечего.
**Что спасло.** Я посмотрел на цифры, а не на галочку: ноль таблиц при
заявленном успехе — противоречие. Дальнейшая проверка показала, что
Grafana действительно подключилась к PostgreSQL (4 соединения от
192.168.1.113), выполнила свои миграции, но схема осталась пустой.
**Возврат выполнен полностью:**
- конфигурация восстановлена из копии;
- контейнер пересоздан;
- проверено: health `ok`, **5 дэшбордов на месте**, файловая база цела
(1,5 МБ), переменных базы в контейнере — 0;
- тестовая база и роль удалены из PostgreSQL.
**Вывод, который надо закрепить в правилах:**
> Если сравнивать нечего — это ОШИБКА, а не успех.
> Проверка обязана падать, когда список проверяемых объектов пуст.
**Что исправлено:**
1. в проверку полноты добавлено условие: пустой список объектов — провал;
2. перед переносом проверяется наличие инструментов чтения файловой базы;
3. в точку отката добавлена запись контрольной суммы файловой базы,
чтобы после возврата доказать, что файл не изменился.
**Состояние Grafana:** работает как прежде, на файловой базе, данные целы.
---
## Образец переноса Grafana: результат
**Попыток: три. Итог: возврат к файловой базе, данные целы.**
### Что выяснилось по ходу
| # | Препятствие | Суть |
|---|---|---|
| 1 | Проверка выдала ложный успех | список таблиц был пуст (нет `sqlite3`), сравнение пустоты прошло как успех |
| 2 | Файлы данных не видны из контейнера баз | CSV создавались на хосте, `psql` работает внутри контейнера |
| 3 | Служба создаёт начальные записи | Grafana при первом запуске создаёт роли, организацию, пользователя — они конфликтуют с переносимыми по уникальным ключам |
| 4 | **Двоичные данные** | `cache_data` и `data_keys` не проходят как текст: `invalid byte sequence for encoding UTF8` |
| 5 | **Схема Grafana 12 не совпадает с файловой** | дэшборды живут в таблице `resource` (единое хранилище), а не в `dashboard` |
### Итог проверки полноты
```
таблиц совпало: 22
расхождений: 8 — включая user (1 вместо 2), resource (0 вместо 1),
data_keys (0 вместо 9 — ключи шифрования)
```
**Частичный перенос опаснее отказа:** служба запускается, но данные потеряны.
Поэтому выполнен **возврат**:
- конфигурация восстановлена, упоминаний PostgreSQL — 0;
- контейнер пересоздан, health `ok`;
- **5 дэшбордов и 5 пользователей на месте**;
- файловая база используется, данные целы;
- тестовая база и роль удалены из PostgreSQL.
### Вывод для дальнейшей работы
Перенос Grafana **возможен, но требует отдельной проработки** трёх вещей:
1. **двоичные данные** — выгружать не как CSV, а как шестнадцатеричные литералы
(`X'...'` в SQLite → `'\x...'::bytea` в PostgreSQL);
2. **начальные записи службы** — очищать таблицы после создания схемы
и до загрузки, при этом не запуская службу между очисткой и загрузкой;
3. **несовпадение схемы** — версия Grafana 12 хранит дэшборды в едином
хранилище (`resource`, `resource_history`), копирование только таблицы
`dashboard` не даёт результата.
Это не тупик, а конкретный список работ. Тот же список нужно составить
для каждого следующего сервиса **до** попытки переноса.
---
## ✅ ПЕРЕНОС GRAFANA ЗАВЕРШЁН (15.10.2026)
**Результат:** Grafana работает на центральной PostgreSQL.
```
таблиц с данными: 28 из 28 — совпали по числу строк
ошибок загрузки: 0
двоичные ключи: 9 из 9, содержимое совпадает ПОБАЙТОВО (52 байта)
дэшборды: 5 пользователи: 5 источники: 5
подключений к PostgreSQL от Grafana: 4
```
### Как проверялось
Не «служба запустилась», а четыре независимые проверки:
1. **Число строк по каждой таблице** — 28 таблиц, расхождений нет.
2. **Содержимое двоичных полей** — 9 ключей шифрования сверены побайтово
с файловой базой.
3. **Данные внутри базы** — в таблице `resource` лежит дэшборд
`buryan-health` вместе с содержимым (`{"kind":"Dashboard",...}`).
4. **Подключения** — 4 соединения от 192.168.1.113 под ролью `grafana_user`.
Отдельно отмечу: API Grafana возвращает имена дэшбордов пустыми, потому что
запрос идёт без входа. Это свойство API, а не потеря данных — содержимое
проверено напрямую в базе.
### Четыре ошибки, найденные и исправленные по ходу
| # | Ошибка | Как проявилась |
|---|---|---|
| 1 | Пустой файл команд засчитан как загрузка | `psql` на пустом файле возвращает успех |
| 2 | Сдвиг полей при разборе строки средствами bash | scope получал значение active; генерацию перевели на awk |
| 3 | Выражение выборки начиналось с разделителя | «SELECT || coalesce(...)» — синтаксическая ошибка |
| 4 | **Несовпадение типов** | в файловой базе `active` целое 0/1, PostgreSQL создаёт его ЛОГИЧЕСКИМ; типы теперь берутся из PostgreSQL |
| 5 | Одинарные кавычки для имён столбцов | в SQL имена требуют двойных |
| 6 | `grep -c` возвращает код 1 при нуле совпадений | «\|\| echo 0» добавлял второй ноль, и вердикт ложно проваливался при успешной загрузке |
### Главное открытие метода
**Контейнер службы нужно УДАЛЯТЬ на время загрузки, а не просто
останавливать.** Проверка «служба остановлена» показывала `exited`, но
Grafana поднималась снова и перезаписывала перенос своими начальными
данными: роли 115 → 7, пользователь 2 → 1. Пока контейнера нет — писать
некому, и совпадение стало 28 из 28.
### Исправленные инструменты (в ops/scripts)
- `migrate-grafana-v2.sh` — перенос со всеми предохранителями;
- `load-blob-table.sh` — загрузка таблиц с двоичными полями,
с учётом типов PostgreSQL и побайтовой сверкой.
### Порядок для следующих сервисов (проверен на Grafana)
1. Разведка: таблицы, строки, **двоичные поля**, где лежат ключевые данные.
2. Точка отката: снимок, копия базы, копия конфигурации.
3. Дать службе создать схему в PostgreSQL.
4. **Удалить контейнер**, очистить таблицы, не давая службе перезапуститься.
5. Загрузить: текст — через CSV, двоичные — через hex с учётом типов.
6. Проверять: число строк по каждой таблице, содержимое двоичных полей.
7. Запустить службу, проверить через API и напрямую в базе.
---
## ✅ ПЕРЕНОС МЕДИА-СЕРВИСОВ ЗАВЕРШЁН (15.10.2026)
**Prowlarr, Sonarr, Radarr переведены на центральную PostgreSQL.**
| Сервис | Совпало таблиц | Ключевые данные | Версия через API |
|---|---|---|---|
| Prowlarr | **6 из 6** | без расхождений | 2.6.5.5623 |
| Sonarr | 9 из 10 | SceneMappings 15 992 = 15 992 | 4.0.20.3014 |
| Radarr | 9 из 10 | QualityDefinitions 30 = 30 | 6.4.4.10685 |
Расхождение только в служебной таблице `Commands` — служба обрабатывает
её на ходу. Отсутствие сериалов и фильмов — **не потеря**: в файловых
базах их тоже ноль, службы просто не были наполнены.
### Главное, что выяснилось
**У медиа-сервисов нельзя очищать таблицу версий миграций (`VersionInfo`).**
Первая попытка выглядела успешной по числу строк, но все три службы
падали при запуске:
```
FluentMigrator ... MigrationController.Migrate
DbFactory.CreateMain — Non-recoverable failure, waiting for user intervention
```
Служба по таблице `VersionInfo` понимает, какие миграции уже применены.
После её очистки служба пыталась применить миграции заново и падала,
потому что таблицы уже существуют. **Схему ведёт FluentMigrator, и его
служебные таблицы очищать нельзя** — в отличие от Grafana, где служба
пересоздаёт состояние сама.
### Вторая находка: остатки обновлений держат порты
Prowlarr не мог запуститься, потому что порт 9696 занимал контейнер
`prowlarr-old-20261014-175122` — временный контейнер от вчерашнего
обновления, который должен был удалиться после проверки.
Во флоте таких нашлось **13** (calibre-web, freshrss, openclaw, plex,
sonarr, radarr, prowlarr, bazarr, overseerr, tautulli, navidrome, linkding,
prometheus, syncthing). Работающие остановлены — порты освобождены.
**Это дефект механизма обновления:** временный контейнер нужно
останавливать сразу после успешной проверки новой версии.
### Третья находка: проверка «контейнер запущен» бесполезна
Первая попытка объявила успех по состоянию контейнера, а приложения
внутри падали. Теперь проверка обязательно включает **ответ через API**:
версия читается — значит, приложение действительно работает.
### Инструмент
`ops/scripts/migrate-arr.sh` — перенос медиа-сервисов: точка отката,
разведка, схема от службы, удаление контейнера, загрузка с сохранением
таблиц миграций, проверка по каждой таблице.
---
## ✅ VAULTWARDEN ПЕРЕНЕСЁН НА POSTGRESQL (15.10.2026)
**Хранилище паролей переведено на центральную PostgreSQL.**
```
пользователи: 2
записи хранилища: 12
устройства: 6
подключений к PostgreSQL: 4 (роль vaultwarden_user, 192.168.1.109)
служба: 200, страница входа отвечает
```
### Как проверялось
Не «контейнер запущен», а сверка содержимого:
| Проверка | Результат |
|---|---|
| Хеши паролей (2 пользователя) | **совпадают** по 64 знака |
| Соли | **совпадают** по 128 знаков |
| Размер каждой из 12 записей | **совпадает байт в байт** |
| Суммарный объём записей | файл 7715 = база 7715 |
| Файловая база | не изменялась с 12.10 — запись идёт в PostgreSQL |
Хранилище зашифровано на стороне клиента, поэтому записи проверены
по объёму и количеству — прочитать их нельзя ни у меня, ни на сервере.
### Четыре препятствия и что они дали
| # | Препятствие | Суть |
|---|---|---|
| 1 | Переменная попала не в ту службу | в файле четыре службы (db, nextcloud, vaultwarden, files_net), а вставка шла в первый блок environment — у службы db. Переменная теперь ставится **строго по имени службы** |
| 2 | Проверка связей между таблицами | `ciphers` ссылается на `users`, и при неудаче `users` валилось всё зависимое. Теперь при загрузке `session_replication_role = replica` — порядок загрузки перестал быть важен |
| 3 | Ложное расхождение по ключу | сверка искала строку по столбцу `name`, которого в `users` нет — ключ называется `uuid`. Данные были на месте, а проверка сообщала о потере. Теперь ключевой столбец берётся из первичного ключа |
| 4 | Ложное расхождение по регистру | `hex()` в файловой базе даёт ЗАГЛАВНЫЕ буквы, `encode(...,'hex')` в PostgreSQL — строчные. Сравнение идёт в одном регистре |
**Три из четырёх — это ошибки проверки, а не переноса.** Данные
переносились правильно, а инструмент сообщал о потере. Отсюда правило:
если проверка говорит о расхождении, сначала проверь саму проверку.
### Правило о служебных таблицах (уточнено)
Служебные таблицы версий миграций **сохраняются** при очистке:
| Служба | Таблица |
|---|---|
| Vaultwarden | `__diesel_schema_migrations` |
| Sonarr, Radarr, Prowlarr | `VersionInfo` |
| Paperless, Bazarr | `alembic_version` |
Их нельзя ни очищать, ни переносить: по ним служба понимает, какие
миграции уже применены.
---
## ✅ BAZARR ПЕРЕНЕСЁН НА POSTGRESQL (15.10.2026)
```
таблиц с данными: 3 из 3 — совпали
настройки языков: 187
настройки увеличений: 129
ответ службы: 200
```
Bazarr переключается флагом `postgresql.enabled` в `config.yaml`.
Схему создаёт сам через Alembic; её служебная таблица `alembic_version`
сохранена, как и положено.
### Пятое правило проверки
**Состояние контейнера «running» не означает готовности службы.**
Bazarr (Python/waitress) поднимает веб-сервер через 60–90 секунд, и первая
попытка была откачена из-за ложного отказа: контейнер работал, а служба
ещё не отвечала. Теперь готовность определяется **ответом 200**, а не
статусом контейнера.
Общий список правил проверки, накопленный за спринт:
| # | Правило | На чём выяснено |
|---|---|---|
| 1 | Пустой список объектов — это ПРОВАЛ, а не успех | Grafana: сравнили пустоту с пустотой |
| 2 | Проверять результат по каталогу, а не вывод команды | переименование базы с дефисом |
| 3 | Контейнер службы УДАЛЯТЬ на время загрузки | Grafana перезаписывала перенос |
| 4 | Таблицы миграций не очищать и не переносить | *arr: падение FluentMigrator |
| 5 | Готовность = ответ службы, а не статус контейнера | Bazarr: 60–90 секунд до ответа |
| 6 | Ключевой столбец брать из первичного ключа | Vaultwarden: сверка искала `name` |
| 7 | Сравнивать в одном регистре | Vaultwarden: `hex` против `encode` |
| 8 | Расхождение — сначала проверь саму проверку | три ложных расхождения за спринт |