# РУКОВОДСТВО АДМИНИСТРАТОРА ## Система ETL MOSTOVIK Версия документа: 1.0 Дата: 2026-01-21 --- ## СОДЕРЖАНИЕ 1. [Общие сведения](#1-общие-сведения) 2. [Архитектура системы](#2-архитектура-системы) 3. [Развёртывание системы](#3-развёртывание-системы) 4. [Конфигурирование](#4-конфигурирование) 5. [Управление службами](#5-управление-службами) 6. [Мониторинг и логирование](#6-мониторинг-и-логирование) 7. [Резервное копирование](#7-резервное-копирование) 8. [Безопасность](#8-безопасность) 9. [Устранение неисправностей](#9-устранение-неисправностей) --- ## 1. ОБЩИЕ СВЕДЕНИЯ ### 1.1. Назначение системы MOSTOVIK — система ETL (Extract, Transform, Load) для сбора и обработки данных из государственных источников: - **Минпромторг** (minpromtorg.gov.ru) — сертификаты промышленного производства, реестр производителей - **Единый реестр проверок** (proverki.gov.ru) — данные о проверках по ФЗ-294 и ФЗ-248 - **ФНС** — бухгалтерская отчётность ### 1.2. Технические характеристики | Параметр | Значение | |----------|----------| | Язык программирования | Python 3.11 | | Фреймворк | Django 3.2.25 | | База данных | PostgreSQL 15.10 | | Кеш/брокер | Redis 7.x | | Очереди задач | Celery 5.3.6 | | Веб-сервер | Apache 2.4.57 + Gunicorn | | Автоматизация браузера | Playwright 1.52+ | --- ## 2. АРХИТЕКТУРА СИСТЕМЫ ### 2.1. Компоненты системы ``` +-------------------------------------------------------------+ | Apache 2.4.57 | | (HTTPS termination) | +-----------------------------+-------------------------------+ | v +-------------------------------------------------------------+ | Gunicorn WSGI | | (3 workers, gevent) | +-----------------------------+-------------------------------+ | v +-------------------------------------------------------------+ | Django Application | | +--------------+ +--------------+ +------------------+ | | | Parsers | | Core | | User | | | | (apps) | | (apps) | | (apps) | | | +--------------+ +--------------+ +------------------+ | +-----------------------------+-------------------------------+ | +-------------+-------------+ v v v +---------------+ +-----------+ +---------------+ | PostgreSQL | | Redis | | File System | | (port 5432) | | (port 6379)| | (logs/media) | +---------------+ +-----------+ +---------------+ ``` ### 2.2. Службы Celery | Служба | Назначение | Порт | |--------|------------|------| | celery-worker | Выполнение фоновых задач | - | | celery-beat | Планирование периодических задач | - | | flower | Мониторинг Celery (опционально) | 5555 | ### 2.3. Структура каталогов ``` /var/www/project/ ├── src/ # Исходный код Django │ ├── config/ # Конфигурация │ │ ├── settings/ # Настройки (dev, prod, test) │ │ ├── celery.py # Конфигурация Celery │ │ └── wsgi.py # Точка входа WSGI │ ├── apps/ # Приложения Django │ │ ├── core/ # Базовые компоненты │ │ ├── parsers/ # Парсеры данных │ │ └── user/ # Пользователи и аутентификация │ └── manage.py # Утилита управления ├── venv/ # Виртуальное окружение Python ├── logs/ # Логи приложения ├── media/ # Пользовательские файлы ├── staticfiles/ # Статические файлы └── deploy/ # Файлы развёртывания ├── systemd/ # Unit-файлы systemd ├── apache/ # Конфигурация Apache └── scripts/ # Скрипты развёртывания ``` --- ## 3. РАЗВЁРТЫВАНИЕ СИСТЕМЫ ### 3.1. Системные требования **Минимальные:** - ЦПУ: 2 ядра - ОЗУ: 4 ГБ - Диск: 20 ГБ - ОС: Astra Linux / Ubuntu 20.04+ **Рекомендуемые:** - ЦПУ: 4 ядра - ОЗУ: 8 ГБ - Диск: 50 ГБ SSD - ОС: Astra Linux Special Edition ### 3.2. Предварительная настройка #### 3.2.1. Установка системных зависимостей ```bash apt-get update && apt-get upgrade -y apt-get install -y \ python3.11 \ python3.11-venv \ python3.11-dev \ postgresql-15 \ postgresql-client-15 \ redis-server \ apache2 \ libapache2-mod-wsgi-py3 \ git \ build-essential \ libpq-dev \ libffi-dev \ libxml2-dev \ libxslt1-dev \ zlib1g-dev ``` #### 3.2.2. Установка менеджера пакетов uv ```bash curl -LsSf https://astral.sh/uv/install.sh | sh source $HOME/.cargo/env ``` ### 3.3. Автоматическое развёртывание ```bash chmod +x deploy/scripts/deploy.sh sudo ./deploy/scripts/deploy.sh ``` Скрипт выполняет: - Обновление системы - Установку зависимостей - Клонирование репозитория - Создание виртуального окружения - Установку зависимостей Python - Настройку базы данных - Выполнение миграций - Настройку systemd и Apache ### 3.4. Ручное развёртывание #### 3.4.1. Настройка базы данных ```bash sudo -u postgres psql < . git checkout main # Создание виртуального окружения uv venv ${PROJECT_PATH}/venv source ${PROJECT_PATH}/venv/bin/activate # Установка зависимостей uv pip install --upgrade pip uv pip install -r requirements.txt ``` #### 3.4.3. Настройка окружения ```bash cp .env.example .env nano .env ``` **Обязательные параметры:** | Переменная | Описание | Пример | |------------|----------|--------| | SECRET_KEY | Ключ шифрования Django | django-insecure-... | | POSTGRES_DB | Имя базы данных | mostovik_prod | | POSTGRES_USER | Пользователь БД | mostovik_user | | POSTGRES_PASSWORD | Пароль БД | secure_password | | POSTGRES_HOST | Узел БД | 127.0.0.1 | | POSTGRES_PORT | Порт БД | 5432 | | REDIS_URL | URL Redis | redis://127.0.0.1:6379/0 | | CELERY_BROKER_URL | URL брокера | redis://127.0.0.1:6379/0 | #### 3.4.4. Выполнение миграций ```bash cd ${PROJECT_PATH}/src python manage.py makemigrations python manage.py migrate python manage.py collectstatic --noinput ``` #### 3.4.5. Создание суперпользователя ```bash python manage.py createsuperuser ``` Или автоматически: ```bash echo "from django.contrib.auth import get_user_model; User = get_user_model(); User.objects.create_superuser('admin', 'admin@example.com', 'adminpass') if not User.objects.filter(username='admin').exists() else None" | python manage.py shell ``` --- ## 4. КОНФИГУРИРОВАНИЕ ### 4.1. Настройка Apache Конфигурационный файл: /etc/apache2/sites-available/project.conf **Основные параметры для изменения:** ```apache ServerName your-domain.com SSLCertificateFile /etc/ssl/certs/your-cert.pem SSLCertificateKeyFile /etc/ssl/private/your-key.pem SSLCertificateChainFile /etc/ssl/certs/your-chain.pem ``` **Активация сайта:** ```bash a2ensite project.conf a2enmod ssl rewrite headers expires a2dissite 000-default systemctl restart apache2 ``` ### 4.2. Настройка systemd Файлы служб расположены в /etc/systemd/system/: | Файл | Служба | |------|--------| | gunicorn.service | WSGI-сервер Gunicorn | | celery-worker.service | Worker Celery | | celery-beat.service | Планировщик Celery | **Перезапуск после изменений:** ```bash systemctl daemon-reload systemctl restart gunicorn systemctl restart celery-worker systemctl restart celery-beat ``` ### 4.3. Настройка брандмауэра ```bash ufw allow 80/tcp ufw allow 443/tcp ufw deny 5432/tcp ufw deny 6379/tcp ufw enable ``` --- ## 5. УПРАВЛЕНИЕ СЛУЖБАМИ ### 5.1. Проверка состояния служб ```bash systemctl status gunicorn systemctl status celery-worker systemctl status celery-beat systemctl status apache2 systemctl status postgresql systemctl status redis-server ``` ### 5.2. Запуск/остановка/перезапуск ```bash systemctl start gunicorn systemctl stop gunicorn systemctl restart gunicorn systemctl start celery-worker systemctl stop celery-worker systemctl restart celery-worker systemctl start celery-beat systemctl stop celery-beat systemctl restart celery-beat systemctl restart apache2 ``` ### 5.3. Включение автозагрузки ```bash systemctl enable gunicorn celery-worker celery-beat apache2 postgresql redis-server ``` ### 5.4. Управление через Makefile ```bash cd /var/www/project make migrate make createsuperuser make shell make logs ``` --- ## 6. МОНИТОРИНГ И ЛОГИРОВАНИЕ ### 6.1. Логи приложения | Лог | Путь | |-----|------| | Django | /var/www/project/logs/django.log | | Celery | /var/www/project/logs/celery.log | | Gunicorn | /var/log/gunicorn/error.log | | Apache error | /var/log/apache2/project_error.log | | Apache access | /var/log/apache2/project_access.log | | PostgreSQL | /var/log/postgresql/postgresql-15-main.log | | Redis | /var/log/redis/redis-server.log | ### 6.2. Просмотр логов в реальном времени ```bash tail -f /var/www/project/logs/django.log tail -f /var/www/project/logs/celery.log journalctl -u gunicorn -f journalctl -u celery-worker -f journalctl -u celery-beat -f journalctl -u apache2 -f ``` ### 6.3. Мониторинг Celery Flower ```bash source /var/www/project/venv/bin/activate celery -A config flower --port=5555 ``` **Доступ:** http://localhost:5555 ### 6.4. Мониторинг базы данных ```bash sudo -u postgres psql mostovik_prod # Проверка размера таблиц SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size FROM pg_tables WHERE schemaname = 'public' ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC; # Проверка активных подключений SELECT * FROM pg_stat_activity WHERE datname = 'mostovik_prod'; ``` ### 6.5. Мониторинг Redis ```bash redis-cli INFO DBSIZE ``` --- ## 7. РЕЗЕРВНОЕ КОПИРОВАНИЕ ### 7.1. Резервное копирование базы данных ```bash #!/bin/bash BACKUP_DIR="/var/backups/mostovik" DATE=$(date +%Y%m%d_%H%M%S) DB_NAME="mostovik_prod" DB_USER="mostovik_user" mkdir -p ${BACKUP_DIR} pg_dump -U ${DB_USER} -h 127.0.0.1 ${DB_NAME} | gzip > ${BACKUP_DIR}/db_backup_${DATE}.sql.gz find ${BACKUP_DIR} -name "db_backup_*.sql.gz" -mtime +7 -delete ``` **Настройка cron:** ```bash 0 2 * * * /var/www/project/scripts/backup_db.sh ``` ### 7.2. Резервное копирование медиафайлов ```bash #!/bin/bash BACKUP_DIR="/var/backups/mostovik" DATE=$(date +%Y%m%d_%H%M%S) MEDIA_DIR="/var/www/project/media" mkdir -p ${BACKUP_DIR} tar -czf ${BACKUP_DIR}/media_backup_${DATE}.tar.gz ${MEDIA_DIR} find ${BACKUP_DIR} -name "media_backup_*.tar.gz" -mtime +7 -delete ``` ### 7.3. Восстановление ```bash # Восстановление БД gunzip -c db_backup_20260121_020000.sql.gz | psql -U mostovik_user -h 127.0.0.1 mostovik_prod # Восстановление медиа tar -xzf media_backup_20260121_020000.tar.gz -C /var/www/project/ ``` --- ## 8. БЕЗОПАСНОСТЬ ### 8.1. Минимальные требования 1. Смена SECRET_KEY в .env 2. Смена паролей БД и суперпользователя 3. Настройка HTTPS с действительным сертификатом 4. Ограничение доступа к портам БД и Redis 5. Регулярное обновление системы ### 8.2. Настройка SSL/TLS ```bash apt-get install certbot python3-certbot-apache certbot --apache -d your-domain.com -d www.your-domain.com certbot renew --dry-run ``` ### 8.3. Обновление зависимостей ```bash source /var/www/project/venv/bin/activate pip-audit uv pip install --upgrade -r requirements.txt systemctl restart gunicorn celery-worker celery-beat ``` ### 8.4. Аудит безопасности ```bash bandit -r /var/www/project/src/ pip-audit python manage.py check --deploy ``` --- ## 9. УСТРАНЕНИЕ НЕИСПРАВНОСТЕЙ ### 9.1. Служба не запускается ```bash journalctl -u -n 50 --no-pager apache2ctl configtest systemctl cat ``` ### 9.2. Ошибки подключения к БД ```bash systemctl status postgresql sudo -u postgres psql -c "SELECT * FROM pg_stat_activity WHERE datname = 'mostovik_prod';" cat /var/www/project/.env | grep POSTGRES ``` ### 9.3. Ошибки Celery ```bash journalctl -u celery-worker -n 100 source /var/www/project/venv/bin/activate celery -A config inspect active celery -A config inspect registered celery -A config status celery -A config purge # осторожно! ``` ### 9.4. Проблемы с производительностью ```bash free -h top -p $(pgrep -d',' -f gunicorn|celery) df -h du -sh /var/www/project/logs ``` **Оптимизация PostgreSQL:** ```sql SELECT query, calls, total_time, mean_time FROM pg_stat_statements ORDER BY mean_time DESC LIMIT 10; VACUUM ANALYZE; ``` --- ## ПРИЛОЖЕНИЕ А. КОМАНДЫ БЫСТРОГО ДОСТУПА ```bash # Перезапуск всех служб systemctl restart apache2 gunicorn celery-worker celery-beat # Проверка состояния systemctl status apache2 gunicorn celery-worker celery-beat postgresql redis-server # Просмотр логов journalctl -u gunicorn -n 100 --no-pager # Django shell cd /var/www/project/src && python manage.py shell # Миграции cd /var/www/project/src && python manage.py makemigrations && python manage.py migrate # Статические файлы cd /var/www/project/src && python manage.py collectstatic --noinput ``` --- ## ПРИЛОЖЕНИЕ Б. ПЕРИОДИЧЕСКИЕ ЗАДАЧИ CELERY | Задача | Расписание | Описание | |--------|------------|----------| | parse_industrial_production | Ежедневно в 3:00 | Парсинг сертификатов Минпромторга | | parse_manufactures | Ежедневно в 4:00 | Парсинг реестра производителей | | scan_fns_directory | Каждые 5 минут | Сканирование папки ФНС | **Изменение расписания:** Через Django Admin: /admin/django_celery_beat/periodictask/ --- *Документ составлен на основе версии кода от 2026-01-21*