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

DocPlatform использует ролевую модель доступа (RBAC) на базе Casbin — авторизационного движка, работающего в рамках процесса. Проверка прав выполняется менее чем за 0.1 мс без обращения к внешним сервисам.

Иерархия ролей

DocPlatform определяет 5 публичных ролей в строгой иерархии. Более высокие роли наследуют все права более низких.

Super Admin         ← Full platform access (all workspaces)
    │
Admin               ← Manage workspace settings, git config, theme
    │
Editor              ← Создание и редактирование страниц (настраивается для каждого workspace)
    │
Commenter           ← View pages, leave comments
    │
Viewer              ← View pages only

Platform Owner — внутренняя роль для операторов самостоятельно размещённых экземпляров, предназначенная для обслуживания платформы (миграции базы данных, управление лицензиями, конфигурация системы). Она не отображается в интерфейсе или API и не входит в публичную иерархию ролей.

Матрица прав

Настраиваемые права редактора

Возможности редактора можно настроить для каждого workspace. Администраторы и Super Admin настраивают их в настройках workspace:

Когда разрешение отключено, редакторы видят действие неактивным в интерфейсе и получают 403 Forbidden от API.

Назначение ролей

Первый пользователь (Super Admin)

Первый пользователь, зарегистрировавшийся на новом экземпляре DocPlatform, автоматически получает роль Super Admin. Это происходит только один раз — последующие регистрации не получают роли в workspace до приглашения.

Super Admin является владельцем организации и создателем аккаунта. Он имеет полный контроль над всеми workspaces, биллингом, подключениями git и приглашениями внешних пользователей.

Приглашение внешних пользователей

Только Super Admin может приглашать внешних пользователей в организацию:

Веб-интерфейс: Org Settings -> Members -> Invite External User

API:

curl -X POST http://localhost:3000/api/v1/org/invitations \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "default_role": "editor"
  }'

Приглашённый пользователь присоединяется к организации и затем может быть назначен в workspaces любым администратором или Super Admin.

Назначение участников в workspace

Администраторы назначают существующих участников организации в свой workspace. Администраторы не могут приглашать внешних пользователей — это может делать только Super Admin.

Веб-интерфейс: Workspace Settings -> Members -> Add Member -> выберите из участников организации -> выберите роль

API:

curl -X POST http://localhost:3000/api/v1/workspaces/:id/members \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "01HY5K3M7Q8P",
    "role": "editor"
  }'

Роль по умолчанию

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

# .docplatform/config.yaml
permissions:
  default_role: viewer

Доступные значения: viewer, commenter, editor, admin

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

Переопределяйте права на уровне workspace для отдельных страниц с помощью frontmatter. Правила доступа во frontmatter ограничивают в рамках роли пользователя — они никогда не предоставляют права сверх роли.

Синтаксис контроля доступа

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

---
title: Internal Security Policy
access:
  roles: ["security-team", "engineering-leads"]
  users: ["@01HY5K3M7Q8P"]
---

Правила:

• Используйте префикс @ для идентификаторов пользователей
• Super Admin и Admin всегда имеют доступ независимо от правил frontmatter
• Frontmatter может только ограничивать — страница не может предоставить доступ сверх роли пользователя в workspace

Примеры

Публичная страница (по умолчанию — все участники workspace могут просматривать):

---
title: Getting Started
---

Ограничена для определённых команд:

---
title: Infrastructure Runbook
access:
  roles: ["security-team", "sre-team"]
---

Ограничена с доступом для отдельного пользователя:

---
title: Budget Proposal
access:
  roles: ["finance-team"]
  users: ["@01HY5K3M7Q8P"]
---

Что означает ограниченный доступ

Когда страница имеет правила access:

• Пользователи без необходимой роли не могут просматривать страницу
• Страница не отображается в результатах поиска для неавторизованных пользователей
• Прямой доступ по URL возвращает 403 Forbidden

Доступ к опубликованной документации

Для опубликованного сайта документации (/p/{slug}/...) контроль доступа работает иначе:

• Все опубликованные страницы публичны по умолчанию — вход не требуется
• Чтобы требовать вход для всего опубликованного сайта, установите PUBLISH_REQUIRE_AUTH=true — это применяется ко всем страницам во всех workspaces
• Контроль доступа для отдельных страниц в опубликованной документации (например, ограничение одной страницы только для workspace, пока остальные публичны) запланирован на будущие версии

В v0.5 поле access во frontmatter сохраняется и доступно для будущего использования, но не применяется на публичных маршрутах. Используйте PUBLISH_REQUIRE_AUTH для ограничения доступа ко всему сайту.

Внутренние уровни ролей

Для справки, каждая роль соответствует числовому уровню. Более высокие уровни наследуют все права более низких:

Super Admin — это роль уровня организации — она полностью обходит проверки прав workspace, а не имеет числовой уровень. Platform Owner — это булевый флаг на записи пользователя, обходящий все проверки глобально.

Действия имеют минимальные уровни: read требует уровень 10+, comment требует 20+, edit требует 30+, write/delete требует 40+ (Редакторы получают edit, но не write/delete, если настраиваемые флаги не включены), admin требует 40+. Уровень роли пользователя сравнивается с минимальным уровнем действия.

Как оцениваются права

API Request
    │
    ▼
Auth Middleware
(extract JWT, identify user)
    │
    ▼
Permission Middleware
(Casbin check: user + role + resource + action)
    │
    ├── Allowed → proceed to handler
    │
    └── Denied → 403 Forbidden

5-шаговый процесс оценки

1. Является ли пользователь Platform Owner? → РАЗРЕШИТЬ (глобальный обход)
2. Является ли пользователь Org Super Admin для организации этого workspace? → РАЗРЕШИТЬ (обход на уровне организации)
3. Найти роль пользователя в workspace → если не участник, ОТКАЗАТЬ
4. Достигает ли уровень роли минимума для действия? → сравнить role_level >= action_min_level, плюс флаги прав редактора
5. Есть ли у страницы правила доступа во frontmatter? → проверить access.roles/access.users, ОГРАНИЧИТЬ в рамках роли

Frontmatter ОГРАНИЧИВАЕТ в рамках роли, никогда не ПРЕДОСТАВЛЯЕТ сверх неё. Некорректный frontmatter по умолчанию переводит страницу в строгий режим — доступ ограничен только для Admin.

Производительность

Кэширование прав

Политики Casbin загружаются из SQLite в память при запуске сервера. Изменения ролей или объявлений доступа во frontmatter вызывают инвалидацию кэша:

1. Администратор меняет роль пользователя -> версия кэша прав увеличивается
2. Редактор обновляет frontmatter страницы с новыми правилами access -> кэш инвалидируется для этой страницы
3. Следующая проверка прав загружает актуальную политику из SQLite

Кэш версионный, а не временной — окно устаревших прав отсутствует.

Распространенные паттерны

Публичная документация с ограниченными внутренними страницами

# Большинство страниц: без правил доступа (открыты для всех участников workspace)

# Внутренние страницы: ограничены
---
title: Incident Response Playbook
access:
  roles: ["sre-team", "admin"]
---

Редактор создает, администратор публикует

1. Установите publishing.default_published: false в конфигурации workspace
2. Редакторы создают и редактируют страницы (неопубликованные по умолчанию)
3. Администраторы проверяют и переключают published: true

Workspaces для отдельных команд

Создайте отдельные workspaces для каждой команды с независимыми списками участников:

• Workspace eng-docs -> инженерная команда
• Workspace product-docs -> продуктовая команда
• Workspace internal-wiki -> все сотрудники

Super Admin имеет доступ ко всем workspaces для межкомандной видимости.

Планы и лимиты мест

Подсчёт мест

Роли Super Admin, Admin и Editor учитываются в лимите мест max_editors плана. Роли Commenter и Viewer не ограничены во всех планах и никогда не учитываются в лимите мест.

Когда лимит мест достигнут, новых участников организации по-прежнему можно приглашать, но им можно назначить только роли Commenter или Viewer, пока место не освободится.

Community Edition

Community Edition — бесплатная и самостоятельно размещаемая, лицензионный ключ не требуется:

Облачные планы

Нужно больше? Свяжитесь с отделом продаж для Enterprise-планов с настраиваемыми лимитами, SSO и SLA.

Подробнее о биллинге смотрите в разделе Биллинг и планы.

Устранение неполадок

“403 Forbidden” на странице, к которой должен быть доступ

1. Проверьте свою роль: Profile -> Workspace Membership
2. Проверьте frontmatter страницы: включает ли access.roles вашу роль?
3. Попросите администратора workspace проверить назначение вашей роли
4. Если вы редактор, проверьте, требует ли действие включения editor_can_create_pages или editor_can_delete_pages

Изменения прав не вступают в силу

Изменения прав должны быть мгновенными (инвалидация кэша синхронна). Если нет:

1. Выйдите и войдите заново (обновите JWT-токены)
2. Проверьте логи сервера на ошибки инвалидации кэша
3. Выполните docplatform doctor для проверки состояния системы прав

Первый пользователь не является Super Admin

Это происходит, если первый пользователь регистрируется, когда база данных уже содержит записи пользователей (например, от предыдущей установки). Для исправления:

1. Остановите сервер
2. Удалите базу данных: rm {DATA_DIR}/data.db
3. Запустите сервер и зарегистрируйтесь заново

Это сбрасывает все данные. Используйте только на новых установках.

«Достигнут лимит мест» при приглашении участника

Достигнут лимит max_editors плана. Варианты:

1. Понизьте существующего Admin или Editor до Commenter или Viewer, чтобы освободить место
2. Пригласите нового пользователя как Commenter или Viewer (они не ограничены)
3. Обновите план для увеличения количества мест