From 21ccc7ac8cebf632801548bf58a18d5992291574 Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Sun, 24 May 2026 15:56:53 +0300 Subject: [PATCH] Fix style in ADR --- docs/adr/ADR-2025-05-07-authelia-sso.md | 10 ++++---- ...025-12-13-os-upgrade-via-server-rebuild.md | 8 +++---- .../ADR-2026-04-04-apprise-notifications.md | 10 ++++---- docs/adr/ADR-2026-05-23-migrate-to-timeweb.md | 23 +++++++++++-------- docs/adr/README.md | 2 +- 5 files changed, 28 insertions(+), 25 deletions(-) diff --git a/docs/adr/ADR-2025-05-07-authelia-sso.md b/docs/adr/ADR-2025-05-07-authelia-sso.md index 39074e0..a0733e6 100644 --- a/docs/adr/ADR-2025-05-07-authelia-sso.md +++ b/docs/adr/ADR-2025-05-07-authelia-sso.md @@ -6,11 +6,11 @@ Для SSO/OIDC на сервере стоял Keycloak (заведён годом ранее, 2024-05-25). Проблема — ресурсы: Keycloak съедал больше 500 МБ RAM, что -тяжело для личного сервера c ограниченной оперативной памятью. При этом вся его мощь +тяжело для личного сервера с ограниченной оперативной памятью. При этом вся его мощь избыточна: пользователей меньше десяти, realms / federation / тяжёлый -enterprise-стек не нужны. Изначально взял Keycloak, потому что нужен был -OIDC сервер для настройки Outline: когда настраивал был понятный гайд -по OIDC и Keycloak. +корпоративный стек не нужны. Изначально взял Keycloak, потому что нужен был +OIDC-сервер для настройки Outline; на тот момент было понятное +руководство по связке OIDC и Keycloak. Требовался лёгкий по памяти SSO-провайдер с хорошей документацией, желательно на Go/Rust. @@ -45,6 +45,6 @@ OIDC сервер для настройки Outline: когда настраив отдельный OIDC-клиент под каждое. - `+` Единая точка аутентификации вместо разрозненного basic auth в Caddy. -- `-` Authelia беднее Keycloak по возможностям (нет полноценного UI +- `-` Authelia беднее Keycloak по возможностям (нет полноценного интерфейса управления пользователями, realms, federation) — но для < 10 пользователей это не нужно. diff --git a/docs/adr/ADR-2025-12-13-os-upgrade-via-server-rebuild.md b/docs/adr/ADR-2025-12-13-os-upgrade-via-server-rebuild.md index cccd935..dbde4f3 100644 --- a/docs/adr/ADR-2025-12-13-os-upgrade-via-server-rebuild.md +++ b/docs/adr/ADR-2025-12-13-os-upgrade-via-server-rebuild.md @@ -5,18 +5,18 @@ ## Контекст На сервере стояла Ubuntu 22.04, и к концу 2025 пора было обновляться. -Обновлять живую боевую систему in-place (`do-release-upgrade`) не +Обновлять живую боевую систему «на месте» (`do-release-upgrade`) не хотелось — это рискованно и тяжело откатывается, если что-то пойдёт не так на работающем сервере. ## Рассмотренные варианты -- **In-place обновление** (`do-release-upgrade` на живой системе). +- **Обновление «на месте»** (`do-release-upgrade` на живой системе). Отвергнуто: риск сломать рабочий сервер, нет простого отката. - **Пересборка на свежем сервере** (выбран). Поднять новый сервер с целевой ОС, накатать ansible, прицепить диск с данными, развернуть приложения — старый сервер остаётся нетронутым как точка отката. - Заодно почистить мусор от прошлой рабоыт сервера. + Заодно — почистить мусор, накопившийся за время работы прошлого сервера. ## Решение @@ -46,7 +46,7 @@ - `+` Обновление ОС без риска для живой системы; откат = вернуться на старый сервер. - `+` Получился воспроизводимый процесс миграции — позже переиспользован - при переезде в Timeweb как «cold cutover» + при переезде в Timeweb как «холодное переключение» (cold cutover) ([ADR-2026-05-23](ADR-2026-05-23-migrate-to-timeweb.md)). - `+` Фиксация uid/gid стала постоянным инвариантом проекта. - `-` Метод требует заранее подготовленных предпосылок (фикс uid/gid + diff --git a/docs/adr/ADR-2026-04-04-apprise-notifications.md b/docs/adr/ADR-2026-04-04-apprise-notifications.md index f6f51d0..024f197 100644 --- a/docs/adr/ADR-2026-04-04-apprise-notifications.md +++ b/docs/adr/ADR-2026-04-04-apprise-notifications.md @@ -1,10 +1,10 @@ -# Apprise как шлюз нотификаций +# Apprise как шлюз уведомлений - Дата: 2026-04-04 ## Контекст -В первую очередь нужны были нотификации о бэкапах — знать, что ночной +В первую очередь нужны были уведомления о бэкапах — знать, что ночной прогон отработал и не сломался. Уведомления слались напрямую в конкретный канал, привязка была зашита в каждом источнике. Хотелось единый слой, который абстрагирует каналы доставки — чтобы добавлять или менять канал в @@ -12,9 +12,9 @@ ## Рассмотренные варианты -- **Прямая интеграция per-канал** (как было). Каждый источник знает про +- **Прямая интеграция с каждым каналом** (как было). Каждый источник знает про конкретный канал; смена канала — правки во многих местах. -- **Apprise** (выбран). Смотрел разные self-hosted шлюзы нотификаций; +- **Apprise** (выбран). Смотрел разные self-hosted шлюзы уведомлений; apprise выиграл зрелостью и числом готовых интеграций (десятки каналов из коробки). @@ -33,5 +33,5 @@ HTTP в apprise, а он разводит его по настроенным к каждую. - `-` Ещё один сервис в обслуживании (контейнер, память). - Окупилось при переезде в Timeweb: провайдер заблокировал Telegram, и - переключение нотификаций (сейчас почта, в планах Matrix) локализовано в + переключение уведомлений (сейчас почта, в планах Matrix) локализовано в шлюзе ([ADR-2026-05-23](ADR-2026-05-23-migrate-to-timeweb.md)). diff --git a/docs/adr/ADR-2026-05-23-migrate-to-timeweb.md b/docs/adr/ADR-2026-05-23-migrate-to-timeweb.md index 20ab22a..86dde1c 100644 --- a/docs/adr/ADR-2026-05-23-migrate-to-timeweb.md +++ b/docs/adr/ADR-2026-05-23-migrate-to-timeweb.md @@ -4,7 +4,7 @@ ## Контекст -`rivendell-v2` жил на VM в Yandex Cloud. Одновременно копились три +`rivendell-v2` жил на виртуальной машине в Yandex Cloud. Одновременно копились три проблемы: - **Цена.** ≈ 2 887 ₽/мес за конфигурацию, которую другие провайдеры @@ -17,7 +17,7 @@ HDD вместо SSD/NVMe — страдала отзывчивость (Gitea, Outline, тёплый старт контейнеров, restic check/forget). -Это личный сервер — допустим мягкий даунтайм. +Это личный сервер — допустимы небольшие простои. ## Рассмотренные варианты @@ -37,16 +37,18 @@ Рамки решения: -- Переезжает **только compute** (VM с приложениями). S3 (restic, бекапы), +- Переезжает **только сам сервер с приложениями** (compute). S3 (restic, бэкапы), Container Registry, Postbox SMTP и DNS-зона `vakhrushev.me` остаются в Yandex и используются с новой машины. -- Стратегия — **cold cutover**: погасить сервисы на источнике, раскатать +- Стратегия — **холодное переключение** (cold cutover): погасить сервисы + на источнике, раскатать ansible на новом сервере без запуска приложений (сохраняя uid/gid), перенести данные `rsync`'ом, запустить, переключить DNS. - Диск: фаза 1 — один 80 ГБ NVMe (всего 22 ГБ данных + 17 ГБ системных, влезает с запасом). «Холодный» второй диск под крупные данные — отдельная фаза 2, не на критическом пути. -- Источник не удаляется сразу после cutover: держим «холодным запасным» +- Источник не удаляется сразу после переключения: держим «холодным + запасным» пару недель ради отката. Детальный план — [`../drafts/timeweb.md`](../drafts/timeweb.md), @@ -59,7 +61,7 @@ закрыты все три исходные проблемы. - `+` Запас по RAM убирает OOM-риск при всплесках нагрузки. - `+` Диверсификация по облакам: раньше сервер и данные были в одном - аккаунте Yandex Cloud, теперь compute в Timeweb, а бэкапы (S3) — в + аккаунте Yandex Cloud, теперь сам сервер в Timeweb, а бэкапы (S3) — в Yandex. Если заблокируют или потеряем доступ к одному провайдеру, данные остаются доступны через другой. - `-` Диск меньше (80 ГБ NVMe против 120 ГБ HDD), но сейчас занят @@ -67,13 +69,14 @@ - `-` Сохраняется зависимость от Yandex Cloud (S3, Container Registry, Postbox SMTP, DNS) — переезд её не устраняет. - `-` Timeweb активно блокирует Telegram (в отличие от YC) — интеграция - отвалилась. Затронуты `transcriber`, `remembos` и нотификации о - бэкапах. Ожидаемо; нотификации остались через почту, второй канал + отвалилась. Затронуты `transcriber`, `remembos` и уведомления о + бэкапах. Ожидаемо; уведомления остались через почту, второй канал рассматривается через Matrix. - `-` Из-за тех же блокировок Timeweb перестали обновляться некоторые RSS-фиды в `miniflux`. - `-` Для доступа к `cr.yandex` вне YC появился долгоживущий OAuth-токен - Яндекса в vault (`yc_oauth_token`) с широким blast radius. При желании - сузить — IAM-ключ сервисного аккаунта отдельной итерацией. + Яндекса в vault (`yc_oauth_token`): при утечке он открывает доступ ко + всему аккаунту Яндекса. Сузить можно IAM-ключом сервисного аккаунта — + отдельной итерацией. - Инвентарь временно раздвоен (`production.yml` + `timeweb.yml`); после стабилизации источник удаляется, `timeweb.yml` → `production.yml`. diff --git a/docs/adr/README.md b/docs/adr/README.md index ce23b44..7d02b07 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -64,7 +64,7 @@ | Дата | Запись | Статус | | ---------- | ---------------------------------------------------------------------------------------------- | ------ | | 2026-05-23 | [Переезд сервера с Yandex Cloud на Timeweb VPS](ADR-2026-05-23-migrate-to-timeweb.md) | — | -| 2026-04-04 | [Apprise как шлюз нотификаций](ADR-2026-04-04-apprise-notifications.md) | — | +| 2026-04-04 | [Apprise как шлюз уведомлений](ADR-2026-04-04-apprise-notifications.md) | — | | 2025-12-13 | [Обновление ОС пересборкой на свежем сервере](ADR-2025-12-13-os-upgrade-via-server-rebuild.md) | — | | 2025-12-07 | [Данные приложений на отдельном диске](ADR-2025-12-07-app-data-on-separate-disk.md) | — | | 2025-05-07 | [Authelia вместо Keycloak для SSO](ADR-2025-05-07-authelia-sso.md) | — |