Подробно
Мультитенантный SaaS: группы, роли и проверка прав в Postgres
Опубликовано · 5 мин чтения· Anton Shubin
Другие языки: العربية, Deutsch, English, Español, Français, 日本語, Português (Brasil) и 简体中文

Коротко
- В Seed клиент (тенант) — это группа. В каждой строке есть group_id, а доступ человека — одна строка в group_members с ролью от 1 до 4.
- Кто что может — набор маленьких чистых функций. Каждый обработчик читает роль и вызывает нужную; WebSocket и HTTP используют одни и те же обработчики.
- Каждая запись перечитывает роль в своей транзакции под блокировкой, так что участник, удалённый мгновение назад, не успеет сделать последнюю запись.
- Row-level security нет. Чужой получает 404, а не 403, и тесты проверяют, что одна группа никогда не видит данных другой.
Как построить мультитенантный SaaS на Postgres, чтобы одна команда никогда не увидела данные
другой? В Seed тенант — это группа. В каждой строке, принадлежащей тенанту, есть group_id,
доступ человека — одна строка в group_members с ролью, и каждый запрос проверяет эту роль в коде,
прежде чем читать или писать. Запись проверяет её дважды: в обработчике и ещё раз внутри своей
транзакции, под блокировкой. Одна общая база, одна схема, без row-level security.
Статья для разработчиков командного продукта, которым нужен целый работающий ответ, а не схема на доске. Всё это есть в коде Seed под лицензией MIT, а фрагменты ниже — настоящие строки, слегка сокращённые.
Что такое тенант в Seed?
Группа. Отдельного «личного» вида нет: регистрация создаёт обычную группу «Personal», где вы единственный участник. Поэтому один пользователь и команда из 50 человек проходят через один и тот же код, и ничего не нужно переносить, когда одиночка приглашает коллегу. Человек может состоять в скольких угодно группах.
Членство — одна таблица (миграция):
CREATE TABLE group_members (
group_id UUID NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
user_id INT4 NOT NULL REFERENCES users(id) ON DELETE CASCADE,
role INT2 NOT NULL,
...
PRIMARY KEY (group_id, user_id),
CONSTRAINT group_members_role_check CHECK (role BETWEEN 1 AND 4)
);
Два правила держит сам Postgres: роль от 1 до 4, а частичный уникальный индекс разрешает ровно
одного владельца на группу. Передача владения сначала понижает старого владельца, потом повышает
нового, в одной транзакции, потому что индекс не допустит двух владельцев даже на мгновение. У
каждой строки фичи (заметки, тега, файла) свой столбец group_id.
Какие есть роли и что может каждая?
Четыре, фиксированные и упорядоченные: viewer (1), editor (2), admin (3), owner (4). Благодаря
порядку большинство правил — одно сравнение: «editor и выше» значит role >= 2.
| Что | Viewer | Editor | Admin | Owner |
|---|---|---|---|---|
| Читать заметки группы | да | да | да | да |
| Создавать, править и удалять заметки | нет | да | да | да |
| Приглашать людей как viewer или editor | нет | нет | да | да |
| Переименовать группу, видеть почту участников | нет | нет | да | да |
| Назначить кого-то admin | нет | нет | нет | да |
| Платить, удалить группу, передать владение | нет | нет | нет | да |
Admin управляет viewer и editor, но не другим admin, и владельца не трогает никто, кроме него самого. На плане Free приглашение добавляет только viewer: другие роли — то, за что платят в Pro. Ниже расскажу, как план и роль не смешиваются.
Где живёт проверка прав?
В маленьких чистых функциях доменной библиотеки, по одной на вопрос
(libs/domain/groups).
Самая сложная — кто может менять чью роль — и самая длинная:
export function canManageMember(actor: GroupRole, target: GroupRole, next?: GroupRole): boolean {
if (!isGroupRole(actor) || !isGroupRole(target) || (next !== undefined && !isGroupRole(next))) {
return false
}
if (actor === GroupRole.OWNER) return true
if (actor !== GroupRole.ADMIN || target > GroupRole.EDITOR) return false
return next === undefined || next <= GroupRole.EDITOR
}
Ни базы, ни запроса, ни фреймворка: юнит-тест вызывает её со всеми сочетаниями ролей. Обработчик читает роль и передаёт её в нужную проверку до обращения к репозиторию:
assertCanWriteNotes(await groups.roleOf(data.groupId, data.actor.userId))
В транспорте правил нет вовсе. Вызов приходит по WebSocket или как POST /api/call/<name>, оба
попадают в один обработчик и получают один ответ. Поэтому
реалтайм может откатиться на HTTP без второго
набора проверок, который надо держать в согласии с первым.
Зачем проверять роль дважды?
Потому что роль, прочитанная до записи, к моменту коммита может устареть. Представьте: владелец удаляет редактора в тот же миг, когда редактор сохраняет заметку. Обработчик миллисекунду назад прочитал «editor», удаление коммитится, и заметка попадает в группу, где автора уже нет.
Поэтому каждая запись в группу сначала вызывает lockActorRole внутри своей транзакции
(group-change-log.ts):
const active = await sql`
SELECT 1 FROM groups WHERE id = ${groupId} AND deleted_at IS NULL FOR NO KEY UPDATE
`
if (active.length === 0) throw new GroupNotActiveError(groupId)
const member = (await sql`
SELECT group_members.role
FROM group_members
INNER JOIN users ON users.id = group_members.user_id AND users.deleted_at IS NULL
WHERE group_members.group_id = ${groupId} AND group_members.user_id = ${actorId}
FOR SHARE OF group_members
`)[0]
return member?.role ?? null
Строка группы блокируется первой, в том же порядке, что и при любом изменении состава, поэтому
две операции ждут друг друга, а не попадают в дедлок. Строка членства читается FOR SHARE:
удаление, закоммиченное раньше, будет видно, а пришедшее позже подождёт, пока запись закончится.
Затем репозиторий проверяет полученную роль, так что вторая проверка стоит одного чтения по индексу
в транзакции, которая и так открыта.
Тест доказывает это для каждого вида записи заметки: он держит удаление или понижение открытым,
запускает запись, видит, что она ждёт, коммитит изменение и ожидает отказ без сохранённых данных
(«note update: refused when a removal commits while the write waits» в
tests/integration/group-write-race.integration.test.ts).
Почему чужой получает 404, а не 403?
Потому что 403 говорит: «группа есть, но вам нельзя». Тот, кто не состоит в группе, получает
GROUP_NOT_FOUND — ровно то же, что для группы, которой не существует, поэтому перебором id нельзя
узнать, какие группы настоящие. Участник без нужной роли получает 403 ROLE_INSUFFICIENT: о группе
он и так знает.
Похожее правило и для плана. Когда группа упирается в лимит плана, ответ — 402 Payment Required, а не 403, чтобы приложение отличало «попросите владельца перейти на Pro» от «у вас нет роли». Роль решает, кто может действовать; план — сколько группе положено. Про оплату мест и её вебхуки есть отдельная статья.
Почему не row-level security в Postgres?
Я её рассматривал и записал компромисс в дизайне синхронизации групп. Row-level security положила бы вторую копию правил доступа в базу, в SQL-политики, рядом с копией, которая всё равно нужна обработчикам, чтобы ответить понятной ошибкой «вы viewer». Две копии одного правила рано или поздно расходятся. Кроме того, каждому соединению пришлось бы нести текущего пользователя, а это усложняет пул соединений, фоновые задачи и миграции.
Честная цена: при фильтрах в коде приложения один запрос, забывший group_id, может раскрыть
данные. Seed отвечает на это тремя способами:
- Сигнатуры с группой. Метод репозитория принимает id группы аргументом, например
get(groupId, id), и запрос фильтрует по обоим. Метода «получить заметку по id», которым можно ошибиться, просто нет. - Один чек-лист для каждой фичи. docs/aggregates.md перечисляет правила,
которые копирует новая фича: она живёт в группе, в каждой строке есть
group_id, каждая запись перечитывает роль. - Тесты между группами. Интеграционные тесты работают с настоящим Postgres и посторонним человеком в его собственной группе, в шагах вроде «never counts a note of another group» и «a person who is not a member is told the group does not exist».
Если вашему продукту нужна гарантия на уровне базы, скажем, для аудита соответствия, row-level security — разумный выбор, и её можно добавить поверх. Для стартового шаблона я выбрал одно место для правил.
Чего Seed не делает?
- Своих ролей нет. Четыре фиксированные. Продукту, которому нужен «менеджер по оплате», придётся добавить роль и её проверки.
- Прав на отдельную запись нет. Роль действует на всю группу; поделиться одной заметкой с одним человеком нельзя.
- Row-level security нет, как сказано выше.
- Отдельной схемы или базы на тенанта нет. Все группы делят одни таблицы.
Попробуйте
Откройте демо, создайте группу, пригласите второй аккаунт как viewer и попробуйте из него изменить заметку. Коротко — на странице групп, а статья о первой фиче показывает, как новый вид записей получает всё это, копируя код заметок. Если ваше приложение проверяет роль один раз, до транзакции, — эту гонку я бы закрыл первой.


