Django 多租户 SaaS 启动模板：基于 PostgreSQL 模式隔离的企业级架构实践

本文介绍的Django Multi-Tenant SaaS启动模板基于PostgreSQL模式隔离实现租户数据完全隔离，集成DRF、JWT认证、Docker开发环境和完整CI/CD工作流。其设计理念为"Codex-First"，将维护作为一等公民，支持Agent辅助开发，适合团队快速构建安全合规的企业级SaaS产品。

构建SaaS产品时需解决租户数据隔离问题，常见方案有三种：1.共享数据库+租户标识列（简单但易漏过滤导致数据泄露）；2.独立数据库（隔离性好但运维成本高）；3.共享数据库+独立模式（Schema）（平衡隔离性与运维复杂度）。本模板选择第三种方案，基于PostgreSQL模式隔离实现。

1. PostgreSQL模式隔离：使用django-tenants库，公共模式存租户元数据（如public.tenants），每个租户有独立模式（如tenant_1.users）；2.租户感知JWT认证：登录需指定租户域名，Token含租户标识，中间件自动设置上下文；3.Docker化开发：提供Compose配置，一键启动（./scripts/bootstrap-env.sh + docker compose up）；4.应用结构：apps/tenants（公共模式模型）、apps/authentication（JWT认证）、config/settings（环境配置）等；5.请求流程：Domain Middleware确定租户→设置上下文→JWT验证→业务逻辑→租户范围查询。

1.测试：提供TenantAPITestCase基类，自动处理租户上下文；2.验证脚本：./scripts/verify.sh执行代码格式检查、类型检查、单元测试、文档同步检查等；3.CI/CD：GitHub Actions工作流自动执行PR检查（代码风格、测试等）和主分支部署；4.标准化协作：预配置Issue模板（Bug报告、功能请求等）和PR模板。

模板支持Agent辅助开发，核心为AGENTS.md文件（含项目地图、安全规则、验证命令、技能触发器）和.agents/skills目录（预定义工作流如租户策略检查）。示例Agent工作流：用户需添加orders表status字段→Agent读取AGENTS.md确认允许→生成迁移→执行验证→提交PR（验证通过）或报告错误（失败）。

适用场景：B2B SaaS、教育平台（学校数据隔离）、医疗系统（患者数据隔离）、金融应用（合规要求）、白标产品。不适用场景：C2C产品（用户交互多）、超大规模租户（超过PostgreSQL模式限制）、跨租户分析（频繁聚合数据）。路线图v0.2.0：已完成AGENTS.md、CI/CD、Issue模板；计划添加更多示例应用、Kubernetes部署、监控告警、多区域支持。

本模板不仅是代码模板，更是完整工程实践，解决多租户架构核心问题：数据隔离（PostgreSQL模式）、开发体验（Docker环境）、代码质量（测试验证）、协作效率（Agent-ready）、长期维护（文档同步）。建议正在规划SaaS架构的团队深入研究此模板，作为安全实用的起点。