---
title: 'Безопасность и аудит'
description: 'Узнайте о методах аутентификации AI Agent при построении NocoBase, политиках контроля прав доступа, рекомендуемых практиках, а также о том, как отслеживать каждую операцию.'
keywords: 'Конструктор ИИ,безопасность,права,аутентификация,Token,OAuth,журнал операций,аудит'
---

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

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

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

:::

Когда пользователи через [NocoBase CLI](../ai/quick-start.md) используют AI Agent для управления NocoBase, особое внимание следует уделять аутентификации, контролю прав и аудиту, чтобы границы операций были чёткими, а сами действия — отслеживаемыми.

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

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

- **Аутентификация по API key**: с помощью плагина [API keys](/auth-verification/api-keys/index.md) создаётся 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`

Например:

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

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

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

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

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

Более общие рекомендации см. в [руководстве по безопасности NocoBase](../security/guide.md).

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

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

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

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

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

Например:

```bash
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](../security/token-policy/index.md).

- Срок действия 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
- Редактировать определённые страницы
- Запускать часть рабочих процессов
- Не разрешать менять права ролей
- Не разрешать включать, отключать и устанавливать плагины
- Не разрешать удалять ключевые таблицы

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

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

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

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

Например:

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

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

## Журналы

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

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

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

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

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

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

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

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

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

- `req.header.x-request-source`

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

Подробнее о каталоге и полях журнала запросов см. [Серверные журналы NocoBase](../log-and-monitor/logger/index.md).

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

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

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

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

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

Подробное описание журнала аудита см. в разделе [Журнал аудита](../security/audit-logger/index.md).

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

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

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

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

- [Быстрый старт с Конструктором ИИ](./index.md) — установка и подготовка окружения
- [Управление окружениями](./env-bootstrap) — проверка окружения, добавление окружений и диагностика
- [Настройка прав доступа](./acl.md) — настройка ролей, политик прав и оценка рисков
- [NocoBase CLI](../ai/quick-start.md) — инструмент командной строки для установки и управления NocoBase
- [Руководство по безопасности NocoBase](../security/guide.md) — более полные рекомендации по настройке безопасности
- [Серверные журналы NocoBase](../log-and-monitor/logger/index.md) — каталог и поля журнала запросов
- [Журнал аудита](../security/audit-logger/index.md) — поля записей аудита и инструкции по использованию
- [NocoBase MCP](../ai/mcp/index.md) — подключение AI Agent через протокол MCP
