Kontrum On-Premise

Клиентское руководство, основанное на текущем пакете onprem/ и исходниках Windows Server проекта.

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

Также требуются DNS-имя или VPN-имя, доверенный TLS-сертификат и исходящий HTTPS-доступ к api.kontrum.kz для регистрации и проверки лицензии.

2. Установка на Linux

1. Получите официальный версионированный On-Premise пакет через Kontrum.
2. Разместите пакет на сервере клиента под отдельной системной учётной записью.
3. Выполните ./scripts/prepare.sh.
4. Создайте .env из .env.example и задайте уникальные значения. Не используйте примеры в production.
5. Получите одноразовый код регистрации сервера в личном кабинете.
6. Выполните регистрацию: python3 scripts/register.py --code 'KTR-SRV-EXAMPLE'.
7. Добавьте TLS-сертификат в certs/fullchain.pem и certs/privkey.pem.
8. Запустите ./scripts/install.sh.
9. Проверьте ./scripts/status.sh.

3. Windows Server

Поддерживаемая архитектура использует нативную Windows-службу и отдельный WSL2-контур, в котором работают Docker Engine, PostgreSQL и Kontrum Server. Это не установка через Docker Desktop.

1. Подготовьте Windows Server 2022/2025 с аппаратной виртуализацией.
2. Установите официальный signed package Kontrum Server.
3. Укажите DNS, HTTPS port и server registration code.
4. Дождитесь подготовки WSL2 и контейнеров.
5. Добавьте доверенный TLS certificate и проверьте health.

4. Первый запуск и лицензия

1. В личном кабинете активируйте локальное или выделенное размещение.
2. Укажите REST URL, например https://server.company.example:8443.
3. Укажите WSS URL: wss://server.company.example:8443/api/v1/ws.
4. Зарегистрируйте сервер одноразовым кодом.
5. Войдите в Kontrum и проверьте runtime endpoint.
6. Убедитесь, что рабочие данные открываются напрямую с сервера клиента.

5. TLS, HTTPS и firewall

• Для браузерного клиента обязательны HTTPS и WSS; HTTP вызовет блокировку mixed content.
• По умолчанию gateway использует TCP 8443. Можно выбрать другой согласованный HTTPS-порт.
• Открывайте входящий порт только для нужных сетей или VPN.
• PostgreSQL нельзя публиковать в интернет.
• Сертификат должен быть доверенным на рабочих устройствах.
• Разрешите исходящий HTTPS к api.kontrum.kz.

6. Резервные копии

Linux package содержит `./scripts/backup.sh`. Скрипт создаёт PostgreSQL backup; для production включите шифрование через получателя AGE и храните копии вне сервера.

./scripts/backup.sh

1. Проверяйте завершение backup по расписанию.
2. Контролируйте свободное место и retention.
3. Регулярно выполняйте restore rehearsal на отдельном контуре.
4. До обновления создавайте дополнительную проверенную копию.

7. Обновление и rollback

1. Запишите текущую версию и сделайте backup.
2. Проверьте checksum нового официального package.
3. Не перезаписывайте рабочий `.env` и TLS keys.
4. Выполните source validation из package.
5. Пересоберите server image и примените Compose update по release instructions.
6. Проверьте migrations, health и вход пользователя.

Для rollback используйте сохранённый предыдущий package и backup, совместимый с его схемой. Не выполняйте destructive unregister WSL2 без проверенной резервной копии: это удалит PostgreSQL disk.

8. Monitoring и диагностика

• Проверяйте `docker compose ps` или `./scripts/status.sh`.
• Контролируйте health PostgreSQL, server и gateway.
• Следите за диском, backup age, TLS expiry и license check.
• При проблеме фиксируйте время, component status и безопасный log fragment.
• Не отправляйте `.env`, private keys, database password или registration token в поддержку.