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

Эта страница — «симптом → что ввести». Сначала соберите диагностический пакет (§0), затем откройте раздел по каналу или теме.

---

0. Что собрать для поддержки

Если в вашей поставке есть скрипт support-bundle (спросите у поставщика путь) — запустите его. Иначе соберите вручную из каталога установки Portal:

Docker:

cd /путь/к/portal-*-docker-bundle
./portal-cli/portal-cli status --mode docker > /tmp/portal-status.txt
docker compose ps > /tmp/portal-ps.txt
docker compose logs --tail=200 backend worker frontend > /tmp/portal-logs.txt
# Не присылайте файл .env целиком (там пароли). При необходимости — только имена переменных:
grep -E '^[A-Z0-9_]+=' .env | cut -d= -f1 > /tmp/portal-env-keys.txt

Kubernetes:

kubectl -n portal get pods,svc,ingress > /tmp/portal-k8s.txt
kubectl -n portal logs deploy/portal-backend --tail=200 > /tmp/portal-api-logs.txt

Native Linux:

systemctl status portal-api portal-worker --no-pager > /tmp/portal-systemd.txt
journalctl -u portal-api -u portal-worker -n 200 --no-pager > /tmp/portal-journal.txt

Передайте эти файлы в поддержку без паролей и LICENSE.key.

---

1. Общие проверки (любой канал)

Выполните по порядку:

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

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

Ожидается: status без упавших сервисов, health отвечает, version и license-status возвращают JSON.

---

2. Docker

Симптом: db-init failed

docker compose logs db-init
docker compose --env-file .env ps
docker compose run --rm db-init

Проверьте, что PostgreSQL доступен и POSTGRES_* в .env верные.

Симптом: Backend unhealthy / API не отвечает

docker compose logs --tail=100 backend
docker compose ps backend
curl -sS http://127.0.0.1:3001/health

Проверьте в .env: JWT_SECRET, POSTGRES_*. Затем:

docker compose up -d --force-recreate backend

Симптом: 502 от frontend / вылет на логин / /chat-hub 502

Чаще всего backend/chat не слушают порт или nginx держит старый Docker IP после recreate.

docker compose ps
curl -sS http://127.0.0.1:3001/health
curl -sS http://127.0.0.1:3010/health
docker compose exec frontend nginx -s reload

Frontend сам делает nginx -s reload при смене IP (20-upstream-watch.sh). Подождите 10 секунд и обновите страницу.

Модуль чата и звонки: Корпоративный чат.

Симптом: Portal Office не открывает документ

grep -E 'WOPI_HOST_URL|PORTAL_OFFICE' .env || true
curl -sS http://127.0.0.1:9980/hosting/discovery | head
docker compose ps office

Проверьте WOPI_HOST_URL и PORTAL_OFFICE_PUBLIC_URL. См. Portal Office.

Полезные команды Docker

docker compose --env-file .env ps
docker compose logs -f backend worker
docker compose run --rm db-init

---

3. Kubernetes

Симптом: Pending PVC

kubectl get sc
kubectl get pvc -n portal
kubectl describe pvc -n portal

Нужен StorageClass в кластере.

Симптом: db-init Job Failed

kubectl get jobs -n portal
kubectl logs -n portal job/portal-db-init

Проверьте секрет пароля Postgres и доступность БД.

Симптом: Ingress 404

kubectl get ingress -n portal
kubectl describe ingress -n portal

Сверьте host в Ingress с адресом в браузере и наличие Ingress Controller.

Симптом: ImagePullBackOff

kubectl describe pod -n portal <имя-пода>

Сделайте docker load образов или проверьте credentials registry.

Общие команды K8s

kubectl get pods -n portal
kubectl describe pod -n portal <name>
helm status portal -n portal
kubectl logs -n portal -l app.kubernetes.io/component=backend -f

---

4. Native Linux

Симптом: API не стартует

systemctl status portal-api --no-pager
journalctl -u portal-api -n 100 --no-pager
source /etc/portal/portal.env
psql -h "$POSTGRES_HOST" -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c 'SELECT 1'

Если psql падает — исправьте Postgres в /etc/portal/portal.env, затем:

sudo systemctl restart portal-api portal-worker

Симптом: 502 от nginx

ss -tlnp | grep 3001
sudo nginx -t
curl -sS http://127.0.0.1:3001/health
sudo systemctl restart portal-api
sudo systemctl reload nginx

Логи Worker

journalctl -u portal-worker -n 50 --no-pager
journalctl -u portal-api -f

---

5. Native Windows

Get-Service PortalApi, PortalWorker
sc.exe query PortalApi
Get-EventLog -LogName Application -Source PortalApi -Newest 20
Invoke-RestMethod http://127.0.0.1:3001/health

Если служба не Running — смотрите Event Log и C:\ProgramData\Portal\portal.env (Postgres, Redis, S3).

---

6. LDAP / Active Directory

Что видите	Что сделать
Доменный вход 400 LDAP not configured	Админка → Службы → Синхронизация AD → Настройки — URL, Base DN, Bind DN, пароль; badge «Подключён»
ad-sync недоступна / available: false	LDAP не настроен или проверка не проходит — смотрите /admin/settings/ldap-status
Поиск в каталоге пустой	searchFilter, baseDn, права bind-учётки; запрос минимум 2 символа
Группы AD не появляются	Включите Синхронизировать группы AD; запустите ad-sync вручную
Состав группы AD не совпадает	Синхронизируются только прямые member; вложенные группы не разворачиваются
Пользователь не деактивируется	Включите «Деактивировать пользователей, отсутствующих в AD» (cronDeactivateMissing) — и при ручном запуске, и по cron. Не путать с флагами очистки групп

Проверка API (нужна cookie администратора):

curl -sS http://localhost/api/v1/admin/settings/ldap-status -b cookies.txt

Локальный OpenLDAP в Docker (если включён профиль):

docker compose --profile ldap ps
docker compose --profile ldap logs ldap

См. Группы доступа.

---

7. Часовой пояс и даты

Что видите	Что сделать
Бронирования / таймлайн со сдвигом	Проверьте portal.timezone в portal.config.yaml и TZ в .env / portal.env
Службы по расписанию не вовремя	Worker использует TimeZoneInfo.Local = TZ процесса — задайте зону и перезапустите API/Worker

Docker — проверка времени в контейнере:

docker compose exec backend date
grep -E '^(TZ|)' .env | head

Должно совпадать с регионом организации. Затем:

docker compose up -d --force-recreate backend worker

Native:

grep ^TZ= /etc/portal/portal.env
sudo systemctl restart portal-api portal-worker

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

---

8. Лицензия

Что видите	Что сделать
402 LICENSE_EXPIRED	Активируйте LICENSE.key в Настройки → Продукт и лицензия или CLI ниже
402 LICENSE_CHANNEL_MISMATCH	Канал/платформа ключа ≠ установка. Сверьте install.mode / install.platform в PORTAL_DATA_DIR; запросите ключ с правильным channel/platform
invalid license	Проверьте файл ключа; выполните portal-cli install до активации (для ключей с channel) или новый ключ у поставщика
Trial истёк / нет ключа	Новый signed trial или коммерческий ключ от поставщика
mode: invalid без ключа	Ожидаемо: без ключа запись недоступна

Активация CLI:

./portal-cli/portal-cli license activate --file LICENSE.key
./portal-cli/portal-cli upgrade --mode docker   # или k8s / native
curl -sS http://localhost/api/v1/system/license-status

Пробный период — подписанный LICENSE.key с "kind": "trial" (30 дней, привязка к инсталляции). Локальный сброс файлами или БД новый trial не открывает: нужен новый ключ от поставщика (повторная выдача на ту же привязку не выполняется).

---

9. Миграции

Docker:

docker compose run --rm db-init
docker compose logs db-init

Native Linux:

sudo -u portal bash -c 'set -a; source /etc/portal/portal.env; set +a; \
  MIGRATIONS_PATH=/opt/portal/migrations /opt/portal/bin/Portal.DbInit'

Затем проверьте health и вход в портал.

---

10. Логи (шпаргалка)

Режим	Команда
Docker	docker compose logs -f backend worker
K8s	kubectl logs -n portal -l app.kubernetes.io/component=backend -f
Native	journalctl -u portal-api -f

---

11. Обновление и версия релиза

Что видите	Что сделать
Версия релиза в админке не изменилась	Образы/бинарники из нового bundle; см. команды ниже
Миграции не применились после upgrade	Повторите portal-cli upgrade --mode <канал> или §9
Проверить обновления не работает	Нужен HTTPS до korport.ru; в air-gap сравнивайте RELEASE с дистрибутивом

Проверка файла RELEASE:

# Docker
docker compose exec backend cat /app/RELEASE

# Native Linux
cat /opt/portal/RELEASE

Полная инструкция: Обновление Portal.

---

12. Онлайн-обновление из админки

Что видите	Что сделать
Update-runner Offline	Команды ниже + один PORTAL_UPDATE_RUNNER_TOKEN у API и runner
Нет кнопки Обновить	Сначала Проверить обновления; нужны новая версия, лицензия, Online runner. В air-gap кнопки нет
Задание сразу failed: лицензия / entitle	Ключ не просрочен; привязка и канал = установка; на korport.ru есть артефакт вашего канала
Задание зависло (running > 2 ч)	Логи runner; API помечает зависшие как failed — исправьте и запустите снова
После обновления runner снова offline	docker compose up -d update-runner

Docker:

docker compose up -d update-runner
docker compose ps update-runner
docker compose logs --tail=80 update-runner

Native Linux:

systemctl status portal-update-runner --no-pager
# или: portal-cli update-runner
journalctl -u portal-update-runner -n 80 --no-pager

Проверка heartbeat (подставьте токен из .env):

source .env   # или: grep PORTAL_UPDATE_RUNNER_TOKEN .env
curl -sS -X POST http://localhost/api/v1/internal/upgrade-queue/heartbeat \
  -H "Content-Type: application/json" \
  -H "X-Portal-Update-Token: $PORTAL_UPDATE_RUNNER_TOKEN" \
  -d '{"source":"manual"}'

См. Обновление Portal.

---

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

• Обновление Portal
• Корпоративный чат
• Portal Office
• Офлайн установка
• Внешние сервисы