Информация, необходимая для установки и эксплуатации
Version 0.2.0 (редакция RU), проект · Download DOCX
Draft: the documents are under legal review. The [ЗАПОЛНИТЬ] and [ПРОВЕРИТЬ] markers will be resolved before the application is filed.
1. Общие сведения
1.1. Назначение документа
Документ содержит сведения, необходимые для установки, настройки, запуска, обновления и эксплуатации программного комплекса «Айтечество» (далее — программный комплекс): требования к аппаратным и программным средствам, порядок установки в Kubernetes и Docker Swarm, параметры конфигурации, порядок первого запуска, обновления, резервного копирования и восстановления, а также порядок удалённого доступа к экземпляру облачной версии (раздел 12). Документ предназначен для системных администраторов заказчика и правообладателя и для экспертов, проверяющих программный комплекс. Документ предусмотрен подпунктом «д» пункта 11 Правил формирования и ведения единого реестра российских программ для электронных вычислительных машин и баз данных и единого реестра программ для электронных вычислительных машин и баз данных из государств — членов Евразийского экономического союза, за исключением Российской Федерации, утверждённых постановлением Правительства Российской Федерации от 16.11.2015 № 1236 (в редакции от 13.08.2026) (далее — Правила).
Функции программного комплекса описаны в документе «Описание функциональных характеристик», работа пользователей в веб-консоли — в документе «Руководство пользователя».
1.2. Состав программного комплекса
Программный комплекс состоит из сервисов, каждый из которых поставляется в виде образа контейнера для платформы linux/amd64. Сервисы gateway, api, worker, nlp, extractor и web выполняются от пользователя без прав администратора (UID 10001), с файловой системой только для чтения (запись разрешена только во временный каталог) и без дополнительных привилегий ядра.
| Сервис | Назначение | Порты | Проверка состояния |
|---|---|---|---|
| gateway | Шлюз: приём запросов к моделям, маскирование и восстановление данных, применение политик, проксирование к провайдерам моделей | 8080 (внешний), 8081 (внутренний), 9090 (метрики) | /healthz, /readyz; :9090/healthz/deps |
| api | API управления (веб-консоль), обработка платежей, выдача служебных маркеров | 8000 | /api/v1/healthz, /api/v1/readyz |
| worker | Фоновые задачи: запись журнала запросов, оповещения, вебхуки, письма, хранение и удаление данных, биллинг | 9091 (метрики) | /healthz |
| migrations | Разовая задача: создание ролей и миграция схемы базы данных, создание корзины объектного хранилища | — | — |
| nlp | Распознавание именованных сущностей (ФИО, организации, географические названия) | 8070 | /healthz, /readyz |
| extractor | Извлечение текста из вложенных документов; работает без доступа к сети | 8071, 9071 (метрики) | /healthz, /readyz |
| web | Веб-сайт, веб-консоль и чат | 3000 | /healthz |
| backup | Резервное копирование базы данных (только при установке в Docker Swarm) | — | — |
Сервисы api, worker и migrations используют один образ (api) с разными командами запуска.
Сторонние сервисы, необходимые для работы:
| Сервис | Версия | Назначение |
|---|---|---|
| PostgreSQL | 17 | Основная база данных (настройки, политики, журнал запросов, биллинг) |
| Valkey | 8.1 | Кэш, счётчики ограничений, очередь событий |
| Объектное хранилище с интерфейсом S3 | — | Счета в PDF, выгрузки журналов и персональных данных |
| Обратный прокси с TLS | — | Приём HTTPS-трафика: контроллер входящего трафика ingress-nginx (Kubernetes) или Traefik (Docker Swarm) |
| Почтовый сервер SMTP или сервис Unisender Go | — | Отправка писем (подтверждение адреса, приглашения, оповещения, счета) |
1.3. Варианты установки
- Kubernetes с Helm — основной вариант для промышленной эксплуатации в инфраструктуре заказчика: отказоустойчивая база данных (оператор CloudNativePG), горизонтальное масштабирование, сетевые политики.
- Docker Swarm — установка на один или несколько серверов; база данных, кэш и объектное хранилище разворачиваются в том же стеке, резервное копирование выполняет сервис backup.
- Docker Compose — установка на одну рабочую станцию для ознакомления и тестирования; не предназначена для промышленной эксплуатации.
1.4. Комплект поставки и получение дистрибутива
Комплект поставки версии включает:
- образы контейнеров gateway, api, nlp, extractor, web, backup, помеченные номером версии vX.Y.Z;
- чарты Helm aitechestvo (приложение) и aitechestvo-data (база данных и кэш) с файлами значений;
- шаблон стека Docker Swarm, сценарии подготовки (render.sh — формирование файла стека, gen-secrets.sh — генерация секретов, smoke.sh — проверка после установки);
- файл закрепления сторонних образов (images.lock.yaml) с дайджестами SHA-256;
- эксплуатационную документацию.
Комплект поставки распространяется через реестр образов правообладателя на территории Российской Федерации (документ «Описание технических средств хранения исходного текста и объектного кода и средств компиляции», раздел 3). Образы контейнеров и чарты Helm (в формате OCI) получаются из реестра по номеру версии и проверяются по дайджесту SHA-256; остальные файлы комплекта (шаблон стека Docker Swarm, сценарии, файл закрепления сторонних образов, документация) передаются архивом, который размещается в том же реестре вместе с образами версии и сопровождается контрольной суммой SHA-256. Копии сторонних образов, закреплённых в файле images.lock.yaml, размещаются в том же реестре. После заключения лицензионного договора заказчик получает персональные учётные данные с правом только чтения, действующие в течение срока договора (документ «Описание технических средств активации, выдачи, распространения и управления лицензиями», раздел 3.2). Адрес реестра: [ЗАПОЛНИТЬ: адрес реестра образов правообладателя]. [ПРОВЕРИТЬ ДО ПОДАЧИ: шаблон стека Docker Swarm, файлы значений чартов и файл images.lock.yaml ссылаются только на этот реестр]
Пользователям облачной версии комплект поставки не передаётся. Порядок удалённого доступа к экземпляру облачной версии, в том числе для экспертной проверки, приведён в разделе 12.
2. Требования к аппаратному и программному обеспечению
2.1. Аппаратные требования
Минимальная конфигурация для установки всех сервисов на один сервер (Docker Swarm): 4 виртуальных процессора x86-64, 8 ГБ оперативной памяти и 2 ГБ файла подкачки, 80 ГБ дискового пространства. Перед каждым развёртыванием в хранилище Docker должно быть свободно не менее 8 ГБ. Сумма лимитов памяти всех сервисов в установившемся режиме — около 6 ГБ.
Конфигурация для промышленной эксплуатации подбирается по ожидаемой нагрузке (число пользователей, запросов в минуту, объём текста запросов и вложений): шлюз и nlp масштабируются горизонтально (раздел 9.5), сервис extractor — числом одновременно обрабатываемых документов (раздел 8.6). Типовые конфигурации для заданной нагрузки правообладатель не публикует; расчёт выполняется по запросу заказчика в рамках технической поддержки.
Ресурсы сервисов при установке в Docker Swarm (лимит и резерв памяти, лимит процессора):
| Сервис | Экземпляров | Память: лимит / резерв | Процессор, ядер |
|---|---|---|---|
| gateway | 2 | 512 МБ / 512 МБ | 1,0 |
| nlp | 2 | 768 МБ / 768 МБ | 1,0 |
| extractor | 1 | 2176 МБ / 256 МБ | 2,0 |
| api | 1 | 448 МБ / 160 МБ | 0,75 |
| worker | 1 | 320 МБ / 96 МБ | 0,5 |
| web | 1 | 320 МБ / 128 МБ | 0,5 |
| migrations | разово | 384 МБ | 0,5 |
| postgres | 1 | 384 МБ / 192 МБ | 1,0 |
| valkey | 1 | 160 МБ / 48 МБ | 0,25 |
| объектное хранилище | 1 | 384 МБ / 128 МБ | 0,5 |
| backup | 1 | 192 МБ / 32 МБ | 0,25 |
Ресурсы при установке в Kubernetes (запрос / лимит):
| Компонент | Процессор | Память | Экземпляров |
|---|---|---|---|
| gateway | 250m / 1 | 384Mi / 384Mi | 2–4 (автомасштабирование) |
| nlp | 250m / 1 | 768Mi / 768Mi | 2–4 (автомасштабирование) |
| extractor | 250m / 2 | 2176Mi / 2176Mi | 1 |
| api | 100m / 750m | 160Mi / 448Mi | 1–2 (автомасштабирование) |
| worker | 50m / 500m | 96Mi / 320Mi | 1 |
| web | 50m / 500m | 128Mi / 320Mi | 1 |
| PostgreSQL (CloudNativePG) | — | 512Mi / 1Gi | 2, том 20Gi каждый |
| Valkey | — | 64Mi / 512Mi | 1, том 2Gi |
2.2. Программные требования
Серверная часть:
- операционная система семейства Linux для платформы x86-64 с поддержкой контейнеров (совместимость с операционными системами, соответствующими требованиям к доверенному программному обеспечению, — раздел 2.4);
- для установки в Docker Swarm — Docker Engine версии 29.9 в режиме Swarm (версия, с которой проверены установка, обновление и проверочный сценарий раздела 7.5) [ПРОВЕРИТЬ: работа с другими версиями Docker Engine не проверялась, минимальная поддерживаемая версия не определена]; формат файла стека 3.9;
- для установки в Kubernetes — Kubernetes версии 1.29 или новее, Helm 3 (проверено с Helm 3.22), сетевой плагин с поддержкой сетевых политик (NetworkPolicy), контроллер входящего трафика ingress-nginx, cert-manager с издателем сертификатов по протоколу ACME (HTTP-01), оператор CloudNativePG с модулем резервного копирования barman-cloud, внешнее объектное хранилище с интерфейсом S3;
- PostgreSQL 17 и Valkey 8.1 (входят в стек Docker Swarm и чарт aitechestvo-data; могут быть заменены внешними). Valkey работает с политикой вытеснения noeviction, журналом AOF (everysec), паролем и ограничением памяти около 80 % лимита.
Клиентская часть: веб-браузер с включёнными JavaScript и cookie. Работа сайта и веб-консоли проверяется автоматическими сквозными тестами в браузере Chromium версии 156. Другие современные браузеры, в том числе Яндекс Браузер и Firefox, поддерживаются [ПРОВЕРИТЬ: работа в Яндекс Браузере и Firefox тестами не проверялась]. Установка дополнительного программного обеспечения на рабочее место пользователя не требуется. Для обращения к API — любое HTTP-клиентское программное обеспечение с поддержкой TLS 1.2 и Server-Sent Events.
2.3. Сетевые требования
Входящие соединения принимаются только на портах 80 и 443 обратного прокси; остальные порты сервисов наружу не публикуются. Требования к обратному прокси:
- TLS 1.2 и выше, заголовок HSTS, отдельный сертификат для каждого имени;
- для адреса шлюза — без буферизации ответов, время ожидания чтения не менее 600 секунд (потоковые ответы моделей), ограничение размера запроса 25 МБ;
- для адресов веб-консоли — ограничение размера запроса 2 МБ; путь /api/ направляется в сервис api, остальные пути — в сервис web.
Исходящие соединения:
| Сервис | Назначение | Порт |
|---|---|---|
| gateway | YandexGPT: llm.api.cloud.yandex.net | 443 |
| gateway | GigaChat: gigachat.devices.sberbank.ru; получение маркера доступа: ngw.devices.sberbank.ru | 443; 9443 |
| gateway | Модели заказчика с OpenAI-совместимым API (адреса задаются в подключениях) | по настройке |
| api | ЮKassa (api.yookassa.ru) — при включённом биллинге; DaData (suggestions.dadata.ru) — необязательно; объектное хранилище | 443 |
| worker | Почтовый сервер SMTP или Unisender Go (go1.unisender.ru); вебхуки организаций; объектное хранилище | 587 или 465; 443 |
| backup | Объектное хранилище для резервных копий | 443 |
| nlp, extractor, web | Исходящих соединений не требуется | — |
Шлюз не устанавливает соединения с узлами из встроенного списка запрещённых узлов иностранных сервисов искусственного интеллекта; список действует всегда и может быть только расширен параметром UPSTREAM_DENIED_HOST_SUFFIXES. Соединения с адресами частных сетей и по незащищённому HTTP по умолчанию запрещены; модели в локальной сети заказчика разрешаются параметром UPSTREAM_ALLOWED_PRIVATE_CIDRS.
2.4. Совместимость с операционными системами
Совместимость программного комплекса с операционными системами, соответствующими требованиям к доверенному программному обеспечению (подпункт «м» пункта 5 Правил), подтверждается испытаниями на двух операционных системах разных производителей — Astra Linux Special Edition 1.8 и РЕД ОС 8. Программа испытаний для каждой из них: установка Docker Engine (версия указывается в протоколе), установка программного комплекса в Docker Swarm по разделу 5, проверки разделов 7.2 и 7.5, обновление на следующую версию по разделу 10 и восстановление из резервной копии по разделу 11.4. Протоколы испытаний и документы, подтверждающие совместимость, прилагаются к заявлению в соответствии с подпунктом «и» пункта 11 Правил. [ПРОВЕРИТЬ ДО ПОДАЧИ: испытания на обеих операционных системах проведены и протоколы оформлены; обе системы соответствуют требованиям к доверенному программному обеспечению; до этого совместимость не заявляется]
3. Подготовка к установке
3.1. Имена и сертификаты
Подготовьте DNS-имена и направьте их на обратный прокси:
- адрес веб-консоли (например, https://ai.example.ru) — параметр PUBLIC_WEB_URL; дополнительные адреса консоли перечисляются в PUBLIC_WEB_ORIGINS, первым указывается PUBLIC_WEB_URL;
- адрес шлюза (например, https://gw.example.ru) — параметр PUBLIC_GATEWAY_URL; дополнительные имена шлюза — PUBLIC_GATEWAY_ALIASES.
Адреса указываются в нормализованном виде: схема https, имя в нижнем регистре (национальные домены — в кодировке punycode), без пути, завершающей косой черты и порта по умолчанию.
3.2. Секреты
Секреты (ключи шифрования, пароли баз данных) генерируются сценарием из комплекта поставки; для работы сценария нужен только openssl:
umask 077
deploy/gen-secrets.sh --stand-passwords > secrets.env || rm -f secrets.env
Сценарий выводит все значения или ничего (при ошибке). Наборы ключей имеют формат <идентификатор>:<32 байта в base64>, несколько ключей перечисляются через запятую, действующий ключ задаётся отдельным параметром *_ACTIVE_*. Сервисы не запускаются при неверном формате ключа. Файл секретов хранится только в защищённом хранилище секретов заказчика и не помещается в образы и системы контроля версий. Без наборов ключей зашифрованные поля базы данных (учётные данные провайдеров моделей и др.) не могут быть прочитаны, поэтому их резервная копия хранится отдельно от резервных копий базы данных.
В файл секретов добавляются учётные данные внешних сервисов: SMTP_USER и SMTP_PASSWORD (или UNISENDER_GO_API_KEY), при необходимости YOOKASSA_SHOP_ID и YOOKASSA_SECRET_KEY, DADATA_API_KEY, учётные данные платформенных моделей (PLATFORM_YANDEX_API_KEY и PLATFORM_YANDEX_FOLDER_ID, PLATFORM_GIGACHAT_AUTH_KEY), SENTRY_DSN (необязательно).
3.3. Провайдеры моделей
Подготовьте учётные данные хотя бы одного провайдера:
- YandexGPT — API-ключ сервисного аккаунта и идентификатор каталога Yandex Cloud;
- GigaChat — ключ авторизации и область доступа (GIGACHAT_API_PERS, GIGACHAT_API_B2B или GIGACHAT_API_CORP); корневой сертификат Russian Trusted Root CA уже встроен в шлюз, дополнительные сертификаты подключаются параметром EXTRA_CA_CERTS_FILE;
- модель заказчика с OpenAI-совместимым API — адрес и, при необходимости, ключ доступа.
Учётные данные указываются либо при установке (платформенные модели, доступные всем организациям инсталляции), либо администраторами организаций в веб-консоли.
3.4. Биллинг
Встроенный биллинг (тарифы, оплата через ЮKassa, счета) включается параметром BILLING_ENABLED. Для корпоративной установки без продажи доступа третьим лицам биллинг обычно выключен. При включённом биллинге требуются файлы настроек налогов (tax.yaml) и реквизитов продавца (seller.yaml), подключаемые в каталог /etc/aitech/billing, и адрес уведомлений ЮKassa https://<адрес консоли>/api/v1/webhooks/yookassa, доступный из сетей ЮKassa.
4. Установка в Kubernetes
-
Установите компоненты платформы кластера: контроллер входящего трафика ingress-nginx, cert-manager с издателем сертификатов (ClusterIssuer, проверка HTTP-01), оператор CloudNativePG и модуль barman-cloud. Версии и дайджесты образов приведены в файле images.lock.yaml.
-
Создайте пространство имён и установите выпуск данных (PostgreSQL 17 в двух экземплярах, Valkey, резервное копирование в объектное хранилище); пароли передаются параметрами чарта:
kubectl create namespace aitechestvo helm upgrade --install aitechestvo-data deploy/helm/aitechestvo-data \ -n aitechestvo -f values-data.yaml --atomic --waitПри использовании внешних PostgreSQL и Valkey выпуск данных не устанавливается; секреты aitech-db и aitech-valkey создаются вручную, в базе заранее создаются роли aitech_gateway (без входа) и aitech_gateway_login.
-
Создайте секреты и настройки биллинга (чарт приложения секреты не создаёт):
kubectl -n aitechestvo create secret generic aitechestvo-secrets \ --from-env-file=secrets.env kubectl -n aitechestvo create secret generic aitechestvo-s3 \ --from-literal=S3_ACCESS_KEY_ID=<ключ> \ --from-literal=S3_SECRET_ACCESS_KEY=<секрет> kubectl -n aitechestvo create configmap aitechestvo-billing \ --from-file=tax.yaml --from-file=seller.yaml -
Подготовьте файл значений инсталляции (values-local.yaml) на основе values-ru.yaml: адреса (global.publicWebUrl, global.publicWebOrigins, global.publicGatewayUrl), реестр образов (image.registry), параметры входящего трафика (ingress.*), сторонние сервисы (thirdParty.*), версии юридических документов (legal.*), биллинг (billing.*), ресурсы и масштабирование компонентов.
-
Установите выпуск приложения, указав дайджесты образов версии:
helm upgrade --install aitechestvo deploy/helm/aitechestvo -n aitechestvo \ -f deploy/helm/aitechestvo/values-ru.yaml -f values-local.yaml \ --set gateway.image.digest=<дайджест> --set nlp.image.digest=<дайджест> \ --set api.image.digest=<дайджест> --set worker.image.digest=<дайджест> \ --set web.image.digest=<дайджест> --set extractor.image.digest=<дайджест> \ --atomic --wait --timeout 15mМиграции базы данных выполняются задачей перед установкой и каждым обновлением выпуска. Чарт отказывается формировать манифесты при ошибках конфигурации (ненормализованные адреса, недостаточные лимиты памяти, превышение числа соединений с базой данных и др.).
-
Проверьте сетевые политики и работоспособность:
helm test aitechestvo -n aitechestvoи выполните проверку из раздела 7.5.
5. Установка в Docker Swarm
-
Инициализируйте Swarm и пометьте узлы: узел данных (тома PostgreSQL, Valkey, объектного хранилища и локальных резервных копий) — ровно один, метка aitechestvo=true; узлы приложений — метка aitechestvo-app=true (при установке на один сервер обе метки ставятся на него):
docker swarm init docker node update --label-add aitechestvo=true \ --label-add aitechestvo-app=true <узел> -
Выберите адреса внутренних оверлейных сетей стека (internal, egress, extract), не пересекающиеся с другими сетями узлов.
-
Подготовьте файл параметров инсталляции (адреса, размещение, число экземпляров, лимиты) на основе файла параметров региона ru из комплекта поставки и файл секретов (раздел 3.2), дополненный параметрами резервного копирования: адрес, корзина и ключи объектного хранилища для копий, открытый ключ шифрования копий (age). [ПРОВЕРИТЬ ДО ПОДАЧИ: в комплект поставки включён образец файла параметров региона ru без значений инсталляции правообладателя]
-
Сформируйте файлы стеков приложения и обратного прокси (Traefik) с тегом версии:
deploy/swarm/render.sh --stand ru --secrets-file secrets.env \ --tag vX.Y.Z --out aitechestvo.yml deploy/swarm/render.sh --stand ru --secrets-file secrets.env \ --edge --out balancer.ymlСценарий записывает файлы с правами 600; они содержат секреты и хранятся так же, как файл секретов.
-
Разверните обратный прокси, затем приложение:
docker stack deploy -c balancer.yml balancer docker stack deploy --with-registry-auth --resolve-image always --prune \ -c aitechestvo.yml aitechestvo -
Проверьте, что разовая задача migrate завершилась (состояние Complete, сервис показывает 0/1):
docker stack ps aitechestvoи выполните проверки из разделов 7.2 и 7.5.
Обновлять отдельные сервисы командой docker service update --image нельзя: при этом не выполняются миграции. Обновление всегда выполняется повторным развёртыванием всего стека (раздел 9).
6. Установка для ознакомления (Docker Compose)
Ознакомительная установка выполняется из рабочей копии исходного текста: образы сервисов собираются локально. На рабочей станции нужны Docker с Compose v2.24 или новее, GNU make, openssl и uv; сторонние образы (PostgreSQL, Valkey, объектное хранилище и др.) получаются из реестра образов правообладателя (раздел 1.4) [ПРОВЕРИТЬ ДО ПОДАЧИ: файл docker-compose.yml ссылается на копии сторонних образов в реестре правообладателя, в том числе на образ объектного хранилища]. Из корневого каталога рабочей копии:
make env # файл .env с новыми ключами для ознакомительной установки
make up # сборка и запуск всех сервисов, ожидание готовности
make seed # тарифы, тестовый провайдер, учётная запись администратора
После запуска веб-консоль доступна по адресу http://localhost:8888, шлюз — http://localhost:8080. Пароль учётной записи администратора выводится командой make seed один раз. В ознакомительной установке вместо внешних сервисов работают их имитаторы (провайдер моделей, ЮKassa, DaData), а письма перехватываются локальным почтовым сервером с веб-интерфейсом на порту 8025. Остановка — make down, остановка с удалением данных — make down-volumes.
7. Первый запуск
7.1. Миграции базы данных
При каждом развёртывании разовая задача миграций (aitech-api db ensure-roles и aitech-api migrate):
- ожидает доступности базы данных и берёт рекомендательную блокировку, чтобы миграции не выполнялись параллельно;
- создаёт или проверяет роли базы данных aitech_app, aitech_gateway и aitech_gateway_login;
- применяет миграции схемы до текущей версии и добавляет недостающие тарифы;
- создаёт корзину объектного хранилища.
Сервис api отвечает кодом 503 на /api/v1/readyz, пока схема не достигла текущей версии; шлюз ожидает готовности схемы и загрузки кэша платформы.
7.2. Проверка состояния
| Проверка | Ожидаемый результат |
|---|---|
| https://<адрес консоли>/api/v1/readyz | 200 |
| https://<адрес шлюза>/readyz | 200 |
| gateway, порт 9090: /healthz/deps | Доступность PostgreSQL, Valkey и nlp |
| nlp, порт 8070: /readyz | 200 после загрузки моделей |
| extractor, порт 8071: /readyz | 200 |
7.3. Первый администратор платформы
-
Зарегистрируйтесь в веб-консоли и подтвердите адрес электронной почты по ссылке из письма.
-
Назначьте учётной записи права администратора платформы:
aitech-api create-admin --email <адрес>(в Kubernetes — через kubectl exec в под api; в Docker Swarm — через служебный сервис cli стека).
-
Включите двухфакторную аутентификацию в разделе «Настройки» → «Безопасность»: без неё раздел администрирования платформы недоступен.
7.4. Модели
Платформенные модели (доступные организациям инсталляции без собственных учётных данных) создаются командой seed-platform по учётным данным PLATFORM_* из файла секретов:
aitech-api seed-platform --global-rpm <лимит запросов в минуту>
Рекомендуемое значение --global-rpm — около 80 % лимита, выданного провайдером. Организации подключают собственные модели в веб-консоли в разделе «Провайдеры и модели».
7.5. Проверочный сценарий
Сценарий deploy/swarm/smoke.sh из комплекта поставки проверяет: ответы /api/v1/readyz и /readyz, наличие HSTS, маскирование тестового ИНН через демонстрационный метод маскирования, разрешения CORS для каждого адреса консоли и (при заданном API-ключе) потоковый ответ модели через шлюз.
8. Конфигурация
Параметры передаются сервисам переменными окружения. Секретные параметры передаются только через секреты Kubernetes или файл секретов стека Docker Swarm. Ниже приведены основные параметры; полный перечень с проверками формата — в файлах значений чартов (values.schema.json).
8.1. Общие параметры и адреса
| Параметр | Назначение |
|---|---|
| AITECH_ENV | Режим: dev, staging, prod. В режимах кроме prod страницы закрыты от индексации, в staging регистрация выключена |
| AITECH_REGION | Регион инсталляции; для Российской Федерации — ru (рубли, ЮKassa, русский язык по умолчанию) |
| PUBLIC_WEB_URL, PUBLIC_WEB_ORIGINS | Основной и все адреса веб-консоли |
| PUBLIC_GATEWAY_URL, PUBLIC_GATEWAY_ALIASES | Основной адрес и дополнительные имена шлюза |
| CORS_ORIGINS | Источники, которым шлюз разрешает запросы из браузера (по умолчанию — адреса консоли) |
| TRUSTED_PROXY_CIDRS, TRUSTED_PROXY_DNS | Адреса обратного прокси, которому доверяется заголовок адреса клиента |
| LOG_LEVEL, LOG_FORMAT | Уровень (info) и формат (json) журналов |
| SIGNUP_ENABLED, LEADS_ENABLED, COOKIE_SECURE | Открытая регистрация, форма заявок на сайте, флаг Secure для cookie |
| LEGAL_VERSION_* | Версии юридических документов (пять параметров), обязательны для api |
8.2. Хранилища
| Параметр | Назначение |
|---|---|
| DATABASE_URL | Подключение api, worker и служебных команд к PostgreSQL (роль aitech_app) |
| GATEWAY_DATABASE_URL | Подключение шлюза (роль aitech_gateway_login) |
| ADMIN_DATABASE_URL, APP_DB_PASSWORD, GATEWAY_DB_PASSWORD | Только для задачи миграций: создание ролей |
| DB_POOL_SIZE, DB_MAX_CONNS, DB_STATEMENT_TIMEOUT_MS | Размер пулов соединений и ограничение времени запросов |
| REDIS_URL | Подключение к Valkey |
| S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY | Объектное хранилище (адресация в стиле пути) |
8.3. Ключи
| Параметр | Назначение |
|---|---|
| ENCRYPTION_KEYS, ENCRYPTION_ACTIVE_KEY | Шифрование полей базы данных (api, worker) |
| GATEWAY_ENCRYPTION_KEYS | Расшифровка учётных данных провайдеров шлюзом |
| API_KEY_PEPPERS, API_KEY_ACTIVE_PEPPER | Хеширование API-ключей |
| GATEWAY_JWT_KEYS, GATEWAY_JWT_ACTIVE_KEY | Подпись маркеров веб-консоли для обращения к шлюзу и служебных маркеров |
| RESTORE_TOKEN_KEYS, RESTORE_TOKEN_ACTIVE_KEY | Шифрование маркеров восстановления (только шлюз) |
| TRIAL_CLAIM_KEY | Учёт использования пробного периода |
8.4. Внешние сервисы
| Параметр | Назначение |
|---|---|
| EMAIL_PROVIDER | Способ отправки писем: smtp (по умолчанию) или unisender_go |
| EMAIL_FROM, SUPPORT_EMAIL, SALES_EMAIL | Адрес отправителя; адрес поддержки (ответы на письма, контакты на сайте); адрес для заявок |
| SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_STARTTLS | Почтовый сервер (порт 587 со STARTTLS или 465 с TLS) |
| UNISENDER_GO_API_KEY, UNISENDER_GO_API_URL | Отправка писем через Unisender Go |
| BILLING_ENABLED, BILLING_TAX_CONFIG_FILE, SELLER_REQUISITES_FILE, BILLING_TZ, INVOICE_PREFIX | Биллинг: включение, налоги, реквизиты продавца, часовой пояс (Europe/Moscow), префикс номеров счетов |
| YOOKASSA_SHOP_ID, YOOKASSA_SECRET_KEY, YOOKASSA_API_URL, YOOKASSA_WEBHOOK_TRUSTED_CIDRS, YOOKASSA_AUTOPAY_ENABLED | Приём платежей через ЮKassa и автопродление |
| DADATA_API_URL, DADATA_API_KEY | Заполнение реквизитов организации по ИНН (необязательно) |
| SENTRY_DSN | Отправка сведений об ошибках api и worker в сервис сбора ошибок, совместимый с протоколом Sentry, размещённый на территории Российской Федерации (необязательно; персональные данные не передаются) |
8.5. Провайдеры моделей и сетевые ограничения
| Параметр | Назначение |
|---|---|
| ALLOWED_PROVIDER_KINDS | Разрешённые виды провайдеров; по умолчанию yandexgpt, gigachat, openai_compatible |
| PLATFORM_YANDEX_API_KEY, PLATFORM_YANDEX_FOLDER_ID | Учётные данные платформенных моделей YandexGPT |
| PLATFORM_GIGACHAT_AUTH_KEY, PLATFORM_GIGACHAT_SCOPE | Учётные данные платформенных моделей GigaChat |
| GIGACHAT_OAUTH_URL, EXTRA_CA_CERTS_FILE | Адрес получения маркера GigaChat; дополнительные корневые сертификаты |
| UPSTREAM_DENIED_HOST_SUFFIXES | Дополнения к встроенному списку запрещённых узлов |
| UPSTREAM_ALLOWED_PRIVATE_CIDRS, WEBHOOK_ALLOWED_PRIVATE_CIDRS | Разрешённые частные сети для моделей заказчика и вебхуков |
| EGRESS_DENY_CIDRS, OUTBOUND_ALLOW_HTTP | Дополнительно запрещённые сети; разрешение незащищённого HTTP (по умолчанию запрещён) |
| NLP_URL, EXTRACTOR_URL, GATEWAY_INTERNAL_URL, API_INTERNAL_URL | Адреса внутренних сервисов; пустой EXTRACTOR_URL выключает извлечение текста из документов |
8.6. Ограничения шлюза и сервисов
| Параметр | Назначение |
|---|---|
| MAX_BODY_BYTES | Максимальный размер запроса (25 МБ) |
| MAX_REQUEST_TEXT_BYTES | Максимальный объём текста запроса (1 МБ) |
| GOMEMLIMIT | Ограничение памяти среды выполнения шлюза (около 80 % лимита контейнера) |
| SHUTDOWN_DELAY_S, SHUTDOWN_DRAIN_S | Задержка и время завершения потоковых ответов при остановке шлюза (5 и 540 секунд) |
| NLP_LANGS, NLP_WORKERS | Языки (ru, en) и число процессов распознавания (около 400 МБ памяти каждый) |
| EXTRACTOR_CONCURRENCY, EXTRACTOR_LIBREOFFICE_MEMORY_MB, EXTRACTOR_WORKER_MEMORY_MB | Число одновременно обрабатываемых документов (2) и ограничения памяти (768 МБ) |
9. Эксплуатация
9.1. Служебные команды
Служебные команды выполняются в контейнере api (в Docker Swarm — через служебный сервис cli стека с одним экземпляром на время выполнения).
| Команда | Назначение |
|---|---|
| aitech-api migrate, aitech-api db ensure-roles | Миграции и роли базы данных (выполняются автоматически) |
| aitech-api seed-plans | Добавление недостающих тарифов |
| aitech-api seed-platform | Создание и обновление платформенных моделей; параметры --global-rpm, --remove-kind |
| aitech-api create-admin --email | Назначение администратора платформы |
| aitech-api rotate-encryption | Перешифрование данных действующим ключом после ротации |
| aitech-api gen-keys | Генерация ключей |
| aitech-api replay-dlq | Повторная обработка событий, не записанных в журнал |
| aitech-api send-test-email --to | Проверка отправки писем |
9.2. Мониторинг
Сервисы публикуют метрики в формате Prometheus на внутренних портах: gateway — 9090, api — 8000 (/metrics), worker — 9091, nlp — 8070, extractor — 9071. В комплект поставки входят правила оповещений (шлюз, api, фоновые задачи, nlp, биллинг, платформа, целевые показатели доступности) и панели Grafana; в Kubernetes они подключаются ресурсами ServiceMonitor и PrometheusRule. Внешний мониторинг доступности проверяет /api/v1/readyz консоли, /readyz шлюза и срок действия сертификатов (оповещение менее чем за 14 дней).
9.3. Журналы
Сервисы пишут журналы в стандартный вывод в формате JSON с полями ts, level, msg, request_id, org_id, service. Содержимое запросов и ответов, заголовки и параметры строки запроса в журналы не записываются. В Docker Swarm размер журналов ограничен ротацией (3 файла по 10 МБ на сервис).
9.4. Ротация ключей
Ротация набора ключей выполняется поэтапно, с развёртыванием после каждого этапа: добавление нового ключа неактивным; назначение его действующим; перешифрование данных (aitech-api rotate-encryption) или ожидание истечения срока действия маркеров; удаление старого ключа. Выведенные ключи хранятся не менее 30 дней. Рекомендуемая периодичность: ключи подписи и маркеров восстановления — каждые 90 дней, ключи шифрования и пароли — каждые 12 месяцев, а также немедленно при подозрении на компрометацию или увольнении сотрудника с доступом.
9.5. Масштабирование
Шлюз и nlp масштабируются горизонтально увеличением числа экземпляров (в Kubernetes — автоматически по загрузке). Адрес NLP_URL должен разрешаться во все экземпляры nlp. Число соединений с базой данных ограничивается: сумма пулов всех экземпляров не должна превышать max_connections PostgreSQL (чарт проверяет это условие).
10. Обновление
- Получите номер новой версии и убедитесь, что её образы есть в реестре. Используются только неизменяемые теги vX.Y.Z (в Kubernetes — дополнительно дайджесты образов, параметр image.requireDigest).
- Выполните резервное копирование базы данных (раздел 11).
- Kubernetes: helm upgrade с новыми дайджестами (раздел 4, шаг 5); миграции выполняются до обновления сервисов. Docker Swarm: сформируйте файл стека с новым тегом (раздел 5, шаг 4) и разверните весь стек (шаг 5); задача migrate выполнится повторно.
- Выполните проверки разделов 7.2 и 7.5.
Миграции схемы обратно совместимы с предыдущей версией (удаление и переименование полей выполняются на следующем выпуске), поэтому во время обновления предыдущая и новая версии работают с одной базой данных.
Откат выполняется повторным развёртыванием предыдущей версии (в Docker Swarm также командой docker service rollback для отдельного сервиса; при неуспешном обновлении Swarm откатывает сервис автоматически). Откат схемы базы данных не требуется и не выполняется.
11. Резервное копирование и восстановление
11.1. Что копируется
| Данные | Порядок |
|---|---|
| База данных PostgreSQL | Автоматически (разделы 11.2, 11.3) |
| Файл секретов, наборы ключей, пароли | При установке и каждом изменении — в защищённое хранилище секретов, отдельно от копий базы данных |
| Файлы настроек биллинга, файлы значений и параметров инсталляции | При изменении |
| Закрытый ключ шифрования резервных копий | При создании — в защищённое хранилище секретов |
Не копируются: Valkey (восстанавливается из базы данных), объектное хранилище (счета формируются заново, выгрузки хранятся 24 часа), сертификаты TLS (выпускаются заново).
11.2. Docker Swarm
Сервис backup ежедневно в 03:00 UTC выполняет pg_dump, шифрует копию открытым ключом age и выгружает её в объектное хранилище вне узла данных; хранятся копии за 14 дней и две последние копии локально. При ошибке выполняется одна повторная попытка через 30 минут. Точка восстановления — до 24 часов. Команды сервиса: backup.sh --once (внеочередная копия), --check (проверка свежести), --list (перечень копий).
11.3. Kubernetes
Оператор CloudNativePG непрерывно архивирует журнал транзакций и ежедневно в 02:00 UTC создаёт базовую копию в объектном хранилище; срок хранения — 14 дней. Возможно восстановление на момент времени.
11.4. Восстановление
- Остановите сервисы gateway, api и worker (число экземпляров 0).
- Восстановите базу данных: в Docker Swarm — restore.sh <копия> (нужен закрытый ключ age), в Kubernetes — созданием кластера CloudNativePG из резервной копии.
- Выполните действия после восстановления: очистите в Valkey ключи балансов, удалите сеансы пользователей, проверьте счётчики номеров счетов, сверьте платежи ЮKassa за период после копии, повторите удаления данных, выполненные после копии.
- Запустите сервисы и выполните проверки разделов 7.2 и 7.5.
Ежемесячно рекомендуется проверочное восстановление во временную базу данных (restore.sh --drill) со сверкой числа строк.
12. Удалённый доступ к экземпляру (облачная версия)
12.1. Назначение
Раздел содержит инструкцию по удалённому доступу к экземпляру программного комплекса, который правообладатель развернул для проверки на сервере на территории Российской Федерации. Экземпляр установлен из того же комплекта поставки, что и описанный в этом документе, и работает в режиме для Российской Федерации. Установка программного обеспечения на рабочее место эксперта не требуется: достаточно веб-браузера (раздел 2.2), для проверки API — HTTP-клиента, например curl.
12.2. Сведения о доступе
| Параметр | Значение |
|---|---|
| Адрес веб-консоли | https://айтечество.рф/ru/login (страница «Вход в консоль») |
| Адрес шлюза | [ЗАПОЛНИТЬ: адрес шлюза экземпляра] |
| Учётная запись эксперта (владелец организации) | [ЗАПОЛНИТЬ: адрес электронной почты для входа; пароль передаётся отдельно от документа] |
| Учётная запись сотрудника организации | [ЗАПОЛНИТЬ: адрес электронной почты для входа; пароль передаётся отдельно от документа] |
| Роль и тариф | Владелец и сотрудник отдельной организации, созданной для проверки; тариф «Корпоративный» (владельцу доступны все разделы веб-консоли, кроме администрирования платформы). По запросу эксперта создаётся учётная запись администратора платформы с обязательной двухфакторной аутентификацией |
| Срок доступа | [ЗАПОЛНИТЬ: срок доступа] |
| Модели | Платформенные модели YandexGPT и GigaChat, включённые для организации |
| Обращения по доступу | Адрес технической поддержки (документ «Описание процессов, обеспечивающих поддержание жизненного цикла программного обеспечения», раздел 5.1) |
[ПРОВЕРИТЬ ДО ПОДАЧИ: экземпляр по адресу https://айтечество.рф развёрнут из образов реестра правообладателя на сервере на территории Российской Федерации, арендованном правообладателем; учётные записи эксперта созданы и проверены входом]
12.3. Порядок проверки
-
Откройте адрес веб-консоли, на странице «Вход в консоль» введите адрес электронной почты и пароль учётной записи эксперта. После первого входа рекомендуется сменить пароль: «Настройки» → «Аккаунт» → «Пароль».
-
В разделе «Песочница» введите текст с вымышленными персональными данными (например, «Иванов Пётр Сергеевич, ИНН 1234567894, тел. +7 900 000-00-00») и нажмите «Замаскировать»: рядом с исходным текстом отображается «Что получила бы модель». Блок «Восстановление» подставляет исходные значения обратно.
-
В разделе «Чат» выберите модель платформы, отправьте сообщение и нажмите «Что увидела модель», чтобы увидеть текст, переданный модели.
-
В разделе «Политики» откройте политику по умолчанию, измените действие для категории и проверьте результат в блоке «Проверка».
-
В разделе «API-ключи» создайте ключ и выполните запрос к шлюзу:
curl https://<адрес шлюза>/v1/chat/completions \ -H "Authorization: Bearer <ключ>" \ -H "Content-Type: application/json" \ -d '{"model": "yandexgpt", "messages": [{"role": "user", "content": "Привет"}]}' -
В разделах «Журнал запросов» и «Аудит» проверьте записи о выполненных запросах и действиях.
Работа с разделами веб-консоли описана в документе «Руководство пользователя».
12.4. Ограничения
- Экземпляр предназначен только для проверки программного комплекса; используйте вымышленные данные.
- Запросы к моделям учитываются в квоте и балансе организации, созданной для проверки.
- По истечении срока доступа организация, созданная для проверки, приостанавливается и затем удаляется вместе с учётными записями эксперта (данные организации удаляются через 30 дней после её удаления).