300 lines
12 KiB
Markdown
300 lines
12 KiB
Markdown
# GVSDS · 多租户 SAAS 管理平台
|
||
|
||
> GVS Distributed System — 基于 Django + gevent 的企业级 SAAS 框架，配套分布式 SDK 与多模板前端。
|
||
|
||
---
|
||
|
||
## ⚠️ 重要声明 · IMPORTANT
|
||
|
||
> **本仓库为 GVSDS 平台生产环境核心代码，不允许在本地或非授权环境中部署运行。**
|
||
|
||
- 🚫 **禁止本地部署**：本仓库代码仅供**已授权的运维人员**通过内部部署系统在受控环境中运行
|
||
- 🚫 **禁止私自 clone 后跑通**：任何 `python Main.py` / `gunicorn` / `python manage.py runserver` 的本地启动行为均属违规
|
||
- 🚫 **禁止公开演示/截图/录屏**：核心业务逻辑、特权流程、数据库结构、API 设计不得外传
|
||
- ✅ **允许的用途**：阅读源码学习架构、参与授权下的代码审查、提交合规的 PR
|
||
- ✅ **如需调试**：请联系平台运维团队申请**独立的测试沙盒环境**
|
||
|
||
违规者将依据《服务协议》追究责任。
|
||
|
||
---
|
||
|
||
## 一、项目定位⚠️ 重要声明 · IMPORTANT
|
||
|
||
> **本仓库为 GVSDS 平台生产环境核心代码，不允许在本地或非授权环境中部署运行。**
|
||
|
||
- 🚫 **禁止本地部署**：本仓库代码仅供**已授权的运维人员**通过内部部署系统在受控环境中运行
|
||
- 🚫 **禁止私自 clone 后跑通**：任何 `python Main.py` / `gunicorn` / `python manage.py runserver` 的本地启动行为均属违规
|
||
- 🚫 **禁止公开演示/截图/录屏**：核心业务逻辑、特权流程、数据库结构、API 设计不得外传
|
||
- ✅ **允许的用途**：阅读源码学习架构、参与授权下的代码审查、提交合规的 PR
|
||
- ✅ **如需调试**：请联系平台运维团队申请**独立的测试沙盒环境**
|
||
|
||
违规者将依据《GVSDS 平台使用协议》追究责任。
|
||
|
||
---
|
||
|
||
## 一、项目定位
|
||
|
||
GVSDS 是面向中小企业的多租户企业管理平台，核心能力：
|
||
|
||
- **多租户 SAAS 框架**：租户入驻、审核、数据隔离（公司 / 部门 / 工作组 / 商铺 四级）
|
||
- **企业资源管理（GERP）**：组织、角色、权限、菜单、工单、文件资产、文档
|
||
- **三大业务引擎**：分佣引擎（Commission）、支付网关（Payment）、分布式事务（Transaction）
|
||
- **分布式通信底座（MSYNC）**：服务注册 / 发现 / 跨服务调用
|
||
- **多模板前端**：GERP / CCCRB / AKS / MSOC / librok 等多套站点
|
||
- **多域名部署**：单一进程同时服务 `gvsds.com / gvsds.org / gvsds.dev / gvsds.studio / yc8z.org / ycbz.org / librok.gvsds.com` 等多个域名
|
||
|
||
详细架构说明参见 [SAAS_ARCHITECTURE.md](./SAAS_ARCHITECTURE.md)。
|
||
|
||
---
|
||
|
||
## 二、技术栈
|
||
|
||
| 层 | 技术 |
|
||
|---|---|
|
||
| **后端框架** | Django 4.2+ / DRF / SimpleJWT |
|
||
| **WSGI 服务器** | gevent + pywsgi（单进程多协程）/ Gunicorn 兼容 |
|
||
| **异步任务** | Celery + Redis（可降级同步执行） |
|
||
| **实时通信** | python-socketio |
|
||
| **数据库** | MySQL 5.7+（7 库分库路由） |
|
||
| **缓存 / 锁** | Redis（可降级 locmem） |
|
||
| **安全** | bcrypt / AES-256-GCM / JWT / 自研 IP 过滤 + 攻击检测 |
|
||
| **前端** | 原生 HTML / JS + 自研 NeoUI / GERPUI 组件 + Tailwind |
|
||
| **反向代理** | Nginx |
|
||
|
||
---
|
||
|
||
## 三、目录结构
|
||
|
||
```
|
||
d:\SMANAGE\
|
||
├── Main.py # WSGI 入口（gevent 启动 + 域名路由 + 中间件链）
|
||
├── manage.py # Django 命令行
|
||
├── gvsds/ # 主服务器（Django 项目）
|
||
│ ├── settings.py # 全局配置
|
||
│ ├── urls.py # 路由聚合
|
||
│ ├── auth.py # CustomJWTAuthentication
|
||
│ ├── middleware.py # 6 个自定义中间件
|
||
│ ├── db_router.py # 分库路由器
|
||
│ └── apps/ # 14 个业务 App
|
||
│ ├── core/ # 用户/认证基础设施
|
||
│ ├── gerp/ # ERP 主模块（FormAPI / CheckAdmin / 角色权限）
|
||
│ ├── ugm/ # 用户管理
|
||
│ ├── crb/ # 货币钱包/企业
|
||
│ ├── invite/ # 邀请码
|
||
│ ├── ccgo/ # 协同办公
|
||
│ ├── sve/ # 工单
|
||
│ ├── t4/ # T4 计划
|
||
│ ├── mc/ # 我的世界
|
||
│ ├── doc/ # 文档
|
||
│ ├── api/ # API 网关
|
||
│ ├── msync/ # 分布式通信
|
||
│ ├── payment/ # 支付
|
||
│ ├── commission/ # 分佣
|
||
│ └── stats/ # 统计
|
||
├── gvsdsdk/ # 分布式 SDK / 通用 SAAS 服务层
|
||
│ ├── auth/ # 认证与权限（RoleManager/AuthManager/AdminUserManager 等 17 个 Manager）
|
||
│ ├── msync/ # 服务注册/发现
|
||
│ ├── commission/ # 分佣引擎
|
||
│ ├── payment/ # 支付网关
|
||
│ ├── order/ # 订单
|
||
│ ├── stats/ # 统计引擎
|
||
│ └── management/ # 管理工具
|
||
├── ATestCServer/ # 子服务器示例（通过 SDK 接入主服务）
|
||
├── TempLate/ # 前端模板与静态资源
|
||
│ ├── GERP/ # ERP 主前端（pages/ + assets/ + DbTableHelper）
|
||
│ ├── CCCRB/ # 货币钱包前端
|
||
│ ├── AKS/ MSOC/ ... # 其他模板
|
||
│ ├── rok/lib/ # 静态资源库（librok.gvsds.com）
|
||
│ └── Errors/ # 错误页（404 / 反盗链）
|
||
├── SSL/ # SSL 证书
|
||
├── nginx/ # Nginx 配置
|
||
├── deploy/ # 部署脚本
|
||
├── logs/ # 运行日志
|
||
├── secrets.ini # 数据库/Redis 凭据（不入库）
|
||
├── gunicorn.conf.py # Gunicorn 配置
|
||
└── app.ini # 应用配置
|
||
```
|
||
|
||
---
|
||
|
||
## 四、核心架构
|
||
|
||
### 4.1 双包架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────┐
|
||
│ d:\SMANAGE（项目根） │
|
||
│ │
|
||
│ ┌────────────────────┐ ┌────────────────────┐ │
|
||
│ │ gvsds │ │ gvsdsdk │ │
|
||
│ │ 主服务器（业务层）│◄─┤ 分布式 SDK │ │
|
||
│ │ - Django 项目 │ │ - 协议契约层 │ │
|
||
│ │ - 14 个业务 App │ │ - 惰性加载 │ │
|
||
│ │ - 完整业务实现 │ │ - PascalCase 协议 │ │
|
||
│ └────────────────────┘ └────────────────────┘ │
|
||
│ ▲ ▲ │
|
||
│ ┌────────────────────┐ ┌────────────────────┐ │
|
||
│ │ ATestCServer │ │ TempLate/ │ │
|
||
│ │ 子服务器示例 │ │ 前端模板资源 │ │
|
||
│ │ 通过 SDK 接入 │ │ GERP/AKS/MSOC... │ │
|
||
│ └────────────────────┘ └────────────────────┘ │
|
||
└──────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.2 SAAS 多租户四层架构
|
||
|
||
```
|
||
第 4 层 鉴权规则层 RBAC 操作权限 + ABAC 数据权限（RoleScope）
|
||
第 3 层 角色权限载体层 Role + UserRole + RolePermission
|
||
第 2 层 岗位模板层 PositionTemplate → CopyToRole（一次性快照）
|
||
第 1 层 组织人事层 Tenant → Company → Department / Workgroup
|
||
UserDept（员工-部门多对多）+ Position（标签）
|
||
```
|
||
|
||
### 4.3 权限模型（角色超级管理员标记）
|
||
|
||
特权级采用**角色级**标记而非用户级 `IsSuperuser`：
|
||
|
||
- `admin:super`（跨租户超级管理员，最高）
|
||
- `admin:tenant`（租户内管理员）
|
||
- 权限码查询走 `RolePermission → Permission`
|
||
- 详见 [gvsdsdk/auth/admin_service.py](./gvsdsdk/auth/admin_service.py)
|
||
|
||
### 4.4 分库路由（7 库）
|
||
|
||
`Users` / `GerpCore` / `Plans` / `Tasks` / `T4PC` / `Document` / `Minecraft`，由 `gvsds/db_router.py` 路由。
|
||
|
||
---
|
||
|
||
## 五、多域名与静态站点
|
||
|
||
`Main.py` 内置域名路由：
|
||
|
||
| 域名 | 用途 |
|
||
|---|---|
|
||
| `gvsds.com / www.gvsds.com / api.gvsds.com` | 主站 + API |
|
||
| `gvsds.dev` / `gvsds.studio` | 备用主域 |
|
||
| `gvsds.org` | 主域别名 |
|
||
| `yc8z.org` / `ycbz.org` | 镜像站 |
|
||
| `librok.gvsds.com` | 静态站点（`TempLate/rok/lib/`） |
|
||
|
||
新增静态站点：在 `Main.py` 的 `STATIC_SITES` 字典中添加 `host → Path` 映射。
|
||
|
||
---
|
||
|
||
## 六、严禁本地部署
|
||
|
||
> **再次强调：本仓库为平台生产环境核心代码，不允许本地部署。**
|
||
|
||
### 1. 禁止行为
|
||
|
||
- ❌ 任何个人或团队成员**不得**在本地（开发机、笔记本、虚拟机）clone 后启动 `Main.py` / `gunicorn` / `python manage.py runserver`
|
||
- ❌ 不得使用本地 MySQL / Redis 模拟生产环境"试跑"
|
||
- ❌ 不得在公网演示环境部署本仓库代码
|
||
- ❌ 不得将本仓库代码上传至 GitHub / GitLab / Gitee 等任何公开平台
|
||
|
||
### 2. 允许的运行方式
|
||
|
||
- ✅ **仅**通过内部部署系统（`deploy/` 目录脚本 + Ansible / SaltStack）部署到**已审批的生产服务器**
|
||
- ✅ 部署目标服务器需满足：
|
||
- 内网 IP，不暴露公网
|
||
- 防火墙白名单限定运维来源 IP
|
||
- 与生产数据库主从同步
|
||
- 启用审计日志（`logs/` 实时收集）
|
||
- ✅ 沙盒调试需向运维团队申请**独立的测试沙盒环境**（与生产数据完全隔离）
|
||
|
||
### 3. 违规处理
|
||
|
||
- 首次违规：警告 + 撤销代码访问权限 7 天
|
||
- 二次违规：撤销代码访问权限 30 天 + 通报
|
||
- 三次违规：依据《GVSDS 平台使用协议》追究法律责任
|
||
|
||
### 4. 如何申请部署 / 调试
|
||
|
||
1. 通过企业微信联系 **平台运维团队**
|
||
2. 提交申请单（用途 / 环境 / 时段 / 审批人）
|
||
3. 审批通过后由运维团队协助完成
|
||
|
||
---
|
||
|
||
## 七、API 与 SDK
|
||
|
||
### 7.1 REST API
|
||
|
||
- 路由前缀：`/API/<AppName>/<Action>/<Resource>`
|
||
- 鉴权：JWT（HttpOnly Cookie）+ `admin_verify=1` 特权模式
|
||
- 核心 API：
|
||
- `/API/FormAPI/CheckAdmin` — 权限查询
|
||
- `/API/FormAPI/Get/<Table>` — 列表查询（带 company_scope / tenant_scope）
|
||
- `/API/FormAPI/Add/Modify/Delete/<Table>` — 增改删
|
||
|
||
### 7.2 SDK 使用（子服务器）
|
||
|
||
```python
|
||
# 子服务器通过 gvsdsdk 接入主服务
|
||
from gvsdsdk.auth.admin_service import IsAdmin, IsSuperAdmin
|
||
from gvsdsdk.commission.engine import CommissionEngine
|
||
from gvsdsdk.msync.client import MSyncClient
|
||
|
||
# 权限判断（统一走角色级 admin:super / admin:tenant 标记）
|
||
if IsSuperAdmin(request):
|
||
# 跨租户超级管理员逻辑
|
||
...
|
||
|
||
# 注册到主服务
|
||
client = MSyncClient('sub-server-01', version='1.0.0')
|
||
client.register()
|
||
```
|
||
|
||
---
|
||
|
||
## 八、命名与代码规范
|
||
|
||
- **类名 / 模型字段**：PascalCase（`UserName`, `RoleUUID`, `CurrentRoleUUID`）
|
||
- **函数 / 变量**：snake_case（`get_user_role`, `current_role_uuid`）
|
||
- **常量**：UPPER_SNAKE（`WHITE_HOSTS`, `STATIC_SITES`）
|
||
- **文件名**：业务模块小写、Python 类用 PascalCase
|
||
- **DB 字段**：所有 UUID 字段以 `UUID` 后缀，类型 `BINARY(16)`
|
||
- **前端**：Tailwind utility-first + 自研 GERPUI 组件
|
||
- 详见 [SAAS_ARCHITECTURE.md](./SAAS_ARCHITECTURE.md)
|
||
|
||
---
|
||
|
||
## 九、部署
|
||
|
||
### 9.1 目录约定
|
||
|
||
- `deploy/` — 部署脚本
|
||
- `nginx/` — 反向代理配置
|
||
- `gunicorn.conf.py` — Gunicorn worker / 超时 / 绑定
|
||
- `SSL/` — 证书（生产用 Let's Encrypt / 商业证书）
|
||
|
||
### 9.2 启动顺序
|
||
|
||
1. MySQL / Redis
|
||
2. 启动 `Main.py`（或 Gunicorn）
|
||
3. Nginx 反向代理 `127.0.0.1:<port>` → HTTPS
|
||
4. 防火墙放行 80/443
|
||
|
||
### 9.3 日志
|
||
|
||
- `logs/` — 应用日志
|
||
- 控制台：彩色输出（`colorama`）
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- [SAAS_ARCHITECTURE.md](./SAAS_ARCHITECTURE.md) — 完整 SAAS 架构与数据模型
|
||
- [gvsdsdk/INSTALL.md](./gvsdsdk/INSTALL.md) — SDK 安装与使用
|
||
- [gvsdsdk/API.md](./gvsdsdk/API.md) — SDK API 参考
|
||
- [BENAME.MD](./BENAME.MD) — 重命名与版本变更日志
|
||
|
||
---
|
||
|
||
## 十一、许可证与联系
|
||
|
||
- 项目所有者：GVSDS Team
|
||
- 内部仓库，不对外开放
|
||
- 问题反馈：通过 Issue / 企业微信群
|