Перейти к содержимому

Подробно

Мультитенантный SaaS: группы, роли и проверка прав в Postgres

Опубликовано · 5 мин чтения·

Другие языки: العربية, 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 и попробуйте из него изменить заметку. Коротко — на странице групп, а статья о первой фиче показывает, как новый вид записей получает всё это, копируя код заметок. Если ваше приложение проверяет роль один раз, до транзакции, — эту гонку я бы закрыл первой.

Следующий пост — на почту

Короткое письмо, когда выходит новый пост или что-то запускается. Подписка подтверждается один раз по почте, отписаться можно в один клик.

Все посты