魔方 NewLife.Cube

魔方是一个快速 Web 开发平台，面向“数据驱动 + 快速迭代 + 可深度定制”场景。几分钟内即可把实体 / 数据库表转为带权限、列表、详情、增删改、导出、统计的完整后台界面，并开放标准 API 给 Vue / Blazor / Antd / 移动端或第三方系统调用。默认模板已在真实项目中经历单表 100 亿数据增删改查考验。

演示站点：https://cube.newlifex.com CentOS7 + CDN
SSO中心：https://sso.newlifex.com OAuth 服务端
Swagger：https://cube3.newlifex.com

魔方教程：https://newlifex.com/cube
XCode教程：https://newlifex.com/xcode
核心库教程：https://newlifex.com/core

文档索引：详细需求文档、功能清单、架构设计见 Doc/ 目录：

• 📋 需求文档 — 愿景、核心目标、功能需求
• ✅ 功能清单 — 实现/测试/注释三维状态追踪
• 🏗️ 架构设计 — 分层架构、模块设计、关键决策
• 🤖 AI 人工智能 — AI 能力清单、配置与扩展点
• 🔔 在线告警与站内信 — 在线新高告警、系统级广播站内信与未读闭环
• � 邮箱/手机验证 — 账号激活契约（注册→激活→登录），前端皮肤接入规范
• 🛡️ 安全防御 — 内置威胁检测、自动封禁与安全事件审计
• �📚 魔方用户手册 — 完整的用户与开发手册

目录索引

• 魔方 NewLife.Cube
  • 目录索引
  • 核心价值
  • 总体架构
  • 项目结构与子工程说明
  • 核心概念
  • 快速拥有
  • 最小示例（.NET 8/9 Minimal Hosting）
  • 字段与界面定制示例
  • API 与前后端分离
  • 权限与安全
  • 主题 / 皮肤 / UI 扩展
    • 新一代前端皮肤包
    • 前端 workspace 构建约定
  • 多数据库与大数据支持
  • 性能特性
  • 部署方式
  • 快速部署用户中心
    • 快速部署用户中心
  • 第三代魔方
    • 项目参与须知
    • 目标蓝图
    • 春雨计划（里程碑摘录）
    • WebApi 接口说明（节选）
  • 常见使用场景
  • 贡献指南
  • FAQ 速览
  • 魔方特性
  • ASP.NET Core 安装
  • ASP.NET MVC 安装
  • 新生命项目矩阵
  • 新生命开发团队

核心价值

1. 极速“数据到界面”生产力：实体类 + 控制器 = CRUD / 统计 / 导出 / 权限 即刻可用。
2. 全维权限：用户 / 角色 / 菜单 / Action 粒度，支持 SSO + OAuth + JWT。
3. 多前端共存：Vue / Blazor / AntDesign / 传统 Razor 可渐进迁移。
4. 多数据库 + 自动建表 + 自动分表 + 读写分离（依赖 XCode）支持超大规模数据。
5. 可扩展：字段元数据、视图覆写、主题插件、IModule 模块化。
6. AI 智能洞察：任何数据页面一键 AI 分析——自动统计、异常检测、趋势预判、可执行建议。支持 SSE 流式输出和深度推理模式。MVC / Vue 双前端适配。
7. AI 对话助手：右下角对话面板统一入口，上下文感知（当前页面/实体/查询）。基于 NewLife.AI 工具层，对话即可完成数据分析、智能填表（元数据驱动通用填表）、记录分析与系统诊断，支持深度推理开关。
8. 工作台 Widget 部件体系：工作台 / 首页由可配置部件（KPI、图表、监控）组成，支持个性化布局与 /Cube/Widget 部件管理。
9. 导出增强：数据导出支持 xlsx 全量导出、Zip 打包、CSV 表头与枚举数字，并带 SYLK 防护。
10. SVG 文字头像：用户头像缺失时自动兜底生成 SVG 文字头像（中文取前 N 字 + 渐变视觉）。
11. Scalar API 文档：集成 Scalar 在线接口文档，配合 Swagger 按区域自动分组，接口在线调试更便捷。
12. 多租户开关：多租户能力可一键开关，关闭后隐藏租户菜单与字段，支持运行时租户切换。
13. 长期演进 & 多目标框架，易升级、稳定可控。

总体架构

+-------------------------------------------------------------+
|         前端 (Vue / Blazor / Antd / 传统 Razor UI)           |
+----------------------+------------------+-------------------+
|  皮肤视图(Razor)     |  API Controllers | Swagger 分组文档  |
+----------------------+------------------+-------------------+
|  EntityController / ReadOnlyEntityController 基础能力        |
+------------------+---------------------+--------------------+
| 权限(EntityAuthorize) | 过滤(ApiFilter) | 统一响应(ApiResponse)|
+-------------------------------------------------------------+
|            实体 & 业务逻辑 (XCode ORM + 扩展)                |
+-------------------------------------------------------------+
| 数据访问：MySql/SqlServer/SQLite/Oracle/PostgreSQL/达梦等    |
+-------------------------------------------------------------+
| NewLife.Core(日志/配置/缓存/序列化/追踪) + 生态组件          |
+-------------------------------------------------------------+

项目结构与子工程说明

• NewLife.Cube：核心（实体控制器、权限、菜单、字段元数据、API）。
• NewLife.CubeNC：旧版 MVC / Razor 兼容层。
• 皮肤主题：AdminLTE / Metronic / Metronic8 / Tabler / LayuiAdmin / ElementUI / Blazor（各独立包）。
• 新一代前端皮肤（pnpm workspace）：NaiveUI / MUI / Shadcn / ArcoVue / Angular / Vuetify / Svelte / TDesign。
• NewLife.Cube.Swagger：按区域自动分组的 Swagger 文档。
• CubeDemo / CubeDemoNC：示例。
• CubeSSO：统一用户中心 & OAuth 服务端。
• NewLife.Cube.Blazor：Blazor 前端实验。
• Test / XUnitTest：测试与验证。

核心概念

• EntityController：通过静态构造器配置字段、操作按钮、关联跳转、统计、导出。
• 字段元数据接口：GetFields?kind=List|Detail|AddForm|EditForm 驱动动态前端生成。
• 菜单树：/Admin/Index/GetMenuTree 根据权限生成多级菜单。
• 权限模型：用户 -> 角色 -> 菜单(Action 集合)。首个用户抢管理员，admin 被禁用。
• ApiResponse：标准响应包装 code / data / page / stat。
• IModule：启动模块注入服务和静态资源（主题、Swagger 等）。
• AI 对话助手：全局 AiController 统一 AiChat 端点（/Ai/AiChat）+ NAI AiChatService 编排（会话历史 ChatSessionService 保持/工具循环/SSE 事件流）。实体控制器经 IEntityAiContext 能力接口向全局端点暴露数据查询/工具集/提示词重载点（保留子类重载 SearchData/CreateCubeTools/BuildChatSystemPrompt）。工具集含 get_data_context（数据上下文）/get_form_schema（编辑模式带已有值）/fill_form（智能填表）/get_page_context（页面上下文，IPageDataContext 服务端优先/浏览器采集兜底）/get_system_info（系统诊断）/run_js（页面脚本执行，SSE 下发 + 前端回传，检查点经事件总线广播支持分布式集群），均带中文描述供 LLM 决策。SSE 事件驱动前端填表与工具卡片展示，MVC 与 Vue 双端浮窗。
• AI 洞察（已合并）：原 AiInsight 独立端点已合并到 AI 对话助手，数据收集保留 AiInsightHelper（14 类敏感字段黑名单）。

快速拥有

通过 NuGet 引入 NewLife.Cube.Core。MIT 协议，可私有化替换字符串“NewLife”。支持 VS 与 CLI。newlife.snk 已公开便于强命名一致性。

命令行体验：

dotnet new install NewLife.Templates
dotnet new cube --name CubeWeb
dotnet new xcode --name Zero.Data
cd CubeWeb
dotnet build
start http://localhost:6080
dotnet run

最小示例（.NET 8/9 Minimal Hosting）

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCube(); // 注册权限、菜单、实体控制器扫描
var app = builder.Build();
app.UseMetronic(app.Environment); // or UseAdminLTE / UseTabler ...
app.UseCube(app.Environment);      // 路由 & 静态资源 & 中间件
app.Run();

访问 / 登录后台；Swagger 查看接口；前端可调用标准 CRUD API。

字段与界面定制示例

public class AppController : EntityController<App, AppModel>
{
    static AppController()
    {
        LogOnChange = true;                 // 修改日志
        ListFields.RemoveField("Secret");   // 隐藏敏感列
        var log = ListFields.AddListField("Log", "UpdateUserId");
        log.DisplayName = "修改日志";
        log.Url = "/Admin/Log?category=应用系统&linkId={ID}";
        log.Target = "_blank";
    }
}

前端：/Cube/App/GetFields?kind=1 获取列表字段定义，无需硬编码。

API 与前后端分离

• 登录：/Auth/Login -> JWT Token（Header/Cookie/Query）。
• 菜单：/Cube/MenuTree。
• 字段：/{Area}/{Controller}/GetFields?kind=1..4。
• 查询：主路由 + 动态参数（支持分页、排序、条件拼装）。
• CRUD：Detail / Insert / Update / Delete。
• 统计：返回 stat；分页信息：page。

权限与安全

• EntityAuthorize：登录 + 角色 + 菜单 Action 校验。
• 首个用户自动管理员，原 admin 禁用。
• 支持外部 OAuth / SSO / JWT，多端统一身份。
• 建议生产：关闭未用第三方登录、启用 HTTPS、加强密码策略。
• 安全防御：内置威胁检测（扫描器/注入/蜜罐）、持久化自动封禁（阶梯时长）与安全事件审计，默认自动模式（连续攻击自动封禁、大范围攻击临时拦截并自动回落），可配置或自动学习可信代理防伪造，可一键切换观察/拦截模式。

主题 / 皮肤 / UI 扩展

• 主题内嵌静态资源：CubeEmbeddedFileProvider。
• UIService 注册皮肤：AddTheme/AddSkin。
• 自定义：仿照 MetronicModule 实现 IModule 并在 Use 阶段挂载。
• 视图覆写：子项目同路径同名 .cshtml 覆盖父级。

新一代前端皮肤包

基于 pnpm workspace + 公共模块 @newlifex/api-core（统一 API / Token / 类型）和 @newlifex/field-mapping（字段元数据 → 控件映射），8 套皮肤均开箱即用，NuGet 引包即得完整前端。

前端 workspace 构建约定

• 仓库根目录 pnpm build：仅构建 packages/ 下公共模块，不再默认递归编译所有皮肤。
• 仓库根目录单皮肤构建：使用 pnpm build:vue、pnpm build:react、pnpm build:naive、pnpm build:mui、pnpm build:shadcn、pnpm build:arco、pnpm build:angular、pnpm build:vuetify、pnpm build:svelte、pnpm build:tdesign。
• 仓库根目录单皮肤开发：使用对应的 pnpm dev:xxx。
• 需要一次性构建或启动全部前端时，显式使用 pnpm build:all 或 pnpm dev:all。
• 若已进入具体皮肤目录 web/，继续使用该目录下的 pnpm build / pnpm dev 即可，互不干扰。

// 使用示例（任选其一）
app.UseNaiveUI(app.Environment);
app.UseMUI(app.Environment);
app.UseShadcn(app.Environment);
app.UseArcoVue(app.Environment);
app.UseAngular(app.Environment);
app.UseVuetify(app.Environment);
app.UseSvelte(app.Environment);
app.UseTDesign(app.Environment);

多数据库与大数据支持

• XCode：实体同步建表、字段演进、自动分表、读写分离、二级缓存。
• 三库分离示例：Membership(权限) / Cube(业务) / Log(日志)。
• 支持 MySql / SQLite / SqlServer / Oracle / PostgreSql / SqlCe / Access / 达梦。
• PluginServer 自动下载数据库驱动 & 前端资源。

性能特性

• 过滤器统一记录耗时，易接入 Stardust APM。
• 日志判级避免无谓字符串拼接。
• 多 TFM 架构允许在高版本启用 Span/ValueTask 优化。

部署方式

• 单机：dotnet publish 后拷贝 dll + 配置即可。
• 服务：结合 NewLife.Agent 安装为 Windows Service 或 systemd。
• 集群：发布后打zip包，通过星尘代理StarAgent拉起守护，或通过星尘平台发布。
• 容器：简单 Dockerfile（复制发布目录，设置环境变量）。
• 横向扩展：无状态多实例，共享数据库 & 缓存。

快速部署用户中心

(下方为原始详尽步骤，保持一致)

1. 拉取源码并编译 CubeSSO 项目…… 详见下节。

快速部署用户中心

1. 拉取源码并编译CubeSSO项目，切换到输出目录Bin/SSO，按需修改appsettings.json配置，打包exe/dll/appsettings.json/CubeSSO.runtimeconfig.json等文件，并发布到服务器。

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Urls": "http://*:8080;https://*:8081",
  //"StarServer": "http://star.newlifex.com:6600",
  "ConnectionStrings": {
    "Membership": "Data Source=..\\Data\\Membership.db;provider=sqlite",
    "Cube": "Data Source=..\\Data\\Cube.db;provider=sqlite",
    "Log": "Data Source=..\\Data\\Log.db;provider=sqlite"

    //"Membership": "Server=.;Port=3306;Database=Membership;Uid=root;Pwd=root;provider=mysql",
    //"Cube": "Server=.;Port=3306;Database=Membership;Uid=root;Pwd=root;provider=mysql",
    //"Log": "Server=.;Port=3306;Database=Membership;Uid=root;Pwd=root;provider=mysql"
  }
}

2. 启动并访问SSO系统，首次登录可以用admin/admin进去，也可以使用第三方登录（新生命用户中心），第一个用户将会作为系统管理员，同时禁用admin。
3. 作为用户中心正式部署时，需要关闭SSO的第三方登录，魔方设置->OAuth设置->禁用所有。
   
4. 修改系统名称为新生命用户中心，魔方设置->系统设置->显示名称。

第三代魔方

第三代聚焦“前后端分离 + 多前端生态 + 最小侵入”。后端接口合并在 master，前端仓库独立（Vue / QuickVue / Antd / Blazor）。

Vue版：https://vue.newlifex.com, https://quickvue.newlifex.com
Antd版：https://antd.newlifex.com
Swagger：https://cube3.newlifex.com/swagger/index.html

项目参与须知

1. 加入 NewLifeX 团队，向 dev 分支提交。
2. WebApi 后台：NewLife.Cube；MVC 保留在 NewLife.CubeNC。
3. 新前端独立仓库（如 NewLife.CubeAntd）。
4. 文档/代码标注负责人。
5. 待办任务：https://github.com/orgs/NewLifeX/projects/1 。

目标蓝图

1. 现代化 UI + 保留覆写机制。
2. 多框架前端：Vue/React/Angular/Svelte + 8 套开箱即用皮肤包。
3. NuGet 引包即得默认皮肤。
4. 移动端 & 小程序 & 混合应用。
5. 数据大屏增强。

春雨计划（里程碑摘录）

• [*] 新建 WebApi 项目 NewLife.Cube
• [*] 迁移 NetCore 专属代码到 NewLife.CubeNC
• [*] 新版 EntityController / EntityReadonlyController
• [*] 接口文档 & Vue 登录主页
• [] Vue 用户/角色列表与表单

前端仓库：
https://github.com/NewLifeX/NewLife.CubeVue
https://github.com/NewLifeX/NewLife.QuickVue
https://github.com/NewLifeX/NewLife.CubeAntd
https://github.com/NewLifeX/NewLife.CubeBlazor

WebApi 接口说明（节选）

1. 地址 https://cube3.newlifex.com/swagger/index.html
2. 登录 /Auth/Login 测试账号 admin/admin test/test
3. JWT：Header / Cookie / Query(token)
4. 菜单 /Cube/MenuTree
5. 字段 /{Area}/{Controller}/GetFields?kind=1 (1=List 2=Detail 3=AddForm 4=EditForm)
6. 列表：主路由 + 动态查询参数
7. page：分页信息
8. stat：统计行
9. 详情 Detail | 新增 Insert | 修改 Update | 删除 Delete

常见使用场景

• 企业/部门内部管理后台、SaaS 管理面。
• IoT 设备/点位/日志/告警管理与数据导出。
• 数据中台快速发布标准查询接口。
• 统一身份认证与授权中心（SSO/OAuth）。
• 运营支撑系统（订单、配置、任务调度、版本发布）。

贡献指南

• 规范：参考 .github/copilot-instructions.md。
• Issue / PR：描述场景、期望、复现；性能类附数据规模。
• 新主题：独立仓库 + README 说明构建方式。
• 优先复用 NewLife 生态，避免不必要依赖。
• 多 TFM 编译通过后再提交。

FAQ 速览

Q: 隐藏字段?
A: 控制器静态构造：ListFields.RemoveField("字段")。
Q: 自定义统计?
A: 重写搜索逻辑，填充返回集合的 stat。
Q: 切换主题?
A: 引入主题包并 app.UseXXX(env)，后台可配置默认。
Q: 数据库驱动来源?
A: 首次运行自动从 PluginServer 下载，可自定义。
Q: 集成自定义前端?
A: 依靠字段元数据 + 标准 CRUD/JWT 登录。

魔方特性

• 通用权限管理，用户、角色、菜单、权限，支持控制器Action权限控制
• 多数据库，支持 MySql / SQLite / Sql Server / Oracle / PostgreSql / SqlCe / Access
• 免部署，系统自动创建数据库表结构，以及初始化数据，无需人工干涉
• 强大的视图引擎，支持子项目视图重写父项目相同位置视图，任意覆盖修改默认界面
• 内置富文本（Quill）与 Markdown（EasyMDE）双编辑器，支持图片上传与安全控制

ASP.NET Core 安装

• 在 Visual Studio 中新建ASP.NET Core Web项目
• 通过 NuGet 引用NewLife.Cube.Core，或自己编译最新的魔方 NewLife.CubeNC源码
• 在appsettings.json的ConnectionStrings段设置名为Membership的连接字符串，用户角色权限菜单等存储在该数据库
• 系统自动识别数据库类型，默认Data Source=..\Data\Membership.db
• 编译项目，项目上点击鼠标右键，查看，在浏览器中查看，运行魔方平台
• 系统为MySql/SQLite/Oracle/SqlCe数据库自动下载匹配（x86/x64）的数据库驱动文件，驱动下载地址可在Config\Core.config中修改PluginServer
• 系统自动下载脚本样式表等资源文件，下载地址可在Config/Cube.config中修改PluginServer
• 默认登录用户名是admin，密码是admin，也可以使用NewLife等第三方OAuth登录，首个进入系统的用户抢得管理员，原admin禁用
• 项目发布时只需要拷贝*.dll、appsettings.json、*.deps.json、*.runtimeconfig.json，以及其它自己添加的资源文件

ASP.NET MVC 安装

• 在 Visual Studio 中新建ASP.NET MVC项目
• 通过 NuGet 引用NewLife.Cube，或自己编译最新的魔方 NewLife.Cube源码
• 在Web.config的<connectionStrings>段设置名为Membership的连接字符串，用户角色权限菜单等存储在该数据库
• 系统自动识别数据库类型，默认<add name="Membership" connectionString="Data Source=..\Data\Membership.db" providerName="Sqlite"/>
• 编译项目，项目上点击鼠标右键，查看，在浏览器中查看，运行魔方平台
• 系统为MySql/SQLite/Oracle/SqlCe数据库自动下载匹配（x86/x64）的数据库驱动文件，驱动下载地址可在Config\Core.config中修改PluginServer
• 系统自动下载脚本样式表等资源文件，下载地址可在Config/Cube.config中修改PluginServer
• 默认登录用户名是admin，密码是admin，也可以使用NewLife等第三方OAuth登录，首个进入系统的用户抢得管理员，原admin禁用
• 推荐安装 Visual Studio 插件 Razor Generator，给.cshtml文件设置自定义工具为RazorGenerator，可以把.cshtml编译生成到DLL里面
• 项目发布时只需要拷贝Bin、web.config、Global.asax，以及其它自己添加的资源文件

新生命项目矩阵

各项目默认支持net9.0/netstandard2.1/netstandard2.0/net4.62/net4.5，旧版（2024.0801）支持net4.0/net2.0

新生命开发团队

新生命团队（NewLife）成立于2002年，是新时代物联网行业解决方案提供者，致力于提供软硬件应用方案咨询、系统架构规划与开发服务。
团队主导的80多个开源项目已被广泛应用于各行业，Nuget累计下载量高达400余万次。
团队开发的大数据中间件NewLife.XCode、蚂蚁调度计算平台AntJob、星尘分布式平台Stardust、缓存队列组件NewLife.Redis以及物联网平台FIoT，均成功应用于电力、高校、互联网、电信、交通、物流、工控、医疗、文博等行业，为客户提供了大量先进、可靠、安全、高质量、易扩展的产品和系统集成服务。

我们将不断通过服务的持续改进，成为客户长期信赖的合作伙伴，通过不断的创新和发展，成为国内优秀的IoT服务供应商。

新生命团队始于2002年，部分开源项目具有20年以上漫长历史，源码库保留有2010年以来所有修改记录
网站：https://newlifex.com
开源：https://github.com/newlifex
QQ群：1600800/1600838
微信公众号：