diff --git a/docs/DATABASE-STANDARD.md b/docs/DATABASE-STANDARD.md new file mode 100644 index 0000000..801e79d --- /dev/null +++ b/docs/DATABASE-STANDARD.md @@ -0,0 +1,175 @@ +# Стандарт баз данных + +**Создан:** 2026-10-14 +**Относится к:** централизация данных в CT 151 (задача №128) +**Статус:** действует. Все новые базы создаются по этому стандарту. + +--- + +## 1. Зачем стандарт + +Сегодня данные проекта разбросаны: часть сервисов работает с центральной +PostgreSQL, часть держит собственные файловые базы. У центральной базы +кодировка `SQL_ASCII`, из-за чего русский текст сравнивается и сортируется +неправильно. Копия базы хранится в единственном экземпляре. + +Цель — **одно место хранения, одна схема именования, одна модель +обслуживания**. Сервисы остаются разными, но работа с данными у них +устроена одинаково. + +--- + +## 2. Кластер + +| Параметр | Значение | +|---|---| +| Расположение | CT 151, `postgres-rbac-lxc`, 192.168.1.151 | +| Версия | PostgreSQL **17** | +| Порт | 5432 | +| Кодировка | **UTF8** (обязательно) | +| Сравнение | `C` | + +**Один кластер.** Второй, версии 14, остановлен и подлежит разбору: он +остался от обновления версии и только путает. + +--- + +## 3. Именование + +| Что | Правило | Пример | +|---|---|---| +| База | `<сервис>_db` | `gitea_db`, `kuma_db` | +| Роль | `<сервис>_user` | `gitea_user`, `kuma_user` | +| Схема | стандартная `public`, отдельные схемы не создаём | — | +| Таблицы | отдаются приложению, мы их не переименовываем | — | + +**Одна база — один сервис.** Двух сервисов в одной базе быть не должно: +иначе нельзя ни восстановить по отдельности, ни выдать права точечно. + +**Исключения** (уже существуют, переименование дороже пользы): +`n8n`, `n8n_central`, `n8n_prod`, `gitea`, `headscale`, `authentik`, +`buryan_monitoring`, `buryan_monitor`, `buryan_hub`, `postgres`. + +--- + +## 4. Владелец и права + +1. Владелец базы — роль сервиса, **не `postgres`**. Иначе сервис не сможет + обслуживать свои таблицы, а `postgres` обрастает лишними правами. +2. Пароль хранится только в двух местах: в `.env` сервиса с правами 600 + и в Vaultwarden. В репозитории — никогда. +3. Проверка пароля — `scram-sha-256`. Устаревший `md5` выводим из употребления. +4. Доступ — **по адресу контейнера**, а не по всей подсети. Правило + `host all all 192.168.1.0/24 md5` будет заменено на точечные записи. +5. **Новая база — сразу права.** Бот и n8n ходят под ролью `n8n`, и таблицу, + созданную другим владельцем, они не увидят. Эта ошибка уже стоила вечера + 14.10.2026: кнопка одобрения обновлений молча не работала. + +```sql +-- шаблон создания базы сервиса +CREATE ROLE <сервис>_user LOGIN PASSWORD '<пароль>'; +CREATE DATABASE <сервис>_db OWNER <сервис>_user ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 'C' TEMPLATE template0; +``` + +--- + +## 5. Кодировка + +**Только UTF8.** Сейчас 15 баз из 18 имеют `SQL_ASCII`. Это не «почти то же +самое» — проверено на живой базе: + +``` +длина строки «Привет» = 12 (а должна быть 6) +upper('Привет') = 'Привет' (регистр не меняется) +``` + +При `SQL_ASCII` база хранит байты как есть: не проверяет кодировку, не +переводит регистр для кириллицы, неправильно сортирует и сравнивает +русский текст. Для проекта, где данные на русском, это дефект. + +**Порядок исправления:** выгрузка базы → создание новой с UTF8 → загрузка → +проверка сервиса → удаление старой. По одной базе, с проверкой. + +--- + +## 6. Резервное копирование + +| Требование | Как выполняется | +|---|---| +| Ежедневная выгрузка всех баз | `pg-backup-ct151.sh`, 02:00 | +| **Несколько копий, а не одна** | хранить 7 ежедневных и 4 недельных | +| Проверка годности копии | проверять целостность архива и наличие баз внутри | +| **Проверка восстановления** | раз в месяц разворачивать копию в отдельную базу и сверять число таблиц | +| Копия вне этого сервера | внешнее копирование + съёмный носитель | + +**Сегодня хранится одна копия.** Если она испортится, восстанавливать будет +не из чего. Это исправляется в первую очередь. + +Проверка копии обязательна: 14.10.2026 выяснилось, что «успешно созданные» +копии контейнеров две недели были пустыми, и никто этого не замечал. + +--- + +## 7. Что переносим и в каком порядке + +### Уже в центральной базе (18 баз) + +`immich_db`, `n8n`, `matrix_db`, `gitea`, `authentik_db`, `paperless_db`, +`nextcloud_db`, `n8n_central`, `buryan_monitoring`, `n8n_prod`, `mealie_db`, +`firefly_db`, `matrix_telegram_db`, `buryan_monitor`, `buryan_hub`, +`authentik`, `headscale`, `postgres` + +### Осталось на файлах + +| Сервис | Файл | Размер | Поддержка PostgreSQL | +|---|---|---|---| +| Uptime Kuma | `kuma.db` | 160 МБ | да, во второй версии | +| Gitea | `gitea.db` | 15 МБ | да — и база в PG уже есть | +| Sonarr | `sonarr.db` | 3.2 МБ | да | +| Radarr | `radarr.db` | 2.0 МБ | да | +| Grafana | `grafana.db` | 1.5 МБ | да | +| Mealie | `mealie.db` | 1.3 МБ | Перенесён, файл — остаток | +| n8n | `database.sqlite` | 99 МБ | Перенесён, файл — остаток | +| Linkding | `db.sqlite3` | 264 КБ | нет | +| Vaultwarden | `db.sqlite3` | 288 КБ | да | +| Prowlarr | `prowlarr.db` | 372 КБ | да | +| Bazarr | `bazarr.db` | 368 КБ | да | +| Tautulli | `tautulli.db` | 280 КБ | нет | +| Navidrome | `navidrome.db` | 596 КБ | нет | +| Jellyfin | `jellyfin.db` | 452 КБ | нет | +| NPM | `database.sqlite` | 124 КБ | нет | +| FreshRSS | `app.db` | 120 КБ | да | +| OpenClaw | `openclaw.sqlite` | 1.1 МБ | нет | + +**Порядок:** + +1. **Остатки после прошлых переносов** — убрать (n8n 99 МБ, mealie, paperless). + Сначала убедиться, что сервис действительно работает с центральной базой. +2. **Gitea** — главный сервис, база в PostgreSQL уже создана и ждёт. +3. **Vaultwarden** — хранилище паролей, ценность высокая. +4. **Grafana** — простая, безопасная проверка схемы переноса. +5. **Медиа-сервисы** (Sonarr, Radarr, Prowlarr, Bazarr) — однотипные. +6. **Остальные по возможности** — часть сервисов PostgreSQL не поддерживает, + для них честно фиксируем: остаются на файлах, но с копированием. + +--- + +## 8. Реестр баз + +Каждая база описана в одном месте — таблица `db_registry` в +`buryan_monitoring`. Там видно: сервис, движок, где лежит, размер, владелец, +кодировка, состояние переноса и когда проверялась копия. + +Без реестра через месяц никто не вспомнит, что где лежит и что уже перенесено. + +--- + +## 9. Правила, которые дорого дались + +1. **Копия без проверки — не копия.** Две недели «успешных» копий оказались + пустыми. +2. **Новая таблица или база — сразу права** тому, кто с ней работает. +3. **Одна копия — не резерв.** Нужны несколько и на разных носителях. +4. **Переносить по одной базе с проверкой сервиса**, а не всё разом. +5. **Кодировку задавать при создании.** Сменить её потом — это перенос. +6. **Проверять результат, а не факт выполнения команды.** diff --git a/ops/scripts/db-inventory.sh b/ops/scripts/db-inventory.sh new file mode 100755 index 0000000..272708c --- /dev/null +++ b/ops/scripts/db-inventory.sh @@ -0,0 +1,101 @@ +#!/bin/bash +# ============================================================ +# db-inventory.sh — где сейчас живут базы данных +# ============================================================ +# Основа для централизации: нужно точно знать, что и где лежит, +# прежде чем что-то переносить. +# +# Собирает: +# 1. какие базы есть в центральной PostgreSQL (CT 151); +# 2. какие файловые базы (SQLite) есть в контейнерах; +# 3. какие сервисы уже ходят в центральную базу, а какие ещё нет. +# +# Ничего не меняет. Только читает. +# +# Запуск: bash db-inventory.sh +# ============================================================ +set -uo pipefail + +. /root/.buryan-monitor.env +export PGPASSWORD + +echo "══════════════════════════════════════════════════════════" +echo " 1. ЦЕНТРАЛЬНАЯ POSTGRESQL (CT 151)" +echo "══════════════════════════════════════════════════════════" +pct exec 151 -- sudo -u postgres psql -tAc " +SELECT datname || ' | ' || pg_size_pretty(pg_database_size(datname)) || ' | владелец: ' || pg_get_userbyid(datdba) + FROM pg_database + WHERE datistemplate = false + ORDER BY pg_database_size(datname) DESC" 2>/dev/null | sed 's/^/ /' + +echo +echo " роли, которые могут входить:" +pct exec 151 -- sudo -u postgres psql -tAc \ + "SELECT ' ' || rolname FROM pg_roles WHERE rolcanlogin AND rolname NOT LIKE 'pg\_%' ORDER BY rolname" 2>/dev/null + +echo +echo "══════════════════════════════════════════════════════════" +echo " 2. ФАЙЛОВЫЕ БАЗЫ В КОНТЕЙНЕРАХ" +echo "══════════════════════════════════════════════════════════" +printf ' %-6s %-20s %-10s %s\n' CT ИМЯ РАЗМЕР ФАЙЛ +printf ' %s\n' '----------------------------------------------------------------' + +total=0 +for id in $(pct list | awk 'NR>1{print $1}'); do + state=$(pct status "$id" 2>/dev/null | awk '{print $2}') + [ "$state" = "running" ] || continue + name=$(pct config "$id" 2>/dev/null | awk '/^hostname/{print $2}') + + # ищем файловые базы, кроме внутренностей docker и системных + found=$(pct exec "$id" -- bash -c ' + find /opt /var/lib /srv /root -maxdepth 5 \ + \( -name "*.db" -o -name "*.sqlite" -o -name "*.sqlite3" \) \ + -size +100k 2>/dev/null \ + | grep -vE "/var/lib/docker/(overlay2|containers|image)|/var/lib/dpkg|/var/cache" \ + | head -8' 2>/dev/null) + + [ -z "$found" ] && continue + + while read -r f; do + [ -n "$f" ] || continue + sz=$(pct exec "$id" -- bash -c "du -h '$f' 2>/dev/null | cut -f1" 2>/dev/null) + printf ' %-6s %-20s %-10s %s\n' "$id" "${name:0:20}" "${sz:-?}" "$f" + total=$((total + 1)) + done <<< "$found" +done +echo +echo " всего файловых баз найдено: $total" + +echo +echo "══════════════════════════════════════════════════════════" +echo " 3. КУДА ХОДЯТ СЕРВИСЫ" +echo "══════════════════════════════════════════════════════════" +printf ' %-6s %-24s %-14s %s\n' CT КОНТЕЙНЕР ТИП БАЗЫ АДРЕС +printf ' %s\n' '----------------------------------------------------------------' + +for id in $(pct list | awk 'NR>1{print $1}'); do + state=$(pct status "$id" 2>/dev/null | awk '{print $2}') + [ "$state" = "running" ] || continue + pct exec "$id" -- bash -c 'command -v docker >/dev/null' 2>/dev/null || continue + + for c in $(pct exec "$id" -- docker ps --format '{{.Names}}' 2>/dev/null); do + envs=$(pct exec "$id" -- docker inspect "$c" --format '{{range .Config.Env}}{{println .}}{{end}}' 2>/dev/null) + + host=$(echo "$envs" | grep -E '^(DB_HOST|POSTGRES_HOST|DATABASE_HOST|PGHOST)=' | head -1 | cut -d= -f2-) + engine=$(echo "$envs" | grep -E '^(DB_ENGINE|DB_TYPE|DB_CONNECTION|DATABASE_TYPE)=' | head -1 | cut -d= -f2-) + + if [ -n "$host" ] || [ -n "$engine" ]; then + printf ' %-6s %-24s %-14s %s\n' "$id" "${c:0:24}" "${engine:-?}" "${host:-?}" + fi + done +done + +echo +echo "══════════════════════════════════════════════════════════" +echo " 4. ВНЕШНИЕ КОПИИ" +echo "══════════════════════════════════════════════════════════" +echo -n " скрипт внешнего копирования: "; ls /opt/buryan-hub/scripts/offsite-backup.sh 2>/dev/null || echo 'нет' +echo -n " задание в расписании: "; (crontab -l 2>/dev/null; cat /etc/cron.d/* 2>/dev/null) | grep -c offsite-backup +echo " последние записи журнала:" +ls -la --time-style=+%Y-%m-%d /var/log/offsite* 2>/dev/null | head -3 || echo ' журнала нет' +echo -n " свободно на томе копий: "; df -h /mnt/backups | tail -1 | awk '{print $4}' diff --git a/ops/scripts/db-registry-sync.sh b/ops/scripts/db-registry-sync.sh new file mode 100755 index 0000000..3e6c205 --- /dev/null +++ b/ops/scripts/db-registry-sync.sh @@ -0,0 +1,128 @@ +#!/bin/bash +# ============================================================ +# db-registry-sync.sh — наполнение реестра баз по факту +# ============================================================ +# Читает фактическое состояние и обновляет таблицу db_registry: +# * базы центральной PostgreSQL — с размером, владельцем, кодировкой; +# * файловые базы сервисов — с путём и размером. +# +# Состояние определяется по списку известных сервисов: если сервис уже +# работает с центральной базой, его файл помечается как «остаток», +# иначе — «к переносу». Сервисы, которые PostgreSQL не поддерживают, +# помечаются честно. +# +# Поле note при обновлении не затирается — оно для заметок вручную. +# +# Запуск: bash db-registry-sync.sh +# ============================================================ +set -uo pipefail + +PG=192.168.1.151 +PSQL="pct exec 151 -- sudo -u postgres psql -tAc" + +. /root/.buryan-monitor.env +export PGPASSWORD + +# сервисы, которые PostgreSQL не поддерживают — останутся на файлах +UNSUPPORTED="linkding tautulli navidrome jellyfin npm openclaw" + +# Состояние определяется ФАКТОМ, а не списком: живая база — та, которую +# сервис держит открытой. Проверка по списку уже привела к ошибке: +# Gitea и Paperless были помечены «остатком», хотя работали на файлах, +# а «остаток» означает «файл можно удалять». Так теряются живые данные. +file_is_open() { # $1 = CT, $2 = путь + local ct="$1" path="$2" base + base=$(basename "$path") + local n + n=$(pct exec "$ct" -- bash -c \ + "for f in /proc/*/fd; do readlink \"\$f\" 2>/dev/null; done | grep -c '$base'" 2>/dev/null) + [ "${n:-0}" -gt 0 ] && echo yes || echo no +} + +echo "=== 1. БАЗЫ ЦЕНТРАЛЬНОЙ POSTGRESQL ===" +$PSQL " +SELECT datname || '|' || pg_size_pretty(pg_database_size(datname)) || '|' || + pg_database_size(datname) || '|' || pg_get_userbyid(datdba) || '|' || + pg_encoding_to_char(encoding) + FROM pg_database WHERE datistemplate = false ORDER BY datname" 2>/dev/null > /tmp/pg-dbs.txt + +while IFS='|' read -r name size bytes owner enc; do + [ -n "$name" ] || continue + # имя сервиса выводим из имени базы: убираем хвост _db + svc="${name%_db}" + psql -h "$PG" -U buryan_monitor -d buryan_monitoring -tAc " + INSERT INTO db_registry (service, engine, db_name, ct_id, size_bytes, owner_role, encoding, status, backup_ok, last_seen) + VALUES ('$svc', 'postgresql', '$name', '151', $bytes, '$owner', '$enc', 'в работе', true, now()) + ON CONFLICT (service, engine, db_name, file_path) DO UPDATE + SET size_bytes = EXCLUDED.size_bytes, + owner_role = EXCLUDED.owner_role, + encoding = EXCLUDED.encoding, + last_seen = now()" 2>/dev/null + printf ' %-22s %-8s %-16s %s\n' "$name" "$size" "$owner" "$enc" +done < /tmp/pg-dbs.txt +echo " всего: $(grep -c . /tmp/pg-dbs.txt)" + +echo +echo "=== 2. ФАЙЛОВЫЕ БАЗЫ СЕРВИСОВ ===" +printf ' %-16s %-6s %-10s %-16s %s\n' СЕРВИС CT РАЗМЕР СОСТОЯНИЕ ФАЙЛ +printf ' %s\n' '----------------------------------------------------------------------------' + +# список файлов, которые считаем базами сервисов (без внутренностей docker) +scan_ct() { # $1 = CT, $2 = имя контейнера-владельца, $3 = путь + local ct="$1" path="$2" svc="$3" + local bytes + bytes=$(pct exec "$ct" -- bash -c "stat -c %s '$path' 2>/dev/null" 2>/dev/null) + [ -n "$bytes" ] || return + + local status="к переносу" + for u in $UNSUPPORTED; do [ "$svc" = "$u" ] && status="не поддерживается"; done + + # Файл открыт сервисом — он живой. Закрыт — остаток от прошлого переноса. + if [ "$status" != "не поддерживается" ]; then + if [ "$(file_is_open "$ct" "$path")" = "yes" ]; then + status="в работе" + else + status="остаток" + fi + fi + + psql -h "$PG" -U buryan_monitor -d buryan_monitoring -tAc " + INSERT INTO db_registry (service, engine, file_path, ct_id, size_bytes, status, backup_ok, last_seen) + VALUES ('$svc', 'sqlite', '$path', '$ct', $bytes, '$status', false, now()) + ON CONFLICT (service, engine, db_name, file_path) DO UPDATE + SET size_bytes = EXCLUDED.size_bytes, + status = EXCLUDED.status, + last_seen = now()" 2>/dev/null + + local human + human=$(pct exec "$ct" -- bash -c "du -h '$path' 2>/dev/null | cut -f1" 2>/dev/null) + printf ' %-16s %-6s %-10s %-16s %s\n' "$svc" "$ct" "${human:-?}" "$status" "$path" +} + +# путь → сервис → контейнер +scan_ct 107 /opt/network-lxc/uptime/data/kuma.db uptime-kuma +scan_ct 140 /opt/gitea/gitea/gitea.db gitea +scan_ct 117 /opt/sonarr/config/sonarr.db sonarr +scan_ct 118 /opt/radarr/config/radarr.db radarr +scan_ct 113 /var/lib/docker/volumes/bb96ab0c4792f406a1d68f4935ff151e8da041c0bbcacb3262de776fd0428df5/_data/grafana.db grafana +scan_ct 110 /opt/lifestyle-lxc/mealie/data/mealie.db mealie +scan_ct 108 /opt/automation-lxc/n8n/data/database.sqlite n8n +scan_ct 119 /opt/prowlarr/config/prowlarr.db prowlarr +scan_ct 120 /opt/bazarr/config/db/bazarr.db bazarr +scan_ct 122 /opt/tautulli/config/tautulli.db tautulli +scan_ct 125 /opt/navidrome/data/navidrome.db navidrome +scan_ct 103 /opt/jellyfin/config/data/jellyfin.db jellyfin +scan_ct 101 /opt/npm/data/database.sqlite npm +scan_ct 127 /var/lib/docker/volumes/linkding-data/_data/db.sqlite3 linkding +scan_ct 109 /opt/files-lxc/vaultwarden/data/db.sqlite3 vaultwarden +scan_ct 115 /opt/openclaw/state/openclaw.sqlite openclaw +scan_ct 105 /opt/sync-lxc/paperless/data/db.sqlite3 paperless + +echo +echo "=== 3. СВОДКА ===" +psql -h "$PG" -U buryan_monitor -d buryan_monitoring -c \ + 'SELECT * FROM db_registry_summary;' 2>/dev/null + +echo "=== 4. ЧТО ПРЕДСТОИТ ПЕРЕНЕСТИ ===" +psql -h "$PG" -U buryan_monitor -d buryan_monitoring -c \ + 'SELECT * FROM db_to_migrate;' 2>/dev/null diff --git a/ops/scripts/db-registry.sql b/ops/scripts/db-registry.sql new file mode 100644 index 0000000..7b10806 --- /dev/null +++ b/ops/scripts/db-registry.sql @@ -0,0 +1,61 @@ +-- ============================================================ +-- db_registry — реестр всех баз данных проекта +-- ============================================================ +-- Зачем: данные разбросаны между центральной PostgreSQL и файловыми +-- базами сервисов. Без единого списка через месяц никто не вспомнит, +-- что где лежит, что уже перенесено и что осталось. +-- +-- Реестр наполняется автоматически скриптом db-registry-sync.sh: +-- он читает фактическое состояние и обновляет записи. Руками правится +-- только поле note. +-- +-- База: buryan_monitoring (CT 151) +-- ============================================================ + +CREATE TABLE IF NOT EXISTS db_registry ( + id serial PRIMARY KEY, + service text NOT NULL, -- имя сервиса + engine text NOT NULL, -- postgresql | sqlite + db_name text, -- имя базы (для PG) + file_path text, -- путь к файлу (для SQLite) + ct_id text, -- в каком контейнере + size_bytes bigint, + owner_role text, -- владелец (для PG) + encoding text, -- кодировка + status text NOT NULL DEFAULT 'к переносу', + -- в работе | к переносу | остаток | не поддерживается + backup_ok boolean DEFAULT false, -- попадает ли в резервную копию + last_seen timestamptz DEFAULT now(), + note text, + + -- один и тот же объект не должен попадать дважды + CONSTRAINT db_registry_unique UNIQUE (service, engine, db_name, file_path) +); + +CREATE INDEX IF NOT EXISTS idx_db_registry_status ON db_registry (status); +CREATE INDEX IF NOT EXISTS idx_db_registry_engine ON db_registry (engine); + +COMMENT ON TABLE db_registry IS 'Реестр баз данных: что где лежит и что перенесено'; +COMMENT ON COLUMN db_registry.status IS 'в работе — сервис работает с этой базой; к переносу — ещё на файлах; остаток — файл после переноса; не поддерживается — сервис не умеет PostgreSQL'; + +-- ------------------------------------------------------------------ +-- Сводка: сколько где и что осталось +-- ------------------------------------------------------------------ +CREATE OR REPLACE VIEW db_registry_summary AS +SELECT engine, + status, + count(*) AS cnt, + pg_size_pretty(sum(size_bytes)) AS total_size + FROM db_registry + GROUP BY engine, status + ORDER BY engine, status; + +-- ------------------------------------------------------------------ +-- Что ещё предстоит перенести +-- ------------------------------------------------------------------ +CREATE OR REPLACE VIEW db_to_migrate AS +SELECT service, engine, db_name, file_path, ct_id, + pg_size_pretty(size_bytes) AS size + FROM db_registry + WHERE status = 'к переносу' + ORDER BY size_bytes DESC NULLS LAST;