Для первого входа в систему администрирования создайте суперадминистратора через терминал. Логин и пароль задаёте вы: стандартной учётной записи и публичной страницы регистрации владельца нет.
Откуда приложение получает настройки
Для dev настройки берутся из .env: make dev подготавливает файл, а Makefile передаёт его значения процессам. При прямом запуске через go run передайте переменные самостоятельно — такой запуск не читает .env автоматически.
Для prod-local и сервера контроллер читает deploy/environments/<имя>.json. Из него он создаёт рабочую конфигурацию в <root>/config, размещает секреты в <root>/secrets и подключает файлы к контейнерам. Изменение dev-файла .env не меняет настройки prod-local.
| Переменная backend | Назначение |
|---|---|
APP_PROFILE |
local для dev, production для контейнерного серверного режима, включая prod-local |
HTTP_HOST, HTTP_PORT |
Адрес и порт прослушивания API; публикацией HTTPS занимается reverse proxy |
DATABASE_URL / DATABASE_URL_FILE |
Строка PostgreSQL либо путь к приватному файлу с ней |
DB_SSL_MODE |
В Makefile участвует в построении dev DATABASE_URL; готовый DATABASE_URL имеет приоритет |
MEDIA_ROOT |
Постоянная папка local-изображений, доступная backend |
AUTH_SIGNING_KEYS_JSON_FILE |
Файл ключей подписи токенов; backend также понимает AUTH_SIGNING_KEYS_JSON |
AUTH_ACTIVE_SIGNING_KEY_ID |
Какой из ключей используется для новых подписей |
AUTH_ISSUER |
Идентификатор приложения, выпускающего токены |
ADMIN_ALLOWED_ORIGINS |
Разрешённые origins браузерной системы администрирования |
TRUSTED_PROXY_CIDRS |
Сети доверенных reverse proxy |
В production backend подключается к PostgreSQL с sslmode=verify-full. Режим проверяет сертификат и имя сервера; путь к доверенному сертификату CA передаётся через sslrootcert. Контроллер готовит эти настройки. Если проверка не проходит, исправьте сертификат или адрес сервера. Переключение на disable или require уберёт нужную проверку, а не устранит причину ошибки.
Разрешённый origin определяет, откуда браузер может обращаться к API. Права на конкретные сущности и записи API проверяет отдельно. Токены и ключи нельзя помещать в VITE_*: эти переменные доступны frontend. Для смены серверных секретов используйте ротацию, чтобы все компоненты получили новые значения.
В local dev
При первом make dev появится предложение создать аккаунт. Сообщение Initial superadmin already exists означает, что активный суперадминистратор уже есть и этот шаг пропущен. Это нормальный результат.
Отдельный запуск из корня проекта:
make up
make bootstrap-superadmin
В prod-local или на сервере
После успешного развёртывания выполните команду на компьютере или сервере, где работает backend:
docker exec -it example_project-local-backend-1 \
admin bootstrap-superadmin --if-needed --login owner
Для сервера замените имя контейнера на его фактическое имя. Пароль вводится скрыто и подтверждается повторным вводом. Требование: 12–128 байт UTF-8, пароль должен отличаться от логина. Для ASCII это 12–128 символов; кириллица занимает несколько байт на символ.
Эта команда предназначена только для создания первого суперадминистратора. Она не сбрасывает пароль и не добавляет нового владельца к существующим аккаунтам. Параметр --if-needed пропускает создание, если инициализация уже выполнена. Если аккаунты есть, но среди них нет активного суперадминистратора, доступ нужно восстанавливать отдельно. Не удаляйте аккаунты из БД, чтобы заставить bootstrap сработать ещё раз.
Запуск без интерактивного терминала
Если терминал не поддерживает ввод пароля, передайте --password-file /путь/к/файлу. Это должен быть обычный файл с правами 0600, который может прочитать процесс admin. Пароль не передают аргументом команды или переменной окружения. Не сохраняйте файл в Git и не печатайте его содержимое в CI-логах. При запуске в контейнере отдельно предоставьте файл backend-процессу: путь на вашем компьютере не становится доступным в контейнере автоматически.
Где настраиваются доступ и домены
| Настройка | Для чего нужна |
|---|---|
| Entity CRUD access | Какие операции доступны в системе администрирования |
| External API access | Закрыт ли external API, нужен ли вход или разрешён анонимный доступ |
| External READ rules | Какие записи сервер разрешает прочитать через external list/get |
allowedOrigins в deployment JSON |
С каких точных origins разрешены запросы системы администрирования |
trustedProxyCIDRs |
Каким reverse proxy backend доверяет информацию о клиенте |
| Signing keys и issuer | Подпись и проверка токенов приложения |
Первые три пункта настраиваются в UI генератора, затем требуют Generate и обновления приложения. Домен, origin, proxy и секреты относятся к окружению запуска. Origin содержит протокол и, если он нестандартный, порт: https://admin.local.test:8443.
В сгенерированном deployment домены admin и API должны соответствовать поддерживаемой схеме same-site — принадлежать одному сайту с точки зрения браузера. В production используйте HTTPS и точные origins. При ошибке входа проверьте эти настройки; не отключайте проверки origin/CSRF и не разрешайте доверие ко всем proxy.
После переноса БД
Аккаунты и хеши паролей входят в дамп. Поэтому после импорта dev-БД в prod-local входите с dev-логином и паролем, а не с первоначальным prod-local аккаунтом. Signing keys и другие runtime-секреты дамп не заменяет. Существующие браузерные сессии могут стать недействительными — выйдите и войдите заново.
Если вход проходит, а следующие запросы отклоняются, проверьте адрес API, HTTPS, allowedOrigins, время на сервере и cookies браузера. Если сам backend не запускается, начните с логов: создание аккаунта не исправит подключение к БД или медиахранилищу.
bash ./deploy/control logs --env local --service backend
Для production замените local на имя окружения. Не публикуйте содержимое файлов секретов вместе с логами.