Обновление Portal

Инструкция для администраторов: обновление уже установленного Portal. Доступны два способа:

1. Из админки (онлайн) — проверка лицензии на korport.ru, скачивание бандла и применение через update-runner.
2. Вручную — новый дистрибутив поставщика + portal-cli upgrade (обязательно для air-gap).

Подходит для всех каналов: Docker, Kubernetes, Native Linux и Native Windows.

Перед обновлением сделайте резервную копию PostgreSQL и файлов в S3.

Portal Office: в Docker/K8s обновляется вместе с образом portal/office в bundle. Для Native (и отдельного хоста редактора) — отдельно: админка → Проверить версию Office → пакет с korport.ru/portal-office. См. Portal Office.

Что происходит при обновлении

1. Заменяются бинарники / Docker-образы / статика frontend.
2. Запускаются только новые SQL-миграции (db-init / Portal.DbInit).
3. Перезапускаются API и Worker.

Данные не удаляются: пользователи, списки, элементы, библиотеки, документы в S3, кастомные WebPart, Event Receivers и Timer Jobs сохраняются.

Не используйте docker compose down -v и не переустанавливайте Portal «с нуля» на пустую БД — это уничтожит данные.

Во время применения портал может быть кратко недоступен (рестарт API/Worker). После успеха в админке обновится версия релиза из файла RELEASE.

Обновление из админки (онлайн)

Когда подходит

Условие	Нужно
Исходящий HTTPS к korport.ru	Да
Действующая лицензия (LICENSE.key)	Да
Канал/платформа лицензии = установка	Да
Запущен update-runner	Да
Air-gap / без интернета	Нет — только ручное обновление

Право на обновление: валидный непросроченный ключ с совпадением install / channel / platform. Отдельного поля «срок обновлений» в ключе нет.

Update-runner

Хост-процесс (как backup-runner): забирает задание из очереди API, проверяет лицензию на korport.ru, скачивает бандл и выполняет upgrade.

Канал	Как запустить / проверить
Docker	docker compose up -d update-runner → docker compose ps update-runner → docker compose logs -f update-runner
Native Linux	sudo systemctl enable --now portal-update-runner или portal-cli update-runner → journalctl -u portal-update-runner -f
Native Windows	.\portal-cli.ps1 update-runner (оставьте окно/службу запущенной)
Kubernetes	На jump-хосте с kubeconfig (тот же, что для install): portal-cli update-runner --mode k8s

При чистой установке через portal-cli install в .env / portal.env уже прописываются PORTAL_UPDATE_* (токен, URL korport, staging). В Docker Compose сервис update-runner поднимается вместе со стеком (restart: unless-stopped).

В админке статус runner: Online / Offline (секция Продукт и лицензия). Offline — кнопка Обновить недоступна.

Шаги в админке

1. Войдите как администратор портала.
2. Админка → Настройки → Продукт и лицензия.
3. Убедитесь, что лицензия действительна и update-runner Online.
4. Нажмите Проверить обновления — сравнение с активным релизом на korport.ru, changelog.
5. Если доступно обновление — Обновить и подтвердите (рекомендуется backup заранее).
6. Дождитесь завершения; страница покажет фазу и сообщение. При успехе версия релиза обновится автоматически.

Фазы задания

Фаза	Что происходит
queued	Задание в очереди, ожидание runner
entitle	Проверка LICENSE.key на korport.ru, выдача одноразовой ссылки на бандл
download	Скачивание дистрибутива канала установки
apply	docker load / распаковка + миграции + portal-cli upgrade
restart	Ожидание готовности API после рестарта
done / succeeded	Готово
failed	Ошибка — текст в сообщении задания и в логах runner

Как это устроено (кратко)

Админка → очередь API → update-runner
  → POST https://korport.ru/api/portal/updates/entitle  (лицензия + привязка + канал)
  → скачивание бандла по одноразовому URL
  → apply (миграции + рестарт) → complete в API

Клиентский API: версия релиза и обновление.

Переменные окружения

Задаются при portal-cli install (или вручную в .env / /etc/portal/portal.env):

Переменная	Назначение	По умолчанию при install
PORTAL_UPDATE_RUNNER_TOKEN	Токен для /api/v1/internal/upgrade-queue	случайный секрет
PORTAL_UPDATE_ENTITLE_URL	Entitle API на korport.ru	https://korport.ru/api/portal/updates/entitle
PORTAL_UPDATE_CHECK_URL	Проверка версии	https://korport.ru/api/portal/version
PORTAL_UPDATES_PAGE_URL	Страница changelog	https://korport.ru/updates
PORTAL_UPDATE_STAGING_DIR	Каталог скачанного бандла	/var/lib/portal/update-staging

PORTAL_UPDATE_RUNNER_TOKEN обязателен: internal upgrade-queue принимает только заголовок X-Portal-Update-Token с тем же секретом (без доверия по IP / X-Forwarded-For).

Типичные ошибки онлайн-обновления

Симптом	Что проверить
Update-runner Offline	Контейнер/служба запущена; логи; совпадение PORTAL_UPDATE_RUNNER_TOKEN у API и runner
Нет кнопки Обновить	Нет новой версии / нет лицензии / runner Offline / air-gap
«Лицензия отклонена korport.ru»	Срок expires, привязка, канал/платформа; на korport настроены артефакты активного релиза
Зависло на download / apply	Логи runner; место на диске; доступ к korport.ru и Gitea (со стороны korport)
Задание failed после рестарта	Логи API/Worker; миграции; повторно Проверить обновления

Подробнее: Устранение неполадок.

Ручное обновление из дистрибутива

Получите у поставщика bundle новой версии (portal-X.Y.Z-…), сделайте backup, затем выполните команды ниже из корня распакованного bundle (сохраните существующий portal.config.yaml / .env).

Файл RELEASE

В каждом дистрибутиве есть файл RELEASE с номером версии (например 1.0.0):

Канал	Расположение в bundle
Docker / K8s	RELEASE в корне архива; в контейнере API — /app/RELEASE
Native Linux / Windows	opt/portal/RELEASE, рядом с бинарниками — opt/portal/bin/RELEASE

Портал читает этот файл при старте. В админке версия релиза отображается автоматически.

Docker Compose

# 1. Загрузите образы из нового bundle (air-gap)
docker load -i images/portal-images.tar

# 2. Обновите PORTAL_VERSION в .env (если меняется между релизами)
# PORTAL_VERSION=1.1.0

# При смене часового пояса отредактируйте portal.timezone в portal.config.yaml
# и перегенерируйте .env (или вручную TZ=...) перед upgrade

# 3. Обновление
./portal-cli/portal-cli upgrade --mode docker

Команда upgrade:

• запускает db-init (миграции);
• перезапускает контейнеры (docker compose up -d), включая backup-runner и update-runner.

Подробнее: Быстрый старт: Docker.

Kubernetes / Helm

docker load -i images/portal-images.tar   # или push в registry кластера

./portal-cli/portal-cli upgrade --mode k8s

При upgrade выполняется Helm hook Job db-init (миграции до переключения подов).

Подробнее: Быстрый старт: Kubernetes.

Native Linux

tar xzf portal-1.1.0-native-linux-amd64.tar.gz
cd portal-1.1.0-native-linux-amd64

# Сохраните существующий portal.config.yaml / /etc/portal/portal.env

./portal-cli/portal-cli upgrade --mode native

Обновляются бинарники в /opt/portal, применяются миграции, перезапускаются portal-api и portal-worker.

Подробнее: Быстрый старт: Native Linux.

Native Windows

Expand-Archive portal-1.1.0-native-windows-amd64.zip -DestinationPath C:\Portal
cd C:\Portal\portal-1.1.0-native-windows-amd64

.\portal-cli\portal-cli.ps1 upgrade -Mode native
Restart-Service PortalApi, PortalWorker

Подробнее: Быстрый старт: Native Windows.

Активация лицензии после обновления

Если получили новый LICENSE.key:

• Админка: Настройки → Продукт и лицензия — загрузка файла или вставка ключа
• CLI:

./portal-cli/portal-cli license activate --file LICENSE.key
./portal-cli/portal-cli upgrade --mode docker   # или k8s / native

Проверка версии после обновления

1. portal-cli status

./portal-cli/portal-cli status --mode docker
# или: k8s | native

2. API (сервер установки)

curl -s http://localhost/health
curl -s http://localhost/api/v1/system/version | jq .

Ответ /api/v1/system/version — версия сборки (assembly). Версия релиза из файла RELEASE — в админке и в GET /api/v1/admin/settings/release (нужен вход администратора).

3. Админка портала

Админка → Настройки → Продукт и лицензия:

• Версия релиза — из файла RELEASE;
• Проверить обновления — сравнение с актуальным релизом на korport.ru;
• Обновить — онлайн-обновление (при Online runner и действующей лицензии).

4. Файл RELEASE на сервере

# Docker
docker compose exec backend cat /app/RELEASE

# Native Linux
cat /opt/portal/RELEASE

Проверка наличия нового релиза (онлайн)

Публичный API поставщика (без авторизации):

curl -s https://korport.ru/api/portal/version | jq .

Пример ответа:

{
  "success": true,
  "data": {
    "version": "1.1.0",
    "releasedAt": "2026-07-01T00:00:00.000Z",
    "whatsNew": ["…"],
    "fixes": ["…"],
    "updatesUrl": "https://korport.ru/updates"
  }
}

Список опубликованных релизов: GET https://korport.ru/api/portal/releases. Описания изменений: korport.ru/updates.

В изолированном контуре (air-gap) сравнивайте номер в своём RELEASE с версией из поставленного дистрибутива. См. Офлайн установка.

Чеклист после обновления

• portal-cli status — сервисы работают
• curl …/health — ok
• В админке отображается ожидаемая версия релиза
• Вход пользователей, списки и библиотеки на месте
• Часовой пояс (portal.timezone / TZ) соответствует региону организации
• Кастомные WebPart / Event Receivers / Timer Jobs активны (Службы, Event Receivers, Timer Jobs)
• (онлайн) update-runner снова Online; повторная Проверить обновления → «Актуальная версия»

Устранение неполадок

См. Устранение неполадок. Типичные случаи:

• миграция не применилась — повторно db-init / Portal.DbInit;
• API не стартует — логи контейнера или journalctl -u portal-api;
• версия релиза не обновилась — образы/бинарники из нового bundle и актуальный файл RELEASE;
• онлайн-обновление — раздел онлайн-обновление из админки.

API: версия релиза и обновление.