Руководство администратора

1. Назначение документа и роли администраторов

Документ предназначен для специалистов, выполняющих настройку и сопровождение программного обеспечения «CShark» на объекте заказчика.

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

Права разграничиваются ролевой моделью (раздел 12); разделение на роли выше — организационное.

2. Состав программного обеспечения и размещение компонентов

Профиль наблюдаемости входит в проверочный комплект; наружу публикуется Grafana на 13000/tcp, остальные его службы доступны только внутри Compose-сети.

Все службы выполняются в контейнерах в закрытом сетевом периметре объекта. Обращения к внешним сервисам в процессе работы не выполняются.

3. Управление службами

Рабочий каталог: /opt/cshark-stand.

# состояние служб
sudo docker compose --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml --profile obs ps

# запуск
sudo docker compose --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml --profile obs up -d

# остановка
sudo docker compose --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml --profile obs stop

# перезапуск отдельной службы
sudo docker compose --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml restart core

# журналы службы
sudo docker compose --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml logs -f core

4. Параметры настройки

Параметры задаются переменными окружения (файл .env рядом с файлом описания служб). После изменения параметров службу требуется перезапустить.

5. Первичная настройка объекта

При первом входе доступен мастер первичной настройки. Последовательность:

1. Сменить пароль встроенной учётной записи администратора.
2. Создать объект (парковку), уровни, зоны, машиноместа.
3. Загрузить графическую подложку уровня и разместить объекты на схеме.
4. Зарегистрировать камеры и связать их с машиноместами.
5. Создать шаблоны и устройства информационных табло.
6. Настроить граф достижимости зон и точки въезда.
7. Создать роли и учётные записи операторов.
8. Настроить правила обработки событий.

6. Настройка топологии и схемы

Раздел «Администрирование» → «Топология».

Иерархия: организация → парковка → уровень → зона → машиноместо.

Коды машиномест отображаются пользователям и должны соответствовать разметке на объекте.

7. Настройка камер видеоаналитики

Раздел «Оборудование».

1. Настроить камеру на отправку событий по адресу шлюза устройств (протокол вендора поверх HTTP). Адрес и порт указываются в настройках камеры.
2. Камера, обратившаяся к системе, появляется в списке необнаруженных устройств.
3. Зарегистрировать камеру: задать наименование, сетевой адрес, размещение.
4. Связать камеру с машиноместами, которые она обслуживает.
5. Проверить поступление событий: статус связанного машиноместа должен изменяться при изменении обстановки.

Контроль работоспособности выполняется автоматически по периодическим сигналам присутствия. Состояние устройства отображается в разделе «Оборудование» и на схеме объекта. История изменения состояния сохраняется.

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

8. Настройка информационных табло

Раздел «Табло».

8.1. Шаблоны

Шаблон описывает компоновку кадра и состоит из регионов:

Размер шрифта подбирается автоматически под размеры региона; при недостаточной вместимости региона выдаётся предупреждение при сохранении шаблона.

8.2. Устройства отображения

1. Создать устройство, выбрать класс: текстовая светодиодная панель (протокол EK07, TCP/RS-485) либо веб-киоск на мониторе высокого разрешения.
2. Указать параметры подключения.
3. Привязать шаблон, зону и точку въезда.
4. Проверить результат предварительным просмотром сформированного кадра.

Для веб-киоска формируется публичный адрес вида /kiosk/display/<идентификатор>?token=<токен>; монитор открывает эту страницу в режиме киоска. Токен ограничивает доступ к содержимому.

8.3. Приоритеты содержимого

Аварийное → ручное замещение → расписание → штатное. Аварийное содержимое (режим пожара или укрытия) вытесняет любое другое и не может быть замещено вручную.

8.4. Адресат текстов

Формулировки причин недоступности разделены на публичные (отображаются водителю) и административные (доступны только персоналу). Административные тексты физически отсутствуют в публичном ответе киоска и в потоке WebSocket. Диагностическое состояние табло доступно по адресу /api/displays/{id}/state только для аутентифицированного персонала.

9. Настройка навигации

Раздел «Администрирование» → «Зоны», вкладка связей.

1. Задать рёбра графа достижимости между зонами (какие зоны достижимы из каких).
2. Указать точки въезда на объект.
3. Привязать направляющие табло к точкам въезда.

Система рассчитывает количество доступных свободных мест относительно конкретной точки въезда и направление движения к ним. Состояние «данные недоступны» отображается на табло обозначением, отличным от значения «ноль», — водитель не должен принимать неисправность за отсутствие мест.

10. Настройка режимов объекта и зон

Состояния зоны и объекта: штатный, пожарный, укрытие, обслуживание.

Смена режима одномоментно изменяет: доступность машиномест зоны, содержимое информационных табло (аварийное содержимое получает высший приоритет), правила обработки событий, состав уведомлений.

Возврат в штатный режим выполняется администратором вручную после устранения причины.

11. Настройка правил обработки событий

Раздел «Администрирование» → «Правила».

Правило задаётся по схеме:

триггер (тип события) × область (объект, зона, группа мест, конкретное место) × условие (время, статус, иные признаки) → действия

Доступные действия: уведомить оператора, создать инцидент, изменить статус, передать команду устройству.

Правило вступает в силу без перезапуска служб. Порядок применения правил определяется их приоритетом.

Примеры: «нарушение разметки в зоне для маломобильных граждан → создать инцидент критического уровня»; «машиноместо у входа занято более 10 минут без разрешения → уведомить старшего смены».

12. Управление пользователями, ролями и правами

Раздел «Администрирование» → «Пользователи» и «Роли».

• Разрешения задаются в едином пространстве вида «ресурс:действие» (например, displays:manage, users:manage).
• Роль — именованный набор разрешений. Пользователю назначается роль; дополнительно могут выдаваться индивидуальные разрешения.
• Разделы интерфейса, недоступные пользователю по правам, не отображаются в навигации.
• Действия пользователей фиксируются в журнале действий.

Требования к паролям: не менее 6 символов. Пароли хранятся в виде хешей (алгоритм bcrypt), в открытом виде не хранятся и не передаются.

Сессии реализованы подписанными токенами; секрет подписи задаётся параметром CSHARK_AUTH_SECRET. Смена секрета завершает все активные сессии.

13. Настройка интеграции с внешними системами

Раздел «Администрирование» → «Интеграции».

Взаимодействие с партнёрской автоматизированной парковочной системой (въездная группа) выполняется через эти механизмы.

14. Хранение данных и политики срока хранения

Срок хранения задаётся политиками в разделе системных настроек. Кадры доступны только по ссылкам с ограниченным сроком действия; прямой публичный доступ к объектам хранилища закрыт.

15. Резервное копирование и восстановление

15.1. Резервное копирование

tools/backup/backup.sh /path/to/backups

Формируется дамп базы данных и манифест медиаматериалов. Объекты хранилища копируются отдельно средствами синхронизации — команда выводится сценарием. Рекомендуемая периодичность: база данных — ежедневно (по расписанию на хосте), медиаматериалы — еженедельно. Глубина хранения копий — не менее срока хранения данных в системе.

15.2. Проверка копии

Восстановление во временную базу без риска для рабочей:

tools/backup/restore.sh backups/cshark-XXXX.dump cshark_restore_check

Сценарий выводит контрольные счётчики (машиноместа, посещения, инциденты, пользователи) для сверки.

15.3. Восстановление

Перед восстановлением остановить core и gateway через Compose-файл /opt/cshark-stand/compose.yml, выполнить штатный сценарий восстановления из поставки и затем запустить те же службы. Команды и путь к резервной копии фиксируются в журнале работ; восстановление сначала проверяется на отдельном стенде.

Медиаматериалы восстанавливаются синхронизацией в контейнер объектов со сверкой по манифесту.

16. Мониторинг и диагностика

Программное обеспечение формирует метрики, журналы и трассировки по стандарту OpenTelemetry. При включённом профиле наблюдаемости доступны панели Grafana.

Ключевые показатели:

Персональные и чувствительные данные исключаются из журналов автоматически.

17. Обновление программного обеспечения

Обновление инициируется администратором заказчика. Механизмы принудительного обновления и удалённого управления из-за пределов периметра объекта отсутствуют.

Текущий выпуск не содержит автоматического удалённого обновления. До внедрения перспективного управляемого механизма обновление выполняется как отдельная регламентная поставка: принять подписанный offline-комплект, проверить SHA-256 и подпись внешним ключом, создать и проверить резервную копию, выполнить инструкцию конкретного выпуска и полный smoke-test. Операция проводится администратором в согласованное окно обслуживания.

Миграции выполняются по принципу «расширение — сжатие»: разрушающие изменения схемы выпускаются в релизе, следующем за релизом кода, который работает без них. Поэтому возврат на предыдущую версию кода безопасен и не требует отката схемы.

Возврат допускается только на заранее сохранённый и проверенный комплект предыдущей версии после оценки совместимости схемы данных. Произвольная смена тега контейнеров в установленном экземпляре не является штатным обновлением.

18. Типовые неисправности и способы устранения

19. Расположение файлов и компонентов

Доступ внутрь контейнера:

sudo docker compose --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml exec core sh
docker run --rm cshark-core:<версия> cat /etc/os-release    # базовая ОС образа

20. Техническая поддержка

Порядок обработки обращений, приоритеты и сроки реакции приведены в документе «Описание процессов, обеспечивающих поддержание жизненного цикла программного обеспечения».