dedinit.ru/openspec/changes/deploy-sftp-incremental/design.md

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с на чтение с сервера; приемлемо по сравнению с перезаливкой.