595 lines
17 KiB
Markdown
595 lines
17 KiB
Markdown
# РУКОВОДСТВО АДМИНИСТРАТОРА
|
||
## Система 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*
|