Установка и развёртывание

Шлюз поставляется как один исполняемый файл и разворачивается в контуре компании (self-hosted). Для пилотного запуска в самом продукте есть пошаговый чек-лист на странице «Начало работы» (/web/getting-started): установка, настройка 1С, приглашение команды, подключение AI-клиента, первый черновик, одобрение.

Хранилище

Конфигурация читается из переменных окружения. Базу данных выбирает DB_DRIVER:

Одиночный экземпляр работает на любом из трёх бэкендов: PostgreSQL, SQLite или MSSQL (поддерживается с SQL Server 2016). Режим нескольких экземпляров (GATEWAY_CLUSTER_ENABLED, по умолчанию выключен) требует PostgreSQL.

Обратный прокси и TLS

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

1. Сервер говорит на чистом HTTP, TLS терминируется на прокси. Бинарник сам TLS не обслуживает. Впереди должен стоять обратный прокси (nginx, Caddy, traefik), который терминирует HTTPS и проксирует на приложение через loopback. Чистый HTTP-порт нельзя открывать клиентам напрямую.
2. Приложение слушает loopback. LISTEN_ADDR по умолчанию 127.0.0.1:8443, то есть из коробки до приложения дотягивается только прокси на том же хосте. Явная привязка к не-loopback адресу без TRUST_PROXY_HEADERS=true даёт громкое предупреждение при старте.
3. MCP-endpoint полагается на прокси в проверке Origin и Host. Встроенная localhost-защита MCP SDK отключена, потому что за прокси заголовок Host принадлежит прокси. Это безопасно только когда впереди доверенный прокси; прямое открытие наружу не поддерживается.
4. TRUST_PROXY_HEADERS=true только за доверенным прокси. Флаг заставляет доверять X-Forwarded-For / X-Real-IP (корректные IP клиентов в аудите) и X-Forwarded-Proto. На открытом напрямую сервере эти заголовки подделываются клиентом и отравили бы журнал аудита, поэтому по умолчанию false.
5. Аутентификация на /mcp обязательна всегда. Каждый запрос несёт Authorization: Bearer ent_live_<...>, анонимный получает 401. Лимиты частоты действуют независимо от прокси.
6. Задайте WEB_PUBLIC_URL. За прокси ссылки приглашений иначе строились бы от подделываемого заголовка Host. Укажите канонический HTTPS-адрес, например WEB_PUBLIC_URL=https://mcp.your-company.tld; приложение предупреждает при старте, если за прокси адрес не задан.

Минимальный набросок nginx (иллюстративный, укрепляйте под свою среду):

server {
    listen 443 ssl;
    server_name mcp.your-company.tld;
    # ssl_certificate / ssl_certificate_key ...

    location / {
        proxy_pass http://127.0.0.1:8443;   # приложение на loopback
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # Streamable HTTP и SSE требуют потоковой отдачи и долгих чтений:
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}

Затем запустите приложение с LISTEN_ADDR=127.0.0.1:8443, TRUST_PROXY_HEADERS=true и WEB_PUBLIC_URL=https://mcp.your-company.tld.

Базовые переменные окружения

Таймауты HTTP

Транспортные таймауты встроенного HTTP-сервера настраиваются. Все значения это Go-длительности (30s, 2m, 1h). Их можно задать переменными окружения или настроить в админ-разделе /web/admin/http-timeouts; сохранённое в интерфейсе значение переопределяет переменную окружения.

Семантика применения: четыре глобальных таймаута (READ / READ_HEADER / WRITE / IDLE) снимаются сервером при старте, поэтому изменение вступает в силу после перезапуска. Два потоковых читаются на каждую передачу: HTTP_ARCHIVE_WRITE_TIMEOUT действует уже на следующем запросе /archive, HTTP_UPLOAD_NETWORK_TIMEOUT действует для новых загрузок. Значение вне диапазона отклоняется при старте (fail-closed) и в интерфейсе (422) с тем же сообщением.

Подключение к 1С

Шлюз читает данные 1С через поставляемое расширение конфигурации mcp_service. Подключения к базам 1С создаются и настраиваются в веб-интерфейсе, в разделе /web/admin/onec. Это основной и рекомендуемый способ: адрес базы, учётные данные и активация задаются в интерфейсе, а править базу данных напрямую или описывать подключение переменными окружения не нужно.

Для каждой записи в разделе /web/admin/onec администратор задаёт:

Записи хранятся в базе данных шлюза; адаптер каждой базы пересобирается при сохранении, поэтому смена адреса, логина или пароля вступает в силу без перезапуска сервиса. Перед включением операций записи переустановите mcp_service.cfe с write-обработчиками и выдайте необходимые права учётной записи mcp_service.

Переменные окружения ONEC_* (устаревший путь подключения). Раньше подключение к 1С описывалось переменными ONEC_BASE_URL, ONEC_BASIC_USER и ONEC_BASIC_PASSWORD. В текущей модели единого хаба адрес базы, учётная запись и пароль хранятся записью в базе данных и задаются в интерфейсе, поэтому эти три переменные для описания подключения больше не используются.

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

Поведение операций записи тоже настраивается глобально (все переменные необязательные): ONEC_WRITE_RETRY_MAX_ATTEMPTS (по умолчанию 2, повторяются только транзиентные ошибки), ONEC_DISABLE_SCHEMA_VALIDATION (false), ONEC_SCHEMA_VALIDATION_STRICT (true, неизвестные поля отклоняются), ONEC_RESTRICT_CATALOG_WRITES (false, блокирует запись элементов справочников через RBAC-гейт).

Пароль 1С и systemd (устаревший способ)

Пароль 1С задаётся в веб-интерфейсе (/web/admin/onec) и хранится в базе в зашифрованном виде, поэтому передавать его через окружение не требуется. Ниже для справки по старым развёртываниям оставлен прежний способ передачи ONEC_BASIC_PASSWORD через systemd LoadCredential=. Общий принцип прежнего способа: не размещать ONEC_BASIC_PASSWORD в env-файлах, видимых через /proc/*/environ, а подавать его через systemd LoadCredential=:

[Service]
LoadCredential=onec_basic_password:/etc/mcp-1c-enterprise/onec.basicpass
EnvironmentFile=/run/credentials/%n/environment

Файл /etc/mcp-1c-enterprise/onec.basicpass содержит ровно одну строку:

ONEC_BASIC_PASSWORD=<пароль>

Права: chmod 0400, владелец root:mcp-1c-enterprise. systemd проецирует файл в /run/credentials/<unit>/... только для процесса сервиса, другие процессы на хосте его не прочитают.

Установка расширения в Конфигураторе

На Windows-хосте с Конфигуратором расширение mcp_service загружается в целевую базу неинтерактивно:

mcp-1c-enterprise.exe install-cfe ^
    --base-path C:\1cbase ^
    --user Admin ^
    --pass-file C:\secrets\admin.txt ^
    --cfe-path C:\dist\mcp_service.cfe

Ключевые флаги (полный список: mcp-1c-enterprise install-cfe --help):

• --base-path <каталог> или --server-base <строка>: файловая либо клиент-серверная база, флаги взаимоисключающие.
• --user <имя> и --pass-file <путь>: учётные данные 1С. Инлайн-флаг --pass намеренно не поддержан, чтобы секрет не светился в ps.
• --cfe-path <файл>: готовый .cfe для загрузки.
• --designer-path <exe>: переопределение поиска 1cv8.exe; учитывается и $ONEC_DESIGNER_PATH.
• --dry-run: печатает отредактированные аргументы Конфигуратора и выходит с кодом 0, не вызывая 1cv8.exe.
• --verbose: стримит декодированный журнал Конфигуратора в stdout.

Повторные запуски безопасны: лестница повторов сама обрабатывает случаи «Уже существует» (удалить и загрузить заново), «Конфигурация заблокирована» и «Сеанс работы заблокирован» (повтор с паузой, до 3 попыток) и предупреждение о переопределении свойств заимствованных объектов. На Linux и macOS подкоманда сразу выходит с кодом 2, поэтому её безопасно звать в любом CI. Ручная установка через GUI описана в поставляемом extensions/mcp_service/INSTALL.md.

Подпись релизов и SBOM

Релизные бинарники подписаны Ed25519: рядом с бинарником и его SBOM лежит открепленная подпись .sig. Публичный ключ вшит в бинарник как якорь доверия; --verify самопроверяется против встроенного ключа, а установочный скрипт проверяет подпись независимо: подпись есть и валидна, установка продолжается; есть и невалидна, установка останавливается (fail-closed); отсутствует, выводится предупреждение (либо жёсткое требование через REQUIRE_SIGNATURE).

Каждый релизный артефакт сопровождается SBOM в формате CycloneDX 1.6 с перечнем Go-модулей, вкомпилированных именно в этот бинарник, и sha256-сайдкаром для проверки целостности:

cd bin
sha256sum -c mcp-1c-enterprise.cdx.json.sha256   # GNU/Linux
shasum -a 256 -c mcp-1c-enterprise.cdx.json.sha256   # macOS/BSD