• Русский

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

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

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

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

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

      ИИ агенты подключаются к NocoBase в основном двумя способами аутентификации:

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

      Оба способа работают с командами nb. Разница — в источнике идентичности, применимых сценариях и стратегиях контроля рисков.

      Аутентификация по API-ключу

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

      • периодическая синхронизация данных ИИ агентом
      • частые вызовы nb api в окружениях разработки
      • выполнение класса понятных стабильных задач по сборке с фиксированной ролью

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

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

      Например:

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

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

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

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

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

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

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

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

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

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

      1. Добавьте окружение CLI с методом аутентификации oauth
      2. Выполните nb env auth
      3. Браузер откроет страницу аутентификации — войдите и завершите аутентификацию
      4. CLI сохранит данные аутентификации; последующие запросы nb api обращаются к NocoBase от имени текущего пользователя
      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 сохраняет данные аутентификации в конфигурации текущего окружения, и можно продолжать вызывать nb api через ИИ агента.

      Сроки действия токена доступа и токена обновления OAuth следуют конфигурации политики токенов системы.

      • Токен доступа OAuth имеет тот же срок действия, что и системные токены, по умолчанию 1 день
      • Токен обновления OAuth имеет тот же срок действия, что и системные сессии, по умолчанию 7 дней

      CLI в приоритете использует токен обновления для автоматического обновления сессии, когда токен доступа скоро истечёт. Если токен обновления истёк, недоступен или сервер не вернул токен обновления, нужно снова выполнить nb env auth. Если вы изменили политику токенов, перезапустите систему, чтобы изменения вступили в силу в сервисе OAuth.

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

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

      Выбирайте по следующим принципам:

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

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

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

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

      У самого ИИ агента нет «дополнительных прав» — что он может делать, полностью зависит от используемой идентичности и роли.

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

      • при доступе через API-ключ граница прав определяется ролью, привязанной к этому токену
      • при доступе через OAuth граница прав определяется текущим вошедшим пользователем и его текущей ролью

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

      Роли и стратегии прав доступа

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

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

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

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

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

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

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

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

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

      Например:

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

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

      Логи

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

      Обратите внимание на два типа логов:

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

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

      Логи запросов

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

      Файлы логов обычно расположены по пути:

      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.

      Подробнее о логах аудита см. Логи аудита.

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

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

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

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