feat(docs-i18n): translate all documentation into 20 languages

All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
2026-08-03 07:46:42 +02:00 · 2026-07-11 13:52:47 +08:00
parent 00b651c9f8
commit 4963ab3bbd
3620 changed files with 306134 additions and 0 deletions
@@ -0,0 +1,264 @@
+---
+description: "Управление пользователями, встроенными и пользовательскими ролями, разрешениями, ключами API, командами, сессиями и журналом аудита в SnapOtter."
+i18n_source_hash: 5e28af686c96
+i18n_provenance: human
+i18n_output_hash: 140592d03c47
+---
+
+# Пользователи, роли и разрешения {#users-roles-permissions}
+
+SnapOtter поставляется с тремя встроенными ролями, 17 гранулярными разрешениями и поддержкой пользовательских ролей с опциональным контролем доступа на уровне отдельных инструментов. Эта страница охватывает полную модель авторизации, ограничение области действия ключей API, управление командами и журналирование аудита.
+
+::: tip Связанные страницы
+[OIDC / SSO](/ru/guide/oidc) | [SAML SSO](/ru/guide/saml) | [Провижининг SCIM](/ru/guide/scim) | [Безопасность и усиление защиты](/ru/guide/security)
+:::
+
+## Пользователи {#users}
+
+### Создание пользователей {#creating-users}
+
+Администраторы могут создавать пользователей через панель администратора или конечную точку `POST /api/auth/register`. У каждого пользователя есть имя пользователя, роль, назначение в команду и опциональный адрес электронной почты.
+
+### Администратор по умолчанию {#default-admin}
+
+При первом запуске SnapOtter создаёт учётную запись администратора по умолчанию. Учётные данные берутся из переменных окружения:
+
+| Переменная | По умолчанию | Описание |
+|---|---|---|
+| `DEFAULT_USERNAME` | `admin` | Имя пользователя для начальной учётной записи администратора |
+| `DEFAULT_PASSWORD` | `admin` | Пароль для начальной учётной записи администратора |
+
+Администратор по умолчанию обязан сменить пароль при первом входе.
+
+### Провайдеры аутентификации {#authentication-providers}
+
+Пользователи могут аутентифицироваться несколькими способами:
+
+- **Локально** — имя пользователя и пароль, хранящиеся в базе данных SnapOtter
+- **OIDC** — любой провайдер OpenID Connect (см. [OIDC / SSO](/ru/guide/oidc))
+- **SAML** — провайдеры идентификации SAML 2.0 (см. [SAML SSO](/ru/guide/saml))
+- **SCIM** — автоматизированный провижининг от провайдера идентификации (см. [Провижининг SCIM](/ru/guide/scim))
+
+### Отключение аутентификации {#disabling-authentication}
+
+Задайте `AUTH_ENABLED=false`, чтобы полностью отключить аутентификацию. В этом режиме для всех запросов используется синтетический анонимный пользователь с ролью `admin`. Вход не требуется.
+
+::: warning 
+Отключение аутентификации предоставляет полный доступ администратора любому, кто может достучаться до экземпляра. Используйте это только в доверенных средах.
+:::
+
+## Встроенные роли {#built-in-roles}
+
+SnapOtter включает три встроенные роли. Их нельзя изменить или удалить.
+
+### Admin {#admin}
+
+Все 17 разрешений. Полный контроль над экземпляром.
+
+`tools:use` `files:own` `files:all` `apikeys:own` `apikeys:all` `pipelines:own` `pipelines:all` `settings:read` `settings:write` `users:manage` `teams:manage` `features:manage` `system:health` `audit:read` `compliance:manage` `webhooks:manage` `security:manage`
+
+### Editor {#editor}
+
+7 разрешений. Может использовать все инструменты и управлять всеми файлами и конвейерами, но не имеет доступа к административным функциям.
+
+`tools:use` `files:own` `files:all` `apikeys:own` `pipelines:own` `pipelines:all` `settings:read`
+
+### User {#user}
+
+5 разрешений. Может использовать инструменты и управлять собственными ресурсами.
+
+`tools:use` `files:own` `apikeys:own` `pipelines:own` `settings:read`
+
+## Справочник по разрешениям {#permissions-reference}
+
+| Разрешение | Описание |
+|---|---|
+| `tools:use` | Использовать любой инструмент обработки |
+| `files:own` | Просматривать собственные файлы и управлять ими |
+| `files:all` | Просматривать файлы всех пользователей и управлять ими |
+| `apikeys:own` | Создавать собственные ключи API и управлять ими |
+| `apikeys:all` | Просматривать ключи API всех пользователей |
+| `pipelines:own` | Создавать собственные конвейеры и управлять ими |
+| `pipelines:all` | Просматривать конвейеры всех пользователей и управлять ими |
+| `settings:read` | Просматривать настройки экземпляра |
+| `settings:write` | Изменять настройки экземпляра |
+| `users:manage` | Создавать, обновлять и удалять учётные записи пользователей |
+| `teams:manage` | Создавать, обновлять и удалять команды |
+| `features:manage` | Устанавливать наборы функций ИИ и управлять ими |
+| `system:health` | Доступ к конечным точкам health и readiness |
+| `audit:read` | Просматривать журнал аудита и получать список ролей |
+| `compliance:manage` | Управлять жизненным циклом GDPR и функциями комплаенса |
+| `webhooks:manage` | Настраивать исходящие вебхуки |
+| `security:manage` | Управлять настройками безопасности (список разрешённых IP, принудительное SSO) |
+
+## Пользовательские роли {#custom-roles}
+
+Администраторы с разрешением `security:manage` могут создавать пользовательские роли через панель администратора или API ролей. Для получения списка ролей требуется `audit:read`.
+
+### Создание пользовательской роли {#creating-a-custom-role}
+
+```bash
+curl -X POST http://localhost:1349/api/v1/roles \
+  -H "Authorization: Bearer si_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "reviewer",
+    "description": "Can use tools and view all files",
+    "permissions": ["tools:use", "files:own", "files:all", "settings:read"]
+  }'
+```
+
+Имена ролей должны содержать от 2 до 30 символов, строчные буквенно-цифровые символы с дефисами и подчёркиваниями.
+
+### Зарезервированные для администратора разрешения {#admin-reserved-permissions}
+
+Три разрешения зарезервированы для встроенных ролей и не могут быть назначены пользовательским ролям:
+
+- `compliance:manage`
+- `webhooks:manage`
+- `security:manage`
+
+API ролей отклоняет любой запрос, включающий эти разрешения. Доступ к ним есть только у встроенной роли `admin`.
+
+### Разрешения на уровне инструментов {#tool-level-permissions}
+
+Пользовательские роли могут опционально ограничивать, к каким инструментам может обращаться пользователь. Доступны два режима:
+
+| Режим | Поведение | Требование лицензии |
+|---|---|---|
+| `category` | Ограничение по модальности (image, video, audio, document, file) | Нет (бесплатно) |
+| `tool` | Ограничение по идентификатору отдельного инструмента | Требуется корпоративная функция `per_tool_permissions` |
+
+Когда установлен режим `tool`, но корпоративная функция недоступна, SnapOtter деградирует корректно и разрешает доступ ко всем инструментам.
+
+```json
+{
+  "name": "image-only",
+  "permissions": ["tools:use", "files:own"],
+  "toolPermissions": {
+    "mode": "category",
+    "allowed": ["image"]
+  }
+}
+```
+
+### Удаление пользовательской роли {#deleting-a-custom-role}
+
+При удалении пользовательской роли все назначенные ей пользователи автоматически переназначаются на роль `user`.
+
+## Команды {#teams}
+
+Команды группируют пользователей для управления хранилищем и хранением. Команда `Default` создаётся при первом запуске.
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `name` | string | Уникальное имя команды (1–50 символов) |
+| `storageQuota` | number | Лимит хранилища на команду в байтах (работает без enterprise) |
+| `retentionHours` | number | Автоудаление результатов через указанное число часов (требует `team_retention_overrides`, enterprise) |
+| `legalHold` | boolean | Предотвращать автоматическое удаление файлов участников команды (требует `legal_hold`, enterprise) |
+
+::: info 
+Команду `Default` нельзя удалить. Команды, в которых всё ещё есть участники, удалить нельзя. Сначала переназначьте участников.
+:::
+
+## Ключи API {#api-keys}
+
+Пользователи могут генерировать ключи API для программного доступа. Каждый ключ использует префикс `si_` и показывается только один раз при создании.
+
+### Ограниченные по области разрешения {#scoped-permissions}
+
+Ключи API могут опционально нести массив `permissions`. Когда он задан, эффективные разрешения для запроса — это **пересечение** разрешений роли пользователя и ограниченных по области разрешений ключа. Это означает, что ключ API никогда не может выйти за пределы собственных разрешений пользователя.
+
+```bash
+curl -X POST http://localhost:1349/api/v1/api-keys \
+  -H "Authorization: Bearer si_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "CI pipeline key",
+    "permissions": ["tools:use", "files:own"],
+    "expiresAt": "2027-01-01T00:00:00Z"
+  }'
+```
+
+### Истечение срока действия {#expiration}
+
+Ключи принимают опциональную временную метку `expiresAt`. Ключи с истёкшим сроком действия отклоняются во время аутентификации.
+
+## Журнал аудита {#audit-log}
+
+SnapOtter записывает значимые для безопасности события в структурированный журнал аудита, хранящийся в таблице базы данных `audit_log`.
+
+### Просмотр журнала аудита {#viewing-the-audit-log}
+
+```
+GET /api/v1/audit-log?page=1&limit=50&action=LOGIN_FAILED&from=2026-01-01T00:00:00Z&to=2026-12-31T23:59:59Z
+```
+
+Требует разрешение `audit:read`. Поддерживает пагинацию (`page`, `limit`) и фильтры (`action`, `ip`, `from`, `to`).
+
+### Аудит операций с инструментами {#tool-operation-auditing}
+
+::: warning 
+События `TOOL_EXECUTED` **не** журналируются по умолчанию. Они включаются опционально через один из двух путей:
+
+1. Установите значение админ-настройки `auditToolOperations` в `true`.
+2. Держите активную лицензию с функцией `audit_export` (доступна как в плане team, так и в плане enterprise).
+
+Без одного из этих условий отдельные выполнения инструментов не записываются в журнал аудита.
+:::
+
+### Экспорт {#exporting}
+
+```
+GET /api/v1/enterprise/audit/export?format=csv&from=2026-01-01T00:00:00Z
+```
+
+Требует разрешение `audit:read` и корпоративную функцию `audit_export` (доступна как в плане team, так и в плане enterprise). Поддерживает форматы CSV и JSON, с фильтрацией по `action`, `actorId`, `targetType`, `targetId`, `from` и `to`.
+
+### Защищённая от подделки подпись {#tamper-resistant-signing}
+
+Когда включено, каждая запись журнала аудита подписывается HMAC, производным от `DATA_ENCRYPTION_KEY`. Это требует:
+
+1. Установки `DATA_ENCRYPTION_KEY` в вашем окружении.
+2. Включения админ-настройки `tamperResistantAudit`.
+3. Корпоративной лицензии с функцией `tamper_resistant_audit`.
+
+### Хранение {#retention}
+
+Задайте `AUDIT_RETENTION_DAYS` для автоматической очистки старых записей. Значение по умолчанию — `0`, что означает, что записи хранятся бессрочно.
+
+### Справочник по событиям {#event-reference}
+
+| Событие | Категория |
+|---|---|
+| `LOGIN_SUCCESS`, `LOGIN_FAILED` | Аутентификация |
+| `OIDC_LOGIN_SUCCESS`, `OIDC_LOGIN_FAILED` | Аутентификация |
+| `SAML_LOGIN_SUCCESS`, `SAML_LOGIN_FAILED` | Аутентификация |
+| `LOGOUT` | Аутентификация |
+| `USER_CREATED`, `USER_UPDATED`, `USER_DELETED` | Управление пользователями |
+| `PASSWORD_CHANGED`, `PASSWORD_RESET` | Управление пользователями |
+| `MFA_ENROLLED`, `MFA_DISABLED`, `MFA_VERIFIED`, `MFA_VERIFY_FAILED` | MFA |
+| `MFA_CHALLENGE_ISSUED`, `MFA_RECOVERY_USED`, `MFA_RESET` | MFA |
+| `ROLE_CREATED`, `ROLE_UPDATED`, `ROLE_DELETED` | Роли |
+| `API_KEY_CREATED`, `API_KEY_DELETED` | Ключи API |
+| `SETTINGS_UPDATED`, `IP_ALLOWLIST_UPDATED` | Настройки |
+| `FILE_UPLOADED`, `FILE_DELETED` | Файлы |
+| `TOOL_EXECUTED` | Инструменты (опционально) |
+| `SCIM_USER_PROVISIONED`, `SCIM_USER_UPDATED`, `SCIM_USER_DEPROVISIONED` | SCIM |
+| `SCIM_GROUP_SYNCED` | SCIM |
+| `LEGAL_HOLD_APPLIED`, `LEGAL_HOLD_RELEASED` | Комплаенс |
+| `GDPR_EXPORT_INITIATED`, `GDPR_USER_PURGED`, `GDPR_TEAM_PURGED` | Комплаенс |
+| `CONFIG_EXPORTED`, `CONFIG_IMPORTED` | Конфигурация |
+
+## Управление сессиями {#session-management}
+
+Сессии основаны на cookie и контролируются `SESSION_DURATION_HOURS` (по умолчанию: 168 часов / 7 дней).
+
+### Изменение роли аннулирует сессии {#role-changes-invalidate-sessions}
+
+Когда администратор меняет роль пользователя, все активные сессии этого пользователя удаляются. Пользователь должен войти снова, чтобы получить новые разрешения.
+
+### Защитные ограничения {#safety-guards}
+
+- **Защита последнего администратора**: последнего оставшегося администратора нельзя понизить до более низкой роли. API возвращает ошибку при попытке.
+- **Предотвращение самоудаления**: администраторы не могут удалить собственную учётную запись через API.