Ru

Инструкция по миграции MySQL → PostgreSQL#

Введение#

ВАЖНО! ЕСЛИ у вас версия AI Server равна или меньше 2.0.0 то в вашей версии используется MySQL и PostgreSQL 16 версии одновременно. В новой версии 2.1.0+ используется только PostgreSQL 17 версии.

Вам необходимо сделать миграцию с mysql на PostgreSQL, а так же выполнить миграцию данных с 16 версии PostgreSQL на 17 версию.

Эта инструкция описывает процесс миграции базы данных Sherpa AI Server с MySQL на PostgreSQL. Миграция включает перенос данных, обновление конфигураций и переход на новую систему управления базами данных.

ВНИМАНИЕ! Если у вас есть возможность ОТКАЗАТЬСЯ ОТ ДАННЫХ (ЕСЛИ ОНИ ВАМ НЕ НУЖНЫ) рекомендуем вместо выполнения данной инструкции перейти к инструкции по установке c нуля:

Установка Sherpa AI Serverdocs.sherparpa.ru

Системные требования#

Минимальные требования для миграции:#

  • Свободное место на диске: минимум 2x размер базы данных (для исходных данных + миграция)
  • Оперативная память: минимум 4 ГБ RAM для pgloader
  • Docker: версия 20.10+ с поддержкой Docker Compose
  • Сетевое подключение: стабильное соединение с базами данных

Предварительные проверки#

Перед запуском миграции выполните следующие проверки:

# Проверьте доступное место на диске
df -h

# Проверьте доступную оперативную память
free -h

# Проверьте статус Docker
docker --version
docker compose version

# Проверьте доступность баз данных
docker ps | grep -E "(mysql|postgres)"
💡 Комментарии к проверкам

df -h - показывает использование дискового пространства в человеко-читаемом формате

  • Проверьте, что свободного места минимум в 2 раза больше размера вашей базы данных

free -h - показывает информацию об оперативной памяти

  • Для pgloader требуется минимум 4 ГБ RAM
  • При недостатке памяти миграция может завершиться с ошибкой "Heap exhausted"

docker --version - проверяет версию Docker

  • Требуется Docker 20.10+ для корректной работы всех функций

docker compose version - проверяет версию Docker Compose

  • Убедитесь, что compose поддерживает современный синтаксис

docker ps - показывает запущенные контейнеры

  • Должны быть видны контейнеры mysql/postgres для доступа к данным

Подготовка к миграции#

Скачивание необходимых файлов#

Если контур закрыт, необходимо скачать заранее АРХИВЫ ДЛЯ УСТАНОВКИ и в дополнение следующие файлы:

curl -fSL -OJ https://sherparpa.ru/downloads/private/SherpaAIServer/pgloader_image.tar
curl -fSL -OJ https://sherparpa.ru/downloads/private/SherpaAIServer/alpine_image.tar
💡 Комментарии к скачиванию файлов

curl -fSL -OJ - скачивает файлы с сервера

  • -f - тихо завершается при ошибках сервера
  • -S - показывает ошибки даже при использовании -f
  • -L - следует редиректам
  • -O - сохраняет файл с именем с сервера
  • -J - использует имя файла, предоставленное сервером

pgloader_image.tar - Docker-образ с инструментом pgloader для переноса данных alpine_image.tar - легковесный Linux-образ для операций с файлами

Создайте директорию /opt/SherpaAIServerNew и поместите в нее все скачанные архивы И ФАЙЛЫ ИЗ ИНСТРУКЦИИ ПО УСТАНОВКЕ:

# Создайте новую директорию для миграции
sudo mkdir -p /opt/SherpaAIServerNew

# Переместите скачанные файлы в новую директорию (и файлы из подготовки к скачиванию)
sudo mv pgloader_image.tar /opt/SherpaAIServerNew/
sudo mv alpine_image.tar /opt/SherpaAIServerNew/
💡 Комментарии к подготовке директории

sudo mkdir -p - создает директорию с родительскими папками

  • -p предотвращает ошибку если директория уже существует

sudo mv - перемещает файлы в новую директорию

  • Перемещение в /opt/SherpaAIServerNew изолирует файлы миграции от текущей установки

Что скачивается:

  • pgloader_image.tar - Docker-образ с pgloader и необходимыми инструментами
  • alpine_image.tar - легковесный образ Alpine Linux для работы с volume (не влияет на вашу текущую операционную систему)

Остановка сервисов#

  1. Остановка контейнеров кроме баз данных:
# перейти в старую директорию
cd /opt/SherpaAIServer/

docker compose stop orchestrator embed nginx vllm
docker-compose stop orchestrator embed nginx vllm

# перейти в новую директорию
cd /opt/SherpaAIServerNew/
💡 Комментарии к остановке сервисов

docker compose stop - останавливает указанные сервисы без удаления

  • orchestrator - основной сервис оркестрации
  • embed - сервис для работы с эмбеддингами
  • nginx - веб-сервер и прокси
  • vllm - сервис языковой модели

Две команды - выполнены обе версии синтаксиса для совместимости Оставшиеся сервисы - pgembeding (PostgreSQL с эмбеддингами) и orchestrator-db (MySQL) должны продолжать работать для доступа к данным

Почему останавливаем сервисы: Во время миграции необходимо исключить любые изменения в базе данных, чтобы обеспечить консистентность данных.

Примечание: Не нужно удалять контейнеры, только остановить. Должны остаться pgembeding и orchestrator-db.

Создание резервных копий#

Определение имен volumes:

Сначала найдите правильные имена volumes в вашей системе:

docker volume list
💡 Комментарии к определению volumes

docker volume list - показывает все Docker volumes в системе

  • DRIVER - тип драйвера (обычно local)
  • VOLUME NAME - уникальное имя volume

Префикс имен - зависит от названия папки проекта:

  • Для папки SherpaAIServer → префикс sherpaaiserver_
  • Для папки myproject → префикс myproject_

Основные volumes:

  • *orchestrator-mysql-data - данные MySQL базы
  • *pgdata - данные PostgreSQL базы
  • *storage - файловое хранилище

Пример вывода:

DRIVER    VOLUME NAME
local     sherpaaiserver_orchestrator-mysql-data
local     sherpaaiserver_pgdata
local     sherpaaiserver_storage

Создание бэкапов volume:

Замените имена volumes на актуальные из вашего списка:

# Бэкап MySQL данных (замените VOLUME_NAME на реальное имя)
docker run --rm -v VOLUME_NAME:/data -v $(pwd)/backup_mysql:/backup pgembeding tar czf /backup/mysql_backup.tar.gz -C /data .

# Бэкап PostgreSQL данных (если существуют) (замените VOLUME_NAME на реальное имя с postgres)
docker run --rm -v VOLUME_NAME:/data -v $(pwd)/backup_pg:/backup pgembeding tar czf /backup/pg_backup.tar.gz -C /data .
💡 Комментарии к созданию бэкапов

docker run --rm - запускает контейнер и автоматически удаляет его после выполнения

  • --rm предотвращает накопление остановленных контейнеров

Монтирование volumes:

  • -v VOLUME_NAME:/data - монтирует Docker volume в контейнер
  • -v $(pwd)/backup_mysql:/backup - монтирует локальную папку для сохранения архива

tar czf - создает сжатый архив

  • c - создать архив
  • z - сжать с помощью gzip
  • f - указать имя файла
  • -C /data . - изменяет директорию на /data перед архивацией

pgembeding - использует существующий образ PostgreSQL с инструментами

Примеры с конкретными именами:

Для проекта в папке SherpaAIServer:

docker run --rm -v sherpaaiserver_orchestrator-mysql-data:/data -v $(pwd)/backup_mysql:/backup pgembeding tar czf /backup/mysql_backup.tar.gz -C /data .
docker run --rm -v sherpaaiserver_pgdata:/data -v $(pwd)/backup_pg:/backup pgembeding tar czf /backup/pg_backup.tar.gz -C /data .
💡 Пример для Sherpa AI Server

Первый volume: sherpaaiserver_orchestrator-mysql-data

  • Содержит данные MySQL базы orchestrator
  • Архив сохраняется в backup_mysql/mysql_backup.tar.gz

Второй volume: sherpaaiserver_pgdata

  • Содержит данные PostgreSQL базы (если есть)
  • Архив сохраняется в backup_pg/pg_backup.tar.gz

Для проекта в папке myproject:

docker run --rm -v myproject_orchestrator-mysql-data:/data -v $(pwd)/backup_mysql:/backup pgembeding tar czf /backup/mysql_backup.tar.gz -C /data .
docker run --rm -v myproject_pgdata:/data -v $(pwd)/backup_pg:/backup pgembeding tar czf /backup/pg_backup.tar.gz -C /data .
💡 Пример для myproject

Первый volume: myproject_orchestrator-mysql-data

  • Аналогично, но с префиксом myproject_
  • Используйте реальное имя папки вашего проекта

Второй volume: myproject_pgdata

  • PostgreSQL данные с соответствующим префиксом
💡 Что делают эти команды
  • Создают сжатые архивы всех данных из Docker volume
  • Архивы сохраняются в локальные директории backup_mysql и backup_pg

Проверка созданных бэкапов:

# Проверьте размер архивов
ls -lh backup_mysql/ backup_pg/

# Проверьте содержимое архивов
tar -tzf backup_mysql/mysql_backup.tar.gz | head -20
💡 Комментарии к проверке бэкапов

ls -lh - показывает подробную информацию о файлах

  • -l - длинный формат
  • -h - размеры в человеко-читаемом виде
  • Проверьте, что архивы имеют разумный размер

tar -tzf - показывает содержимое архива без распаковки

  • -t - список содержимого
  • -z - распаковать с помощью gzip
  • -f - указать имя файла
  • | head -20 - показывает первые 20 файлов

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

Основная логика миграции#

Разархивирование и подготовка инструментов#

  1. Разархивировать client files:
tar -xvzf "$(ls client_files_*.tgz | sort -V | tail -n 1)"
💡 Комментарии к разархивированию

tar -xvzf - распаковывает архив

  • -x - извлечь
  • -v - подробный вывод
  • -z - распаковать с помощью gzip
  • -f - указать имя файла

Подкоманда выбора файла:

  • ls client_files_*.tgz - находит все архивы client-files
  • sort -V - сортирует по версии (1.0, 1.1, 2.0 и т.д.)
  • tail -n 1 - берет последний (самый свежий) файл

Результат: Создается папка pgloader с инструментами миграции

  1. Перейти в директорию pgloader:
cd pgloader
💡 Комментарии к переходу в директорию

cd pgloader - переходит в папку с инструментами миграции

  • Все последующие команды выполняются из этой директории
  • Содержит скрипты и конфигурации для pgloader
  1. Загрузка Docker-образа pgloader:
./load_pgloader.sh
💡 Комментарии к загрузке образа

./load_pgloader.sh - скрипт загрузки Docker-образа

  • Импортирует pgloader_image.tar в локальный Docker daemon
  • После выполнения образ становится доступен как pgloader:latest
  • Может занять несколько минут в зависимости от размера образа
  1. Сборка контейнера для миграции:
./run.sh build
💡 Комментарии к сборке контейнера

./run.sh build - собирает Docker-контейнер для миграции

  • Создает контейнер на основе загруженного образа pgloader
  • Настраивает все необходимые зависимости и инструменты
  • После сборки контейнер готов к выполнению миграции

Настройка конфигурации миграции#

Создание файла .env с параметрами подключения:

Все пароли можно найти в файле oais/backend/config/config.ini.

cp .env.template .env

nano .env

# URI для исходной MySQL базы данных
MIGRATE_MYSQL="mysql://user:pass@host:port/db"

# URI для целевой PostgreSQL базы данных
MIGRATE_PG="postgres://user:pass@host:port/db"

# Параметры для создания дампа (опционально)
DUMP_PATH="/path/для/дампа"
DUMP_URI="mysql://user:pass@host/db"

# Параметры для восстановления (опционально)
RESTORE_URI="postgres://user:pass@host/db"
RESTORE_PATH="/path/к/дампу.sql"
💡 Комментарии к переменным окружения

MIGRATE_MYSQL - URI подключения к исходной MySQL базе

  • Формат: mysql://username:password@host:port/database
  • Используется pgloader для чтения данных

MIGRATE_PG - URI подключения к целевой PostgreSQL базе

  • Формат: postgres://username:password@host:port/database
  • Должна быть доступна для записи данных

DUMP_ / RESTORE_ ** - опциональные параметры для создания/восстановления дампов

  • Полезны для отладки или поэтапной миграции

Пример рабочей конфигурации:

# Для MySQL базы данных
DUMP_URI="mysql://root:pass@91.206.149.183:3306/orchestrator"
MIGRATE_MYSQL="mysql://root:pass@91.206.149.183:3306/orchestrator"

# Для PostgreSQL базы данных
MIGRATE_PG="postgres://postgres:pass@91.206.149.183:5432/postgres"
💡 Пример конфигурации

MySQL параметры:

  • Хост: 91.206.149.183 (внешний сервер)
  • Порт: 3306 (стандартный для MySQL)
  • База: orchestrator
  • Пользователь: root (с полными правами)

PostgreSQL параметры:

  • Хост: тот же сервер
  • Порт: 5432 (стандартный для PostgreSQL)
  • База: postgres (системная база)
  • Пользователь: postgres (администратор)

Важно: Пароли должны быть взяты из существующего config.ini

Важно: Убедитесь, что порты и хосты доступны из контейнера Docker.

Выполнение миграции#

Тестовый запуск (рекомендуется)

./run.sh dry-run
💡 Комментарии к тестовому запуску

./run.sh dry-run - симуляция миграции без изменений

  • Подключается к обеим базам данных
  • Анализирует структуру и данные
  • Показывает план миграции и потенциальные проблемы
  • Не вносит никаких изменений в PostgreSQL

Проверяет:

  • Доступность и корректность подключений
  • Совместимость типов данных MySQL → PostgreSQL
  • Наличие всех таблиц и связей
  • Ожидаемый объем данных для переноса

Рекомендация: Всегда выполняйте dry-run перед реальной миграцией

Основная миграция

./run.sh migrate
💡 Комментарии к основной миграции

./run.sh migrate - выполняет фактическую миграцию данных

  • Создает схему orchestrator в PostgreSQL
  • Переносит структуру таблиц с преобразованием типов
  • Копирует все данные из MySQL в PostgreSQL
  • Создает индексы и ограничения целостности

Этапы выполнения:

  1. Проверка подключений и прав доступа
  2. Создание схемы базы данных
  3. Миграция структуры (таблицы, типы данных)
  4. Перенос данных с оптимизацией производительности
  5. Создание индексов и ограничений

Важно: Процесс может быть долгим для больших баз данных

Опции миграции:

  • --force - выполнить миграцию даже если схема уже существует
  • --build - пересобрать контейнер перед запуском
  • --rmi - удалить образ после завершения

Время выполнения: Зависит от размера базы данных. Для баз до 10 ГБ - от 30 минут до нескольких часов. Для больших баз - может занять несколько часов или дней.

Очистка после миграции#

# Удаление Docker-образа pgloader (опционально)
./run.sh rmi

# Возврат в корневую директорию проекта
cd ..
💡 Комментарии к очистке

./run.sh rmi - удаляет Docker-образ pgloader

  • Освобождает дисковое пространство
  • Удаляет временные образы и контейнеры
  • Опционально - можно оставить для повторного использования

cd .. - возвращает в родительскую директорию

  • Выходит из папки pgloader
  • Возвращает в корень проекта SherpaAIServer

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

Копирование данных в новые volumes#

После успешной миграции базы данных может потребоваться перенос файлового хранилища между Docker volumes.

Загрузка Alpine образа#

docker load -i alpine_image.tar
💡 Комментарии к загрузке Alpine

docker load -i - импортирует Docker-образ из tar-архива

  • -i - читать из локально сохраненного tar-архива
  • Загружает образ в локальный Docker daemon

Alpine Linux - минималистичный дистрибутив Linux

  • Размер образа ~5-10 МБ (в сравнении с Ubuntu ~100+ МБ)
  • Содержит только необходимые инструменты (cp, ls, tar и т.д.)
  • Идеален для операций с файлами в контейнерах

Использование: Для копирования данных между Docker volumes

Создание нового volume#

docker volume create aiserver-storage
💡 Комментарии к созданию volume

docker volume create - создает новый именованный Docker volume

  • aiserver-storage - имя для нового volume
  • Volume создается пустым и готовым для использования

Характеристики volume:

  • Управляется Docker автоматически
  • Доступен всем контейнерам на хосте
  • Сохраняется при перезапуске Docker daemon
  • Поддерживает snapshot и backup операции

Назначение: Хранилище файлов Sherpa AIServer (загрузки, кэш, логи и т.д.)

Определение текущих volumes#

Найти имена используемых volumes:

docker volume list
💡 Повторное определение volumes

docker volume list - повторная проверка списка volumes

  • Убеждаемся, что все volumes доступны
  • Проверяем корректность имен перед копированием данных

Важно: Сравните с результатами первой проверки

  • Убедитесь, что volumes не были случайно удалены
  • Проверьте доступность всех необходимых данных

Пример вывода (имена зависят от названия папки проекта):

DRIVER    VOLUME NAME
local     sherpaaiserver_orchestrator-mysql-data
local     sherpaaiserver_pgdata
local     sherpaaiserver_storage

Или, если папка проекта называется иначе (например, myproject):

DRIVER    VOLUME NAME
local     myproject_orchestrator-mysql-data
local     myproject_pgdata
local     myproject_storage

Перенос данных между volumes#

Определить источник данных:

В команде ниже замените STORAGE_DATA на имя вашего текущего volume для хранения данных (например, sherpaaiserver_storage):

docker run --rm \
  -v STORAGE_DATA:/from \
  -v aiserver-storage:/to \
  alpine ash -c "cp -av /from/. /to/"
💡 Комментарии к переносу данных

docker run --rm - запускает временный контейнер Alpine

  • --rm - контейнер удалится после выполнения

Монтирование volumes:

  • -v STORAGE_DATA:/from - исходный volume монтируется в /from
  • -v aiserver-storage:/to - целевой volume монтируется в /to

ash -c - выполняет команду в shell Alpine

  • ash - Almquist shell (легковесный)
  • -c - выполнить команду

cp -av /from/. /to/ - копирует все файлы

  • -a - режим архивации (сохраняет права, владельцев, временные метки)
  • -v - подробный вывод
  • /from/. - копирует содержимое, а не саму папку /from
  • /to/ - в целевую директорию

Пример замены: STORAGE_DATA → sherpaaiserver_storage

Проверка успешности копирования:

# Проверить содержимое нового volume
docker run --rm -v aiserver-storage:/data alpine ls -la /data

# Сравнить размеры (примерные)
docker run --rm -v STORAGE_DATA:/data alpine du -sh /data
docker run --rm -v aiserver-storage:/data alpine du -sh /data
💡 Комментарии к проверке копирования

docker run --rm -v aiserver-storage:/data alpine ls -la /data

  • Проверяет содержимое нового volume
  • ls -la показывает все файлы с правами доступа и размерами
  • Убеждаемся, что файлы скопировались корректно

docker run --rm -v STORAGE_DATA:/data alpine du -sh /data

  • Проверяет размер исходного volume
  • du -sh - использование диска, сводка, человеко-читаемый формат
  • Сравниваем размеры для проверки полноты копирования

Ожидания:

  • Количество файлов должно совпадать
  • Размеры должны быть примерно равны
  • Структура директорий должна быть идентичной

Если размеры отличаются: Проверьте логи копирования на ошибки

Миграция с PostgreSQL 16 на 17 версию#

Подготовка к обновлению версии PostgreSQL#

Предварительные действия:

  1. Оставить старую базу данных запущенной - контейнер pgembeding должен продолжать работать
  2. Распаковать новые client-files - в архиве должны быть обновленные docker-compose.yml и .env
  3. Перенести конфигурацию - скопировать параметры подключения из старой версии /opt/SherpaAIServer/oais/backend/config/config.ini в новый .env
  4. Изменить порт - временно установить порт 5433 для новой PostgreSQL, чтобы избежать конфликта

Распаковка архива с клиентскими файлами#

# Найдите и распакуйте архив (автоматически выбирается самая свежая версия)
tar -xvzf "$(ls client_files_*.tgz | sort -V | tail -n 1)"
💡 Что делает эта команда
  • ls client_files_*.tgz - находит все файлы архивов
  • sort -V - сортирует версии естественно (1.0 < 1.1 < 1.10)
  • tail -n 1 - выбирает самый свежий файл
  • tar -xvzf - распаковывает архив с выводом содержимого

Ожидаемый результат: Будет создана директория sh_scripts/ с исполняемыми скриптами и другие необходимые файлы.

Подготовка скриптов к выполнению#

# Перейдите в директорию со скриптами
cd sh_scripts/

# Сделайте все скрипты исполняемыми
chmod +x *.sh

# Вернитесь в корневую директорию проекта
cd ..
💡 Что делают эти команды
  • chmod +x *.sh - устанавливает права исполнения для всех shell-скриптов
  • Это необходимо для запуска скриптов в следующих этапах установки

Структура распакованного архива:#

После распаковки вы должны увидеть следующие файлы и директории:

  • sh_scripts/ - директория с установочными скриптами
    • download_all_latest_docker_images.sh - скрипт для скачивания Docker-образов
    • load_all_docker_images.sh - скрипт для загрузки образов в Docker
    • extract_models.sh - скрипт для распаковки моделей ИИ
    • extract_llama.sh - скрипт для распаковки LLM-моделей
  • docker-compose.yml - конфигурация Docker Compose для клиентской установки
  • .env - файл с переменными окружения для настройки системы

Загрузка Docker-образов#

# Запустите скрипт загрузки Docker-образов
sudo ./sh_scripts/load_all_docker_images.sh
💡 Что делает скрипт
  1. Загружает все Docker-образы из скачанных .tar.gz файлов
  2. Импортирует образы в локальный Docker registry
  3. Проверяет успешность загрузки

Распаковка моделей ИИ#

# Запустите скрипт распаковки основных моделей
sudo ./sh_scripts/extract_models.sh
💡 Что делает скрипт
  1. Распаковывает модель Whisper для распознавания речи
  2. Распаковывает модель BGE Reranker для улучшения поиска
  3. Распаковывает модели для генерации эмбеддингов
  4. Создает необходимые директории
  5. Проверяет успешность распаковки
# Запустите скрипт распаковки LLM модели
sudo ./sh_scripts/extract_llama.sh
💡 Что делает скрипт
  1. Распаковывает модель Llama 3 для языкового моделирования
  2. Удаляет префикс model-store/ из путей файлов
  3. Помещает файлы непосредственно в директорию моделей
  4. Проверяет содержимое после распаковки

Структура директорий после распаковки(примерная):#

./whisper/
└── models/
    ├── base.pt
    └── ...

./bge_reranker/
└── models/
    └── bge-reranker-large/
        ├── config.json
        ├── model.bin
        └── ...

./embed-server/app/
└── model-store/
    └── sentence-transformers/
        └── paraphrase-multilingual-MiniLM-L12-v2/
            ├── config.json
            ├── pytorch_model.bin
            └── ...

./llm-server/models/
├── meta-llama/
│   └── Meta-Llama-3-8B-Instruct/
│       ├── config.json
│       ├── model-00001-of-00004.safetensors
│       ├── model-00002-of-00004.safetensors
│       └── ...
└── tokenizer.json

Запуск новой версии PostgreSQL#

docker compose up -d
💡 Комментарии к запуску новой версии

docker compose up -d - запускает сервисы в фоне

  • -d - отсоединенный режим (работа в фоне)
  • Запускает все сервисы из docker-compose.yml
  • Включает PostgreSQL 17 в контейнере aiserver-pg

Важно:

  • Старая база данных должна продолжать работать
  • Новая версия запускается на другом порту (5433)
  • Процесс инициализации может занять несколько минут

Мониторинг запуска:

# Следить за логами инициализации
docker logs aiserver

# Проверить статус контейнеров
docker ps | grep aiserver
💡 Комментарии к мониторингу

docker logs aiserver - показывает логи контейнера

  • Следит за процессом инициализации PostgreSQL
  • Ищет сообщения об успешном запуске и применении миграций
  • Прерывать можно Ctrl+C

docker ps | grep aiserver - проверяет статус

  • docker ps - показывает запущенные контейнеры
  • grep aiserver - фильтрует по имени
  • Должен показать контейнер aiserver-pg в состоянии Up

Остановка сервисов для переноса данных#

Остановить все сервисы кроме новой базы данных:

docker-compose stop aiserver aiserver-code_interpreter aiserver-llm-server aiserver-embed aiserver-whisper aiserver-bge_reranker
docker compose stop aiserver aiserver-code_interpreter aiserver-llm-server aiserver-embed aiserver-whisper aiserver-bge_reranker
💡 Комментарии к остановке сервисов

docker compose stop - останавливает указанные сервисы

  • Выполняются обе версии синтаксиса для совместимости
  • Останавливаются все сервисы Sherpa AIServer кроме базы данных

Останавливаемые сервисы:

  • aiserver - основной веб-сервер
  • aiserver-code_interpreter - интерпретатор кода
  • aiserver-llm-server - языковая модель
  • aiserver-embed - сервис эмбеддингов
  • aiserver-whisper - сервис распознавания речи
  • aiserver-bge_reranker - сервис ранжирования

Результат: Только aiserver-pg (новая PostgreSQL) продолжает работать

Перенос данных между версиями#

Выполнить последовательность команд для переноса данных:

# 1. Создать дамп из старой базы
docker exec -t postgres pg_dump -U postgres -d postgres -Fc -f /tmp/postgres.dump && \

# 2. Скопировать дамп на хост
docker cp postgres:/tmp/postgres.dump ./postgres.dump && \

# 3. Удалить старую базу в новом контейнере
docker exec -it aiserver-pg psql -U postgres -d template1 -c "DROP DATABASE IF EXISTS postgres;" && \

# 4. Создать новую базу
docker exec -it aiserver-pg psql -U postgres -d template1 -c "CREATE DATABASE postgres;" && \

# 5. Создать необходимые расширения
docker exec -it aiserver-pg psql -U postgres -d postgres -c "CREATE EXTENSION IF NOT EXISTS embedding;" && \
docker exec -it aiserver-pg psql -U postgres -d postgres -c "CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";" && \

# 6. Скопировать дамп в новый контейнер
docker cp ./postgres.dump aiserver-pg:/tmp/postgres.dump && \

# 7. Восстановить данные
docker exec -t aiserver-pg pg_restore -U postgres -d postgres /tmp/postgres.dump
💡 Комментарии к переносу между версиями PostgreSQL

Шаг 1: Создание дампа из старой базы

  • docker exec -t postgres - выполняет команду в контейнере postgres (версия 16)
  • pg_dump -U postgres -d postgres -Fc - создает специальный формат дампа
  • -Fc - сжатый специальный формат (лучше для больших БД)
  • Сохраняется в /tmp/postgres.dump внутри контейнера

Шаг 2: Копирование дампа на хост

  • docker cp postgres:/tmp/postgres.dump ./postgres.dump
  • Переносит дамп из контейнера на локальный диск
  • Необходим для передачи между контейнерами

Шаг 3: Удаление старой базы в новом контейнере

  • Подключается к системной базе template1
  • Удаляет существующую базу postgres (если есть)

Шаг 4: Создание новой базы

  • Создает чистую базу данных postgres в контейнере aiserver-pg

Шаг 5: Создание расширений

  • embedding - расширение для векторных эмбеддингов
  • uuid-ossp - генерация UUID (нужно для некоторых таблиц)

Шаг 6: Копирование дампа в новый контейнер

  • Обратная операция копирования
  • Помещает дамп в контейнер aiserver-pg

Шаг 7: Восстановление данных

  • pg_restore - восстанавливает из специального формата дампа
  • -t - выделяет TTY для прогресса
  • Автоматически создает таблицы, индексы и данные

Валидация результатов миграции#

Проверка корректности переноса данных#

Базовые проверки:

# Подключиться к новой базе данных
docker exec -it aiserver-pg psql -U postgres -d postgres

# Проверить количество таблиц
\dt orchestrator.*

# Проверить количество записей в основных таблицах
SELECT schemaname, tablename, n_tup_ins AS rows
FROM pg_stat_user_tables
WHERE schemaname = 'orchestrator'
ORDER BY n_tup_ins DESC;

# Проверить наличие расширений
\dx

# Выйти из psql
\q
💡 Комментарии к базовым проверкам

docker exec -it aiserver-pg psql -U postgres -d postgres

  • Подключается к PostgreSQL в интерактивном режиме
  • -it - интерактивный терминал
  • -U postgres - пользователь postgres
  • -d postgres - база данных postgres

\dt orchestrator.* - показывает все таблицы в схеме orchestrator

  • \dt - список таблиц
  • orchestrator.* - фильтр по схеме

SELECT ... FROM pg_stat_user_tables - статистика по таблицам

  • n_tup_ins - количество вставленных строк (примерное количество записей)
  • Сортировка по убыванию показывает самые большие таблицы

\dx - показывает установленные расширения

  • Должны быть видны embedding и uuid-ossp

\q - выход из psql

Тестирование функциональности#

  1. Запустить основные сервисы Sherpa AI Server
  2. Выполнить тестовые запросы к API
  3. Проверить работу веб-интерфейса
  4. Выполнить базовые операции с данными

Диагностика и устранение проблем#

Распространенные ошибки и решения#

Если возникли ошибки миграции обратитесь за помощью в техподдержку, а пока вы можете вернутся в старую директорию /opt/SherpaAIServer и запустить на прошлых настройках Sherpa AI Server

"Heap exhausted" или нехватка памяти

Решение: Увеличить лимит памяти для pgloader
export SBCL_DYNAMIC_SPACE_SIZE=8192

Ошибка подключения к базе данных

Проверки:
- Проверить доступность портов: telnet host port
- Проверить корректность учетных данных
- Проверить сетевую доступность контейнеров

Нарушение целостности данных

Действия:
1. Проверить логи pgloader: cat migrate.log
2. Сравнить количество записей в исходной и целевой БД
3. Проверить наличие всех таблиц и индексов

Прерывание миграции

Действия:
- Не перезапускать миграцию
- Обратиться в техническую поддержку с логами
- Предоставить: migrate.log, конфигурацию .env, размер базы данных
💡 Комментарии к мониторингу миграции

tail -f migrate.log - следит за логами в реальном времени

  • -f - следить (обновляется при добавлении новых строк)
  • Показывает прогресс миграции pgloader
  • Ищет ошибки или предупреждения

docker stats - мониторит использование ресурсов контейнерами

  • Показывает CPU, память, сеть, диск для всех контейнеров
  • Полезно для отслеживания нагрузки на систему
  • Прерывать Ctrl+C

watch -n 30 - повторяет команду каждые 30 секунд

  • Подсчитывает общее количество записей во всех таблицах orchestrator
  • watch - утилита для периодического выполнения команд
  • -n 30 - интервал 30 секунд

Использование: Держать эти команды в отдельных терминалах во время миграции

Завершение миграции#

После успешного выполнения всех шагов:

  1. Запустить все сервисы Sherpa AI Server
  2. Выполнить финальное тестирование системы
  3. Удалить временные файлы и старые контейнеры (при необходимости)

Рекомендация: Сохраните логи миграции и конфигурационные файлы для будущих ссылок.