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

> 一个以 Agent 优先维护理念设计的 Django 多租户 SaaS 启动模板，采用 PostgreSQL 模式隔离实现租户数据完全隔离，集成 DRF、JWT 认证、Docker 开发环境和完整的 CI/CD 工作流。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-06T14:14:39.000Z
- 最近活动: 2026-06-06T14:26:42.149Z
- 热度: 154.8
- 关键词: Django, 多租户, SaaS, PostgreSQL, Schema隔离, django-tenants, JWT, DRF, Docker, Agent工作流
- 页面链接: https://www.zingnex.cn/forum/thread/django-saas-postgresql
- Canonical: https://www.zingnex.cn/forum/thread/django-saas-postgresql
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：mohamedBalkhi
- 来源平台：github
- 原始标题：Django-Multi-Tenant-SaaS-Starter-Template
- 原始链接：https://github.com/mohamedBalkhi/Django-Multi-Tenant-SaaS-Starter-Template
- 来源发布时间/更新时间：2026-06-06T14:14:39Z

## 原作者与来源\n\n- **原作者/维护者**: mohamedBalkhi\n- **来源平台**: GitHub\n- **原始标题**: Django-Multi-Tenant-SaaS-Starter-Template\n- **原始链接**: https://github.com/mohamedBalkhi/Django-Multi-Tenant-SaaS-Starter-Template\n- **发布时间**: 2026年6月6日\n\n---\n\n## 引言：多租户架构的选型困境\n\n当你决定构建一个 SaaS 产品时，第一个需要回答的技术问题就是：**如何隔离不同租户的数据？**\n\n这个问题看似简单，但答案将深刻影响你的架构演进。常见的方案有三种：\n\n**共享数据库 + 租户标识列**：所有租户的数据放在同一个表，通过 `tenant_id` 字段区分。优点是简单，缺点是查询必须带租户过滤，一旦遗漏就是严重的数据泄露。\n\n**独立数据库**：每个租户一个数据库。隔离性最好，但运维成本高，数据库连接池难以管理。\n\n**共享数据库 + 独立模式（Schema）**：租户共享同一个 PostgreSQL 数据库，但每个租户有独立的模式（schema）。这是平衡隔离性和运维复杂度的最佳实践。\n\n本文介绍的 Django Multi-Tenant SaaS Starter 正是基于第三种方案，它不仅仅是一个代码模板，更是一套完整的工程实践，包含了从开发到部署、从测试到维护的全流程设计。\n\n---\n\n## 项目概述：不止于模板\n\n这个项目的独特之处在于它的设计理念——**"Codex-First"**。\n\n传统的启动模板只关注第一次运行的体验：克隆、安装依赖、启动服务。但这个项目更进一步，它将**维护作为一等公民**来对待。\n\n什么是维护作为一等公民？\n\n- 租户安全规则从第一天就定义清楚\n- 验证命令和检查脚本开箱即用\n- Issue 模板和 PR 模板标准化协作流程\n- 文档同步机制确保代码和文档不脱节\n- Agent-ready 的工作流支持 AI 辅助开发\n\n这种设计特别适合团队开发——新成员可以快速理解项目规范，Agent 工具可以安全地执行维护任务。\n\n---\n\n## 核心特性解析\n\n### PostgreSQL 模式隔离\n\n项目使用 `django-tenants` 库实现真正的模式隔离：\n\n```sql\n-- 公共模式存储租户元数据\npublic.tenants\npublic.domains\n\n-- 每个租户有自己的模式\ntenant_1.users\ntenant_1.orders\ntenant_1.products\n\ntenant_2.users\ntenant_2.orders\ntenant_2.products\n```\n\n这种隔离级别意味着：\n\n- 租户 A 的查询永远看不到租户 B 的数据，即使忘记加过滤条件\n- 可以为特定租户单独备份和恢复\n- 支持租户级别的性能优化（索引、分区）\n- 满足大多数企业的数据隔离合规要求\n\n### 租户感知的认证系统\n\n项目内置了完整的 JWT 认证，并且认证是租户感知的：\n\n- 登录时需要指定租户域名\n- JWT Token 中包含租户标识\n- 中间件自动设置当前请求的租户上下文\n- API 自动限制在当前租户的模式内\n\n这意味着你的业务代码可以完全专注于功能实现，无需在每个 API 中手动处理租户过滤。\n\n### Docker 化开发环境\n\n项目提供完整的 Docker Compose 配置：\n\n```bash\n# 一键启动\n./scripts/bootstrap-env.sh\ndocker compose up --build\n\n# 创建演示租户\ndocker compose exec web python manage.py setup_demo\n```\n\n开发环境特性：\n\n- PostgreSQL 运行在独立容器，端口映射到主机的 5433（避免与本地 PostgreSQL 冲突）\n- 热重载支持代码修改自动生效\n- 演示数据生成命令快速创建测试租户\n- 本地开发和容器开发无缝切换\n\n### Agent-Ready 维护工作流\n\n这是项目最具前瞻性的特性。项目根目录的 `AGENTS.md` 定义了：\n\n- **项目地图**：代码组织结构、关键文件位置\n- **安全规则**：哪些操作是安全的、哪些需要人工确认\n- **验证命令**：如何验证修改没有破坏功能\n- **技能触发器**：Agent 可以调用的标准化任务\n\n`.agents/skills/` 目录包含预定义的 Agent 工作流：\n\n- 租户策略检查\n- 文档同步验证\n- 测试覆盖率分析\n- PR 摘要生成\n\n这种设计让 AI 辅助开发从概念走向实践——Agent 不再是黑盒，而是在明确的规则和边界内协助开发。\n\n---\n\n## 架构设计\n\n### 应用结构\n\n```\napps/\n├── tenants/          # 公共模式：租户和域名模型\n├── authentication/   # 租户感知的 JWT 认证\n├── api/              # 示例租户级 API\n└── core/tests/       # 可复用的租户感知测试基类\n\nconfig/\n└── settings/         # 基础、开发、生产配置\n\n.docs/                # 架构文档、测试指南、路线图\n.agents/skills/       # Agent 工作流定义\n.github/              # CI 工作流、Issue/PR 模板\nscripts/              # 验证、引导脚本\n```\n\n### 请求处理流程\n\n```\nHTTP Request\n    ↓\nDomain Middleware (确定租户)\n    ↓\nTenant Context Setup (设置 search_path)\n    ↓\nJWT Authentication (验证 Token)\n    ↓\nTenant-Aware View (业务逻辑)\n    ↓\nTenant-Scoped Query (自动限制在当前模式)\n```\n\n这种设计让租户切换对业务代码完全透明。\n\n---\n\n## 快速上手\n\n### 环境准备\n\n需要安装：\n- Docker 和 Docker Compose\n- Python 3.11+（本地开发可选）\n- Make（可选，用于快捷命令）\n\n### Docker 方式启动\n\n```bash\n# 克隆项目\ngit clone https://github.com/mohamedBalkhi/Django-Multi-Tenant-SaaS-Starter-Template.git\ncd Django-Multi-Tenant-SaaS-Starter-Template\n\n# 引导环境（创建 .env 文件）\n./scripts/bootstrap-env.sh\n\n# 启动服务\ndocker compose up --build\n```\n\n服务启动后：\n- 公共管理后台：`http://localhost:8000/admin/`\n- 租户 API 示例：`http://school1.localhost:8000/api/`\n\n### 本地开发方式\n\n```bash\nmake setup              # 安装依赖\ndocker compose up -d db  # 只启动数据库\nmake migrate           # 执行迁移\nmake demo              # 创建演示数据\nmake run               # 启动开发服务器\n```\n\n注意：本地命令使用 `POSTGRES_HOST=localhost`，Docker 命令使用 `POSTGRES_HOST=db`。\n\n---\n\n## 测试与验证\n\n### 核心检查\n\n```bash\n# Docker 配置检查\ndocker compose config\n\n# Django 系统检查\npython manage.py check\n\n# 运行测试\npytest\n\n# 文档检查\n./scripts/check-docs.sh\n```\n\n### 完整验证\n\n```bash\n./scripts/verify.sh\n```\n\n这个脚本会执行：\n- 代码格式检查（Black、isort）\n- 静态类型检查（mypy）\n- 单元测试\n- 集成测试\n- 文档同步检查\n- 安全扫描（bandit）\n\n### 租户感知测试\n\n项目提供了 `TenantAPITestCase` 基类，让测试自动处理租户上下文：\n\n```python\nfrom apps.core.tests import TenantAPITestCase\n\nclass ItemAPITests(TenantAPITestCase):\n    def test_list_items(self):\n        # 自动在测试租户上下文中运行\n        response = self.client.get('/api/items/')\n        self.assertEqual(response.status_code, 200)\n```\n\n---\n\n## CI/CD 集成\n\n项目包含完整的 GitHub Actions 工作流：\n\n### PR 检查\n\n每次 PR 自动执行：\n- 代码风格检查\n- 类型检查\n- 测试套件\n- 覆盖率报告\n- 文档同步验证\n\n### 部署工作流\n\n主分支合并后自动：\n- 构建 Docker 镜像\n- 推送镜像到仓库\n- 触发部署（需要配置）\n\n### Issue 管理\n\n预配置的 Issue 模板：\n- Bug 报告\n- 功能请求\n- 租户相关问题\n- 安全漏洞报告\n\n标签清单（labels manifest）标准化了分类体系。\n\n---\n\n## Agent 工作流详解\n\n### AGENTS.md 结构\n\n```markdown\n# AGENTS.md\n\n## 项目地图\n- 关键文件位置\n- 架构决策记录\n- 依赖关系图\n\n## 安全规则\n- 允许的操作（绿色清单）\n- 需要确认的操作（黄色清单）\n- 禁止的操作（红色清单）\n\n## 验证命令\n- 如何验证修改有效\n- 回滚策略\n\n## 技能触发器\n- /check-tenants：验证租户配置\n- /sync-docs：同步文档\n- /coverage：分析测试覆盖\n```\n\n### 示例：Agent 执行安全的数据库迁移\n\n```\n用户：需要给 orders 表添加一个 status 字段\n\nAgent：\n1. 读取 AGENTS.md 确认迁移是允许的操作\n2. 生成迁移文件\n3. 执行 ./scripts/verify.sh 验证\n4. 如果验证通过，提交 PR\n5. 如果验证失败，报告错误并停止\n```\n\n这种设计让 Agent 在明确的边界内工作，既发挥了 AI 的自动化能力，又保留了人类对关键决策的控制。\n\n---\n\n## 适用场景\n\n### 何时选择这个模板？\n\n1. **B2B SaaS**：需要为每个企业客户提供独立数据空间\n2. **教育平台**：学校/机构级别的数据隔离\n3. **医疗系统**：患者数据必须严格隔离\n4. **金融应用**：合规要求数据隔离\n5. **白标产品**：同一套代码服务多个品牌\n\n### 何时不适合？\n\n1. **C2C 产品**：用户之间需要大量交互（如社交网络）\n2. **超大规模**：租户数量超过 PostgreSQL 模式限制\n3. **跨租户分析**：需要频繁跨租户聚合数据\n\n---\n\n## 路线图与展望\n\n项目 v0.2.0 的重点是 Codex-First 维护基础：\n\n- [x] AGENTS.md 和项目文档\n- [x] Repo-local Agent 技能\n- [x] CI/CD 工作流\n- [x] Issue/PR 模板\n- [ ] 更多示例应用（CRM、项目管理）\n- [ ] Kubernetes 部署配置\n- [ ] 监控和告警集成\n- [ ] 多区域部署支持\n\n---\n\n## 总结\n\nDjango Multi-Tenant SaaS Starter 不只是一个代码模板，而是一套完整的工程实践。它解决了多租户架构中最棘手的问题：\n\n1. **数据隔离**：PostgreSQL 模式隔离提供真正的数据边界\n2. **开发体验**：Docker 化环境让新成员快速上手\n3. **代码质量**：完整的测试和验证体系\n4. **协作效率**：Agent-ready 设计让 AI 辅助成为现实\n5. **长期维护**：文档同步和标准化流程\n\n对于正在规划 SaaS 架构的团队，这个项目提供了一个经过深思熟虑的起点。它不仅让你快速启动，更重要的是让你能够持续地、安全地、高效地维护这个产品。\n\n如果你正在寻找一种既安全又实用的多租户方案，这个模板值得深入研究。