Руководство администратора «Апостол CSMS»

1. Назначение документа и границы применимости

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

Порядок действий одинаков для всех вариантов поставки. Различается лишь то, кто владеет сервером: при облачной подписке инфраструктурой управляет правообладатель, при лицензии на инфраструктуру заказчика — сам заказчик.

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

2. Состав поставки

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

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

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

3. Требования к серверу

Операционная система: дистрибутив Linux с поддержкой контейнеризации. Проверены Debian 12 и новее, Ubuntu 22.04 и новее.

Программное обеспечение: Docker версии 24 и новее, Docker Compose версии 2. Дополнительно требуются git, curl, jq и gettext — установочный скрипт при необходимости доустановит их сам через пакетный менеджер системы.

Минимальные ресурсы, проверяемые перед установкой: 4 ГБ оперативной памяти, 10 ГБ свободного дискового пространства. Практический минимум для небольшой сети — 2 вычислительных ядра и 3 ГБ памяти; для сети от тысячи станций рекомендуется 8 ядер, 16 ГБ памяти и твердотельные накопители.

Открытые входящие порты: 80 и 443 для веб-интерфейсов и программного интерфейса, отдельный порт для подключения зарядных станций по протоколу OCPP.

Рекомендуется настроить синхронизацию времени: проверка подписанного описания развёртывания отвергает расхождение часов более пяти минут.

4. Доменные имена

Система обслуживает несколько имён в пределах одного домена. Каждое имя соответствует своему приложению: основной домен — сайт бренда, отдельные имена для кабинета организации, кабинета оператора, консоли мониторинга станций, административного кабинета, интерфейса авторизации, приложения водителя, приложения оплаты, программного интерфейса, канала веб-сокета и подключения зарядных станций.

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

Сама установка разрешение имён не проверяет. Проверка входит в отдельный предварительный режим пусковой команды развёртывания и выполняется до установки; выполнять её не обязательно, но полезно — незаведённое имя иначе обнаружится только на этапе выпуска сертификата.

5. Сертификаты TLS

Обслуживание ведётся только по защищённому соединению. Сертификаты размещаются в каталоге секретов до установки; обратный прокси-сервер получает их копию на этапе сборки и в дальнейшем продлевает самостоятельно.

Важная особенность: конфигурация прокси-сервера ссылается на отдельный каталог для каждого имени, поэтому выпускать нужно отдельный сертификат на каждое имя, а не один общий сертификат со списком альтернативных имён. Общий сертификат будет размещён в каталоге, названном по первому имени, и остальные имена окажутся необслуженными.

Если на сервере есть собственная служба продления сертификатов, её следует отключить: продлением занимается контейнер прокси-сервера, а хостовая служба не сможет занять уже используемый порт.

6. Секреты развёртывания

Пароли ролей базы данных, секреты приложений протокола авторизации, учётные данные почтового сервера и ключи платёжного провайдера хранятся в отдельном файле окружения вне репозитория развёртывания. Файл должен иметь права доступа только для владельца — установка это проверяет.

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

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

Установка отказывается продолжать, если в конфигурации остались незаполненные значения-заглушки.

7. Лицензионный конверт

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

Конверт подписан по алгоритму Ed25519 и проверяется сервером приложений при запуске и при каждой смене файла. Изменить эти сведения через интерфейс невозможно — в этом и состоит смысл конверта.

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

8. Окружения и фиксация версии

Репозиторий развёртывания описывает несколько окружений — как правило, среду разработки, предварительную и промышленную. Для каждого окружения хранится собственный набор параметров и файл фиксации версии платформы.

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

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

9. Установка

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

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

# установка на подготовленный сервер
./install.sh --env=prod

# проверка без внесения изменений
./install.sh --env=prod --dry-run

10. Что происходит при установке

Предварительные проверки: наличие и версия Docker, наличие Docker Compose, свободное место на диске, наличие необходимых утилит, наличие каталога запрошенного окружения и файла фиксации версии, наличие сертификатов, файла секретов с правами только для владельца и лицензионного конверта. Недостаточный объём свободной памяти даёт предупреждение, остальные несоответствия останавливают установку.

Повторная установка на уже развёрнутой системе отклоняется до того, как что-либо будет изменено.

Чтение файла фиксации версии. Сборка рабочей конфигурации из общего шаблона и шаблона окружения. Проверка обязательных признаков рынка — валюты, кода страны и платёжной системы: они определяют денежное выражение базы данных, и после установки ничто их не пересинхронизирует, поэтому пустые значения останавливают установку.

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

Первый запуск в строгой последовательности: сначала база данных — установка ждёт её готовности, затем одноразовый контейнер первичной инициализации, создающий роли, схемы, справочники и первичное описание бренда из лицензионного конверта. Затем поднимаются остальные сервисы; контейнер миграций запускается в их числе и по условию зависимости — только после успешного завершения инициализации.

После запуска отрабатывает перехватчик завершения, записывается установленная версия и выполняется проверка состояния.

11. Проверка развёртывания

Проверка состояния выполняется отдельным скриптом и покрывает десять аспектов: состояние и работоспособность всех контейнеров, готовность базы данных, ответ программного интерфейса, доступность описания протокола авторизации, приём соединений на порту зарядных станций, ответ основного домена, срок действия сертификатов, заполненность диска, доступную память и совпадение установленной версии с версией образов.

Код возврата: ноль — всё исправно, единица — есть предупреждения, двойка — есть отказы. Предусмотрен машиночитаемый вывод для систем мониторинга.

Отдельный режим проверки через локальный интерфейс нужен на серверах, которые не могут обратиться к собственному публичному адресу — распространённая особенность недорогих площадок.

./check.sh              # человекочитаемый вывод
./check.sh --json       # для системы мониторинга
./check.sh --local      # если сервер не видит свой публичный адрес

12. Повседневная эксплуатация

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

Журналы сервисов доступны средствами Docker; ограничение размера журналов настраивается на уровне демона Docker и по умолчанию при подготовке сервера выставляется в разумные пределы, иначе журналы со временем заполнят диск.

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

Все внутренние сервисы, кроме обратного прокси-сервера, не публикуют портов наружу и доступны только внутри сетей развёртывания.

./docker-up.sh          # поднять стек
./docker-down.sh        # остановить
./docker-logs.sh        # журналы всех сервисов

13. Обновление версии

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

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

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

Предусмотрены частичные режимы — обновление только пользовательских приложений или только сайта бренда, а также показ отличий текущей композиции от эталонной.

Важная особенность: скрипт обновления не пересобирает рабочий файл окружения заново, а лишь обновляет в нём значения секретов. Поэтому переменная, добавленная в шаблон окружения, до работающего развёртывания сама не доедет — её нужно дописать в рабочий файл окружения на сервере в тот же заход.

./update.sh                      # на версию из файла фиксации
./update.sh --platform=1.6.5     # на указанную версию
./update.sh --frontend-only      # только пользовательские приложения
./update.sh --dry-run            # без внесения изменений

14. Возврат к предыдущей версии

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

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

./update.sh --rollback

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

Резервному копированию подлежат: база данных, том с загруженными файлами, том с секретами развёртывания, лицензионный конверт и каталог сертификатов.

Копия базы данных снимается штатным средством СУБД в двоичном формате. Восстановление выполняется обратной операцией на пустую базу.

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

# снятие копии
docker compose exec -T postgres pg_dump -U postgres -Fc "$PGDATABASE" > backup.dump

# восстановление на пустую базу
docker compose exec -T postgres pg_restore -U postgres -d "$PGDATABASE" \
  --clean --if-exists < backup.dump

16. Слои конфигурации

Параметры развёртывания разложены по четырём слоям, и смешивать их не следует.

Лицензионный конверт — только идентичность бренда. Подписан, через интерфейс не редактируется.

Файл окружения — инфраструктурные секреты и параметры подключения: пароли, ключи, адреса внешних служб.

Реестр настроек в базе данных — рабочие переключатели и настройки поведения: режим работы платёжного провайдера, включение отдельных функций, почтовый домен отправителя.

Описание бренда в базе данных — то, что видит пользователь: цвета оформления, логотипы, публичные ключи платёжного провайдера и картографии, язык, контактный адрес поддержки. Изменяется через программный интерфейс с правами администратора.

Описание бренда формируется один раз при установке и при обновлении не пересоздаётся. Поэтому изменение значения в файле окружения после установки до описания бренда само не доходит — его нужно применить через программный интерфейс.

17. Учётные записи и разграничение прав

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

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

Права проверяются в базе данных, а не в интерфейсе. Роли и их границы описаны в руководстве пользователя.

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

18. Диагностика типичных неисправностей

Контейнер не поднимается после перезапуска и сообщает о занятом файле процесса — файл остался от предыдущего запуска; снимается пересозданием контейнера.

Проверка состояния сообщает об отсутствии ответа программного интерфейса при исправном стеке — как правило, сервер не может обратиться к собственному публичному адресу; следует воспользоваться режимом проверки через локальный интерфейс.

Ошибка проверки пароля роли базы данных — рассогласование между файлом окружения и паролями, с которыми база была создана. Пароли ролей задаются при первичной инициализации и в дальнейшем хранятся в томе секретов; изменение их в файле окружения задним числом базу не перенастраивает.

Сообщение о недоступности лицензии — не смонтирован либо повреждён лицензионный конверт, либо расходятся часы сервера.

Ошибка миграции при обновлении — стек остаётся на предыдущей версии, обслуживание продолжается. Следует изучить журнал контейнера миграций и обратиться в техническую поддержку; повторный запуск обновления после устранения причины безопасен.

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

19. Прекращение эксплуатации

Остановка выполняется штатной командой остановки композиции. Данные при этом сохраняются в томах.

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

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

20. Связанные документы

• Описание функциональных характеристик
• Руководство пользователя
• Лицензионный договор-оферта