Appearance
核心能力
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 等持续增加中。
| 插件 | 版本 | 功能 |
|---|---|---|
| example | 0.1.0 | 示例插件,演示开发模式 |
| cms | 0.5.0 | 文章、版本、频道、分类、标签 |
| comment-interaction | 0.1.0 | 评论、点赞、收藏、举报、分享、统计 |
| topic | 0.1.0 | 专题管理 |
| flash | 0.1.0 | 快讯/快讯分类 |
| community | 0.1.0 | 论坛板块、帖子、回复 |
| search | 0.2.0 | 全文搜索、搜索建议、热词 |
| seo | 0.3.1 | TDK、站点地图、robots、重定向、内链 |
| media | 1.1.0 | 上传流水线、分片上传、图片样式、审核、配额、回收站 |
| author | 0.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 Token | 30 分钟 | API 请求鉴权 |
| Refresh Token | 7 天 | 刷新 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 层中间件:
| 序号 | 中间件 | 作用 |
|---|---|---|
| 1 | RequestID | 生成/透传 X-Request-ID(UUID) |
| 2 | RequestLogger | 结构化日志(状态、方法、路径、IP、耗时、trace_id) |
| 3 | SecurityHeaders | X-Content-Type-Options、X-Frame-Options DENY、CSP、HSTS 等 |
| 4 | CharsetUTF8 | 强制 JSON 写入 UTF-8 |
| 5 | CORS | 可配置源/方法/头,release 模式禁止通配符 * |
| 6 | AcceptLanguage | i18n 语言协商 |
| 7 | RateLimitRedis | Redis 滑动窗口限流(三级:匿名 100/min、认证 100/min、管理 500/min) |
| 8 | BodyLimit | 请求体上限 10MB |
| 9 | Recovery | panic 恢复 + 结构化日志 |
限流返回 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 /healthz | K8s 存活探针 | 进程存活即 200 |
GET /readyz | K8s 就绪探针 | DB + Redis 均连接才 200,否则 503 |
GET /api/version | 版本信息 | Version + Commit + Date |

