Руководство администратора системы "Симулятор регионов"

1. Общая архитектура системы

Система "Симулятор регионов" представляет собой комплексную платформу для экономического моделирования, состоящую из следующих компонентов:

Backend API - основное приложение на Node.js/Express
PostgreSQL - база данных для хранения игровых данных и конфигураций
Minio - объектное хранилище для файлов
PM2 - менеджер процессов для управления приложением
Nginx - веб-сервер и reverse proxy

2. Процесс установки и настройки

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

Обязательные компоненты:

Docker версии 20.10+
Nginx версии 1.18+
NVM (Node Version Manager) версии 0.39+
Node.js версии 20.10.0 (устанавливается через NVM)

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

ОС: Ubuntu 20.04+ / CentOS 8+ / RHEL 8+
ОЗУ: минимум 4GB, рекомендуется 8GB+
Дисковое пространство: минимум 20GB, рекомендуется 50GB+
CPU: минимум 2 ядра, рекомендуется 4+

2.2 Подготовка сервера

2.2.1 Настройка SSH ключей

Сгенерировать SSH ключ на локальном компьютере:

ssh-keygen -t rsa -b 4096 -C "admin@regionsim.local"

Добавить публичный ключ на сервер:

cat ~/.ssh/id_rsa.pub | ssh user@server 'mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys'

Добавить публичный SSH ключ сервера в репозиторий проекта (для клонирования кода).

2.2.2 Создание пользователей

# Создание пользователя для приложения
sudo useradd -m -s /bin/bash regionsim
sudo usermod -aG docker regionsim

2.3 Скрипты установки

2.3.1 Создание install_sim_region.sh

Разместить в домашней директории сервера скрипт установки:

#!/bin/bash
# install_sim_region.sh

set -e

# Загрузка конфигурации
source ./config_sim_region

echo "=== Установка системы RegionSim ==="

# Проверка Docker
if ! command -v docker &> /dev/null; then
    echo "Ошибка: Docker не установлен"
    exit 1
fi

# Установка NVM и Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20.10.0
nvm use 20.10.0

# Установка PM2 глобально
npm install -g pm2

# Клонирование репозитория
git clone $REPO_URL regionsim
cd regionsim

# Создание .env файла
cat > .env << EOF
DATABASE_URL="postgresql://$DB_USER:$DB_PASSWORD@localhost:5432/$DB_NAME"
NODE_ENV=$NODE_ENV
PORT=$APP_PORT
JWT_SECRET=$JWT_SECRET
EOF

# Развертывание инфраструктуры
docker-compose up -d

# Установка зависимостей
npm install

# Генерация Prisma клиента
npm run prisma:generate

# Выполнение миграций
npx prisma migrate deploy

# Заполнение начальными данными
npm run prisma:seed

# Сборка приложения
npm run build

# Запуск через PM2
pm2 start ecosystem.config.js
pm2 save
pm2 startup

echo "=== Установка завершена ==="

2.3.2 Создание config_sim_region

# config_sim_region
# Конфигурационный файл для установки RegionSim

# Репозиторий
REPO_URL="git@github.com:your-org/regionsim.git"

# База данных
DB_USER="postgres"
DB_PASSWORD="your_secure_password_here"
DB_NAME="regions"

# Приложение
NODE_ENV="production"
APP_PORT="3000"
JWT_SECRET="your_jwt_secret_here"

# Minio (если используется)
MINIO_ACCESS_KEY="your_minio_access_key"
MINIO_SECRET_KEY="your_minio_secret_key"

2.4 Конфигурация Nginx

Создать файл /etc/nginx/sites-available/regionsim:

server {
    listen 80;
    server_name your-domain.com;

    # Проксирование API запросов
    location /api/ {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_timeout 300s;
        proxy_read_timeout 300s;
    }

    # Статические файлы
    location /static/ {
        alias /home/regionsim/regionsim/static/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Документация API
    location /api-docs {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Активировать конфигурацию:

sudo ln -s /etc/nginx/sites-available/regionsim /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

3. Резервное копирование и восстановление

3.1 Стратегия резервного копирования

3.1.1 Резервное копирование PostgreSQL

Создать скрипт /opt/regionsim/backup-db.sh:

#!/bin/bash

BACKUP_DIR="/opt/regionsim/backups"
DB_NAME="regions"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/db_backup_$DATE.sql"

mkdir -p $BACKUP_DIR

# Создание резервной копии
pg_dump -h localhost -U postgres -d $DB_NAME > $BACKUP_FILE

# Сжатие резервной копии
gzip $BACKUP_FILE

# Удаление старых резервных копий (старше 30 дней)
find $BACKUP_DIR -name "*.sql.gz" -mtime +30 -delete

echo "Резервная копия создана: $BACKUP_FILE.gz"

3.1.2 Автоматизация через cron

# Ежедневное резервное копирование в 2:00
0 2 * * * /opt/regionsim/backup-db.sh

# Еженедельная полная резервная копия в воскресенье в 3:00
0 3 * * 0 /opt/regionsim/backup-full.sh

3.1.3 Резервное копирование конфигураций

#!/bin/bash
# backup-configs.sh

BACKUP_DIR="/opt/regionsim/backups/configs"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Создание архива конфигураций
tar -czf "$BACKUP_DIR/configs_$DATE.tar.gz" \
    /home/regionsim/regionsim/.env \
    /home/regionsim/regionsim/ecosystem.config.js \
    /etc/nginx/sites-available/regionsim \
    /opt/regionsim/config_sim_region

3.2 Процедуры восстановления

3.2.1 Восстановление базы данных

#!/bin/bash
# restore-db.sh

BACKUP_FILE=$1

if [ -z "$BACKUP_FILE" ]; then
    echo "Использование: ./restore-db.sh /path/to/backup.sql.gz"
    exit 1
fi

# Остановка приложения
pm2 stop all

# Восстановление БД
gunzip -c $BACKUP_FILE | psql -h localhost -U postgres -d regions

# Запуск приложения
pm2 start all

echo "Восстановление завершено"

3.2.2 Тестирование восстановления

Регулярно (раз в месяц) выполнять тестовое восстановление:

#!/bin/bash
# test-restore.sh

# Создание тестовой БД
createdb -h localhost -U postgres regions_test

# Восстановление в тестовую БД
gunzip -c /opt/regionsim/backups/latest_backup.sql.gz | \
    psql -h localhost -U postgres -d regions_test

# Проверка целостности данных
psql -h localhost -U postgres -d regions_test -c "SELECT COUNT(*) FROM users;"

# Удаление тестовой БД
dropdb -h localhost -U postgres regions_test

echo "Тест восстановления прошел успешно"

4. Критические ситуации и мониторинг

4.1 Мониторинг через PM2

4.1.1 Основные команды PM2

# Просмотр статуса процессов
pm2 status

# Просмотр логов
pm2 logs

# Мониторинг в реальном времени
pm2 monit

# Перезапуск приложения
pm2 restart sim_region_game_back-production

# Просмотр метрик
pm2 show sim_region_game_back-production

4.1.2 Настройка автозапуска

# Сохранение текущих процессов
pm2 save

# Генерация скрипта автозапуска
pm2 startup

# Выполнить команду, которую вернет pm2 startup

4.2 Telegram бот для алертов

4.2.1 Создание бота мониторинга

Создать скрипт /opt/regionsim/monitor.sh:

#!/bin/bash

TELEGRAM_BOT_TOKEN="your_bot_token"
TELEGRAM_CHAT_ID="your_chat_id"
SERVICE_URL="http://localhost:3000/api/test"

send_alert() {
    local message="$1"
    curl -s -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \
        -d "chat_id=$TELEGRAM_CHAT_ID" \
        -d "text=🚨 RegionSim Alert: $message"
}

# Проверка доступности API
if ! curl -f -s $SERVICE_URL > /dev/null; then
    send_alert "API недоступен ($SERVICE_URL)"
fi

# Проверка PM2 процессов
if ! pm2 list | grep -q "online"; then
    send_alert "PM2 процессы не запущены"
fi

# Проверка базы данных
if ! pg_isready -h localhost -p 5432 > /dev/null; then
    send_alert "PostgreSQL недоступен"
fi

# Проверка использования диска
DISK_USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')
if [ $DISK_USAGE -gt 85 ]; then
    send_alert "Высокое использование диска: ${DISK_USAGE}%"
fi

# Проверка использования памяти
MEMORY_USAGE=$(free | grep Mem | awk '{printf("%.0f", $3/$2 * 100.0)}')
if [ $MEMORY_USAGE -gt 90 ]; then
    send_alert "Высокое использование памяти: ${MEMORY_USAGE}%"
fi

4.2.2 Автоматизация мониторинга

# Проверка каждые 5 минут
*/5 * * * * /opt/regionsim/monitor.sh

4.3 Процедуры реагирования на инциденты

4.3.1 Процедура при падении API

Диагностика:

# Проверка статуса PM2
pm2 status

# Просмотр логов
pm2 logs --lines 100

# Проверка системных ресурсов
htop
df -h

Восстановление:

# Перезапуск приложения
pm2 restart all

# Если не помогает - полная перезагрузка PM2
pm2 kill
pm2 start ecosystem.config.js

4.3.2 Процедура при проблемах с БД

Диагностика:

# Проверка статуса PostgreSQL
sudo systemctl status postgresql

# Проверка подключения
pg_isready -h localhost -p 5432

# Проверка логов PostgreSQL
sudo tail -f /var/log/postgresql/postgresql-*.log

Восстановление:

# Перезапуск PostgreSQL
sudo systemctl restart postgresql

# Проверка целостности
psql -h localhost -U postgres -d regions -c "SELECT COUNT(*) FROM users;"

4.3.3 Процедура при нехватке ресурсов

При нехватке диска:

# Очистка логов
pm2 flush
sudo journalctl --vacuum-time=7d

# Очистка старых резервных копий
find /opt/regionsim/backups -mtime +30 -delete

При нехватке памяти:

# Рестарт приложения для освобождения памяти
pm2 restart all

# Временное увеличение swap (если возможно)
sudo swapon -a

4.4 Логирование и анализ

4.4.1 Структура логов

Система использует Pino для структурированного логирования:

Приложение: ~/.pm2/logs/
Nginx: /var/log/nginx/
PostgreSQL: /var/log/postgresql/
Система: /var/log/syslog

4.4.2 Анализ производительности

# Мониторинг загрузки API
tail -f ~/.pm2/logs/sim_region_game_back-production-out.log | grep "POST\|GET"

# Анализ времени ответа БД
tail -f /var/log/postgresql/postgresql-*.log | grep "duration"

# Мониторинг системных ресурсов
vmstat 5
iostat 5

5. Техническое обслуживание

5.1 Обновление системы

#!/bin/bash
# update-system.sh

# Создание резервной копии перед обновлением
/opt/regionsim/backup-db.sh
/opt/regionsim/backup-configs.sh

# Обновление кода
cd /home/regionsim/regionsim
git pull origin main

# Установка обновлений
npm install

# Выполнение миграций
npx prisma migrate deploy

# Сборка
npm run build

# Перезапуск
pm2 restart all

echo "Обновление завершено"

5.2 Плановое обслуживание

Еженедельно:

Проверка логов на наличие ошибок
Анализ использования ресурсов
Тестирование резервного копирования

Ежемесячно:

Обновление зависимостей системы
Анализ производительности
Очистка старых логов и резервных копий

Ежеквартально:

Тестирование процедур восстановления
Аудит безопасности
Планирование масштабирования

6. Контакты службы поддержки

При возникновении критических проблем:

Telegram: @regionsim_admin
Email: admin@regionsim.local
Экстренная связь: +7 (XXX) XXX-XX-XX

Эскалация инцидентов:

P1 (Критический): немедленно
P2 (Высокий): в течение 2 часов
P3 (Средний): в течение 8 часов
P4 (Низкий): в течение 24 часов

Схемы потоков данных системы "Симулятор регионов"

Инструкция по развёртыванию системы "Симулятор регионов"

Руководство администратора системы "Симулятор регионов"

Руководство администратора системы "Симулятор регионов"

1. Общая архитектура системы

2. Процесс установки и настройки

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

2.2 Подготовка сервера

2.2.1 Настройка SSH ключей

2.2.2 Создание пользователей

2.3 Скрипты установки

2.3.1 Создание install_sim_region.sh

2.3.2 Создание config_sim_region

2.4 Конфигурация Nginx

3. Резервное копирование и восстановление

3.1 Стратегия резервного копирования

3.1.1 Резервное копирование PostgreSQL

3.1.2 Автоматизация через cron

3.1.3 Резервное копирование конфигураций

3.2 Процедуры восстановления

3.2.1 Восстановление базы данных

3.2.2 Тестирование восстановления

4. Критические ситуации и мониторинг

4.1 Мониторинг через PM2

4.1.1 Основные команды PM2

4.1.2 Настройка автозапуска

4.2 Telegram бот для алертов

4.2.1 Создание бота мониторинга

4.2.2 Автоматизация мониторинга

4.3 Процедуры реагирования на инциденты

4.3.1 Процедура при падении API

4.3.2 Процедура при проблемах с БД

4.3.3 Процедура при нехватке ресурсов

4.4 Логирование и анализ

4.4.1 Структура логов

4.4.2 Анализ производительности

5. Техническое обслуживание

5.1 Обновление системы

5.2 Плановое обслуживание

6. Контакты службы поддержки