openspec: архив changes series-taxonomy-and-header, archive-by-year-month, deploy-sftp-incremental (2026-09-25)

2026-09-25 08:31:28 +00:00
parent 92b7094fc7
commit 800f93a22f
16 changed files with 97 additions and 4 deletions
@@ -0,0 +1,53 @@
+# Design: Инкрементальный SFTP-деплой
+
+## Проблема
+
+`tools/deploy_sftp.py` mirror-заливал ВСЕ 524 файла (66M) каждый деплой,
+включая неизменные тяжёлые (21M PDF, 11M×2 M4V) — деплой занимал ~36 мин
+(замер №1: run создан 16:54:19Z → прод виден 17:30:20Z). Плюс: при обрыве
+SFTP-соединения скрипт вис бесконечно (нет таймаутов) — оба раза висел на
+`2026/gotosocial-relay-match-by-default/hero.svg`.
+
+## Решение
+
+Единственный файл `tools/deploy_sftp.py`:
+
+1. **Инкремент по (size + SHA1)**: для каждого локального файла — `sftp.stat()`;
+   если удалённый существует и (размер совпадает И SHA1 содержимого совпадает)
+   — пропуск; иначе `sftp.put()`.
+   - mtime НЕ используется: в CI (Gitea Actions) checkout ставит свежий mtime
+     всем файлам → mtime-сравнение бесполезно.
+   - SHA1 читается потоково с удалённого через `sftp.open()` (1MB чанками) —
+     корректно для 21M PDF (несколько секунд).
+   - Для несовпадающих размеров хэш не считается (быстрый путь).
+
+2. **Защита от зависаний**:
+   - `Transport.set_keepalive(15)` — пинги; мёртвое соединение падает само.
+   - `sftp.get_channel().settimeout(120)` — операция дольше 120с прерывается.
+   - `with_retry()` — при исключении переподключение (до 3 попыток, sleep 2с),
+     `put`/`remove` повторяются; после исчерпания — выход с ненулевым кодом.
+
+3. **Mirror-удаление сохранено**: `remote_files - local_files` → `remove()`.
+
+4. **CI**: `python3-paramiko` ставится через **apt** (не pip в venv) — не зависит
+   от PyPI, быстрее (установка случайно занимала 15-20 мин).
+
+## Почему не mtime
+
+В Gitea Actions `actions/checkout` распаковывает репозиторий с текущим mtime →
+все файлы «свежие» относительно сервера → mtime-сравнение никогда не пропускает.
+SHA1 — единственный надёжный индикатор неизменности для CI.
+
+## Альтернативы, отклонённые
+
+- **rsync**: Jino SFTP-only, удалённый exec запрещён.
+- **Манифест (JSON) прошлого деплоя**: усложняет, требует хранения состояния;
+  SHA1-сравнение с сервером самодостаточно.
+- **Только размер**: риск ложного пропуска при изменении содержимого без смены
+  размера (маловероятно для статики, но SHA1 дешевле ошибки).
+
+## Открытые вопросы
+
+- Точное время залива (замер №2) зависит от пропускной способности Jino SFTP.
+- SHA1 крупных файлов при каждом деплое: 21M PDF → ~2-5с на чтение с сервера;
+  приемлемо по сравнению с перезаливкой.