Migration: add draft for timeweb migration

2026-05-22 19:55:54 +03:00
parent 893996f0c9
commit 3545905cbd
1 changed files with 526 additions and 0 deletions
@@ -0,0 +1,526 @@
+# Миграция сервера в Timeweb
+
+## Контекст и цели
+
+Сервер `rivendell-v2` переезжает с виртуальной машины в Yandex Cloud
+(`158.160.46.255`) на VPS в Timeweb.
+
+### Причины переезда
+
+1. **Высокая стоимость.** Тариф в Yandex Cloud обходится в ≈ 2 900 ₽/мес
+   за конфигурацию, которая в Timeweb стоит ≈ 2 000 ₽/мес и при этом
+   мощнее по всем параметрам (см. сравнение ниже).
+2. **Упор в потолок RAM.** Текущий сервер уже использует ≈ 80 %
+   доступной памяти на штатной нагрузке (см.
+   `project_server_specs`). Любой всплеск (миграции БД, индексация
+   в Outline, бэкап с restic) — и приложения начинают конкурировать
+   за память, появляются OOM-риски. Дальше расти на этом тарифе
+   некуда без значительного увеличения цены.
+3. **Медленные диски.** Из-за высокой стоимости в YC приходится
+   использовать дешёвый HDD-том вместо SSD/NVMe — это заметно
+   снижает отзывчивость приложений (особенно Gitea, Outline,
+   тёплый старт контейнеров, рестики check/forget). На Timeweb за
+   меньшие деньги получаем NVMe.
+
+Переезд решает все три проблемы одновременно: дешевле, больше
+RAM, быстрее диск.
+
+### Сравнение тарифов
+
+| Параметр       | Yandex Cloud                              | Timeweb Cloud VPS  |
+| -------------- | ----------------------------------------- | ------------------ |
+| CPU            | Intel Cascade Lake, vCPU 2, гарантия 50 % | 4 × 3.3 ГГц        |
+| RAM            | 4 ГБ                                      | 8 ГБ               |
+| Диск           | 120 ГБ HDD                                | 80 ГБ NVMe         |
+| Публичный IP   | да                                        | да                 |
+| **Цена/месяц** | **2 887 ₽**                               | **1 980 ₽**        |
+
+Итого: **−907 ₽/мес (≈ −31 %)**, при этом **×2 RAM** (закрывает
+причину 2), **×2 ядер**, гарантия CPU 100 % вместо 50 %,
+**NVMe вместо HDD** (закрывает причину 3). Минус — диск меньше
+(80 ГБ против 120 ГБ HDD), что и стало основанием для фазы 2 с
+подключением второго «холодного» диска под крупные данные.
+
+Переезжает **только compute** (VM с приложениями). Остальные сервисы
+Yandex Cloud остаются на месте и продолжают использоваться с новой
+машины:
+
+- **Container Registry** — `cr.yandex/crplfk0168i4o8kd7ade` для образов
+  `homepage-nginx` и `transcriber`.
+- **Object Storage (S3)** — restic-репозиторий `yandex_cloud_s3`.
+- **Postbox SMTP** — `postbox.cloud.yandex.net` (gitea, gramps, wakapi,
+  outline, authelia, apprise).
+- **Yandex 360 / DNS-зона** `vakhrushev.me` — там же управляются записи
+  и почтовый домен.
+
+Параметры даунтайма — мягкие, это личная машина. Стратегия — «cold
+cutover»: остановить сервисы на источнике, раскатать ansible на
+target без запуска приложений, перенести данные с сохранением
+uid/gid, запустить сервисы на target, переключить DNS.
+
+Конфигурация target — Cloud VPS Timeweb с одним диском **80 ГБ** на
+первой фазе. Позднее (отдельной фазой) будет подключён второй
+«медленный» диск под крупные данные (`calibre`, бэкапы, возможно
+`outline`).
+
+---
+
+## Инвентаризация YC-зависимостей в коде
+
+| Компонент | Где | Что делать при переезде |
+| --- | --- | --- |
+| `production.yml` | `ansible_host: 158.160.46.255`, `ansible_user: major` | Заменить на новый IP/пользователя Timeweb |
+| `files/yandex-docker-registry-auth.sh` | Логин в `cr.yandex` через **YC metadata service** (`169.254.169.254`) | **Не работает вне YC.** Перейти на static OAuth-token / IAM-token (новый скрипт + секрет в vault) |
+| `playbook-system.yml` (mount-storage) | UUID `3942bffd-…` монтируется в `/mnt/applications` | Фаза 1: отключить mount или сделать UUID переменной vault. Фаза 2 (после подключения медленного диска): включить заново с новым UUID |
+| `files/backups/config.template.toml` | `[storage.yandex_cloud_s3]` + `AWS_*` ключи | **Не меняем.** Тот же бакет/ключи продолжают работать. Меняется только `host_name` (для подписи снапшотов и нотификаций) — он уже шаблонится |
+| SMTP (`postbox_host/port/user/pass`) | gitea, gramps, wakapi, outline, authelia, apprise | **Не меняем.** Postbox SMTP доступен извне YC по тем же credentials |
+| `files/backups/rclone.template.conf` (`pr86keedav`) | WebDAV-копия restic — внешний сервис | **Не меняем** |
+| Caddy `tls anwinged@ya.ru` | ACME | Не меняется, ACME перевыпустит сертификаты после смены IP |
+
+Никаких других hardcoded YC-эндпоинтов в плейбуках / шаблонах нет —
+SSH, ufw, fail2ban, docker, eget, restic, Caddy полностью переносимы.
+
+---
+
+## UID / GID — критично для rsync
+
+UID/GID каждого приложения зафиксированы в плейбуках и в
+`vars/homepage.yml` / `vars/transcriber.yml`. Роль `owner` создаёт
+группы и пользователей **с явно указанными gid/uid**
+(`roles/owner/tasks/main.yml`). Это значит:
+
+- Если на новой машине **сначала** раскатать все плейбуки (без
+  запуска приложений), пользователи получатся с теми же uid/gid.
+- Тогда `rsync -aAX` (с сохранением owner) корректно ляжет на target.
+- Дополнительный maping uid не нужен.
+
+Список приложений с uid/gid (для сверки и для документации):
+
+```
+caddyproxy   1010 / 1011
+authelia     1011 / 1012
+netdata      1012 / 1013
+miniflux     1013 / 1014
+rssbridge    1014 / 1015
+wakapi       1015 / 1016
+dozzle       1016 / 1017
+transcriber  1017 / 1018
+wanderer     1018 / 1019
+memos        1019 / 1020
+gitea        1005 / 1006
+outline      1007 / 1008
+homepage     1008 / 1009
+gramps       1009 / 1010
+calibre      1102 / 1102
+remembos     1103 / 1103
+apprise      1104 / 1104
+tuwunel      1105 / 1105
+goaccess     1106 / 1106
+```
+
+(Возможные пересечения uid одного приложения и gid другого
+существуют, но Linux держит их в разных пространствах имён — не
+страшно.)
+
+---
+
+## Подготовка кода проекта
+
+Делается **до** аренды Timeweb-машины, отдельным PR (или сериями
+коммитов на отдельной ветке). Цель — чтобы тот же ansible
+работал и на источнике, и на target без условных хаков.
+
+### 1. Заменить YC-specific docker registry auth
+
+`files/yandex-docker-registry-auth.sh` сейчас использует metadata
+service (`169.254.169.254`). Это работает только внутри YC VM,
+поэтому на Timeweb его надо заменить.
+
+**Решение — OAuth-token Яндекса.** Простой и достаточный для
+домашнего сервера механизм:
+
+1. Получить OAuth-token в кабинете Яндекса:
+   <https://oauth.yandex.ru/authorize?response_type=token&client_id=1a6990aa636648e9b2ef855fa7bec2fb>
+   (стандартный client_id для `yc` CLI, токен с правом доступа к
+   Container Registry).
+2. Положить в `vars/secrets.yml` как `yc_oauth_token` (vault).
+3. Переписать `files/yandex-docker-registry-auth.sh` как шаблон
+   (`.template.sh`) и рендерить через `ansible.builtin.template`
+   вместо `script:`. Скрипт сводится к:
+   ```sh
+   #!/usr/bin/env sh
+   set -eu
+   echo "{{ yc_oauth_token }}" | \
+       docker login --username oauth --password-stdin cr.yandex
+   ```
+   Альтернатива — не рендерить, а передавать токен в скрипт
+   аргументом или через переменную окружения, чтобы не светить его
+   в системе.
+4. В `playbook-homepage.yml` и `playbook-transcriber.yml` поменять
+   `ansible.builtin.script:` на `ansible.builtin.template:` +
+   `ansible.builtin.command:` (либо использовать модуль
+   `community.docker.docker_login` напрямую с `username: oauth`,
+   `password: "{{ yc_oauth_token }}"` — это самый чистый вариант,
+   тогда отдельный скрипт вообще не нужен).
+5. То же самое — для локальных push-плейбуков
+   `playbook-homepage-registry.yml` и
+   `playbook-transcriber-registry.yml`.
+
+Рекомендую вариант с `community.docker.docker_login` — это убирает
+shell-скрипт целиком и сильно проще.
+
+Минусы OAuth-token: токен живёт долго и даёт доступ ко всему
+аккаунту Яндекса. Для личного сервера приемлемо; если позже
+захочется минимизировать blast radius — заменить на IAM-key
+сервисного аккаунта (отдельная итерация после миграции).
+
+Затронутые места: `files/yandex-docker-registry-auth.sh` (удалить
+или переписать), `playbook-homepage.yml`, `playbook-transcriber.yml`,
+`playbook-homepage-registry.yml`, `playbook-transcriber-registry.yml`,
+`vars/secrets.yml` (новый ключ `yc_oauth_token`).
+
+### 2. Сделать опциональным монтирование внешнего диска
+
+Сейчас `playbook-system.yml` жёстко монтирует UUID `3942bffd-…` в
+`/mnt/applications`. На Timeweb этого диска нет.
+
+Минимальная правка — вытащить UUID в переменную (`storage_uuid`) и
+обернуть mount-задачу `when: storage_uuid is defined`. В
+`vars/secrets.yml` или `vars/vars.yml` для текущего сервера задать
+UUID, для Timeweb (фаза 1) — не задавать. На фазе 2 (когда придёт
+медленный диск) — задать новый UUID.
+
+Альтернатива: вынести параметры в инвентарь
+(`production.yml` → `host_vars/server.yml`).
+
+При этом сама директория `/mnt/applications` должна создаваться в
+любом случае — playbook уже это делает, надо лишь убедиться, что
+задача «Create directory for mount» не зависит от mount-задачи.
+
+### 3. Параметризовать инвентарь
+
+На время перехода — **два отдельных файла**: текущий
+`production.yml` остаётся как есть, рядом появляется новый
+`timeweb.yml` с настройками Timeweb-машины. Все ansible-команды
+во время миграции явно указывают `-i timeweb.yml`. После того, как
+переезд закончен и старая машина выключена — `production.yml`
+просто удаляется, `timeweb.yml` переименовывается в
+`production.yml`.
+
+`tasks.py` использует `yq` для извлечения `ansible_host` / `ansible_user`
+из инвентаря (`_yq(".ungrouped.hosts.server…")`) — путь к файлу
+зашит константой `HOSTS_FILE = "production.yml"`. Варианты:
+
+- На время миграции временно поменять `HOSTS_FILE = "timeweb.yml"`
+  в локальном коммите (или через env override), потом откатить — после
+  переименования всё снова работает.
+- Принять, что `inv ssh / zj / btop / login` работают только с
+  активным сервером (тем, что в `production.yml`), а к старой
+  машине во время миграции ходим напрямую через `ssh
+  major@158.160.46.255`.
+
+Первый вариант чище. Достаточно одной строчки правки.
+
+### 4. Прочее
+
+- `README.md` — обновить инструкцию по DNS и упомянуть Timeweb.
+- Удалить (или пометить deprecated) yandex-метаданные в комментариях
+  `yandex-docker-registry-auth.sh`.
+- Проверить, что у всех application-плейбуков задача с
+  `community.docker.docker_compose_v2: state: present` помечена
+  тегом `run-app` — это позволит раскатывать `--skip-tags run-app`
+  для подготовки target без запуска контейнеров. Сейчас тег `run-app`
+  есть в большинстве плейбуков, но надо пройтись и убедиться, что
+  он покрывает **все** контейнеры (включая calibre, dozzle,
+  remembos, transcriber, tuwunel, wanderer, memos).
+
+---
+
+## Подготовка target-машины
+
+1. Заказать Cloud VPS в Timeweb:
+   - Ubuntu LTS (та же мажорная версия, что и сейчас — упростит
+     совместимость пакетов).
+   - 4 GB RAM (текущий лимит ≈ 3.8 GiB, см. `project_server_specs`),
+     можно взять чуть с запасом — 4–6 GB, иначе netdata + tuwunel +
+     outline начнут давить.
+   - 2 vCPU.
+   - SSD 80 ГБ.
+   - Снять/настроить firewall провайдера (или отключить, т.к. у нас
+     свой ufw).
+
+2. Создать пользователя с правами sudo (аналог `major`), залить
+   свой SSH-ключ.
+
+3. Добавить хост в инвентарь как `server` (или временный
+   `timeweb`), убедиться, что `ansible -m ping` отвечает.
+
+4. Снизить TTL DNS-записей в Yandex 360 до 60–300 секунд **за
+   ~24–48 часов** до cutover.
+
+---
+
+## Cutover (план дня X)
+
+Предусловия: код выкатан, target-машина пингуется по ansible, TTL
+DNS снижены.
+
+### Шаг 1. Финальный бэкап на источнике
+
+```bash
+inv ssh
+sudo /usr/local/sbin/backup-all.py 2>&1 | tee /tmp/final-backup.log
+```
+
+Убедиться, что в логе все приложения отработали успешно и в S3
+появился свежий restic-snapshot (на случай отката или потери
+данных при rsync).
+
+### Шаг 2. Остановить все приложения на источнике
+
+Аккуратно остановить контейнеры каждого приложения (через
+`docker compose down` от соответствующего пользователя или одним
+проходом):
+
+```bash
+inv ssh
+for user in caddyproxy authelia netdata miniflux rssbridge wakapi \
+    dozzle transcriber wanderer memos gitea outline homepage gramps \
+    calibre remembos apprise tuwunel goaccess; do
+  sudo -iu "$user" bash -c "cd /mnt/applications/$user && docker compose down"
+done
+```
+
+(Можно завести вспомогательный плейбук `playbook-shutdown-all.yml`,
+если такое будет часто.)
+
+Проверить `docker ps`, что пусто. Снять флаги cron на бэкап (чтобы
+финальный backup не побежал во время миграции):
+
+```bash
+sudo systemctl stop cron
+```
+
+### Шаг 3. Раскатать инфраструктуру на target БЕЗ запуска приложений
+
+```bash
+# 1) системная база
+uv run ansible-playbook -i timeweb.yml --diff playbook-all-setup.yml
+
+# 2) приложения (создаём пользователей, каталоги, конфиги,
+#    но НЕ запускаем контейнеры)
+uv run ansible-playbook -i timeweb.yml --diff \
+    --skip-tags run-app \
+    playbook-all-applications.yml
+```
+
+Цель — после этого на target есть:
+
+- Корректные uid/gid для всех приложений.
+- Каталоги `/mnt/applications/<app>/{data,config,backups}`.
+- Шаблоны `docker-compose.yml` и application-конфиги — отрендерены
+  и лежат на месте.
+- Docker и сети созданы.
+- ufw настроен, fail2ban работает.
+
+### Шаг 4. Перенос данных
+
+Два варианта.
+
+**Вариант A — rsync напрямую (быстрее).** С target-машины тянем
+данные со старой:
+
+```bash
+sudo rsync -aAX --info=progress2 --delete \
+    --exclude='lost+found' \
+    major@158.160.46.255:/mnt/applications/ \
+    /mnt/applications/
+```
+
+`-aAX` сохраняет ACL/xattrs и uid/gid (численные значения).
+
+Каждое приложение можно тянуть отдельно — удобнее наблюдать
+прогресс и можно частично пересинхронизировать в случае ошибок.
+
+**Вариант B — restore из restic.** Если по сети источник недоступен
+(например, IP уже закрыли) или хочется проверить, что бэкапы вообще
+рабочие — восстанавливаемся из YC S3:
+
+```bash
+sudo /usr/local/sbin/restic-shell.sh
+restic restore latest --target /mnt/applications --path /mnt/applications
+```
+
+Рекомендую **A с фолбэком на B**: rsync быстрее и точнее (с
+точностью до секунды), restic держим как страховку.
+
+### Шаг 5. Запуск приложений на target
+
+Раскатываем application-плейбуки ещё раз — теперь без `--skip-tags`:
+
+```bash
+uv run ansible-playbook -i timeweb.yml --diff \
+    playbook-all-applications.yml
+```
+
+Этот же запуск проверит идемпотентность шаблонов (не должно быть
+diff'ов кроме docker-up).
+
+После старта — проверить:
+
+- `docker ps` — все контейнеры в healthy.
+- Локально (по IP) `curl http://<target-ip>` — Caddy отвечает (на
+  редирект, т.к. сертификаты ещё не выпущены под этим IP).
+- Логи Caddy — выпуск сертификатов запустится после смены DNS, не
+  раньше. Это нормально.
+
+### Шаг 6. Переключение DNS
+
+В Yandex 360 admin (`admin.yandex.ru/domains/vakhrushev.me`)
+поменять A-записи для всех subdomain'ов на новый IP. Перечень
+поддоменов (из `Caddyfile.template`):
+
+```
+vakhrushev.me           (apex)
+matrix.vakhrushev.me
+auth.vakhrushev.me
+status.vakhrushev.me
+git.vakhrushev.me
+outline.vakhrushev.me
+gramps.vakhrushev.me
+miniflux.vakhrushev.me
+wakapi.vakhrushev.me
+wanderer.vakhrushev.me
+memos.vakhrushev.me
+remembos.vakhrushev.me
+calibre.vakhrushev.me
+wanderbase.vakhrushev.me
+rssbridge.vakhrushev.me
+dozzle.vakhrushev.me
+goaccess.vakhrushev.me
+```
+
+После смены — подождать пока TTL разойдётся, проверить через
+`dig +short <hostname>` с независимой машины.
+
+Caddy сам пойдёт за сертификатами Let's Encrypt — следить за его
+логами (`docker logs caddyproxy_app -f`).
+
+### Шаг 7. Проверка после cutover
+
+Чеклист (примерно по приоритету):
+
+- [ ] `vakhrushev.me` отвечает 200, отдаёт homepage.
+- [ ] `auth.vakhrushev.me` — Authelia, можно залогиниться.
+- [ ] `git.vakhrushev.me` — Gitea, репозитории на месте, ssh-доступ
+      (порт 2222 в ufw уже открыт).
+- [ ] `outline.vakhrushev.me` — открывается, документы на месте.
+- [ ] `matrix.vakhrushev.me` — Tuwunel/Element подключается;
+      federation проверяется через
+      <https://federationtester.matrix.org/>.
+- [ ] `miniflux.vakhrushev.me`, `wakapi.vakhrushev.me`,
+      `memos.vakhrushev.me`, `gramps.vakhrushev.me`,
+      `remembos.vakhrushev.me`, `wanderer.vakhrushev.me`,
+      `calibre.vakhrushev.me`, `rssbridge.vakhrushev.me`,
+      `dozzle.vakhrushev.me`, `goaccess.vakhrushev.me` —
+      открываются, данные на месте.
+- [ ] Netdata `status.vakhrushev.me` — собирает метрики.
+- [ ] Backup-cron — следующий запуск (1:00) проходит успешно,
+      приходит уведомление в apprise.
+- [ ] SMTP — отправить тестовое письмо из gitea/authelia (триггер
+      reset password).
+- [ ] Container Registry — `docker pull cr.yandex/...` на новой
+      машине проходит (это значит, что наша новая аутентификация
+      через OAuth/IAM работает).
+
+### Шаг 8. Заморозка источника
+
+Когда всё подтверждено стабильным (≥ 24 часа):
+
+- Остановить и выключить старую VM в YC.
+- Подождать неделю-две на случай отката.
+- Удалить VM и связанные ресурсы (только compute! S3-бакет с
+  restic-бэкапами и Container Registry **остаются**).
+- Удалить `production.yml`, переименовать `timeweb.yml` →
+  `production.yml`, откатить временную правку `HOSTS_FILE` в
+  `tasks.py` (теперь снова `production.yml`). Закоммитить.
+
+---
+
+## Фаза 2: подключение медленного диска
+
+После того как Timeweb-сервер стабилен:
+
+1. Заказать дополнительный «холодный» диск в Timeweb, прицепить
+   к VPS.
+2. Узнать UUID нового устройства (`lsblk -f`).
+3. Решить, куда монтировать — варианты:
+   - Сохранить текущую схему (`/mnt/applications` на медленном
+     диске целиком). Минус: всё IO приложений уходит на медленный
+     диск.
+   - **Лучше:** оставить `/mnt/applications` на быстром SSD,
+     медленный смонтировать как `/mnt/cold` и под calibre/большие
+     бэкапы делать bind-mount или поменять `data_dir` у нужных
+     приложений.
+4. Восстановить в `playbook-system.yml` mount-задачу с новым
+   UUID (через переменную, заведённую на фазе 1).
+5. Прогнать `inv pl -- system` с тегом `mount-storage`.
+6. Переехать на холодный диск только большие данные. Для calibre
+   это означает остановить контейнер, `rsync` библиотеки книг,
+   поправить `data_dir` в `vars`, запустить.
+
+---
+
+## Что НЕ менять во время миграции
+
+Чтобы не накапливать изменения в одном переезде:
+
+- Версии docker-образов всех приложений — те же, что в источнике.
+- Конфиги приложений — без правок.
+- Restic snapshot policy.
+- Apprise/notification каналы.
+
+Любые улучшения (healthchecks из `docs/drafts/alerts.md`,
+gitea runner и т.п.) — отдельным циклом после миграции.
+
+---
+
+## Откат
+
+Если на target что-то критично сломалось:
+
+1. DNS возвращаем обратно на старый IP.
+2. Старая VM в YC жива и заглушена → стартуем её, поднимаем
+   сервисы (`docker compose up -d` под каждым пользователем).
+3. Изучаем, в чём дело на target, лечим, повторяем cutover.
+
+Поэтому шаг «Заморозка источника» отделён от «удаления» — у нас
+есть «горячее запасное» как минимум на пару дней.
+
+---
+
+## Открытые вопросы
+
+На текущей итерации — нет, все ключевые развилки закрыты:
+
+- ~~Auth для cr.yandex~~ → OAuth-token Яндекса (`yc_oauth_token` в
+  vault, `community.docker.docker_login` в плейбуках).
+- ~~Инвентарь~~ → два отдельных файла, после cutover `timeweb.yml`
+  переименовывается в `production.yml`.
+- ~~Регион/TZ Timeweb~~ → совпадает с текущим.
+- ~~IP-whitelist в конфигах~~ → отсутствует, смена IP безопасна.
+- ~~Объём данных vs 80 ГБ~~ → 22 ГБ всего, из них calibre 16 ГБ;
+  с запасом влезает в фазе 1, второй диск не на критическом пути.
+
+Возможные вопросы по ходу реализации (выяснятся в процессе):
+
+- Конкретная процедура получения OAuth-token Яндекса (через
+  `oauth.yandex.ru` или через `yc` CLI).
+- Поведение Caddy при первом выпуске сертификатов после смены DNS —
+  убедиться, что rate-limit Let's Encrypt не упрётся (≈ 17
+  поддоменов выпускаются сразу, лимит LE — 50 сертификатов в неделю
+  на registered domain, запас есть).
+- Federation Matrix после смены IP — обычно достаточно того, что
+  apex `vakhrushev.me` отдаёт `.well-known/matrix/server`, но
+  стоит проверить через `federationtester.matrix.org` сразу после
+  cutover.