Руководство по эксплуатации программного обеспечения CShark

Идентификация предоставляемого экземпляра

Актуально на 2026-08-06.

1. Назначение

Руководство содержит сведения, необходимые для повседневной эксплуатации CShark после установки. Документ относится к предоставляемому экземпляру в варианте demo для Ubuntu Server 24.04 LTS AMD64.

Установку выполняют по отдельной инструкции. Команды в этом руководстве предполагают каталог /opt/cshark-stand и Compose-проект cshark-stand.

2. Условия эксплуатации

Для работы необходимы:

• исправный сервер Ubuntu Server 24.04 LTS AMD64;
• не менее 8 ГБ RAM и 30 ГБ свободного места;
• корректные дата, время и часовой пояс;
• доступ пользователей к порту 8088/tcp;
• доступ администратора к серверу по защищенному каналу;
• резервное хранилище, отделенное от рабочего экземпляра.

Внешний доступ к PostgreSQL и NATS не требуется и не должен публиковаться.

3. Запуск и остановка

Проверить состояние:

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 down

4. Проверка готовности

После запуска выполните:

curl -fsS http://127.0.0.1:8088/api/health

Дополнительно проверьте:

• контейнеры имеют состояние running или healthy;
• Web-интерфейс доступен по http://<IP-ИЛИ-DNS>:8088;
• Grafana доступна по http://<IP-ИЛИ-DNS>:13000;
• свободное место на диске не ниже эксплуатационного порога;
• время сервера синхронизировано.

5. Первый вход

Первичные реквизиты находятся в файле:

sudo cat /opt/cshark-stand/INITIAL-CREDENTIALS.txt

Войдите под учетной записью администратора и создайте персональные учетные записи пользователей. Не используйте одну общую учетную запись для нескольких операторов: персональные записи необходимы для корректного аудита.

6. Рабочие пространства и роли

После входа пользователь видит только разрешенные ему разделы. Основные рабочие пространства:

Если раздел недоступен, администратор проверяет назначенную роль и разрешения, а не передает пользователю чужую учетную запись.

7. Начальное состояние demo

После установки администратор проверяет:

1. объект Демо-паркинг «Северный» не содержит реального адреса;
2. существует уровень Уровень 1;
3. существуют зоны Синий сектор и Зелёный сектор;
4. созданы ровно 50 мест DEMO-01–DEMO-50;
5. присутствуют места МГН, EV, moto и service;
6. зарегистрированы демонстрационная камера, три устройства ворот и табло;
7. доступен демонстрационный инцидент;
8. mock APS имеет состояние running или healthy;
9. событие эмулятора изменяет состояние связанного места;
10. реальные кадры камер отсутствуют до подключения отдельного медиапакета.

Demo-объект не является данными реального заказчика и предназначен только для проверки и демонстрации функций системы.

8. Работа со схемой

Оператор открывает раздел «Схема», выбирает объект и уровень, затем:

• оценивает сводное состояние;
• переходит от обзора к сектору и месту;
• использует поиск;
• открывает карточку места;
• просматривает историю статусов;
• проверяет связанные инциденты;
• включает только необходимые дополнительные слои.

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

9. Обработка инцидентов

Рекомендуемый порядок:

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

Инцидент не удаляют для сокрытия ошибки: решение оператора должно оставаться в истории и аудите.

10. Журнал и аналитика

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

В аналитике перед интерпретацией показателей проверьте выбранный объект и уровень. Сравнивать значения разных областей данных без учета контекста нельзя.

11. Оборудование

Технический специалист контролирует:

• состояние online или offline;
• время последнего события;
• историю изменения доступности;
• привязку к объекту и зоне;
• параметры драйвера;
• результат безопасной команды.

Перед отправкой команды воротам или другому исполнительному устройству необходимо убедиться, что команда допустима регламентом объекта и не создает опасности.

Эмуляторы используются для функциональной проверки без подключения реального оборудования.

12. Табло и шаблоны

В разделе табло администратор или уполномоченный технический специалист:

1. создает запись экрана;
2. задает его класс и параметры;
3. создает или редактирует шаблон;
4. проверяет предварительный просмотр;
5. назначает шаблон экрану;
6. проверяет фактическое отображение;
7. при необходимости отзывает экранный токен.

Шаблон и назначение сохраняются на сервере. Экран не должен зависеть от открытой сессии оператора. Приоритетное аварийное сообщение имеет преимущество перед штатным информационным содержимым.

Управление шаблонами смен и копирование персональных раскладок операторов относятся к дальнейшему развитию; до их выпуска используется утвержденный набор серверных шаблонов табло.

13. Пользователи и права

Администратор:

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

Сброс администраторского пароля отдельной командой с физическим доступом к серверу относится к планируемой функции. До ее выпуска восстановление доступа выполняется только по утвержденной процедуре сопровождения с резервной копией и журналированием действий.

14. Ежесменный контроль

В начале смены оператор проверяет:

• доступность Web-интерфейса;
• правильность объекта и уровня;
• количество активных инцидентов;
• наличие устройств offline;
• актуальность информационных экранов;
• отсутствие системных предупреждений.

При передаче смены фиксируются незавершенные инциденты, временно отключенные места, неисправные устройства и примененные аварийные сообщения.

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

Создать копию базы данных:

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

Медиа копируются в отдельное S3-совместимое хранилище с проверкой SHA-256. Реквизиты резервного хранилища передаются через защищенный env-файл с правами 0600, а не через аргументы командной строки.

Рекомендуется ежедневно копировать базу данных и еженедельно - медиа. Периодически выполняется восстановление во временную среду с проверкой контрольных счетчиков.

16. Обновление

Перед обновлением:

1. согласуйте окно работ;
2. зафиксируйте текущую версию;
3. проверьте здоровье и свободное место;
4. создайте проверенную резервную копию;
5. получите комплект новой версии;
6. проверьте SHA-256 и примечания к выпуску.

Обновление выполняет системный администратор по отдельной инструкции для конкретной версии. Нельзя обновлять систему командой с тегом latest без идентификации образов и схемы базы данных.

Автоматическое обновление из интерфейса в текущей версии отсутствует.

17. Журналы и диагностика

Последние журналы:

sudo docker compose \
  --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml \
  --profile obs logs --no-color --tail 200

Журнал установки:

sudo cat /opt/cshark-stand/install.log

При обращении в поддержку сохраняют версию, время, последовательность действий, ошибку, состояние контейнеров и релевантные журналы. Секреты и персональные данные перед передачей удаляются или маскируются.

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

19. Действия при отказах

19.1. Недоступен NATS

Перезапустите NATS и проверьте /healthz. Не удаляйте volume Gateway outbox: после восстановления Gateway должен дослать сохраненные события.

19.2. Недоступна камера

Проверьте питание и сеть камеры, время последнего heartbeat и журнал устройства. До восстановления ее места могут сохранять последнее известное состояние.

19.3. Заполнен диск

Определите источник роста. Историю observability можно очищать по отдельной процедуре, но нельзя удалять PostgreSQL, S3 или Gateway outbox без резервной копии и оценки последствий.

19.4. Повреждение данных

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

20. Сроки хранения

Значения по умолчанию:

Фактические сроки определяются политикой владельца объекта и применимыми требованиями. Перед уменьшением срока проверяется влияние на расследования и отчетность.

21. Требования безопасности

• используйте персональные учетные записи;
• применяйте принцип минимальных привилегий;
• ограничьте сетевой доступ межсетевым экраном;
• храните env-файлы и резервные копии в закрытых каталогах;
• не публикуйте PostgreSQL и NATS;
• синхронизируйте системное время;
• регулярно проверяйте журнал аудита;
• не включайте публичный поиск автомобиля без отдельной privacy-приемки;
• не удаляйте данные для устранения симптома без диагностики.

22. Завершение эксплуатации

Перед выводом экземпляра из эксплуатации:

1. остановите прием новых событий;
2. создайте финальную резервную копию;
3. проверьте возможность чтения копии;
4. экспортируйте необходимые отчеты;
5. отзовите API-ключи и экранные токены;
6. остановите контейнеры;
7. удалите данные только по утвержденному акту;
8. зафиксируйте результат и место хранения архивов.