Обновление AW¶

Внимание Перед переходом на релиз 1.39 требуется изучить рекомендации по обновлению предыдущих версий (начиная от вашей текущей).

Внимание!!! Перед обновлением на версию 1.38 и старше необходимо обновиться на 1.37.4.

Внимание Перед переходом на релиз 1.39 настоятельно рекомендуется выполнить резервное копирование БД AW и проверить наличие свободного места на диске (см. ниже).

Технические изменения в выпуске AW 1.39.*¶

Обновление PostgreSQL до версии 18¶

Все базы данных PostgreSQL в составе AW (основная БД db, БД Airflow etl-airflow-db, БД MLflow etl-mlflow-db) переведены на PostgreSQL 18.

Перенос данных выполняется автоматически при первом запуске новой версии с помощью служебных одноразовых сервисов db-upgrade, etl-airflow-db-upgrade и etl-mlflow-db-upgrade. Сервисы баз данных запускаются только после успешного завершения соответствующего сервиса обновления — при ошибке обновления база не стартует, а приложение не увидит частично перенесённые данные.

Обновление выполняется в режиме копирования: данные каждой базы копируются в новый каталог, а старый каталог не изменяется и остаётся резервной копией.

База данных	Старый каталог (резервная копия)	Новый каталог	Переменная
Основная БД (PostgreSQL 13)	../db/postgres	../db/postgres18	AW_DB_POSTGRES18_DIR
БД Airflow (PostgreSQL 12)	../db/airflow	../db/airflow18	AW_DB_AIRFLOW_POSTGRES18_DIR
БД MLflow (PostgreSQL 15)	../db/mlflow	../db/mlflow18	ML_FLOW_POSTGRES18_DIR

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

требуется = размер_базы × 1.5 + 256 МиБ

Например, для базы размером 40 ГиБ требуется около 60 ГиБ свободного места. Оценить размер баз и свободное место можно командами (из рабочей директории приложения):

du -sh ../db/postgres ../db/airflow ../db/mlflow
df -h ../db

Если места недостаточно, обновление не начнется (сервис *-upgrade завершится с ошибкой, в его логе будет указано требуемое и доступное место). В этом случае освободите место на диске или укажите для нового каталога путь на другом диске с помощью переменных AW_DB_POSTGRES18_DIR, AW_DB_AIRFLOW_POSTGRES18_DIR, ML_FLOW_POSTGRES18_DIR.

На большой базе первый запуск после обновления занимает больше времени, чем обычно, — в это время копируются данные. Ход обновления можно посмотреть в логе сервиса:

docker compose logs -f db-upgrade

Лог также сохраняется в файл pg-upgrade-to-18.log в новом каталоге базы. Повторный запуск безопасен: уже обновленные базы пропускаются.

После нескольких дней стабильной работы старые каталоги (../db/postgres, ../db/airflow, ../db/mlflow) можно удалить вручную, чтобы освободить место.

Откат. Так как старые каталоги не изменяются, для отката достаточно остановить AW и развернуть предыдущую версию. Данные, записанные после обновления, при откате будут потеряны, поэтому откат имеет смысл только сразу после обновления.

Переход на аутентификацию SCRAM¶

В PostgreSQL 18 метод шифрования паролей md5 объявлен устаревшим, поэтому AW переведен на scram-sha-256:

pgbouncer обновлен до версии 1.25 и работает с AUTH_TYPE: scram-sha-256;
при переносе базы пароль суперпользователя перешифровывается из md5 в scram-sha-256 (сам пароль не меняется, берется из переменных .env);
если в базе есть созданные вручную роли с md5-паролями, их список выводится в лог сервиса db-upgrade. Пароли таких ролей рекомендуется перешифровать командой ALTER ROLE ... WITH PASSWORD '...'.

Ошибка FATAL: server login failed: wrong password type в логах pgbouncer или приложения означает, что используется pgbouncer со старыми настройками. Убедитесь, что используется docker-compose.yml из нового релиза.

Изменения в конфигурации¶

Добавлены сервисы:

db-upgrade, etl-airflow-db-upgrade, etl-mlflow-db-upgrade — одноразовые сервисы обновления PostgreSQL до версии 18 (см. выше);
code-model-changes — обработка изменений кодовых моделей;
mcp — MCP-сервер AW, доступен по адресу <адрес AW>/mcp.

Внимание!! Если вы используете измененный конфигурационный файл web-сервера Nginx (по умолчанию /opt/aw/app/docker/nginx/nginx.conf) или внешний Nginx, добавьте в него проксирование на сервис mcp:

location ~ ^/mcp {
    proxy_pass http://mcp;
    proxy_set_header Host $http_host;
    proxy_redirect off;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_read_timeout 3600;
}

Добавлены переменные:

Переменная	Описание	Значение по умолчанию
AW_DB_POSTGRES18_DIR	Каталог основной БД (PostgreSQL 18)	../db/postgres18
AW_DB_AIRFLOW_POSTGRES18_DIR	Каталог БД Airflow (PostgreSQL 18)	../db/airflow18
ML_FLOW_POSTGRES18_DIR	Каталог БД MLflow (PostgreSQL 18)	../db/mlflow18
AW_WIDGET_MAX_RESULT_BYTES	Предел объема результата запроса виджета в ClickHouse, байт. 0 — лимит выключен	268435456 (256 МиБ)
AW_WIDGET_MAX_MEMORY_USAGE	Предел памяти одного запроса виджета в ClickHouse, байт. 0 — действует профиль пользователя ClickHouse	0
AW_WIDGET_PHP_MEMORY_LIMIT	Предел памяти процесса PHP на время запроса виджета (-1 — без предела)	2G
MLFLOW_SERVER_ALLOWED_HOSTS	Разрешенные значения заголовка Host для MLflow (список через запятую, `*` — проверка отключена)	*
MLFLOW_AUTH_DB_URI	URI БД прав доступа MLflow	postgresql://mlflow:mlflow@etl-mlflow-db:5432/mlflow_permissions

Лимиты AW_WIDGET_* применяются только к интерактивному получению данных виджета (данные, шапка, итоги) и не затрагивают экспорт и синхронизацию. При срабатывании лимита пользователь получает ошибку, усеченные данные не отображаются и не кэшируются.

Обновление AW¶

Для обновления Системы выполните следующие действия:

Подключитесь к серверу через ssh
Перейдите в рабочую директорию приложения, в дальнейшем ожидается, что остальные команды выполняются из рабочей директории приложения:
```
cd /opt/aw/app
```
Загрузите на сервер дистрибутив AW BI.
Создайте резервную копию файла конфигурации, а также сформируйте список изменений в файле конфигурации по сравнению с шаблоном:
```
cp .env ../env.backup.$(date +'%Y-%m-%d_%H%M%S')
diff -wu .env.dist .env > ../env.diff
```
Остановите AW:
```
docker compose down -v
```
Удалите папку rabbitmq для корректного обновления версии:
```
rm -rf ../db/rabbitmq
```
Распакуйте дистрибутив:
```
tar xvf ./release-VERSION.tar
```
Файл дистрибутива можно удалить, если есть дефицит дискового пространства
Скопируйте шаблон файла конфигурации .env.dist в файл конфигурации .env и примените изменения в нем (автоматически или вручную):
```
cp .env.dist .env
# автоматическое применение изменений:
patch < ../env.diff
```
Автоматическое применение изменений может не сработать в некоторых случаях. В этом случае необходимо будет вручную повторно внести изменения в файле .env.

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

Загрузите в Docker обновленные образы компонентов AW.

Для закрытого контура перейдите в каталог установки Системы и выполните скрипт ./install.sh:

chmod +x install.sh
./install.sh

Для открытого контура: Подключите Docker Registry:

docker login registry.analyticworkspace.ru
# Отобразится запрос о необходимости ввести учетную запись. Введите данные учетной записи, ранее использованной для скачивания дистрибутива

Запустите скрипт create_project_dirs.sh для того чтобы создать необходимые директории:
```
chmod +x create_project_dirs.sh
./create_project_dirs.sh
```
Выполните предварительную проверку обновления PostgreSQL до версии 18 (свободное место на диске, состояние каталогов). Проверка ничего не изменяет:
```
for S in db-upgrade etl-airflow-db-upgrade etl-mlflow-db-upgrade; do docker compose run --rm $S --preflight-only; done
```
Если проверка завершилась с ошибкой, устраните причину (см. раздел Обновление PostgreSQL до версии 18) и повторите проверку.

Выполните запуск Системы и примените миграции:

docker compose up -d
docker compose exec backend php yii migrate --interactive=0 | tee ./backend_migration.log
docker compose exec backend php yii run-code-migrations | tee ./backend_code_migration.log
docker compose exec etl-api /app/manage migrate | tee ./etl_api_migration.log

Выполните очистку docker от старых образов.

Данный пункт не обязателен, но является рекомендацией. Данная операция позволяет избежать лишнего использования дискового пространства.
```
set -e; TAG=$(grep "^AW_VERSION" .env | cut -f2 -d '='); REG=$(grep "^LOCAL_REGISTRY" .env | cut -f 2 -d '='); for i in $(docker images --format "{{.Repository}}:{{.Tag}}" "${REG}/*" | grep -v ${TAG} ); do docker rmi ${i}; done
```