Адмін-панель
Єдина автентифікована поверхня — вхід, призначення екранів, що потрапляє в аудит.
Усе в публічному API — лише на читання. Редагування каталогу відбувається на /admin, за логіном.
Вхід
Один акаунт, налаштований через оточення:
| Налаштування | Що |
|---|---|
ADMIN_USERNAME |
логін |
ADMIN_PASSWORD_HASH_FILE |
шлях до файлу з argon2id-хешем, ніколи не паролем |
ADMIN_SECRET_KEY_FILE |
шлях до файлу з ключем підпису сесійної куки |
(ADMIN_PASSWORD_HASH і ADMIN_SECRET_KEY теж працюють як прямі значення — так
зручно локально. У проді потрібна форма *_FILE, див. попередження нижче.)
Згенеруйте хеш на машині, яка його триматиме:
python -m app.cli hash-password
# Password: ········
# $argon2id$v=19$m=65536,t=3,p=4$...
Ніколи не кладіть хеш у compose-
.env
docker compose розкриває $ у тому самому env_file, який використовує для
власної підстановки змінних. Argon2-хеш повний $, тож $argon2id$v=19$m=65536,…,
записаний у .env, доїжджає в контейнер як =19=65536,…. Панель стартує,
вважає себе налаштованою й відхиляє правильний пароль із 401 — і ніде немає
помилки, яка б це пояснила. Монтуйте обидва значення файлами; прод-compose уже так робить.
Пароль у відкритому вигляді ніде не пишеться — ні в .env, ні в docker inspect, ні в лог деплою. Витік оточення дає хеш для брутфорсу, а не робочий кред.
Прод не стартує без цього
З APP_ENV=production і увімкненою адмінкою відсутній ADMIN_SECRET_KEY чи ADMIN_PASSWORD_HASH — це помилка старту. Порожній ключ підпису робив би кожну сесійну куку підробною, і впасти голосно на буті краще, ніж це обслуговувати.
Сесії — підписані куки, HttpOnly, SameSite=Lax, Secure у проді, дійсні 12 годин. Невдалі спроби входу тротляться по IP клієнта (10 спроб / 5 хвилин). Зміна ADMIN_USERNAME інвалідує всі наявні сесії.
Екрани
Overview — лічильники каталогу й таблиця покриття по провайдерах. Важливі колонки: explicit (закріплено), derived (відповідь дала драбина фолбеку) і unsupported, пораховані лише по активних регіональних мовах, бо базовим мапінг не потрібен. Лічильник derived — це ваша черга роботи.
Providers — та сама таблиця плюс налаштування провайдера: назва, категорія, політика фолбеку, аліаси й інструмент copy mappings для підключення нових.
Matrix — головний екран. Див. Editing the Matrix.
Languages — пошук по назвах, кодах і аліасах; редагування мови; додавання й видалення аліасів; створення нової. Сторінка мови також показує, що кожен провайдер отримає для неї, з можливістю правити по рядку.
Tools — живий тестер резолвінгу, що виконує рівно той самий код, що й /v1/resolve, і JSON-експорт усього каталогу у форматі сід-файлів.
Audit — кожен запис, лише додавання, найновіші зверху.
Що потрапляє в аудит
Кожна мутація фіксує актора, дію, сутність, її ключ і знімок before/after. Актор — це логін адміна плюс IP клієнта: в панелі один акаунт, тож саме IP відрізняє двох людей, які нею користуються.
Рядки аудиту застосунок ніколи не редагує й не видаляє.
Якщо панель недоступна
| Симптом | Причина |
|---|---|
503 admin_unavailable |
порожній ADMIN_PASSWORD_HASH або ADMIN_SECRET_KEY |
| «Session expired» на кожен сабміт | заблоковані куки, або ADMIN_COOKIE_SECURE=true при роботі по HTTP |
429 |
тротлінг входу — перечекайте 5-хвилинне вікно |
ADMIN_ENABLED=false прибирає панель повністю; публічний API це не зачіпає.
Далі
- Editing the Matrix — екран, у якому ви проведете час
- Закріпити код провайдера