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 runserveruv 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Вариант без установки 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 -dmake 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 — не отключать).
Аутентификация — токен раннера в заголовке 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.
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.