← Документация и информация о ПО

Инструкция по установке программного обеспечения

Программное обеспечение: XK Server Management Platform (XKSM)

Версия: 2.64.0

Правообладатель: ООО «XK»

Дата документа: 08.05.2026

Скачать PDF Установка Как получить ПО

1. ВВЕДЕНИЕ

Настоящая инструкция описывает процедуру установки и первоначальной настройки XK Server Management Platform (XKSM) версии 2.64.0 на серверах под управлением операционных систем семейства Linux.

XKSM поставляется в виде набора Docker-контейнеров и разворачивается с помощью Docker Compose. Такой подход обеспечивает совместимость с широким спектром Linux-дистрибутивов и упрощает процедуру обновления.

1.1 Варианты поставки

---

2. ТРЕБОВАНИЯ К СЕРВЕРУ

2.1 Аппаратные требования

2.2 Программные требования

2.3 Сетевые порты (входящие)

2.4 Сетевые порты (исходящие, к управляемым серверам)

---

3. УСТАНОВКА: ОНЛАЙН (bootstrap-скрипт)

3.1 Предварительные условия

# Убедиться, что Docker установлен
docker --version
docker compose version

# Если Docker не установлен (Ubuntu/Debian):
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

3.2 Запуск bootstrap-установщика

# Скачать и запустить установщик
curl -fsSL https://install.xkserv.ru/install.sh | bash

Скрипт выполнит: 1. Проверку системных требований 2. Создание директории /opt/xksm/ 3. Загрузку конфигурационных файлов 4. Скачивание Docker-образов из реестра 5. Генерацию случайных паролей и ключей 6. Первоначальный запуск всех сервисов 7. Применение миграций базы данных

3.3 Параметры установщика (опционально)

# Установка с кастомными параметрами
curl -fsSL https://install.xkserv.ru/install.sh | bash -s -- \
  --domain app.example.ru \
  --admin-email admin@example.ru \
  --data-dir /data/xksm

---

4. УСТАНОВКА: ОФФЛАЙН (архив)

4.1 Получение архива

Обратитесь в техническую поддержку ООО «XK» для получения оффлайн-архива (xksm-2.64.0-offline.tar.gz) и лицензионного файла (LICENSE.xksm).

4.2 Развёртывание из архива

# 1. Скопировать архив на целевой сервер
scp xksm-2.64.0-offline.tar.gz user@server:/opt/

# 2. Распаковать
cd /opt
tar -xzf xksm-2.64.0-offline.tar.gz

# 3. Перейти в директорию установки
cd xksm-2.64.0

# 4. Загрузить Docker-образы из архива
docker load -i images/xksm-backend.tar
docker load -i images/xksm-frontend.tar
docker load -i images/postgres.tar
docker load -i images/redis.tar
docker load -i images/clickhouse.tar
docker load -i images/qdrant.tar

# 5. Скопировать файл лицензии
cp /path/to/LICENSE.xksm ./

# 6. Запустить установщик
./install-offline.sh

---

5. РУЧНАЯ УСТАНОВКА (для разработчиков)

5.1 Клонирование репозитория

git clone https://git.xkserv.ru/xk/xksm-platform.git
cd xksm-platform

5.2 Настройка окружения

# Скопировать пример переменных окружения
cp .env.example .env

# Отредактировать .env — обязательные параметры:
# DB_PASSWORD=<случайный_пароль>
# REDIS_PASSWORD=<случайный_пароль>
# JWT_SECRET_KEY=<случайный_ключ_RS256>
# SECRET_KEY=<случайный_AES_ключ>
# LICENSE_KEY=<ключ_лицензии>
nano .env

5.3 Запуск инфраструктурных сервисов

cd infrastructure
docker compose -f docker/docker-compose.dev.yml up -d
# Запускает: PostgreSQL 16, Redis 7, Qdrant 1.9, ClickHouse 24.8

5.4 Настройка и запуск backend

cd backend

# Создать виртуальное окружение Python
python3 -m venv .venv
source .venv/bin/activate

# Установить зависимости
pip install -r requirements.txt

# Применить миграции БД
alembic upgrade head

# Запустить API-сервер (dev-режим с Swagger UI)
DEBUG=true uvicorn main:app --host 0.0.0.0 --port 8099 --reload

5.5 Запуск фоновых задач (Celery)

cd backend
source .venv/bin/activate
celery -A tasks.celery_app worker \
  --loglevel=info \
  -Q critical,normal,background,firmware,inspect,monitor

5.6 Запуск frontend

cd frontend
npm install
npm run dev   # dev-сервер на :5173
# или
npm run build && npm run preview  # production-сборка

---

6. КОНФИГУРАЦИЯ PRODUCTION

6.1 Структура файлов конфигурации

/opt/xksm/
├── .env                    — основные настройки (пароли, ключи)
├── docker-compose.yml      — описание сервисов
├── nginx/
│   └── nginx.conf          — конфигурация Nginx (reverse proxy)
├── data/
│   ├── postgres/           — данные PostgreSQL
│   ├── redis/              — данные Redis
│   ├── clickhouse/         — данные ClickHouse
│   └── qdrant/             — векторная БД Qdrant
└── backups/                — резервные копии

6.2 Ключевые переменные окружения (.env)

# Приложение
APP_ENV=production
APP_VERSION=2.64.0
DEBUG=false

# База данных PostgreSQL
DB_HOST=postgres
DB_PORT=5432
DB_NAME=xksm
DB_USER=xksm_user
DB_PASSWORD=<СГЕНЕРИРОВАТЬ_НАДЁЖНЫЙ_ПАРОЛЬ>

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=<СГЕНЕРИРОВАТЬ_НАДЁЖНЫЙ_ПАРОЛЬ>

# ClickHouse
CLICKHOUSE_HOST=clickhouse
CLICKHOUSE_PORT=9000

# JWT и безопасность
SECRET_KEY=<32_БАЙТА_BASE64>
JWT_ALGORITHM=RS256
JWT_ACCESS_TOKEN_EXPIRE=30  # минут

# Лицензия
LICENSE_KEY=<ЛИЦЕНЗИОННЫЙ_КЛЮЧ>
LICENSE_SERVER_URL=https://license.xkserv.ru

6.3 SSL/TLS (HTTPS)

Рекомендуется использовать SSL-сертификат от доверенного российского УЦ (например, «Крипто-Про», УЦ ФНС, НУЦ Минцифры).

# Разместить сертификаты в:
/opt/xksm/nginx/ssl/server.crt
/opt/xksm/nginx/ssl/server.key

# Nginx автоматически подхватит их при следующей перезагрузке
docker compose restart nginx

Поддерживается автоматический выпуск сертификата через Let's Encrypt (для серверов с доступом в интернет):

./scripts/setup-ssl.sh --domain app.example.ru --email admin@example.ru

---

7. ЗАПУСК И УПРАВЛЕНИЕ СЕРВИСАМИ

7.1 Запуск всех сервисов

cd /opt/xksm
docker compose up -d

7.2 Остановка

docker compose down

7.3 Просмотр статуса

docker compose ps

7.4 Просмотр логов

# Все сервисы
docker compose logs -f

# Только backend
docker compose logs -f xksm-backend

# Только frontend
docker compose logs -f xksm-frontend

7.5 Перезапуск отдельного сервиса

docker compose restart xksm-backend

---

8. ПЕРВОНАЧАЛЬНАЯ НАСТРОЙКА

8.1 Setup Wizard

После запуска сервисов откройте браузер и перейдите на: https://your-server-address/

Если первоначальная настройка не была выполнена, автоматически откроется Setup Wizard. Следуйте шагам мастера:

1. Введите название организации
2. Создайте учётную запись администратора (логин, email, пароль)
3. Нажмите «Завершить настройку»

8.2 Активация лицензии

После завершения Setup Wizard: 1. Войдите под учётной записью администратора 2. Перейдите в Настройки → Лицензия 3. Нажмите [Активировать лицензию] 4. Для онлайн-активации: введите лицензионный ключ → [Активировать онлайн] 5. Для оффлайн-активации: скопируйте Hardware ID → отправьте в ООО «XK» → получите файл активации → загрузите через [Загрузить файл активации]

---

9. ОБНОВЛЕНИЕ

9.1 Обновление через Docker (рекомендуется)

cd /opt/xksm

# Создать резервную копию перед обновлением
./scripts/backup.sh

# Скачать новые образы
docker compose pull

# Применить новые миграции БД (если есть)
docker compose run --rm xksm-backend alembic upgrade head

# Перезапустить с новыми образами
docker compose up -d

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

curl -s http://localhost:8099/api/v1/system/info | grep version

9.3 Откат к предыдущей версии

# Откат к предыдущей версии образов
docker compose down
docker tag xksm-backend:2.63.0 xksm-backend:latest  # вернуть предыдущий тег
docker compose up -d

# Откат миграций БД (если требуется)
docker compose run --rm xksm-backend alembic downgrade -1

ℹ️ Обновления всегда инициируются клиентом. Автоматических принудительных обновлений с внешних серверов не предусмотрено.

---

10. РЕЖИМ ВЫСОКОЙ ДОСТУПНОСТИ (HA)

10.1 Архитектура HA

              ┌──────────────────┐
              │  Load Balancer   │
              │ (Keepalived/VIP) │
              └────────┬─────────┘
                       │
          ┌────────────┴────────────┐
          │                         │
   ┌──────▼──────┐         ┌───────▼──────┐
   │  XKSM Node 1│         │  XKSM Node 2 │
   │  (Primary)  │         │   (Replica)  │
   └──────┬──────┘         └──────┬───────┘
          │                       │
   ┌──────▼──────────────────────▼───────┐
   │      PostgreSQL + Redis Cluster      │
   │   (Streaming Replication/Sentinel)   │
   └──────────────────────────────────────┘

10.2 Запуск в режиме HA

cd infrastructure
docker compose -f docker/docker-compose.ha.yml up -d

Подробная конфигурация HA: infrastructure/ha/

---

11. ДИАГНОСТИКА УСТАНОВКИ

11.1 Проверка доступности сервисов

# Проверка API
curl -sk https://localhost/api/v1/system/health

# Ожидаемый ответ:
# {"status": "ok", "version": "2.64.0", "database": "ok", "redis": "ok"}

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

11.3 Логи для диагностики

# Просмотр логов всех компонентов за последний час
docker compose logs --since=1h

# Просмотр ошибок backend
docker compose logs xksm-backend 2>&1 | grep -i error

---

12. ДЕИНСТАЛЛЯЦИЯ

cd /opt/xksm

# Остановить и удалить контейнеры
docker compose down -v

# Удалить данные (НЕОБРАТИМО!)
sudo rm -rf /opt/xksm/data/

# Удалить файлы установки
sudo rm -rf /opt/xksm/

⚠️ Убедитесь в наличии актуальной резервной копии данных перед деинсталляцией.

---

XK Server Management Platform — Инструкция по установке v2.64.0 © ООО «XK», 2026. Все права защищены.