Skip to content

核心能力 ​

MengStack v2.0 基于真实源码整理,涵盖框架提供的全部企业级基础设施。

多租户系统 ​

两种运行模式 ​

模式说明配置值
多租户从 X-Tenant-ID 请求头解析租户multi
单租户使用默认租户 UUID,忽略请求头single
yaml
# configs/config.yaml
tenant:
  mode: multi
  default_id: "00000000-0000-0000-0000-000000000001"

数据隔离机制 ​

通过 GORM Scope 在查询层强制隔离:

go
// kernel/tenant/scope.go
func Scope(tenantID string) func(db *gorm.DB) *gorm.DB {
    return func(db *gorm.DB) *gorm.DB {
        if tenantID == "" {
            return db.Where("1 = 0")  // 空租户返回空集
        }
        return db.Where("tenant_id = ?", tenantID)
    }
}

每个实体嵌入 TenantID 字段,作为复合主键的一部分:

go
// kernel/model/base.go
type BaseModel struct {
    ID        uint           `gorm:"primaryKey"`
    TenantID  string         `gorm:"type:uuid;not null;index;primaryKey"`
    CreatedAt time.Time
    UpdatedAt time.Time
    DeletedAt gorm.DeletedAt `gorm:"index"`
    CreatorID uint
}

租户上下文传播 ​

请求进入 → MultiTenant 中间件 → 解析 X-Tenant-ID
  → tenant.WithTenantID(ctx, id) 写入 context.Context
  → Handler 通过 tenant.FromContext(ctx) 读取
  → Repository 通过 tenant.Scope(id) 过滤查询

JWT 认证中间件同样从 Token Claims 中提取 TenantID 写入上下文,下游无需重复解析。

插件系统 ​

Plugin 接口 ​

每个插件实现 6 个方法:

go
// kernel/plugin/plugin.go
type Plugin interface {
    Metadata() Metadata
    Permissions() Permissions
    FxOption() fx.Option
    SetupRoutes(engine *gin.Engine, authMW gin.HandlerFunc,
                tenantResolver tenant.Resolver,
                requirePerm RequirePermissionFunc)
    Init() error
    MigrationsFS() fs.FS
}

当前注册的 25+ 个插件(含 example 示例) ​

权威清单见 api/plugins.yaml(bundled 顺序即挂载顺序,example 标 kernel: true 属内核)。下表为首批 10 款内置插件;生态线收编的 publish-site / seo-multisite / bidding / market-data / daily-report / mail / business-calendar / tools / subscribe / marketplace 等持续增加中。

插件版本功能
example0.1.0示例插件,演示开发模式
cms0.5.0文章、版本、频道、分类、标签
comment-interaction0.1.0评论、点赞、收藏、举报、分享、统计
topic0.1.0专题管理
flash0.1.0快讯/快讯分类
community0.1.0论坛板块、帖子、回复
search0.2.0全文搜索、搜索建议、热词
seo0.3.1TDK、站点地图、robots、重定向、内链
media1.1.0上传流水线、分片上传、图片样式、审核、配额、回收站
author0.1.0入驻申请、作者画像、等级体系、公开作者页

六维权限沙箱 ​

每个插件声明所需权限,运行时由 Sandbox 强制执行:

go
// kernel/plugin/sandbox.go
type Permissions struct {
    Database   []string  // 允许访问的表名
    Storage    bool      // 是否允许文件存储
    Network    []string  // 允许访问的域名
    Events     []string  // 允许发布的事件
    Routes     []string  // 允许注册的路由(支持 /* 通配)
    AdminPanel bool      // 是否允许管理面板
}

沙箱提供 6 个检查方法:

方法作用
CheckDatabase(plugin, table)表级数据库访问控制
CheckStorage(plugin)文件存储访问控制
CheckNetwork(plugin, domain)域名白名单网络控制
CheckEvent(plugin, event)事件发布控制
CheckRoute(plugin, path)路由注册验证
CheckAdminPanel(plugin)管理面板访问控制

SafeInit 和 SafeSetupRoutes 使用 defer recover() 包裹插件调用,单个插件崩溃不会影响整个进程。

.mengplugin 打包格式 ​

go
// kernel/plugin/manifest.go
type Manifest struct {
    ID, Name, Version, Description string
    Author Author
    Type ManifestType  // backend / frontend / theme / hook / mcp_tool
    MinHostVersion, MaxHostVersion string
    Permissions Permissions
    Dependencies []Dependency
    Entry Entry  // Binary, Config, Migrate 路径
}

EventBus 事件总线 ​

同步 + 异步双模式 ​

go
// kernel/eventbus/bus.go
bus.Publish(ctx, envelope)       // 同步发布
bus.PublishAsync(ctx, envelope)  // 异步发布(缓冲通道,容量 1024)
bus.SafePublish(ctx, pluginName, event, permChecker)  // 沙箱检查后发布

异步处理架构 ​

PublishAsync → 缓冲通道(1024) → 4 Workers 并发消费
                                    ↓
                              Handler(ctx, envelope)

Envelope 携带完整上下文:

go
type Envelope struct {
    Event      Event
    PluginName string
    UserID     uint
    TenantID   string
}

启动时通过 bus.StartWorkers(4) 开启 4 个 goroutine 消费异步队列。

WebSocket Hub ​

16 分片架构 ​

go
// kernel/websocket/hub.go
type Hub struct {
    shards [16]*hubShard  // 消除单锁瓶颈
    log    *zap.Logger
    stop   chan struct{}
}

使用 splitmix64 哈希将用户分配到分片,支持 10K+ 并发连接。

核心 API ​

方法说明
SendToUser(userID, msg)向指定用户推送消息
Broadcast(msg)全量广播
PushTo(userID, data)推送原始字节
PushMany(userIDs, data)批量推送(自动分片)
IsOnline(userID)查询在线状态
OnlineUsers()获取在线用户列表
ConnectedCount()获取连接总数

在线状态钩子 ​

当用户连接数从 0→1 触发 onOnline,从 1→0 触发 onOffline。

认证与授权 ​

JWT 双 Token ​

Token默认有效期用途
Access Token30 分钟API 请求鉴权
Refresh Token7 天刷新 Access Token
  • 算法:HS256(HMAC-SHA256),通过 jwt.WithValidMethods([]string{"HS256"}) 强制
  • Refresh Token 轮转:SHA-256 指纹存储在 Redis rt:{tenantID}:{userID}
  • 密码哈希:bcrypt cost 12
  • 防枚举:未知邮箱执行 dummy bcrypt 比较,保持恒定时间

RBAC 权限模型 ​

用户 (User) ←多对多→ 角色 (Role) ←多对多→ 权限 (Permission)

系统预置 3 个角色(每租户自动种子):

角色权限范围
super_admin全部权限
tenant_admin除 rbac.role.write、rbac.permission.assign、rbac.user_role.write 外的全部权限
member只读权限(auth.user.read、dashboard.read、各模块 .read)

系统角色(IsSystem: true)不可修改或删除。共种子 60+ 个权限(权威清单见 rbac/infrastructure/seed.go 的 defaultPermissions),覆盖 auth、rbac、org、audit、settings、notification、dashboard、menu、user 等核心模块及全部已注册插件模块。

Snowflake ID 生成器 ​

go
// kernel/id/snowflake.go
// 自定义纪元:2025-01-01 (1735689600000)
// 10 机器位 (0-1023) + 12 序列位 (0-4095)
// 时钟回拨保护

全局单例,通过 id.Next() / id.NextString() 获取。启动时自动初始化。

中间件链 ​

所有请求按以下顺序经过 9 层中间件:

序号中间件作用
1RequestID生成/透传 X-Request-ID(UUID)
2RequestLogger结构化日志(状态、方法、路径、IP、耗时、trace_id)
3SecurityHeadersX-Content-Type-Options、X-Frame-Options DENY、CSP、HSTS 等
4CharsetUTF8强制 JSON 写入 UTF-8
5CORS可配置源/方法/头,release 模式禁止通配符 *
6AcceptLanguagei18n 语言协商
7RateLimitRedisRedis 滑动窗口限流(三级:匿名 100/min、认证 100/min、管理 500/min)
8BodyLimit请求体上限 10MB
9Recoverypanic 恢复 + 结构化日志

限流返回 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 响应头。

任务调度 ​

go
// kernel/jobs/scheduler.go(基于 gocron/v2)
scheduler.AddIntervalJob(interval, fn)  // 间隔任务
scheduler.AddCronJob(expr, fn)          // Cron 表达式
scheduler.AddOneShotJob(time, fn)       // 一次性任务

每个任务运行时有 5 分钟 context 超时保护。

文件存储 ​

go
// kernel/storage/store.go
type Store interface {
    Upload(ctx, filename, reader) (url, error)
    Delete(ctx, filename) error
    Exists(ctx, filename) (bool, error)
    URL(filename) string
}

两种后端:本地文件系统 和 S3(AWS SDK v2)。SandboxedStore 包装任意 Store,在操作前检查插件权限。上传中间件通过 magic bytes 验证文件内容类型(PNG/JPEG/GIF/WebP/PDF),非仅依赖 Content-Type 头。

配置管理 ​

基于 Viper 的分层配置加载:

默认值 < config.yaml < config.{mode}.yaml < MENGSTACK_* 环境变量

安全校验:

  • JWT 密钥最少 32 字符,禁止已知占位值
  • release 模式 CORS 必须显式配置源,禁止通配符
  • JWT issuer 不可为空

健康检查 ​

端点用途响应
GET /health完整状态DB + Redis + 版本号
GET /healthzK8s 存活探针进程存活即 200
GET /readyzK8s 就绪探针DB + Redis 均连接才 200,否则 503
GET /api/version版本信息Version + Commit + Date

下一步 ​

Released under the Apache 2.0 License.