добавил документов в папку

2026-03-26 15:46:37 +03:00
parent 1b326eb1b0
commit 3b986b6310
8 changed files with 3469 additions and 0 deletions
--- a/docs/RUKOVODSTVO_ADMINISTRATORA.md
+++ b/docs/RUKOVODSTVO_ADMINISTRATORA.md
@@ -0,0 +1,594 @@
+# РУКОВОДСТВО АДМИНИСТРАТОРА
+## Система 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 <<EOF
+CREATE DATABASE mostovik_prod;
+CREATE USER mostovik_user WITH PASSWORD 'secure_password';
+GRANT ALL PRIVILEGES ON DATABASE mostovik_prod TO mostovik_user;
+ALTER DATABASE mostovik_prod OWNER TO mostovik_user;
+EOF
+```
+
+#### 3.4.2. Установка приложения
+
+```bash
+PROJECT_PATH="/var/www/project"
+mkdir -p ${PROJECT_PATH}/{src,logs,media,staticfiles}
+cd ${PROJECT_PATH}
+
+# Клонирование репозитория
+git clone <repository_url> .
+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 <service_name> -n 50 --no-pager
+apache2ctl configtest
+systemctl cat <service_name>
+```
+
+### 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*