Обновление Portal

Эта инструкция для администратора, у которого Portal уже установлен и нужно перейти на новую версию.

Читайте сверху вниз. Есть два способа — выберите свой в §2.
Перед любым обновлением сделайте резервную копию PostgreSQL и файлов в S3.

---

0. Что вы получите в итоге

После успешного обновления:

1. Новые бинарники / Docker-образы / статика frontend.
2. Применены только новые SQL-миграции.
3. Перезапущены API и Worker.
4. В админке отображается новая версия релиза из файла RELEASE.

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

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

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

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

---

1. Два способа обновления

Способ	Когда	Интернет к korport.ru
A. Из админки	Обычный контур с доступом наружу	Нужен
B. Вручную (portal-cli upgrade)	Air-gap, политика безопасности, любой канал	Не нужен

Подходит для Docker, Kubernetes, Native Linux и Native Windows.

---

2. Выберите свой раздел

Ситуация	Откройте
Есть интернет и лицензия, хотите кнопку в админке	§3
Закрытый контур / новый архив от поставщика	§4
Проверить версию после любого способа	§5
Что проверить вручную (чеклист)	§6
Ошибки	§7

---

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

Шаг 3.1. Когда этот способ подходит

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

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

Шаг 3.2. Запустите update-runner

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

Docker:

cd /путь/к/вашему/portal-*-docker-bundle
docker compose up -d update-runner
docker compose ps update-runner
docker compose logs --tail=50 update-runner

Статус должен быть Up / running.

Native Linux:

sudo systemctl enable --now portal-update-runner
# или: portal-cli update-runner
systemctl status portal-update-runner --no-pager
journalctl -u portal-update-runner -n 50 --no-pager

Native Windows (оставьте окно/службу запущенной):

.\portal-cli\portal-cli.ps1 update-runner

Kubernetes (на jump-хосте с тем же kubeconfig, что для install):

./portal-cli/portal-cli update-runner --mode k8s

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

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

Шаг 3.3. Шаги в браузере

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

Шаг 3.4. Фазы задания (что значит статус)

Фаза	Что происходит
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
  → скачивание бандла
  → apply (миграции + рестарт) → complete в API

Шаг 3.5. Переменные (уже заданы при install)

Переменная	Зачем	По умолчанию при install
PORTAL_UPDATE_RUNNER_TOKEN	Токен для /api/v1/internal/upgrade-queue	случайный секрет
PORTAL_UPDATE_ENTITLE_URL	Entitle API	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 обязателен: очередь принимает только заголовок X-Portal-Update-Token с тем же секретом.

Дальше — §5.

---

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

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

Шаг 4.1. Файл RELEASE

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

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

Шаг 4.2. Docker Compose

cd /путь/к/новому/portal-*-docker-bundle

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

# 2. При смене версии между релизами поправьте PORTAL_VERSION в .env
# PORTAL_VERSION=1.1.0

# 3. При смене часового пояса — portal.timezone в portal.config.yaml и TZ в .env

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

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

Проверка:

./portal-cli/portal-cli status --mode docker
docker compose exec backend cat /app/RELEASE

Шаг 4.3. Kubernetes / Helm

cd /путь/к/новому/portal-*-k8s-bundle
docker load -i images/portal-images.tar
# при необходимости: tag + push в registry кластера

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

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

Проверка:

./portal-cli/portal-cli status --mode k8s
kubectl -n portal get pods

Шаг 4.4. 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.

Проверка:

cat /opt/portal/RELEASE
systemctl status portal-api portal-worker --no-pager

Шаг 4.5. 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

Проверка:

Get-Content "C:\Program Files\Portal\bin\RELEASE"
Get-Service PortalApi, PortalWorker

Шаг 4.6. Новый LICENSE.key после обновления

Если поставщик выдал новый ключ:

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

CLI:

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

Дальше — §5.

---

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

Выполняйте по порядку.

Шаг 5.1. portal-cli status

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

Шаг 5.2. Health и версия сборки

curl -sS http://localhost/health
curl -sS http://localhost/api/v1/system/version

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

Шаг 5.3. Админка

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

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

Шаг 5.4. Файл RELEASE на сервере

# Docker
docker compose exec backend cat /app/RELEASE

# Native Linux
cat /opt/portal/RELEASE

Шаг 5.5. Есть ли новый релиз у поставщика (онлайн)

curl -sS https://korport.ru/api/portal/version

Пример ответа: поле data.version, changelog, ссылка на https://korport.ru/updates.
Список релизов: GET https://korport.ru/api/portal/releases.

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

---

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

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

---

7. Типичные проблемы

Что видите	Что сделать
Update-runner Offline	Запустите runner (§3.2). Логи. Один и тот же PORTAL_UPDATE_RUNNER_TOKEN у API и runner.
Нет кнопки Обновить	Нет новой версии / нет лицензии / runner offline / air-gap.
«Лицензия отклонена korport.ru»	Срок expires, привязка, канал/платформа; на korport есть артефакты активного релиза.
Зависло на download / apply	Логи runner; место на диске; доступ к korport.ru.
Задание failed после рестарта	Логи API/Worker; миграции; снова Проверить обновления.
Версия релиза в админке не сменилась	Образы/бинарники из нового bundle; проверьте файл RELEASE.
Миграции не применились	Повторите portal-cli upgrade или db-init вручную — см. Устранение неполадок.
API не стартует	docker compose logs backend или journalctl -u portal-api -n 100.

Подробнее с точными командами: Устранение неполадок (раздел про онлайн-обновление).

---

8. Связанные документы

• Быстрый старт: Docker · Kubernetes · Native Linux · Native Windows
• Офлайн установка
• Portal Office
• Устранение неполадок
• Бэкап и восстановление