Миграция данных¶

Процедуры переноса Р13.Орбита между окружениями (dev → staging → production) или между серверами.

Типы миграций¶

1. Миграция между окружениями¶

Сценарий: Перенос конфигурации и данных из dev → staging → production

Что переносим: - Конфигурационные файлы (с адаптацией) - Домены данных - Тестовые чаты и датасеты (опционально)

Что НЕ переносим: - Production данные в dev/staging - API ключи и пароли (меняются для каждого окружения)

2. Миграция на новый сервер¶

Сценарий: Переезд на новое железо или в другой дата-центр

Что переносим: - Полная конфигурация - База данных метаданных - Docker образы (опционально, можно загрузить из registry) - Домены данных

3. Миграция версии базы данных¶

Сценарий: Обновление схемы БД метаданных при обновлении Р13.Орбита

Что делаем: - Применение миграций Alembic (автоматически внутри контейнера) - Откат миграций при необходимости

Миграция между окружениями¶

Архитектура окружений¶

Development → Staging → Production
(localhost)   (staging.company.com)   (orbita.company.com)

Рекомендуемый подход: Конфигурация хранится в git, данные мигрируются через резервные копии.

Шаг 1: Подготовка конфигурации для целевого окружения¶

Development (.env.dev)¶

# .env.dev
LLM_BASE_URL=http://localhost:11434  # Ollama локально
LLM_MODEL=llama3
CLICKHOUSE_HOST=localhost
METADATA_DB_URL=sqlite:///~/.orbita/dev_metadata.db

Staging (.env.staging)¶

# .env.staging
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=${STAGING_OPENAI_KEY}
LLM_MODEL=gpt-4
CLICKHOUSE_HOST=clickhouse-staging.company.com
METADATA_DB_URL=postgresql://orbita_user:${STAGING_DB_PASS}@postgres-staging:5432/orbita

Production (.env.prod)¶

# .env.prod
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=${PROD_OPENAI_KEY}
LLM_MODEL=gpt-4
CLICKHOUSE_HOST=clickhouse-prod.company.com
METADATA_DB_URL=postgresql://orbita_user:${PROD_DB_PASS}@postgres-prod:5432/orbita

# Production-specific
API_RATE_LIMIT_ENABLED=true
CORS_ALLOWED_ORIGINS=https://orbita.company.com

Шаг 2: Экспорт конфигурации из исходного окружения¶

# На dev сервере
cd ~/orbita

# Создать пакет для миграции
tar -czf orbita-config-for-staging.tar.gz \
  domains/ \
  docker-compose.yml

# НЕ включаем .env (он специфичен для каждого окружения)

Шаг 3: Импорт конфигурации в целевое окружение¶

# На staging сервере
mkdir -p ~/orbita
cd ~/orbita

# Скопировать пакет (через scp, rsync или другим способом)
scp dev-server:~/orbita/orbita-config-for-staging.tar.gz .

# Распаковать
tar -xzf orbita-config-for-staging.tar.gz

# Создать .env для staging (НЕ копировать из dev!)
cp .env.staging .env
nano .env  # Настроить специфичные для staging параметры

Шаг 4: Запуск в новом окружении¶

# На staging сервере
cd ~/orbita

# Загрузить Docker образ
docker pull your-registry.company.com/orbita:1.3.0

# Запустить
docker run -d \
  --name orbita \
  --restart unless-stopped \
  -p 8000:8000 \
  --env-file .env \
  -v $(pwd)/domains:/app/domains \
  -v $(pwd)/logs:/app/logs \
  your-registry.company.com/orbita:1.3.0

# Проверить
curl http://staging-server:8000/health

Шаг 5: Верификация¶

# Проверить health
curl http://staging-server:8000/health

# Проверить подключение к ClickHouse
curl -X POST http://staging-server:8000/api/v1/queries \
  -H "Content-Type: application/json" \
  -d '{"query": "покажи список доменов"}'

# Проверить логи
docker logs orbita --tail 50

Миграция на новый сервер¶

Полная миграция production системы¶

Подготовка нового сервера¶

# 1. Установить Docker
curl -fsSL https://get.docker.com | sh

# 2. Настроить firewall
sudo ufw allow 8000/tcp  # API порт
sudo ufw enable

# 3. Создать пользователя для Р13.Орбита (опционально)
sudo useradd -m -s /bin/bash orbita
sudo usermod -aG docker orbita

Перенос данных¶

Способ 1: Через резервную копию (рекомендуется)

# На старом сервере - создать полную резервную копию
cd ~/orbita
./backup.sh

# Скопировать резервную копию на новый сервер
rsync -avz /backups/orbita/ new-server:/backups/orbita/

# На новом сервере - восстановить
ssh new-server
/usr/local/bin/orbita-restore.sh /backups/orbita/latest.tar.gz

Способ 2: Прямой перенос через rsync

# На старом сервере
rsync -avz ~/orbita/ new-server:~/orbita/ \
  --exclude 'logs/*' \
  --exclude '*.log'

Перенос базы данных метаданных¶

Для PostgreSQL:

# На старом сервере - создать дамп
docker exec postgres-metadata pg_dump -U orbita_user orbita | gzip > orbita_metadata.sql.gz

# Скопировать на новый сервер
scp orbita_metadata.sql.gz new-server:/tmp/

# На новом сервере - восстановить
gunzip < /tmp/orbita_metadata.sql.gz | \
  docker exec -i postgres-metadata psql -U orbita_user orbita

Для SQLite:

# На старом сервере
scp ~/.orbita/metadata.db new-server:~/.orbita/metadata.db

Обновление сетевых настроек¶

# На новом сервере
cd ~/orbita
nano .env

# Обновить:
# - CLICKHOUSE_HOST (если изменился IP)
# - METADATA_DB_URL (если изменился хост PostgreSQL)
# - API_HOST (если используется не 0.0.0.0)
# - CORS_ALLOWED_ORIGINS (если изменился домен)

# Перезапустить
docker restart orbita

DNS и переключение трафика¶

# Вариант 1: Обновить DNS A-запись
# orbita.company.com  A  <new-server-IP>

# Вариант 2: Через load balancer
# Переключить upstream в nginx/haproxy с old-server на new-server

# Вариант 3: Плавное переключение (Blue-Green Deployment)
# 1. Запустить на новом сервере
# 2. Протестировать через прямой IP
# 3. Переключить DNS
# 4. Дождаться истечения TTL
# 5. Остановить старый сервер

Миграция версии базы данных¶

Автоматические миграции при обновлении¶

Р13.Орбита использует Alembic для управления миграциями базы данных метаданных.

Как это работает:

При запуске нового контейнера Р13.Орбита автоматически применяет pending миграции
Если миграции нет - продолжает работу
Если миграция не удалась - контейнер не запустится

Ручное применение миграций¶

# Проверить текущую версию схемы
docker exec orbita alembic current

# Посмотреть историю миграций
docker exec orbita alembic history

# Применить все pending миграции
docker exec orbita alembic upgrade head

# Применить одну миграцию
docker exec orbita alembic upgrade +1

# Откатить одну миграцию
docker exec orbita alembic downgrade -1

# Откатить до конкретной версии
docker exec orbita alembic downgrade <revision_id>

Миграция с downtime (безопасный подход)¶

# 1. Создать резервную копию
./backup.sh

# 2. Остановить контейнер
docker stop orbita

# 3. Применить миграции вручную (опционально)
docker run --rm \
  --env-file .env \
  your-registry.company.com/orbita:1.3.0 \
  alembic upgrade head

# 4. Запустить новую версию
docker run -d \
  --name orbita \
  --restart unless-stopped \
  -p 8000:8000 \
  --env-file .env \
  -v $(pwd)/domains:/app/domains \
  -v $(pwd)/logs:/app/logs \
  your-registry.company.com/orbita:1.3.0

# 5. Проверить логи
docker logs orbita --tail 50 --follow

Миграция без downtime (zero-downtime)¶

# 1. Запустить новую версию на другом порту
docker run -d \
  --name orbita-new \
  -p 8001:8000 \
  --env-file .env \
  -v $(pwd)/domains:/app/domains \
  -v $(pwd)/logs:/app/logs \
  your-registry.company.com/orbita:1.3.0

# Миграции применятся автоматически при старте

# 2. Проверить работоспособность
curl http://localhost:8001/health

# 3. Переключить load balancer с порта 8000 на 8001

# 4. Дождаться завершения активных запросов на старом контейнере (grace period)
sleep 30

# 5. Остановить старый контейнер
docker stop orbita
docker rm orbita

# 6. Переименовать новый контейнер
docker rename orbita-new orbita

# 7. Обновить порт (если нужно)
docker stop orbita
docker rm orbita
docker run -d \
  --name orbita \
  -p 8000:8000 \
  --env-file .env \
  -v $(pwd)/domains:/app/domains \
  your-registry.company.com/orbita:1.3.0

Миграция доменов данных¶

Добавление нового домена¶

# На dev окружении - создать конфигурацию домена
nano ~/orbita/domains/new_domain.yaml

# Пример структуры:
# domain: new_domain
# description: "Описание нового домена"
# tables:
#   - name: table1
#     description: "Описание таблицы"
#     columns:
#       - name: id
#         type: UInt64
#         description: "Идентификатор"

# Протестировать на dev
docker restart orbita
curl http://localhost:8000/api/v1/domains | jq '.domains[] | select(.name=="new_domain")'

# Если работает - скопировать в staging
scp ~/orbita/domains/new_domain.yaml staging-server:~/orbita/domains/

# На staging - перезапустить
ssh staging-server "docker restart orbita"

# После успешного тестирования - в production
scp ~/orbita/domains/new_domain.yaml prod-server:~/orbita/domains/
ssh prod-server "docker restart orbita"

Обновление существующего домена¶

# 1. Создать резервную копию текущей конфигурации
cp ~/orbita/domains/ecommerce.yaml ~/orbita/domains/ecommerce.yaml.backup

# 2. Обновить домен
nano ~/orbita/domains/ecommerce.yaml

# 3. Проверить синтаксис YAML
python -c "import yaml; yaml.safe_load(open('~/orbita/domains/ecommerce.yaml'))"

# 4. Перезапустить контейнер
docker restart orbita

# 5. Протестировать запросы к обновленному домену
curl -X POST http://localhost:8000/api/v1/queries \
  -H "Content-Type: application/json" \
  -d '{"query": "покажи продажи за последний месяц"}'

# 6. Если всё работает - удалить резервную копию
rm ~/orbita/domains/ecommerce.yaml.backup

Миграция данных ClickHouse¶

Внимание

Р13.Орбита не управляет данными в ClickHouse. ClickHouse является внешним источником данных. Р13.Орбита только читает данные через запросы.

Если нужно перенести сами данные ClickHouse между серверами, используйте стандартные инструменты ClickHouse:

Экспорт данных из ClickHouse¶

# Экспорт таблицы в CSV
clickhouse-client --query "SELECT * FROM ecommerce.orders FORMAT CSV" > orders.csv

# Экспорт в Native формате (быстрее)
clickhouse-client --query "SELECT * FROM ecommerce.orders FORMAT Native" > orders.native

# Экспорт схемы таблицы
clickhouse-client --query "SHOW CREATE TABLE ecommerce.orders" > orders_schema.sql

Импорт данных в ClickHouse¶

# Импорт из CSV
clickhouse-client --query "INSERT INTO ecommerce.orders FORMAT CSV" < orders.csv

# Импорт из Native формата
clickhouse-client --query "INSERT INTO ecommerce.orders FORMAT Native" < orders.native

# Создать таблицу из схемы
clickhouse-client < orders_schema.sql

Контрольный список миграции¶

Миграция между окружениями¶

Создан .env для целевого окружения (НЕ копировать из исходного!)
Скопированы конфигурации доменов
Скопирован docker-compose.yml (если используется)
Обновлены сетевые настройки (хосты БД, API URLs)
Обновлены API ключи для LLM провайдера
Проверено подключение к ClickHouse
Проверено подключение к БД метаданных
Выполнен тестовый запрос
Проверены логи на наличие ошибок

Миграция на новый сервер¶

Миграция версии БД¶

Создана резервная копия БД метаданных
Проверена текущая версия схемы (alembic current)
Применены миграции (alembic upgrade head)
Проверены логи миграций на наличие ошибок
Выполнены тесты API после миграции
Проверена работа CLI
Проверена работа с сохраненными датасетами
Протестированы визуализации

Откат миграции¶

Откат миграции базы данных¶

# Откатить последнюю миграцию
docker exec orbita alembic downgrade -1

# Откатить к конкретной версии
docker exec orbita alembic downgrade <revision_id>

# Откатить все миграции
docker exec orbita alembic downgrade base

# После отката - перезапустить предыдущую версию контейнера
docker stop orbita
docker rm orbita
docker run -d \
  --name orbita \
  -p 8000:8000 \
  --env-file .env \
  -v $(pwd)/domains:/app/domains \
  your-registry.company.com/orbita:1.2.5  # Предыдущая версия

Откат миграции конфигурации¶

# Восстановить из резервной копии
cp ~/orbita/domains/ecommerce.yaml.backup ~/orbita/domains/ecommerce.yaml

# Или из git (если храните конфигурацию в git)
cd ~/orbita
git checkout HEAD~1 domains/ecommerce.yaml

# Перезапустить
docker restart orbita

Автоматизация миграций¶

Скрипт миграции между окружениями¶

#!/bin/bash
# migrate-to-env.sh

set -e

SOURCE_ENV="$1"
TARGET_ENV="$2"

if [ -z "$SOURCE_ENV" ] || [ -z "$TARGET_ENV" ]; then
    echo "Usage: $0 <source-env> <target-env>"
    echo "Example: $0 dev staging"
    exit 1
fi

echo "Migrating from $SOURCE_ENV to $TARGET_ENV"

# Создать пакет миграции
tar -czf orbita-migration-to-$TARGET_ENV.tar.gz \
  -C ~/orbita-$SOURCE_ENV \
  domains/ \
  docker-compose.yml

echo "Migration package created: orbita-migration-to-$TARGET_ENV.tar.gz"
echo "Next steps:"
echo "1. Copy this file to $TARGET_ENV server"
echo "2. Extract: tar -xzf orbita-migration-to-$TARGET_ENV.tar.gz"
echo "3. Create appropriate .env.$TARGET_ENV"
echo "4. Start container with new configuration"

Следующие шаги¶

Обновление версии - процедуры обновления системы
Резервное копирование - создание резервных копий перед миграцией
Восстановление - откат после неудачной миграции
Решение проблем - диагностика проблем миграции