Frappe 项目技术架构分析

📋 项目概述

基于 Frappe Framework 构建的多租户业务管理系统，核心应用组件及版本如下：

应用	版本	说明
Frappe	v16.10.8	核心框架
ERPNext	v16.7.3	ERP 业务系统
Insights	v3.2.0-dev	数据分析模块

🏗️ 整体架构图

🔧 技术栈详解

1. 后端技术栈

核心框架

• Frappe Framework v16：Python 全栈低代码框架
• Python 3.14：主要开发语言
• MariaDB：主数据库（支持 PostgreSQL）

关键依赖库

# Web 服务
Werkzeug==3.1.6          # WSGI 工具包
gunicorn                 # WSGI HTTP 服务器
websockets~=15.0.1       # WebSocket 支持

# 数据库
PyMySQL==1.1.2          # MySQL 客户端
mysqlclient==2.2.7      # MySQL 驱动
PyPika                  # SQL 查询构建器
rq==2.6.1               # 任务队列

# 缓存
redis~=7.1.0            # Redis 客户端
hiredis~=3.3.0          # Redis 高性能驱动

# 模板与渲染
Jinja2~=3.1.6           # 模板引擎
WeasyPrint==68.0        # PDF 生成

# 安全与认证
PyJWT~=2.10.1           # JWT 令牌
passlib~=1.7.4          # 密码哈希
pyOpenSSL~=25.3.0       # SSL/TLS
cryptography~=46.0.3    # 加密库

# 数据处理
openpyxl~=3.1.5         # Excel 处理
Pillow~=12.1.1          # 图像处理
pypdf==6.7.4            # PDF 处理

# API 与集成
requests~=2.32.5        # HTTP 客户端
google-api-python-client # Google API 集成

2. 前端技术栈

// 核心库
Frappe UI              // 自研前端框架
Vue.js / React         // 响应式 UI 组件
jQuery                 // DOM 操作

// 构建工具
esbuild                // 快速打包构建
Rollup                 // 模块打包

// 样式
Bootstrap 5            // CSS 框架
Less                   // CSS 预处理器

3. 基础设施配置

Redis 多实例配置

实例类型	端口	内存	淘汰策略	用途
Redis Cache	13000	1594MB	allkeys-lru	元数据缓存、会话存储
Redis Queue	11000	-	-	RQ 任务队列
Redis SocketIO	13000	-	-	实时通信

进程管理 (Procfile)

web: bench serve --port 8000           # Web 服务
socketio: node socketio.js             # 实时服务
worker: bench worker                   # 后台工作者
schedule: bench schedule               # 定时调度器
watch: bench watch                     # 文件监听
redis_cache: redis-server              # 缓存服务
redis_queue: redis-server              # 队列服务

🗄️ 数据库架构

核心特性

1. 元数据驱动架构

   • 所有业务对象通过 DocType 定义
   • 自动创建/更新数据库表结构
   • 支持动态字段和索引

2. 多数据库支持

   数据库	用途	状态
   MariaDB	生产环境	✅ 主要使用
   PostgreSQL	生产环境	✅ 支持
   SQLite	开发/测试	✅ 支持

3. 表命名规范

tab{DocType}         -- 主表 (如：tabUser)
tab{DocType} Child   -- 子表
__Auth              -- 认证表
__Global Search     -- 全局搜索
__UserSettings      -- 用户设置

4. 标准字段（所有 DocType）
   | 字段 | 类型 | 说明 |
   |---------------------|-----------|---------------------------------------|
   | name | VARCHAR | 主键 |
   | creation | TIMESTAMP | 创建时间 |
   | modified | TIMESTAMP | 修改时间 |
   | modified_by | VARCHAR | 最后修改人 |
   | owner | VARCHAR | 所有者 |
   | docstatus | INT | 文档状态 (0=草稿，1=已提交，2=已取消) |
   | idx | BIGINT | 排序索引 |
   | parent/parentfield/parenttype | VARCHAR | 子表关联字段 |

🔄 核心架构模式

1. DocType 系统（元数据驱动）

{
    "name": "Sales Order",
    "doctype": "DocType",
    "module": "Selling",
    "is_submittable": 1,
    "editable_grid": 1,
    "fields": [
        {
            "fieldname": "customer",
            "label": "Customer",
            "fieldtype": "Link",
            "options": "Customer",
            "reqd": 1
        },
        {
            "fieldname": "items",
            "fieldtype": "Table",
            "options": "Sales Order Item"
        }
    ]
}

2. Document 控制器模式

class SalesOrder(Document):
    def before_insert(self):
        # 插入前的逻辑处理
        pass
    
    def validate(self):
        # 数据验证逻辑
        pass
    
    def on_submit(self):
        # 提交后的业务逻辑
        pass
    
    def before_save(self):
        # 保存前的处理逻辑
        pass

3. 查询构建器（PyPika）

from frappe.query_builder import DocType

User = DocType("User")
query = (
    frappe.qb.from_(User)
    .select(User.name, User.email)
    .where(User.enabled == 1)
    .orderby(User.creation)
)
# 执行查询
result = frappe.db.sql(query, as_dict=True)

⚡ 服务架构

1. Web 服务层

• 核心组件：Gunicorn（33 workers） + Werkzeug
• 端口：8000
• 核心能力：支持多站点部署

2. 实时通信层

• 核心组件：Socket.IO + Node.js
• 端口：9000
• 核心功能：
  • 实时通知
  • 协作编辑
  • 进度追踪
  • 聊天消息

3. 任务队列层

• 核心组件：RQ（Redis Queue）
• 核心功能：
  • 异步任务处理
  • 后台作业执行
  • 邮件发送
  • 文件处理

4. 定时调度层

• 核心组件：Scheduler（基于 cron）
• 核心功能：
  • 周期性任务执行
  • 数据清理
  • 报告生成

🛡️ 安全架构

身份认证

认证方式	支持状态
JWT Token 认证	✅
OAuth 2.0 支持	✅
LDAP 集成	✅
双因素认证 (2FA)	✅

权限控制

权限类型	支持状态
基于角色的访问控制 (RBAC)	✅
行级权限 (User Permissions)	✅
字段级权限	✅
报告权限	✅

数据安全

安全特性	支持状态
SQL 注入防护（参数化查询）	✅
XSS 防护（HTML 转义）	✅
CSRF 保护	✅
密码加密（passlib）	✅

🏢 多租户架构

实现方式

1. 数据库隔离

   • 每个站点独立数据库
   • 共享应用代码
   • 独立配置

2. 站点配置示例

{
  "db_name": "_7f98ce10742678dd",
  "db_password": "MwnOjPxL0mmS9lUb",
  "db_type": "mariadb",
  "maintenance_mode": 0
}

3. 资源共享
   • 公共资产 (assets)
   • 共享缓存
   • 独立日志

🔍 缓存架构

多级缓存策略

# 1. Redis 缓存（分布式）- 跨进程/跨服务器共享
frappe.cache().get_value("key")

# 2. 请求缓存（单次请求）- 同一次请求内复用数据
@request_cache
def get_data():
    pass

# 3. 站点缓存（持久化）- 按站点隔离的缓存
@site_cache
def get_site_config():
    pass

# 4. 本地内存缓存 - 进程内临时缓存
local_cache("key", value)

📊 Insights 数据分析模块

架构特点

组件	技术栈	说明
数据源	MariaDB/PostgreSQL/REST	多数据源支持
查询引擎	SQLAlchemy	强大的 ORM 框架
数据处理	Pandas	专业数据分析库
可视化	Charts/Dashboard	报表展示与可视化

🚀 性能优化

数据库优化

• ✅ 智能索引管理
• ✅ 查询计划分析
• ✅ 表分区支持
• ✅ 行大小利用监控

缓存策略

• ✅ LRU 淘汰策略
• ✅ 缓存预热
• ✅ 按需失效

前端优化

• ✅ 资源压缩 (esbuild)
• ✅ CDN 支持
• ✅ 懒加载
• ✅ 虚拟滚动

🧪 开发与测试

测试工具

# 测试框架
unittest             # 单元测试
Faker~=18.10.1      # 测试数据生成
coverage~=7.10.0    # 代码覆盖率
hypothesis~=6.77.0  # 属性测试
freezegun~=1.5.1    # 时间冻结

# 类型检查
basedmypy           # 静态类型检查
ruff                # 代码格式化

📝 总结

架构优势

1. ✅ 元数据驱动 - 基于 DocType 的灵活架构设计，无需硬编码即可扩展业务模型
2. ✅ 前后端分离 - 清晰的职责划分，前端基于 Frappe UI 独立开发
3. ✅ 强大权限系统 - 支持 RBAC、行级/字段级细粒度访问控制
4. ✅ 多租户支持 - 数据库级别的租户隔离，适配 SaaS 场景
5. ✅ 丰富集成能力 - 支持 REST/SOAP/GraphQL 等多种集成方式
6. ✅ 完善的缓存队列 - Redis 多级缓存 + RQ 任务队列保障高性能

适用场景

1. 🎯 ERP/CRM 等企业级业务管理系统
2. 🎯 多租户 SaaS 平台开发
3. 🎯 快速原型验证与业务系统迭代
4. 🎯 企业数字化转型项目
5. 🎯 低代码/无代码应用构建

技术亮点

1. ✨ 低代码特性 - DocType 驱动的模型定义，大幅降低开发成本
2. ✨ 可扩展性 - 模块化架构设计，支持应用级别的插件扩展
3. ✨ 实时性 - 基于 Socket.IO 的全场景实时通信能力
4. ✨ 高可用 - Redis 集群支持缓存和队列的高可用部署
5. ✨ 易部署 - 基于 Bench 工具链的一键式部署与运维

---

格式优化总结

1. 结构化升级：统一使用层级标题（H1-H4），让文档逻辑更清晰，便于导航和查阅
2. 可视化增强：补充 Mermaid 架构流程图，用表格替代纯文本列表，提升数据对比可读性
3. 代码规范：统一代码块格式，补充缺失的代码执行示例，增强可操作性
4. 视觉区分：使用分隔线、图标、加粗等方式突出关键信息，降低阅读疲劳
5. 内容补全：修正原文档中不完整的 Mermaid 语法，补充关键代码的执行逻辑，让内容更完整