• Русский

      • Безопасность и аудит

      Предварительные требования

      Перед чтением этой страницы убедитесь, что Вы установили NocoBase CLI и выполнили инициализацию по инструкции Быстрый старт с Конструктором ИИ.

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

      Аутентификация

      AI Agent подключается к NocoBase главным образом двумя способами:

      • Аутентификация по API key: с помощью плагина API keys создаётся API Key, который сохраняется в окружении CLI и далее используется для прямых запросов к API
      • Аутентификация OAuth: однократный вход через браузер по протоколу OAuth, после чего обращения к API выполняются от имени текущего пользователя

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

      Аутентификация по API key

      API key используется в основном для автоматизации, скриптов и долгоиграющих задач, например:

      • AI Agent периодически синхронизирует данные
      • В среде разработки часто вызывается nb api
      • Стабильные, чётко определённые задачи построения выполняются от имени одной и той же роли

      Базовый сценарий:

      1. Включите в NocoBase плагин API keys и создайте API Key
      2. Привяжите этот API Key к специально выделенной роли, а не напрямую к root или администратору с полным набором прав
      3. Сохраните адрес API и Token в окружении CLI с помощью nb env add

      Например:

      nb env add local \
  --scope project \
  --api-base-url http://localhost:13000/api \
  --auth-type token \
  --access-token <your-api-key>

      После настройки AI Agent может выполнять API-вызовы через это окружение:

      nb api resource list --env local --resource users

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

      • Привязывайте Token только к специальной роли
      • Сохраняйте его только в действительно необходимых окружениях CLI
      • Регулярно ротируйте Token, не используйте «никогда не истекает» по умолчанию
      • При подозрении на утечку немедленно удаляйте Token и создавайте новый

      Более общие рекомендации см. в руководстве по безопасности NocoBase.

      Аутентификация OAuth

      OAuth используется в основном для задач, выполняемых от имени текущего вошедшего пользователя, например:

      • ИИ помогает текущему администратору выполнить разовую настройку
      • Действия должны быть атрибутированы конкретному вошедшему пользователю
      • Нежелательно длительное хранение Token с высокими привилегиями

      Базовый сценарий:

      1. Сначала добавьте окружение CLI, выбрав способ аутентификации oauth
      2. Выполните nb env auth
      3. В браузере откроется страница аутентификации — войдите и завершите вход
      4. CLI сохранит данные аутентификации, последующие вызовы nb api будут идти от имени текущего пользователя
      5. Если у пользователя несколько ролей, конкретную роль можно указать через --role

      Например:

      nb env add local \
  --scope project \
  --api-base-url http://localhost:13000/api \
  --auth-type oauth

nb env auth local

      Команда nb env auth запускает процесс входа в браузере. После успешного входа CLI сохраняет данные аутентификации в текущее окружение, и AI Agent может продолжать вызывать nb api.

      Срок действия access token и refresh token OAuth следует системной настройке политики Token.

      • Срок действия access token OAuth совпадает со сроком действия системного Token; значение по умолчанию — 1 день
      • Срок действия refresh token OAuth совпадает со сроком действия системной сессии; значение по умолчанию — 7 дней

      Когда срок действия access token подходит к концу, CLI сначала пробует автоматически обновить сессию через refresh token. Если refresh token уже истёк, недоступен или сервер не вернул его, потребуется снова выполнить nb env auth. Если изменить политику Token, необходимо перезапустить систему, чтобы изменение вступило в силу для сервиса OAuth.

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

      Рекомендуемые практики

      Рекомендации по выбору:

      • Разработка, тестирование, автоматизация: предпочтительно API key, но обязательно с привязкой к специальной роли
      • Продакшн, операции с участием человека, строгая атрибуция: предпочтительно OAuth
      • Высокорискованные операции: даже если технически возможен Token, рекомендуется использовать OAuth и выполнять действия от имени пользователя с соответствующими правами

      Если конкретных требований нет, действуйте по таким правилам по умолчанию:

      • По умолчанию OAuth
      • API key — только когда явно требуются автоматизация, неинтерактивный или пакетный запуск

      Контроль прав доступа

      У AI Agent нет «дополнительных прав» — он может ровно столько, сколько разрешено текущей учётной записи и роли.

      Иными словами:

      • При доступе по API key границы прав определяются ролью, привязанной к Token
      • При доступе через OAuth — текущим пользователем и его текущей ролью

      ИИ не обходит систему ACL NocoBase. Если у роли нет прав на конкретную таблицу, поле, страницу или настройку плагина, AI Agent, даже зная нужную команду, не сможет её выполнить.

      Роли и политики прав

      Рекомендуется создавать для AI Agent отдельную роль, а не повторно использовать существующую административную.

      Обычно такой роли достаточно открыть права в следующих пределах:

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

      Например, можно создать роль ai_builder_editor, которая позволит:

      • Управлять таблицами CRM
      • Редактировать определённые страницы
      • Запускать часть рабочих процессов
      • Не разрешать менять права ролей
      • Не разрешать включать, отключать и устанавливать плагины
      • Не разрешать удалять ключевые таблицы

      Если ИИ должен помочь настраивать права, для этого можно использовать Настройку прав доступа, но границы прав по-прежнему лучше задавать вручную.

      Принцип минимальных привилегий

      Принцип минимальных привилегий особенно важен в сценариях с Конструктором ИИ. Рекомендуется:

      1. Сначала создать для ИИ выделенную роль
      2. Изначально открыть только права на просмотр
      3. По мере появления задач постепенно добавлять права на создание, редактирование и т. п.
      4. Удаление, изменение прав, управление плагинами и другие операции с высоким риском оставлять под человеческим контролем

      Например:

      • ИИ для ввода контента — только просмотр и создание в нужной таблице
      • ИИ для построения страниц — только права на соответствующие страницы и UI-конфигурацию
      • ИИ для моделирования данных — изменение структуры таблиц только в тестовом окружении, не напрямую в продакшне

      Не рекомендуется напрямую привязывать к AI Agent роли root, admin или роль с глобальной системной конфигурацией. Это удобно при развёртывании, но сильно расширяет поверхность атаки.

      Журналы

      В сценариях Конструктора ИИ журналы помогают отслеживать операции и локализовать проблемы.

      Особое внимание следует уделить двум типам журналов:

      • Журналы запросов: фиксируют путь, метод, статус-код, длительность и источник API-запроса
      • Журналы аудита: фиксируют исполнителя, объект, результат и связанные метаданные ключевых операций

      При вызовах через nb api CLI автоматически добавляет заголовок x-request-source: cli, по которому сервер определяет, что запрос пришёл из CLI.

      Журнал запросов

      Журнал запросов фиксирует информацию об API-вызовах: путь запроса, статус ответа, длительность и метку источника.

      Файлы журнала обычно расположены здесь:

      storage/logs/<appName>/request_YYYY-MM-DD.log

      При вызовах nb api в журнале запросов будет присутствовать:

      • req.header.x-request-source

      Это позволяет отличать запросы из CLI от обычных запросов из браузера.

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

      Журнал аудита

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

      Для операций, попадающих под аудит, в журнале фиксируется:

      • resource
      • action
      • userId
      • roleName
      • status
      • metadata.request.headers.x-request-source

      Например, когда ИИ через CLI вызывает collections:apply, fields:apply или другие записи, попадающие под аудит, в журнале аудита фиксируется x-request-source: cli, что позволяет отличать операции через интерфейс от операций через CLI.

      Подробное описание журнала аудита см. в разделе Журнал аудита.

      Рекомендации по безопасности

      Несколько практических рекомендаций для сценариев Конструктора ИИ:

      • Не привязывайте к AI Agent напрямую роли root, admin или роль с глобальной системной конфигурацией
      • Создавайте для AI Agent отдельную роль и разделяйте права по задачам
      • Регулярно ротируйте API key, не используйте долго один и тот же Token с высокими правами
      • Изменения модели данных, структуры страниц и рабочих процессов сначала проверяйте в тестовом окружении, а потом синхронизируйте в продакшн
      • Включайте и регулярно проверяйте журналы запросов и аудита, чтобы ключевые операции были отслеживаемыми
      • Удаление данных, изменение прав, включение/отключение плагинов и изменение системных настроек — это высокорискованные операции, по возможности подтверждайте их вручную
      • Если ИИ должен работать долго, лучше разбейте окружения на несколько малопривилегированных, чем держать одно высокопривилегированное

      Связанные ссылки