Установка Local App на коробочный портал

Скачать приложение

1. Кому нужен и что даёт

Модуль ставится на коробочный (self-hosted) Bitrix24 — это может быть портал интегратора, портал клиента или оба сразу. Один и тот же дистрибутив подходит для любой роли: кто именно обращается к порталу, определяется ключом подписи, а не сборкой.

• Без Local App платформа ходит на портал по обычному REST и упирается в лимит 2 запроса в секунду.
• С Local App вызов исполняется в собственном процессе Bitrix24 — без HTTP-обращения к /rest/, без шлюза и без лимита.

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

2. Что понадобится

• доступ к файловой системе сервера портала (SSH или панель хостинга);
• портал доступен по HTTPS;
• установленное приложение BIC на портале (Integrator App или Client App) — Local App его не заменяет, а ускоряет;
• ключ подписи (HMAC) — где взять, ниже.

3. Шаг 1. Получите ключ подписи

Ключ показывается один раз — сохраните его сразу.

4. Шаг 2. Разместите файлы на портале

Скачайте архив (кнопка в начале страницы), распакуйте его и скопируйте папку в веб-корень портала так, чтобы получился путь /local/bic/ (в некоторых сборках — bitrix/local/bic/). Проверить можно по адресу вида https://portal.example.com/local/bic/proxy.php.

local/bic/
├── proxy.php          — основная точка входа (POST, проверка подписи)
├── handshake.php      — проверка доступности и версии (GET)
├── install.php        — необязательный прогрев классов
├── config.example.php — скопировать в config.php
└── lib/               — служебные классы

5. Шаг 3. Настройте config.php

Скопируйте config.example.php в config.php и впишите ключ:

return [
    // Обязательно — ключ, которым проверяется подпись запросов от платформы BIC
    'hmac_key' => 'ВАШ-КЛЮЧ-ИЗ-КАБИНЕТА',

    // Необязательно, но рекомендуется в проде — список IP платформы
    'ip_allowlist' => [
        // '203.0.113.10',
    ],

    // Необязательно — путь к JSON-логу прокси. null или '' = логирование выключено
    'log_file' => null,
];

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

6. Шаг 4. Прогрев классов (необязательно)

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

php install.php /path/to/bitrix/local/php_interface/init.php

Шаг необязательный и на работоспособность не влияет.

7. Шаг 5. Включите режим в приложении BIC

• Портал клиента — интегратор нажимает «Включить local» в разделе «Порталы».
• Портал интегратора — «Проверить подключение» в кабинете.

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

8. Как это устроено (и почему это безопасно)

Платформа отправляет на proxy.php POST-запрос, подписанный ключом из вашего config.php. Прокси проверяет подпись и метку времени и только после этого загружает ядро Bitrix и выполняет вызов.

• Подпись HMAC-SHA256 — запрос без верной подписи отбрасывается до загрузки ядра.
• Защита от повтора — метка времени принимается в окне ±60 секунд, перехваченный запрос нельзя переиграть позже.
• Коробка не хранит токенов — OAuth-токен портала передаётся платформой в каждом запросе, поэтому утечка файлов модуля не даёт доступа к порталу.
• Список IP — необязательный, но рекомендуемый дополнительный барьер.
• Резервного канала через вебхуки нет: если ядро или модуль rest недоступны, прокси вернёт явную ошибку, а не выполнит запрос обходным путём.

9. Смена ключа

Порядок: перевыпустить ключ (клиент — «Перевыпустить секрет» в приложении BIC; интегратор — ротация в кабинете), затем сразу заменить hmac_key в config.php.

10. Обновление модуля

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

11. Если режим не включается

• Ошибка подписи — ключ в config.php не совпадает с выданным (частая причина — лишние пробелы или перенос строки при копировании).
• Ядро не загружается — файлы лежат вне веб-корня портала либо путь отличается от /local/bic/.
• Прокси недоступен снаружи — адрес proxy.php закрыт файрволом или базовой авторизацией веб-сервера.
• Запрос отклоняется по IP — заполнен ip_allowlist, но в нём нет адресов платформы.
• Расхождение времени — часы сервера портала уехали более чем на минуту, из-за чего не проходит проверка метки времени. Синхронизируйте время по NTP.

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

Дистрибутив и помощь с развёртыванием — info@bic-24.ru.