Как собрать приложение на keepup

Начало работы

Нужен Python 3.11 или новее. Для разработки хватит SQLite, в работе — PostgreSQL.

python3 -m venv .venv && . .venv/bin/activate
# полная панель: HTTP-слой и вход, разделы, база и один драйвер
pip install "keepup-admin[panel,postgres]" uvicorn

Возможности ставятся extras: один экстра — один дистрибутив. База — только конструктор: ядро, каталог плагинов, реестр служб, жизненный цикл и шов транспорта. Она не объявляет ни одной чужой библиотеки, даже FastAPI; каждая возможность объявляет свои.

Экстра panel ставит всё, что нужно панели, кроме драйвера; драйвер выбирают отдельно — postgres в работе, sqlite для разработки. Два драйвера одной обязательной службы останавливают старт намеренно.

Приложение — это файл, который передаёт настройки и получает ASGI-приложение. Таблицы, объявленные плагинами (get_declared_tables()), ядро создаёт само при старте; первые учётные записи создаёт keepup-auth:

import os

from keepup import KeepupSettings, create_app

PLUGINS_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "plugins")

app = create_app(KeepupSettings(
    title="Your product",
    project_name="yours",
    plugins_dir=PLUGINS_DIR,
    static_mounts=(),
))

{"plugins": [], "roles": []}

Два значения задаёт тот, кто разворачивает, а не код:

export SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
export ADMIN_INITIAL_PASSWORD="придумайте-свой"
uvicorn main:app --port 8000

Что после этого отвечает:

• /selfcare — панель администрирования: вход под admin, восемь разделов; оболочку и разделы ставит keepup-http.
• /api/docs и /api/redoc — описание API.
• /api/health — здоровье процесса.

База по умолчанию — SQLite в data/keepup_db относительно рабочего каталога.

Проверки

Дерево для разработки ставится из репозитория: pip install -e ".[test]" -e packages/keepup-*. Одна команда прогоняет всё: .github/scripts/check.sh — линт, набор с покрытием, выпуск и граф, аудит безопасности и сборку всех колёс; --fast пропускает колёса и аудит. Тесты в дереве называются *_tests.py и запускаются по пути: python -m pytest tests/your_tests.py -v.

Раскладка проекта

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

yours/
├── main.py                   # KeepupSettings -> app
├── plugins/
│   └── hello.py              # class HelloPlugin(BasePlugin)
├── config/
│   ├── modules.json          # плагины, разделы панели, роли
│   ├── auth.yaml             # provider: local (необязателен)
│   └── postgres.properties   # где база (необязателен)
└── static/                   # свой фронтенд, если он есть

Каталог плагинов вычисляйте от расположения файла, а не от рабочего каталога — тогда плагины находятся, откуда бы ни запустили процесс:

import os

PLUGINS_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "plugins")
# Дальше каталог называет настройка: plugins_dir=PLUGINS_DIR.

Два приложения на keepup в одном каталоге — ошибка, а не беспорядок: при старте каталог разделов панели дополняется из config/modules.json, и второе приложение получило бы разделы первого.

KeepupSettings

Единственная точка настройки. Всё, чего каркас не может знать сам, приходит сюда; значения по умолчанию закрывают, а не открывают.

profile — заплатка поверх каталога плагинов (plugins/builtin.json объявляет «panel» и «metrics-only»), а не второй формат настройки: один код служит полной панелью, воркером и процессом, который отвечает только /metrics. Профиль metrics-only заменил удалённую настройку disable_http_server. Настройки app_tables и extra_setup и модуль keepup.schema с его init_db() удалены в 0.5.0.

Плагины и маршруты

Возможность приложения — плагин: класс-наследник BasePlugin в своём файле. Каркас грузит его по объявлению в config/modules.json.

Имя класса выводится из id

Файл — plugins/<id>.py, класс — f"{id.capitalize()}Plugin": hello → HelloPlugin, integration_logs → Integration_logsPlugin. Ошибка в имени не роняет старт: плагин просто не загружается, а в журнале остаётся предупреждение.

Хуки

Маршрут — это словарь

Декораторов нет: каркас сам строит обёртку FastAPI для каждого маршрута, поэтому вход, разбор параметров и аудит у всех маршрутов одинаковы.

Обработчик принимает current_user: dict и обычные именованные аргументы: параметры пути и строки запроса приходят по имени, тело записи — в request. Незнакомый параметр — ответ 400, а не 500: если у маршрута есть маска, решает она и приводит типы; если нет — сигнатура обработчика (обработчик с **kwargs принимает всё).

def get_api_routes(self):
    return [{
        "path": "/api/shops/{shop_id}/offers",
        "methods": ["GET"],
        "handler": self.list_offers,
        "params": {
            "shop_id": {"type": "int"},
            "status": {"type": "str", "choices": ["active", "archived"]},
        },
    }]

async def list_offers(self, current_user: dict, shop_id: int, status: str = "active"):
    ...

Объявление и включение

{
  "plugins": [
    {"id": "hello", "name": "Hello", "enabled": true, "priority": 100,
     "config": {"greeting": "hi"}}
  ],
  "roles": [
    {"name": "ADMIN", "modules": [], "plugins": ["hello"]}
  ]
}

Будет ли объявленный плагин работать, решается по порядку, от сильного к слабому: PLUGINS_DISABLE → PLUGINS_ENABLE → переключатель в панели → флаг enabled в файле. Меньший priority поднимается раньше. Список plugins у роли — это видимость в /api/plugins, а не включение.

Ядро

Плагин загружается конструктором — ядром. Плагин объявляет дескриптор: id, вид (required, optional, transport), что ему нужно (requires, wants) и что он даёт (provides, contributions). Из дескрипторов собирается каталог: собственный каталог каркаса (plugins/builtin.json), файл приложения (config/modules.json) и профиль (settings.profile) — каждый следующий слой правит предыдущий. Плагины публикуют службы в реестр (provides), а берут чужие через requires; жизненный цикл запускает их в две фазы — сперва те, чьи требования уже выполнены, затем остальные. Обязательный плагин и транспорт включаются самим фактом установки, необязательный — файлом, PLUGINS_ENABLE, профилем или администратором.

from keepup.kernel import create_runtime

runtime = create_runtime(settings)   # Runtime, ещё не запущенный

Имена служб, которые плагин может требовать и публиковать, перечислены в doc/service-catalogue.md; контракт конструктора — в doc/plugin_constructor.md. Если приложение собрало менеджер плагинов само, настройка plugin_manager передаёт его ядру.

Панель

Панель живёт на /selfcare. Оболочка — страницы тем, скрипт и стили — едет с keepup-http и отдаётся из shell_mount; база фронтенд не несёт, копировать оболочку к себе не нужно.

Восемь разделов каркаса

Их и оболочку ставит keepup-http. При старте они заносятся в каталог и по умолчанию выданы роли ADMIN:

• Пользователи — учётные записи, роли, сессии.
• Разделы — каталог разделов панели и выдача их ролям.
• Кластер — реплики, их плагины и состояние; остановка, запуск, перезапуск.
• Метрики — процессор и память по репликам.
• Темы — оформление панели.
• События — журнал событий приложения.
• Фоновые задачи — задачи планировщика и распределённые блокировки.
• Журнал интеграций — исходящие вызовы во внешние системы.

Свой раздел

Раздел — это скрипт и, при желании, стиль, объявленные в modules[] того же modules.json, и строка в modules роли. Оболочка загружает скрипт и вызывает window[initFunction]().

{
  "modules": [{
    "id": "orders",
    "name": "Orders",
    "js": "/static/modules/js/orders.js",
    "css": "/static/modules/css/orders.css",
    "initFunction": "initOrdersModule",
    "routePath": "/selfcare/modules/orders",
    "sectionId": "orders-section",
    "config": {}
  }],
  "roles": [{"name": "CLIENT", "modules": ["orders"], "plugins": []}]
}

Каталог живёт в базе; файл — затравка. При старте добавляются только разделы и выдачи, которых в базе ещё нет, — то, что администратор выключил в панели, так и остаётся выключенным.

Темы

Своих тем каркас не навязывает: темы — дистрибутив keepup-ui (keepup_ui.themes), приложение перечисляет их в built_in_themes кортежами (name, page_file, brand, logo). На пустой базе активной становится первая; на существующей остаётся выбор администратора.

База данных

Где база

Если задана переменная DB_TYPE, всё берётся из окружения: DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_PATH, DB_POOL_*. Если нет — из config/postgres.properties (ключи db.*); пароль и тогда можно передать через DB_PASSWORD. Без того и другого — SQLite.

export DB_TYPE=postgres DB_HOST=db.internal DB_NAME=yours DB_USER=yours
export DB_PASSWORD=…

Запросы

DatabaseManagerV2 — движок SQLAlchemy с пулом. Параметры только именованные.

from keepup_db import DatabaseManagerV2

rows = DatabaseManagerV2.execute(
    "SELECT id, name FROM orders WHERE owner_id = :owner", {"owner": user_id})

with DatabaseManagerV2.get_session() as session:   # commit или rollback сам
    ...

Таблица объявляется один раз

Миграций нет. Таблица — объявление SQLAlchemy Core для обоих диалектов; ensure_tables() при каждом старте создаёт недостающее: CREATE TABLE IF NOT EXISTS, недостающие столбцы, индексы. Новый столбец — это просто новый Column.

from sqlalchemy import Column, Integer, Text
from keepup_db import tables

orders = tables.table(
    "orders",
    Column("id", Integer, primary_key=True, autoincrement=True),
    Column("owner_id", Integer, nullable=False),
    Column("title", Text, nullable=False),
    tables.foreign_key("owner_id", "users", ("id",), ondelete="CASCADE"),
)

tables.ensure_tables(orders)

Различия диалектов живут в объявлении (with_variant, ddl_if, tables.per_dialect(postgres=…, sqlite=…)). Столбец на чужой таблице — например, на users — добавляется через tables.ensure_columns("users", Column(…)), а не вторым объявлением.

Несколько реплик против одной базы

Приложение на keepup рассчитано на несколько процессов за балансировщиком. Всё согласование идёт через общую базу — реплики не знают адресов друг друга.

Распределённая блокировка

Фоновая работа, которая должна идти в одной реплике, берётся под блокировку в таблице distributed_locks. Держатель продлевает её, пока работает, поэтому работа может длиться сколько угодно; перехватывается только блокировка того, кто замолчал.

from keepup.locks import distributed_lock, with_distributed_lock

@with_distributed_lock("nightly_report", timeout=300)
async def nightly_report():
    ...   # идёт в одной реплике; в остальных запуск пропускается

async def purge():
    try:
        async with distributed_lock("purge_journal", timeout=1):
            ...
    except Exception:
        pass  # чистит другая реплика — этого достаточно

Декоратор при занятой блокировке пропускает запуск и возвращает None; контекстный менеджер бросает исключение.

Шина сообщений

Задайте notification_channel — и каркас поднимет шину на PostgreSQL LISTEN/NOTIFY до инициализации плагинов. deliver() отправляет конверт другим репликам и раздаёт его подписчикам своей; publish() — только другим.

from keepup import notification_bus

bus = notification_bus.get_notification_bus()
if bus is not None:
    bus.subscribe(self.on_envelope)          # в initialize() плагина

await notification_bus.deliver({"kind": "order_changed", "order_id": 42})

Реестр кластера

Каждая реплика публикует себя в cluster_members и забирает адресованные ей команды из cluster_commands. Раздел «Кластер» панели показывает реплики и их плагины и умеет три команды: stop — процесс жив, но отвечает 503 на API и приостанавливает планировщик; start — обратно; restart — штатная остановка и перезапуск той же командной строки.

Фоновые задачи

Планировщик, который ставит keepup-tasks (keepup_tasks.scheduler), — один на процесс, его задачи видны в разделе «Фоновые задачи» и запускаются оттуда вручную. От запуска одной и той же задачи во всех репликах защищает не планировщик, а блокировка вокруг самой задачи.

Пользователи и вход

Учётные записи живут в базе приложения (provider: local в config/auth.yaml; без файла — то же самое). Роли две — ADMIN и CLIENT (keepup.roles), но пользователь держит набор ролей: он лежит в таблице user_roles, и разделы с плагинами всех ролей набора склеиваются. Спрашивать надо keepup_auth.user_roles.has_role(user, ROLE_ADMIN) (в панели — window.AppRoles.has(user, role)), а не сравнивать user["role"]. Колонки users.role больше нет: в ответах входа (/api/auth/me и список пользователей) поле role осталось посчитанным из набора — для старых панелей. Пустой набор запрещён на запись, а доступ закрывают блокировкой учётной записи, а не снятием ролей. Вход выдаёт токен, подписанный SECRET_KEY, а панель держит сессию в cookie.

• Регистрация закрыта, пока SELF_REGISTRATION_ENABLED не равна true.
• Правило пароля — password_rule(password, username) в настройках: вернуть текст проблемы или None.
• Свои маршруты вне плагинов получают пользователя зависимостями get_current_user и get_current_admin из keepup_auth.dependencies.

Вход через внешний провайдер

OpenID Connect включается одним полем. Без него маршруты /api/auth/oidc/login и /api/auth/oidc/callback даже не регистрируются.

import os

from keepup import KeepupSettings
from keepup.settings import OidcSettings

settings = KeepupSettings(
    title="Your product",
    oidc=OidcSettings(
        issuer="https://id.example.com/realms/yours",
        client_id="yours",
        client_secret=os.environ["OIDC_CLIENT_SECRET"],
        redirect_uri="https://yours.example.com/api/auth/oidc/callback",
        roles_claim="groups",
    ),
)

Без oidc_account_policy человеку, которого приложение ещё не знает, вход закрыт. Политика — функция от утверждений провайдера; готовые лежат в keepup_auth.oidc_policy: refuse_unknown(), create_account(), create_if_email_domain([...]) — последняя сверяет адрес, только если провайдер его подтвердил.

Наблюдаемость

Четыре независимых канала, все подключены в жизненном цикле приложения.

• Аудит входящих запросов — каждый маршрут плагина пишется в incoming_requests через буфер. Из тела запроса по умолчанию остаются только имена полей; иначе решает audit_redaction (готовые — keepup_audit.audit.names_only и keep_as_is).
• Журнал событий — await emit_event(event_type, event_text, event_data) из keepup_audit.events; раздел «События» фильтрует по declared_event_types.
• Метрики — /metrics для Prometheus (без учётных данных — только если metrics_public=True) и снимки процессора и памяти по репликам для панели.
• Логи — локально с ротацией, а при заданном remote_log_url ещё и пакетами в ваш сборщик.

from keepup_audit.events import emit_event

await emit_event("order_accepted", "Order #42 accepted", {"order_id": 42})

Безопасность по умолчанию

Где значению по умолчанию пришлось бы угадывать, каркас закрывает. Приложение само говорит, что ему нужно открыть.

Функции, которые плагины дают друг другу через get_handlers(), по HTTP не публикуются. Проверка токенов провайдера отвергает симметричные алгоритмы и none и на любой провал отвечает одинаково, чтобы по ответу нельзя было понять, какая проверка не прошла.

Публичный интерфейс и версии

Модуль, из которого приложению можно импортировать, объявляет __all__. Всё остальное — внутреннее и может измениться без предупреждения, включая любое имя с подчёркиванием. Тест в репозитории каркаса держит это правило против настоящих приложений: имя, взятое из каркаса и не объявленное публичным, роняет прогон.

Номер версии — три числа. Мажорное меняет то, на что уже опираются: API отвечает иначе, путь проходится иначе. Минорное добавляет возможности или убирает устаревшее. Третье — срочная правка дефекта и ничего больше.

Переезд модулей

Почти все имена keepup.<что-то> уехали в свои дистрибутивы. Слоя совместимости нет: старый импорт даёт ModuleNotFoundError.

Каталога-пакета keepup/ тоже нет: корень репозитория и есть пакет. В базе остались keepup.roles, keepup.locks, keepup.notification_bus, keepup.kernel, keepup.plugins.base, keepup.settings, keepup.security, keepup.cache, keepup.instance, keepup.api_versions и keepup.logging_setup.

Что изменилось от версии к версии — в CHANGELOG.