Обновление с 1.x до 2.0

SnapOtter 1.x хранил всё в одном файле SQLite и работал как один контейнер. SnapOtter 2.0 использует PostgreSQL и Redis. Это руководство описывает перенос установки 1.x на 2.0 без потери данных.

Если коротко: переиспользуйте существующий том /data, и 2.0 автоматически импортирует базу данных 1.x при первом запуске. Ваши пользователи, сохранённые файлы, настройки, ключи API и конвейеры переносятся. Старая база данных никогда не изменяется, поэтому вы всегда можете откатиться назад.

Замечание для наших пользователей 1.x

Многие из вас доверяют SnapOtter с самого начала, и ваши отзывы сформировали этот релиз. 2.0 многое меняет под капотом, и это руководство существует для того, чтобы переход не стоил вам ничего из того, что вам дорого. Ваши учётные записи, файлы, настройки, ключи API и конвейеры переносятся, а старая база данных не затрагивается. Спасибо, что обновляетесь вместе с нами.

Перед началом: сделайте резервную копию всего тома /data

Делайте это первым делом, каждый раз. Резервируйте весь том /data, а не только файл snapotter.db.

Вот почему это важно. 1.x запускает SQLite в режиме WAL, поэтому остановленный контейнер 1.x регулярно оставляет большую часть зафиксированных данных в snapotter.db-wal рядом с почти пустым snapotter.db. Копирование только snapotter.db захватывает пустую базу данных и незаметно теряет всё. Том несёт snapotter.db, snapotter.db-wal, snapotter.db-shm и ваш каталог files/ вместе, и они должны переноситься как единый набор.

# Adjust the volume name to match yours (see "Check your volume name" below).
docker run --rm -v SnapOtter-data:/data -v "$PWD":/backup \
  alpine tar czf /backup/snapotter-1x-data.tgz -C /data .

Сначала обновитесь до 1.17.2

Перед переходом на 2.0 обновите установку 1.x до последнего релиза 1.x (1.17.2). Это позволит 1.x выполнить собственные финальные миграции схемы, чтобы 2.0 импортировал из известной, полной схемы. Обновление со старой версии 1.x сразу до 2.0 не поддерживается.

Проверьте имя тома

Импортёр увидит ваши данные, только если стек 2.0 монтирует тот же том, что использовала установка 1.x. Имена томов Docker чувствительны к регистру, и в старых фрагментах README использовалось строчное snapotter-data, тогда как файлы Compose используют SnapOtter-data. Подтвердите, какое имя у вас:

docker volume ls | grep -i snapotter

Используйте именно это имя в конфигурации 2.0.

Путь A: один контейнер (самый быстрый)

Если вы запускаете SnapOtter одним docker run, продолжайте так же. 2.0 запускает встроенные PostgreSQL и Redis внутри контейнера, когда вы не задаёте DATABASE_URL или REDIS_URL, и автоматически обнаруживает и импортирует /data/snapotter.db при первом запуске.

docker run -d --name snapotter -p 1349:1349 \
  -v SnapOtter-data:/data \
  snapotter/snapotter:latest

Следите за строкой в логах вроде:

Imported 1.x SQLite database: {"tables":{"users":2,"teams":1,...},"blobs":{"present":1,"missing":0}}

Вот и всё. Войдите под своими существующими учётными данными.

Путь B: Compose (рекомендуется для продакшена)

Стек Compose 2.0 запускает три сервиса (приложение, Postgres, Redis). Переиспользуйте том /data из 1.x для сервиса приложения. Приложение автоматически обнаруживает /data/snapotter.db и импортирует его в Postgres при первом запуске.

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    volumes:
      - SnapOtter-data:/data          # your existing 1.x volume
      - SnapOtter-workspace:/tmp/workspace
    environment:
      - DATABASE_URL=postgres://snapotter:snapotter@postgres:5432/snapotter
      - REDIS_URL=redis://:snapotter@redis:6379
    # ...

Если вы предпочитаете указать старую базу данных явно, задайте SQLITE_MIGRATE_PATH=/data/snapotter.db. Явный путь всегда имеет приоритет над автоопределением.

Предварительный просмотр импорта (необязательно)

Чтобы точно увидеть, что будет импортировано, ничего не записывая, выполните пробный запуск для файла базы данных:

pnpm --filter @snapotter/api migrate:sqlite -- /path/to/snapotter.db --dry-run

Он выводит количество строк по таблицам, сколько файлов сохранённой библиотеки найдено на диске, и какие статусы задач будут нормализованы. Ему не нужен работающий Postgres.

Что переносится, а что нет

Переносится:

• Пользователи и возможность входа. Хеши паролей не изменяются, поэтому те же имя пользователя и пароль работают.
• Команды, настройки (включая идентичность экземпляра), роли, ключи API (они продолжают работать) и сохранённые конвейеры.
• Записи истории задач.
• Ваша библиотека сохранённых файлов, как записи, так и сами файлы, потому что /data/files сохраняется на томе.

Не переносится:

• Сессии входа. Все входят один раз после обновления. Учётные данные не изменяются, поэтому это единственный повторный вход, не более того.
• Входные и выходные файлы старых задач обработки. Они находились во временном рабочем пространстве и удалены по замыслу. Записи истории задач сохраняются.
• Пользовательские флаги согласия на аналитику из 1.x, у которых нет эквивалента в 2.0 (аналитика 2.0 — это настройка уровня экземпляра).

Отключение импорта

Если вы намеренно хотите свежую базу данных, даже если на томе присутствует snapotter.db, задайте SQLITE_MIGRATE_PATH=off.

Если в экземпляре 2.0 уже есть данные

Импортёр запускается только для пустой базы данных. Если вы запустили 2.0 с нуля (создав данные), а затем смонтировали старый snapotter.db, 2.0 обнаружит его, но не импортирует, потому что слияние двух наборов данных может привести к конфликту идентификаторов. Вы увидите предупреждение в логах. Чтобы импортировать данные 1.x, вам нужен пустой экземпляр:

• Если экземпляр 2.0 содержит только администратора по умолчанию (вы им фактически не пользовались), остановите стек, удалите том Postgres (SnapOtter-pgdata) и запустите снова с присутствующим старым /data. Импорт пройдёт чисто. Это удалит только временные данные Postgres, а не вашу базу данных 1.x.
• Если экземпляр 2.0 содержит реальные данные, которые вы хотите сохранить, два набора данных нельзя объединить автоматически. Экспортируйте нужное и импортируйте данные 1.x в отдельное свежее развёртывание.

Откат

Обновление никогда не изменяет и не удаляет ваш snapotter.db из 1.x. Если вам нужно вернуться к 1.x, разверните образ 1.x на том же томе. Всё, что вы создали в 2.0 после обновления, находится в Postgres и не будет присутствовать в базе данных 1.x, поэтому откатывайтесь незамедлительно, если собираетесь это делать.