Skip to content
barabackerPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Dashboard

Control plane для парсеров: Django с админкой на Unfold, который знает что и когда запускать, ставит задания в очередь taskiq и ведёт журнал запусков с логами.

Сами парсеры живут в отдельном репозитории и сами решают, куда складывать данные. Через control plane данные не проходят — только задания и отчёты о выполнении.

Стек

Django 5.2
django-unfold 0.91
БД SQLite (файл db.sqlite3)
Очередь taskiq + Redis
Расписания cron-выражения, их исполняет планировщик taskiq
Пакеты и venv uv — pyproject.toml + uv.lock

Из системного нужен только Redis (в Docker он поднимается сам). Python и зависимости ставит uv.

Запуск

make install     # uv sync: создаст .venv и поставит зависимости по локу
make migrate
make superuser
make run

Админка: http://127.0.0.1:8000/admin/

Это только веб-часть. Чтобы источники запускались по расписанию, нужны ещё Redis и два процесса taskiq — см. Запуск по расписанию.

Без Makefile — то же самое напрямую:

uv sync
uv run manage.py migrate
uv run manage.py createsuperuser
uv run manage.py runserver

uv run сам поднимает окружение — активировать venv не нужно. Если uv ещё не стоит:

curl -LsSf https://astral.sh/uv/install.sh | sh                  # macOS / Linux
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"        # Windows

Docker

Вариант без установки Python и uv на машину.

docker compose up -d --build     # или make docker-up
docker compose run --rm web python manage.py createsuperuser

Админка: http://127.0.0.1:8000/admin/ — порт меняется переменной PORT.

migrate прогоняет миграции и завершается, затем стартуют web и scheduler. Миграции вынесены в отдельный шаг намеренно: у SQLite один писатель, и параллельный migrate из двух контейнеров может встать на блокировке. Очередь держит сервис redis: он ничего не сохраняет на диск — задания, потерянные при перезапуске, планировщик поставит заново по расписанию.

Воркер вынесен в профиль — в бою он живёт в репозитории парсеров, но для локальной проверки поднимается вместе с остальным:

RUNNER_TOKEN=... docker compose --profile runner up -d
make docker-logs         # логи всех сервисов
make docker-down         # остановить; том с базой остаётся
docker compose down -v   # остановить и удалить базу

Код прокинут внутрь контейнера томом, поэтому правки видны без пересборки — образ нужно пересобирать только при изменении зависимостей (uv.lock). Виртуальное окружение лежит в /venv, вне /app, чтобы bind-mount его не перекрывал. База — в именованном томе по пути /data/db.sqlite3 (переменная DJANGO_DB_PATH).

Команды

make help покажет список. Основное:

Команда Что делает
make install / make sync зависимости: по локу / строго по локу, без перерешения
make lock / make upgrade пересобрать лок / поднять версии в пределах ограничений
make run сервер разработки, порт меняется через PORT=8080
make scheduler планировщик taskiq: ставит задания по cron источников
make worker референсный воркер парсеров (нужен RUNNER_TOKEN)
make maintenance просроченные запуски и чистка старых логов
make migrate / make migrations применить / создать миграции
make test тесты
make lint / make fmt проверить / отформатировать код (ruff)
make check manage.py check + проверка несозданных миграций
make ci всё, что гоняет CI: lint + check + test
make clean / make distclean убрать кэши / ещё и venv с базой
make docker-up / make docker-down поднять / остановить всё в Docker
make docker-build / make docker-logs пересобрать образ / смотреть логи
make docker-superuser / make docker-shell суперпользователь / shell в контейнере

Структура

.env.example         шаблон переменных окружения
Dockerfile           образ на базе uv, зависимости строго по uv.lock
compose.yaml         сервисы redis, migrate, web, scheduler и runner, общий том с базой
config/settings.py   настройки проекта и словарь UNFOLD (сайдбар, цвета, тема)
config/scheduler.py  точка входа планировщика taskiq
config/urls.py       / → редирект на /admin/
core/admin.py        пользователи и группы под Unfold, бейдж окружения
control/models.py    Source, Run, RunLog, Runner
control/broker.py    брокер taskiq: объявление задачи и публикация заданий
control/schedule.py  источник расписаний для планировщика: читает cron из базы
control/services.py  начало запуска, приём логов и результатов
control/api.py       четыре эндпоинта для воркеров
control/admin.py     админка control plane, лента логов
control/management/commands/maintenance.py   просроченные запуски и чистка логов
runner/              референсный воркер и демо-парсеры
static/              статика проекта (пока пусто, каталог нужен для collectstatic)

Как это настроено

Unfold идёт первым в INSTALLED_APPS — до django.contrib.admin, иначе его шаблоны не подхватятся.

Своя админ-модель наследует ModelAdmin из Unfold:

from unfold.admin import ModelAdmin

@admin.register(Article)
class ArticleAdmin(ModelAdmin):
    list_display = ("title", "created_at")

Для моделей, у которых уже есть готовый ModelAdmin (User, Group), миксуются оба — см. core/admin.py.

Сайдбар задаётся вручную в UNFOLD["SIDEBAR"]["navigation"] — новые разделы нужно дописывать туда, автоматически они не появляются.

Как это работает

Django (control plane)          Redis        Воркер (отдельный репозиторий)
  планировщик по cron      ──→  очередь  ──→   берёт задание
  «Запустить сейчас»       ──→  очередь         выполняет парсер
  журнал: логи и отчёт     ←────── HTTP ──────  шлёт логи пачками и результат

Три процесса: web (админка и API), scheduler (планировщик taskiq) и воркер парсеров. Задания ходят через Redis, журнал — по HTTP: данные и логи в очередь не попадают, там только «выполни источник X».

Планировщик раз в минуту перечитывает активные источники из базы, поэтому cron правится в админке и подхватывается без перезапуска процесса. Само задание — только slug источника: параметры воркер получает, когда начинает запуск, так что в очереди не лежат устаревшие настройки.

Источник — что запускать: ключ парсера, параметры (JSON), cron, уровень логов. Ключ и параметры интерпретирует воркер, control plane в них не заглядывает.

Запуск — журнал: статус, тайминги, счётчики, ошибка и непрозрачная ссылка на то, куда воркер положил данные.

Данные в control plane не хранятся. Схема данных живёт в парсере и может меняться без миграций здесь.

Управление из админки

Раздел Что делает
Источники создать, поменять cron и параметры, включить и выключить, кнопка «Запустить сейчас»
Запуски история со статусами и счётчиками; на странице запуска — лента лога, пока запуск идёт, она сама обновляется
Логи сквозной просмотр по всем источникам: например, все ошибки за сутки
Раннеры токены воркеров и время последней активности

Источник отключается автоматически после N неудач подряд (поле «отключить после N неудач», 0 — не отключать).

API для воркеров

Аутентификация — токен раннера в заголовке X-Runner-Token.

Метод Назначение
POST /api/v1/runs/start/ начать запуск источника, в ответе — параметры; 409, если он уже выполняется
POST /api/v1/runs/<id>/logs/ отправить пачку строк лога, продлевает аренду
POST /api/v1/runs/<id>/heartbeat/ «жив, работаю» — продлить аренду
POST /api/v1/runs/<id>/complete/ завершить: статус, счётчики, ссылка на результат, ошибка

Запись в журнале создаёт start, а не очередь: пока воркер не взялся за работу, запуска нет. Поэтому задание, застрявшее в очереди, не висит в журнале как «выполняется», а два задания по одному источнику не наложатся друг на друга — второй start получит 409.

Если воркер пропал, запуск висит не вечно: у задания есть срок аренды, по его истечении запуск помечается просроченным и источник получает неудачу.

Логи

Парсер пишет обычным logging — воркер подсовывает обработчик, который копит строки и отправляет их пачками. В логи не должны попадать сами данные: только счётчики, идентификаторы и URL, иначе данные просочатся в control plane через чёрный ход.

Ограничители на стороне Django: не больше 10 000 строк на запуск, длина строки до 4 000 символов, срок хранения 30 дней. Настраивается словарём CONTROL в config/settings.py.

Запуск по расписанию

Нужны Redis и три процесса — каждый в своём терминале:

redis-server                                      # очередь заданий
uv run manage.py runserver                        # админка и API
uv run taskiq scheduler config.scheduler:scheduler  # планировщик, он же make scheduler

Воркер парсеров — четвёртый процесс. В runner/ лежит референсная реализация (стандартная библиотека плюс taskiq-redis): её место в репозитории парсеров, здесь она для прогона всего цикла. Токен создаётся в админке, раздел «Раннеры»:

cd runner
DASHBOARD_URL=http://127.0.0.1:8000 RUNNER_TOKEN=... uv run taskiq worker tasks:broker

То же самое — make worker. Кнопка «Запустить сейчас» в админке кладёт задание в ту же очередь: без воркера оно просто дождётся его появления.

Планировщик и воркер общаются только через Redis, адрес берётся из REDIS_URL — воркеру не нужен доступ к базе, а Django не исполняет задачи.

Обслуживание

uv run manage.py maintenance          # просроченные запуски + чистка логов

Вешается на системный планировщик (cron, systemd timer, Планировщик заданий). Ключи --log-days, --run-days, --dry-run.

CI

GitHub Actions (.github/workflows/ci.yml) на каждый push в main и на каждый PR:

Job Что делает
Линтер uv sync --locked, затем ruff check + ruff format --check
Тесты manage.py check, проверка несозданных миграций, manage.py test, collectstatic на Python 3.11 / 3.12 / 3.13

Оба job'а ставят зависимости через uv sync --locked: версии берутся из uv.lock, CI падает, если лок разошёлся с pyproject.toml. После правки зависимостей нужно закоммитить обновлённый uv.lock (make lock).

Локально то же самое — make ci.

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

Настройки читаются из переменных окружения. Локально удобнее держать их в .env:

cp .env.example .env

Файл в git не попадает (.env.example — попадает, это шаблон). Читает его load_env_file() в config/settings.py — без внешних зависимостей. Правила: переменная, уже заданная в окружении, побеждает файл; при дубле ключа в файле побеждает последняя строка; строки с # и пустые игнорируются, кавычки снимаются.

docker compose подхватывает тот же .env сам — и для подстановки ${...} в compose.yaml, и как env_file внутри контейнеров (если файла нет, всё работает на значениях по умолчанию).

Переменная По умолчанию
DJANGO_SECRET_KEY небезопасный ключ для разработки
DJANGO_DEBUG 1
DJANGO_ALLOWED_HOSTS *
CONTROL_LEASE_SECONDS 600 — срок аренды задания
CONTROL_LOG_RETENTION_DAYS 30 — сколько хранить строки логов
REDIS_URL redis://127.0.0.1:6379/0; в Docker — redis://redis:6379/0
RUNNER_TOKEN, DASHBOARD_URL читает воркер: токен из админки и адрес control plane
DJANGO_DB_PATH db.sqlite3 в корне проекта; в Docker — /data/db.sqlite3
PORT 8000 — порт, на котором админка доступна на хосте (Docker и make run)

Перед деплоем обязательно задать свой DJANGO_SECRET_KEY, выключить DJANGO_DEBUG и перечислить реальные хосты в DJANGO_ALLOWED_HOSTS.

Зависимости

Добавить пакет: uv add <пакет> (в dev-группу: uv add --dev <пакет>) — uv сам обновит pyproject.toml, uv.lock и окружение. Удалить: uv remove <пакет>. uv.lock коммитится, .venv/ — нет.

Что дальше

  • Перенести runner/ в репозиторий парсеров и убрать отсюда — здесь он временно, для прогона цикла.
  • Отдельные очереди под тяжёлые источники: queue_name у брокера, чтобы долгий парсер не занимал воркеров, которым нужно успеть к сроку.
  • Цепочки шагов: запускать обработку после успешного парсинга того же источника.
  • Проверки качества по истории счётчиков: «ноль записей два раза подряд» или «записей вдвое меньше среднего» — пометить подозрительным.
  • Свой дашборд на главной, когда будет что показывать: создать каталог templates/, вернуть его в TEMPLATES["DIRS"], положить туда admin/index.html и указать UNFOLD["DASHBOARD_CALLBACK"].
  • Русская локаль для Unfold: часть строк интерфейса («Type to search», «Filters») остаётся английской, лечится собственным .po-файлом.
  • Гео-слой (SpatiaLite + GDAL + карты в формах) — рабочий вариант лежит в истории, коммит d5efad7: git show d5efad7 --stat.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages