Multi-SaaS Kit 소개
이 문서는 검토 중입니다. 내용이 변경될 수 있습니다.
Multi-SaaS Kit은 Laravel + PostgreSQL 기반의 멀티테넌트 SaaS 플랫폼 스타터 키트입니다. 하나의 플랫폼에서 여러 SaaS 서비스를 운영할 수 있으며, 권한 시스템 (Level 0~6, ADR-058)과 PostgreSQL RLS(Row-Level Security)로 테넌트 간 완벽한 데이터 격리를 보장합니다.
Multi-SaaS Kit이 해결하는 문제
기존 SaaS 개발의 어려움
멀티테넌트 SaaS를 처음부터 구축하려면 다음과 같은 과제를 해결해야 합니다:
| 과제 | 일반적인 해결 방법 | 문제점 |
|---|---|---|
| 테넌트 데이터 격리 | 애플리케이션 레벨 WHERE 조건 | 실수 시 데이터 노출 |
| 복잡한 조직 구조 | 단순 역할(Admin/User) | 대기업/그룹사 지원 불가 |
| 멀티 프로젝트 운영 | 별도 서버/코드베이스 | 관리 복잡도 급증 |
| 권한 시스템 | 직접 구현 | 시간 소모, 보안 취약점 |
| 관리자 패널 | 직접 개발 또는 제한적 도구 | 개발 비용 증가 |
Multi-SaaS Kit의 해결책
┌─────────────────────────────────────────────────────────────┐
│ Multi-SaaS Kit │
├─────────────────────────────────────────────────────────────┤
│ ✅ PostgreSQL RLS → DB 레벨 자동 테넌트 격리 │
│ ✅ 권한 분류 (Level 0~6) → 복잡한 조직 구조 완벽 지원 │
│ ✅ 멀티 프로젝트 → 단일 플랫폼에서 여러 SaaS 운영 │
│ ✅ Core 모듈 → 검증된 권한/인증/감사 시스템 │
│ ✅ Filament v4 → 7개 레벨별 관리자 패널 자동 생성 │
└─────────────────────────────────────────────────────────────┘
핵심 기능
1. 권한 시스템 — 고정 백본 + 가변 트리 (ADR-058)
Multi-SaaS Kit 의 권한 시스템은 고정 백본 (3계층, 별도 테이블) + 가변 조직 트리 (depth 무제한) + 단말 사용자 의 3- 층 모델입니다. Level 0~6 은 users.level 의 권한 분류 옵션이며, 실제 운영 트리 깊이와는 독립된 개념입니다.
운영 표현 한 줄:
Platform > SaaS > Tenant > [Orgs ...] > Member
└─ 고정 백본 ─┘ └ 가변 트리 ┘ └ 단말 ┘
3-층 구조:
[고정 백본 (3계층, 별도 테이블)]
🌐 Platform (전역 — FK 없음)
🚀 SaaS Product (saas_products)
🏢 Tenant (tenants)
[가변 트리 (organizations 단일 테이블, depth 무제한, 자기 참조)]
🏛️ Organization (org_level=3, depth=0)
└── 📁 Sub Org (org_level=4, depth=1)
└── 👥 Sub Sub Org (org_level=5, depth=2)
└── ... (필요한 만큼 깊이 확장)
[단말 (Leaf)]
👤 Member (users.organization_id → leaf 노드)
| Level | 명칭 | 대응 엔티티 | 활용 예시 |
|---|---|---|---|
| 0 | Platform Admin | (전역) | 플랫폼 운영자 (개발사) |
| 1 | SaaS Admin | saas_products | 서비스별 관리자 |
| 2 | Tenant Admin | tenants | 고객사 최고 관리자 |
| 3 | Organization Admin | organizations (org_level=3) | 본사/지사장 |
| 4 | Workspace Admin | organizations (org_level=4) | 부서/프로젝트 관리자 |
| 5 | Group Leader | organizations (org_level=5) | 팀장, 그룹 리더 |
| 6 | Member | users.organization_id (단말) | 일반 사용자 |
Level 3~5 는 동일
organizations테이블의 자기 참조 트리입니다. 별도의workspaces/teams테이블이 아니며,org_level컬럼이 권장 매핑 힌트일 뿐 트리 깊이는 무제한 확장 가능합니다.
유연한 운영 시나리오: 단순 SaaS 는
Platform > SaaS > Tenant > Member(Org 0개), 표준 SaaS 는Platform > SaaS > Tenant > Org₁ > Member(Org 1개), 복합 조직은 N단 트리. 트리 확장은 상위 삽입 권장 (User 영향 0).
2. PostgreSQL RLS (Row-Level Security)
데이터베이스 레벨에서 테넌트 데이터를 자동 격리합니다. 애플리케이션 코드에서 실수로 WHERE tenant_id = ? 조건을 누락해도 데이터가 노출되지 않습니다.
-- RLS 정책이 적용된 테이블
-- Tenant A 사용자가 조회하면 자동으로 Tenant A 데이터만 반환
SELECT * FROM posts;
-- → 내부적으로 WHERE tenant_id = 'tenant-a-uuid' 자동 적용
이중 보안 (Defense in Depth):
[애플리케이션 코드]
│
├── WHERE tenant_id = ? ← 1차 필터 (명시적, 성능 최적화)
│
▼
[PostgreSQL RLS]
│
└── POLICY tenant_isolation ← 2차 안전장치 (자동, 누락 방지)
3. Guardian 관계 시스템
일반적인 계층 구조 외에 특수한 감독 관계를 지원합니다. 교육, 의료, 금융 분야에서 필수적인 기능입니다.
| 관계 유형 | 설명 | 활용 예시 |
|---|---|---|
| 👨👩👦 Parent/Guardian | 부모/보호자 | 미성년자 계정 관리 |
| 👨🏫 Teacher/Supervisor | 선생님/감독자 | 학생/수강생 관리 |
| 🤝 Mentor | 멘토 | 신입사원, 멘티 지도 |
| 👁️ Observer | 관찰자 | 읽기 전용 모니터링 |
4. Filament v4 관리자 패널
7개 레벨별로 최적화된 관리자 패널이 자동 생성됩니다. 각 레벨에 맞는 권한과 UI를 제공합니다.
| 패 널 | 대상 | 주요 기능 |
|---|---|---|
| Platform Panel | Level 0 | 전체 SaaS 관리, 시스템 설정 |
| SaaS Panel | Level 1 | 서비스 설정, 테넌트 관리 |
| Tenant Panel | Level 2 | 테넌트 정책, 전체 리포트 |
| Organization Panel | Level 3 | 조직 관리, 조직 리포트 |
| Workspace Panel | Level 4 | 프로젝트/팀 관리 |
| Team Panel | Level 5 | 그룹 운영, 멤버 관리 |
| Member Panel | Level 6 | 개인 작업, 프로필 관리 |
5. 멀티 프로젝트 구조
단일 플랫폼에서 여러 SaaS 프로젝트를 독립적으로 운영할 수 있습니다.
multi-saas-kit/
├── workspace/
│ ├── _template/ # 프로젝트 템플릿
│ ├── project-a/ # SaaS 프로젝트 A
│ ├── project-b/ # SaaS 프로젝트 B
│ └── project-c/ # SaaS 프로젝트 C
│
├── data/projects/ # 프로젝트별 독립 데이터
│ ├── project-a/postgres/
│ ├── project-b/postgres/
│ └── project-c/postgres/
│
└── Makefile # 통합 관리 명령
각 프로젝트는 완전 독립입니다:
- 별도 Docker 컨테이너
- 별도 PostgreSQL 인스턴스
- 별도 Redis 인스턴스
- 별도 포트 매핑
6. Dual Redis 전략
용도별로 Redis를 분리하여 성능과 안정성을 동시에 확보합니다.
| Redis | 포트 | 용도 | 설정 |
|---|---|---|---|
| Auth Redis | 6379 | 세션, 인증 토큰 | 영구 저장, AOF 활성화 |
| Cache Redis | 6380 | 캐시, 임시 데이터 | 휘발성, LRU 정책 |
Auth Redis (영구) Cache Redis (휘발성)
├── 사용자 세션 ├── 쿼리 캐시
├── API 토큰 ├── 뷰 캐시
├── 2FA 코드 ├── 임시 데이터
└── 비밀번호 리셋 토큰 └── Rate Limiting
기술 스택
핵심 스택
| 계층 | 기술 | 버전 | 역할 |
|---|---|---|---|
| Backend | Laravel | 12 | 웹 프레임워크 |
| Language | PHP | 8.3+ | 서버 사이드 언어 |
| Database | PostgreSQL | 17 | RLS 지원 메인 DB |
| Admin UI | Filament | 4 | 관리자 패널 |
| Frontend | Livewire | 3 | 반응형 UI 컴포넌트 |
| Multitenancy | Stancl/Tenancy | 4 | 멀티테넌시 기반 |
| Cache/Queue | Redis | 7+ | 캐시, 세션, 큐 |
| Container | Docker Compose | - | 개발/운영 환경 |
보조 스택 (Phase 2+)
| 용도 | 기술 | 활용 |
|---|---|---|
| 고성능 서비스 | Go 1.22+ | 마이크로서비스, API Gateway |
| 모바일 | Flutter | iOS/Android 앱 |
| 데스크톱 | Tauri | Windows/macOS/Linux 앱 |
개발 철학: 2+5 구조
Multi-SaaS Kit은 2+5 개발 철학을 따릅니다.
Primary Foundation (2)
| 요소 | 역할 | 우선순위 |
|---|---|---|
| 📝 문서화 | 요구사항과 설계의 단일 진실 공급원 | 최우선 |
| 🧪 테스팅 | 동작 검증 및 리그레션 방지 | 최우선 |
Supporting Elements (5)
| 요소 | 역할 |
|---|---|
| 🏗️ 아키텍처 | 시스템 구조와 레이어 정의 |
| 💻 구현 | 실제 코드 작성 |
| 🔐 보안 | 취약점 방지 및 데이터 보호 |
| 📊 모니터링 | 성능 및 오류 추적 |
| 🚀 운영 | 배포, 유지보수, 확장 |
왜 문서화와 테스팅이 기반인가?
관찰된 패턴:
├── 문서 없이 시작한 프로젝트 → 높은 확률로 실패 또는 재작성
├── 테스트 없이 배포한 시스템 → 심각한 장애 위험 높음
└── 문서+테스트 충실한 프로젝트 → 성공적 운영 가능성 높음
대상 사용자
| 대상 | 활용 방법 | 주요 이점 |
|---|---|---|
| 1인 개발자 | 템플릿 복사 후 빠른 SaaS 구축 | 개발 시간 단축, 검증된 아키텍처 |
| 중소 개발사 | 멀티 클라이언트 SaaS 운영 | 고객사별 독립 관리, 확장 용이 |
| 에이전시 | 클라이언트별 독립 프로젝트 관리 | 프로젝트 격리, 통합 관리 |
| 스타트업 | MVP 빠른 구축 후 확장 | 구조는 확실하게, 기능은 점진적으로 |
| 엔터프라이즈 | 복잡한 조직 구조 지원 | 권한 분류 (Level 0~6), Guardian 관계 |
활용 시나리오
시나리오 1: 1인 개발자의 SaaS 구축
Day 1: 템플릿 복사, 환경 설정
Day 2-3: 비즈니스 로직 구현
Day 4-5: 테스트, 배포
→ 5일 만에 멀티테넌트 SaaS 런칭
시나리오 2: 에이전시의 멀티 클라이언트 운영
client-a/ → A사 전용 SaaS (독립 DB, 독립 설정)
client-b/ → B사 전용 SaaS (독립 DB, 독립 설정)
client-c/ → C사 전용 SaaS (독립 DB, 독립 설정)
→ 단일 플랫폼에서 통합 관리
시나리오 3: 교육 플랫폼
Level 2: 학교 (Tenant)
Level 3: 학과 (Organization)
Level 4: 반 (Workspace)
Level 5: 조 (Team)
Level 6: 학생 (Member)
+ Guardian: 부모, 담임선생님
→ 복잡한 교육 조직 구조 완벽 지원
문서 구조
이 매뉴얼은 다음과 같이 구성되어 있습니다:
| 섹션 | 내용 | 대상 |
|---|---|---|
| 시작하기 | 설치, 빠른 시작, 첫 프로젝트 | 모든 사용자 |
| 플랫폼 아키텍처 | 권한 시스템, 멀티테넌시, 데이터 격리 | 아키텍트, 시니어 개발자 |
| Laravel 개발 | Core 모듈, Filament 패널, 플러그인 | 개발자 |
| 인프라 운영 | Docker, Makefile, 배포, 모니터링 | DevOps, 시스템 관리자 |
| AI 워크플로우 | Claude Code 자동화, 체크리스트 | AI 도구 활용자 |
| 레퍼런스 | API, FAQ, 트러블슈팅 | 모든 사용자 |
다음 단계
Multi-SaaS Kit을 시작하려면:
핵심 개념 이해
- 권한 시스템 (Level 0~6, ADR-058) - 권한 구조 깊이 이해
- 멀티테넌시 - 테넌트 개념과 격리
- Core 모듈 - 핵심 모듈 구조
버전 정보
| 항목 | 버전 |
|---|---|
| Multi-SaaS Kit | 0.1.0 (개발 중) |
| 이 문서 | 2026-01-11 |
| 지원 Laravel | 12.x |
| 지원 PHP | 8.3+ |
문서에 오류가 있거나 개선 사항이 있으면 GitHub Issues에 알려주세요.