03 Configuration

03 · Конфигурация

Как устроена конфигурация

Приложение читает настройки слоями (последующие перекрывают предыдущие):

config/config.php — полный набор значений по умолчанию. Под git, не редактируйте в production (файл перезаписывается при обновлении).
.bas-ip.config.local.php в корне проекта — ваш файл: секреты, БД, устройство, overrides любых ключей. В .gitignore: ключи не попадут в репозиторий, а настройки не потеряются при обновлении из git (обновление никогда не трогает этот файл). Альтернативные расположения: config/.bas-ip.config.local.php, config/config.local.php.
.env в корне — простые KEY=value пары (шаблон: .env.example). Удобно для docker/12-factor. Секреты из .env подставляются в конфиг через ${secret:NAME} и env('KEY').
Таблица settings (Админка → Настройки) — операционные настройки, которые правятся из UI без деплоя: каналы уведомлений, лимиты гостевого доступа, ссылка на оплату, тексты, автобэкап и т.д. Значения из UI имеют приоритет над конфигом там, где это предусмотрено.
Шифрованные секреты — php bin/bas-ip secret:set DEVICE_PASSWORD хранит значение в storage/ зашифрованным ключом приложения (AES-256-GCM); в конфиге используется как 'password' => '${secret:DEVICE_PASSWORD}'.

Формат локального файла — обычный PHP-массив, глубокий merge с дефолтами: достаточно указать только отличия.

<?php
declare(strict_types=1);

return [
    'app' => ['name' => 'ЖК «Ромашка»', 'url' => 'https://gate.example.com'],
    'db'  => ['default' => 'mysql'],
    // …только то, что отличается от config/config.php
];

Проверить итоговую конфигурацию: php bin/bas-ip config:show (секреты маскируются) или config:show db.default.

`app` — приложение

Ключ	По умолчанию	Описание
`name` / `short_name`	BAS-IP Gate Manager	Название ЖК в шапке, письмах, PWA
`env`	`production`	`production` / `staging` / `development` / `local`
`debug`	`false`	Никогда `true` в production: показ стектрейсов
`url`	`''` (авто)	Базовый URL — ссылки в письмах и гостевых пропусках
`timezone`	`Europe/Moscow`	Часовой пояс журнала, счетов, расписаний
`locale` / `fallback_locale`	`ru` / `en`	Язык интерфейса
`key`	`null`	base64:32 байта — CSRF, подписи ссылок, шифрование секретов. `bin/bas-ip key:generate`
`key_cipher`	`aes-256-gcm`	Шифр секретов at-rest
`maintenance`	`false`	Режим обслуживания: UI закрыт, шлагбаум продолжает открываться
`maintenance_message`	`null`	Текст на странице 503
`behind_proxy` / `trusted_proxies` / `ip_header`	—	За nginx/Cloudflare: доверенные прокси и заголовок реального IP
`strict_transport_security`	`true`	HSTS на HTTPS-запросах

`db` — база данных

Ключ	По умолчанию	Описание
`default`	`mysql`	Активное соединение: `mysql` / `pgsql` / `sqlite`
`prefix`	`''`	Префикс таблиц (несколько установок в одной БД)
`foreign_keys`	`true`	Контроль внешних ключей
`connections.mysql.*`	—	`host`, `port`, `database`, `username`, `password`, `unix_socket`, `charset` (utf8mb4), `collation` (для MariaDB < 10.6 — `utf8mb4_unicode_ci`), `engine`, `persistent`, `options` (PDO)
`connections.pgsql.*`	—	то же + `schema` (по умолчанию `public`)
`connections.sqlite.*`	—	`database` — путь к файлу (по умолчанию `storage/app/bas-ip.sqlite`), `busy_timeout`

MySQL — рекомендуемая боевая СУБД (проект развивается на MySQL 8 / PHP 8.5). SQLite годится для небольшого дома и демо. Переключение БД = смена db.default + миграции (bin/bas-ip migrate); перенос данных — экспорт/импорт или бэкап (13).

`device` — шлагбаум / панель

Ключ	По умолчанию	Описание
`driver`	`basip`	`basip` (панель Camdroid `/api/v0`), `http-relay` (сторонний контроллер), `dryrun` (эмулятор)
`base_url`	`http://192.168.1.20/api/v0/`	Адрес панели
`login` / `password`	—	Учётка панели; пароль лучше `${secret:DEVICE_PASSWORD}`
`timeout` / `connect_timeout` / `retries` / `retry_delay_ms`	10 / 4 / 2 / 250	Таймауты и повторы при сетевых ошибках и 5xx
`verify_tls` / `ca_bundle`	`true` / null	Проверка сертификата панели (для самоподписанных — свой CA)
`token.ttl` / `refresh_skew` / `store`	1600 / 120 / `db`	Токен устройства: время жизни, досрочное обновление, где хранить (`db`/`file`/`cache`)
`lock.endpoint`	`access/general/lock/open/remote/accepted/{channel}`	Endpoint открытия замка (BAS-IP API)
`lock.channel` / `channels`	1 / `{1: "Main gate"}`	Канал реле и подписи каналов
`lock.pulse_ms`	1000	Длительность импульса
`lock.cooldown_seconds`	3	Анти-даблтап между открытиями
`sip.reregister_time`	315	Интервал перерегистрации SIP (команды sip_enable/disable)
`camera.enabled` / `mode`	true / `snapshot`	`off` / `snapshot` / `proxy` / `mjpeg`
`camera.endpoint` / `stream_url` / `cache_ttl` / `width` / `auth`	`security/ipcam` / — / 2 / 1280 / `token`	Параметры снимков и потока
`gates`	`[]`	Дополнительные устройства: `['north' => ['base_url' => …, …]]` — наследуют общие настройки

Подробности по драйверам — 11 · Устройства.

`auth` — аутентификация и права

Группа	Ключи
Роли	`roles: [admin, operator, resident]`, `default_role`, `allow_registration: false` (жителей создают админы)
Пароли	`password.algo: auto` (argon2id при наличии sodium, иначе bcrypt), `min_length: 10`, `require_mixed_case/digit/symbol`, `breach_check` (haveibeenpwned k-anonymity), `history: 3` (запрет повтора), `max_age_days: 0`
Логин	`login.field: login` (login/email/either), `max_attempts: 5`, `decay_minutes: 15`, `lockout_minutes: 30`, `captcha_after: 3`, `username_enumeration_protection: true`
Сессии	`session.name`, `lifetime: 720` мин (абсолютный), `idle_timeout: 60` мин, `secure: null` (авто по HTTPS), `httponly`, `samesite: Lax`, `regenerate_on_login`, `single_session_per_user`, `remember_me: {enabled, days: 30}`
2FA	`two_factor.enabled`, `required_for: [admin]` (обязательна для ролей), `issuer`, `digits: 6`, `period: 30`, `window: ±1`, `grace_period_minutes: 10080` (7 дней на подключение), `recovery_codes: 8`
IP-allowlist	`ip_allowlist.enabled`, `ips`, `cidrs`, `apply_to: [admin, api]` (+ `panel`/`all`), `deny_action: block` или `log-only`

Матрица ролей и прав — 12 · Безопасность.

`security` — защита

Группа	Ключи
Заголовки	`headers.csp: true`, `csp_report_only`, `csp_extra` (добавить директивы, напр. `['img-src' => 'https:']`), `frame_ancestors: 'self'`, `frame_options: SAMEORIGIN`, `referrer_policy`, `permissions_policy`, `hsts_max_age`, `custom`
Rate-limit	`rate_limits`: `login 5/15мин`, `api 120/мин`, `gate_open 12/мин`, `guest_create 8/час`, `guest_open 20/мин`, `password_reset 3/час`, `status_poll 60/мин`; произвольные `'N,сек'` в маршрутах
Шифрование	`encryption.cipher: aes-256-gcm`, `encrypt_secrets_at_rest: true`
CSRF	`csrf.enabled`, `csrf.except` (имена маршрутов/паттерны `webhook.*`), `token_ttl: 7200`
Загрузки	`upload.max_bytes: 10 МБ`, `allowed_import_extensions: csv, json, txt, xlsx`
Cookie	`cookies.prefix_secure` (`__Secure-` на HTTPS)
Аудит	`audit.enabled`, `log_payload: false`, `retention_days: 365`

`billing` — оплаты

Ключ	По умолчанию	Описание
`currency` / `currency_symbol` / `precision`	RUB / ₽ / 2	Валюта и округление
`rounding`	`half_up`	half_up / up / down / half_even
`allocation`	`equal`	equal / by_persons / by_area / by_share — способ деления суммы
`period_unit`	`month`	month / quarter / year / custom
`due_days`	14	Срок оплаты по умолчанию
`invoice_prefix` / `charge_prefix`	СЧ- / НАЧ-	Префиксы номеров
`allow_partial` / `allow_overpay` / `overpay_to_balance`	true	Частичные оплаты, переплата → на баланс
`late_fee`	выкл	Пени: `percent`/`fixed` после `after_days`
`auto_mark_overdue`	true	Cron помечает просроченные счета
`auto_adjust`	true	Перерасчёт создаёт корректирующие счета
`count_only_active`	true	В расчёте участвуют только активные жители (не отключайте)
`count_only_with_access`	false	Дополнительно требовать флаг «доступ»
`share_column`	`share`	Поле доли для `by_share`
`reminder.before_due_days` / `after_due_days`	[3,1] / [1,7,30]	Напоминания до и после срока

Модель денег целиком — 08 · Биллинг.

`guest` — гостевой доступ

Ключ	По умолчанию	Описание
`default_ttl_hours`	12	Срок пропуска по умолчанию
`max_ttl_hours`	72	Верхняя граница
`ttl_presets_hours`	1…72	Кнопки-пресеты в UI
`max_uses`	0	0 = безлимита открытий в пределах срока
`max_active_per_resident` / `max_active_total`	5 / 200	Лимиты активных пропусков
`code_length` / `code_alphabet`	6 / без 0,O,1,I…	Короткий код для клавиатуры/телефона
`signed_link`	true	HMAC-подпись ссылки (защита от подбора)
`require_guest_name` / `require_plate`	false	Обязательные поля гостя
`allow_self_service`	true	Жители сами создают пропуска
`rate_limit_per_resident_day`	10	Лимит созданий в день
`notify.on_create/on_use/on_expire`	true/false/false	Уведомления жителя
`auto_revoke_expired`	true	Cron гасит истёкшие
`pin_fallback`	true	PIN для клавиатуры панели
`car_sync`	false	Пуш госномера в whitelist устройства (driver-specific)

`notify` — уведомления

default: ['log'] — каналы по умолчанию (добавьте mail, telegram…).
one_per_channel: true — не слать на каждый телефон человека.
channels.* — включение и реквизиты: mail (SMTP), telegram (bot_token), sms (http-шлюз), webhook (url+secret), whatsapp (Cloud API), log.
mail.* — SMTP: host/port/encryption/username/password/from/reply_to (собственный SMTP-клиент, phpmailer не нужен).
queue.* — очередь: enabled, driver: database|sync, max_attempts: 5, retry_backoff: [60,300,900,3600,10800], batch_size, throttle_ms: 150.
templates.* — шаблоны payment_new, payment_reminder, payment_overdue, payment_received, charge_recalculated, guest_created, guest_invite, guest_used, gate_opened, system_alert, welcome. Подстановки: {name}, {apartment}, {amount} (уже с символом валюты), {currency}, {period}, {due_date}, {pay_link}, {balance}, {code}, {link}, {expires_at} и др.; модификаторы {due_date|date:d.m.Y}, {name|upper}, {text|limit:80}, {count|plural:житель,жителя,жителей}. Шаблоны переопределяются из UI (Админка → Уведомления → Шаблоны) и в таблице settings без деплоя.

Подробности — 09 · Уведомления.

`logging`, `cache`, `api`

logging.level (debug…critical), channels (app, audit, gate, device, notify, error, access, update — отдельные файлы), stderr, redact: [password, token, secret, authorization, cookie, otp] — маскирование в логах автоматически.
cache.driver: file (file/apcu/array), ttl: 300, prefix, path.
api.version: v1, префикс /api/v1, docs — встроенная документация.

`update` — автообновление

Ключ	По умолчанию	Описание
`enabled`	true	Проверка новых версий
`channel`	`stable`	`stable` (latest release) / `beta` (включая pre-release)
`mode`	`notify`	`notify` (только уведомить) / `auto` (устанавливать само)
`repo`	`paulmann/BAS-IP`	Откуда обновляться
`api_url` / `download_url`	GitHub API	Замените на свой forge при необходимости
`token`	null	GitHub PAT (повышает rate-limit), храните как secret
`check_interval`	86400	Секунды между проверками
`verify_checksum` / `expected_sha256`	true / null	Проверка артефакта, pin точного SHA-256
`backup_before` / `backup_database`	true	Бэкап файлов и БД перед установкой
`keep_releases`	5	Сколько снимков версий хранить для отката
`auto_migrate`	true	Прогнать миграции после обновления
`maintenance_during_update`	true	Включать режим обслуживания на время установки
`preserve`	`.bas-ip.config.local.php`, `storage`, `.env`, `public/install.lock`	Никогда не перезаписывается
`strategy`	`inplace`	`inplace` / `releases` (symlink-каталоги)
`allow_rollback`	true	Разрешить откат
`php_min`	8.2.0	Минимальный PHP для установки обновления

`backup`, `data`, `ui`, `integrations`

backup: keep: 14, include_db, include_storage, compress, encrypt (ключом приложения), schedule: '0 3 * * *', offsite (sftp).
data: форматы экспорта csv/json/sql, импорта csv/json; max_rows: 100000; CSV: разделитель ;, BOM для Excel; импорт: mode: upsert, match_on: [apartment, full_name], batch_size, skip_errors.
ui: theme: system (light/dark/system + личный выбор пользователя), accent, radius, density, per_page, show_camera, интервалы автообновления статусов/событий/камеры, brand (логотип/фавикон/название), command_palette, animations.
integrations: telegram_bot (token, admin_chat_id, команды open/status/ guest/balance/help, webhook+secret), home_assistant, prometheus (token).

`.env` (опционально)

APP_ENV=production
APP_DEBUG=false
APP_URL=https://gate.example.com
APP_KEY=base64:…
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_DATABASE=bas_ip
DB_USERNAME=bas_ip
DB_PASSWORD=секрет
DEVICE_PASSWORD=секрет-панели

.env тоже в .gitignore. Шаблон — .env.example.

Частые рецепты

Сменить валюту/символ: billing.currency: 'KZT', currency_symbol: '₸'.

Дом за NAT: доступ к админке только для своих: auth.ip_allowlist: {enabled: true, cidrs: ['203.0.113.0/24'], apply_to: ['admin']}.

Панель с самоподписанным сертификатом: device.verify_tls: false (или ca_bundle с вашим CA) — и держите панель в изолированном VLAN.

Всё в SQLite, один дом: db.default: 'sqlite' — файл в storage/app/, нулевое администрирование.

Отключить камеру в панели оператора: ui.show_camera: false.

03 Configuration

03 · Конфигурация

Как устроена конфигурация

app — приложение

db — база данных

device — шлагбаум / панель

auth — аутентификация и права

security — защита

billing — оплаты

guest — гостевой доступ

notify — уведомления

logging, cache, api

update — автообновление

backup, data, ui, integrations

.env (опционально)

Частые рецепты

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BAS-IP Gate Manager

Начало

Повседневная работа

Интеграции и железо

Эксплуатация

Справочно

Clone this wiki locally

`app` — приложение

`db` — база данных

`device` — шлагбаум / панель

`auth` — аутентификация и права

`security` — защита

`billing` — оплаты

`guest` — гостевой доступ

`notify` — уведомления

`logging`, `cache`, `api`

`update` — автообновление

`backup`, `data`, `ui`, `integrations`

`.env` (опционально)