SmartAdmin.AspNetCore 10.3.0

English | 简体中文

<p align="center"> <img src="web/public/icon-192.png" width="80" height="80" alt="SmartAdmin"> </p>

<h1 align="center">SmartAdmin</h1>

<p align="center"> <em>三行代码接入完整后台：认证、RBAC、多机构数据权限、字典配置、日志、文件、定时任务。</em> </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a> <a href="https://github.com/SmartCode-X/SmartAdmin/stargazers"><img src="https://img.shields.io/github/stars/SmartCode-X/SmartAdmin" alt="Stars"></a> <a href="https://github.com/SmartCode-X/SmartAdmin/network/members"><img src="https://img.shields.io/github/forks/SmartCode-X/SmartAdmin" alt="Forks"></a> <a href="https://www.nuget.org/packages/SmartAdmin"><img src="https://img.shields.io/nuget/v/SmartAdmin" alt="NuGet"></a> <img src="https://img.shields.io/badge/.NET-10-512BD4" alt=".NET 10"> </p>

<p align="center"> <a href="https://smartcode-x.github.io/SmartAdmin/zh/"><strong>📖 文档</strong></a>  ·  <a href="https://smartcode-x.github.io/SmartAdmin/zh/guide/getting-started"><strong>🚀 快速开始</strong></a>  ·  <a href="CHANGELOG.md"><strong>📋 更新日志</strong></a> </p>

这是什么

SmartAdmin 是一个以 NuGet 包交付的后台管理系统内核，面向 .NET 10 / ASP.NET Core。用户、角色、菜单、机构、数据权限、字典、配置、日志、文件、定时任务，这些每个后台都要重做一遍的功能装一个包就有，Program.cs 里只需三行：

builder.Services.AddSmartAdmin(builder.Configuration);
var app = builder.Build();
app.MapSmartAdmin();

它和「克隆一个后台模板」的区别在归属：通用功能是包依赖，升级只是换个版本号；仓库里始终只有你自己的业务代码。配套一套自包含的 Vue 3 管理端模板，拷一份就是你项目的前端起点。

亮点

• 零配置起步：默认 SQLite，首启自动建表、写种子，并在控制台打印一次超管密码。换 MySQL、SQL Server、PostgreSQL 只改一处配置。
• 不 fork 就能替换：内置服务全部接口背书、TryAdd 注册，你的实现先注册就赢；长方法拆成 virtual 小步，继承后只覆写关心的那一步。这条由契约测试 ReplaceabilityTests 锁定。
• 多机构数据权限内置：全部 / 本机构 / 本机构及以下 / 仅本人 / 自定义机构，五种范围靠 ORM 全局过滤器自动隔离，业务查询不写机构条件。
• 权限码即路由：GET:/api/v1/xxx 就是权限码，代码里没有权限字符串，授权在角色菜单界面勾路由完成。
• 依赖克制：内核运行时只依赖 SqlSugarCore 和 Microsoft.*。Redis、Excel、第三方登录都是可选包，不装不进发布产物。
• 多副本可扩展：可选 Redis 缓存、集群级限流、雪花 WorkerId 自动抢号、反向代理后真实 IP、定时任务数据库选主，两副本以上同一次触发也只跑一次。
• AI 友好：skills/ 把新建实体、搭 CRUD、替换服务、加定时任务写成了标准 skills，AI 助手照着就能生成符合规范的代码。

快速开始

环境

• .NET 10 SDK
• Node.js 20+（只在跑前端模板时需要）

方式一：新项目，用模板生成

dotnet new install SmartAdmin.Templates
dotnet new smart-app -n MyApp
cd MyApp
dotnet run

生成的 host 已接线一个机构隔离的示例业务模块（Modules/SampleDoc*），复制那四个文件改名就是你的下一个模块。

方式二：已有项目，装包接入

dotnet add package SmartAdmin

Program.cs 加上前面那三行，JWT、RBAC、数据权限和全部管理端点就注册好了。

首次登录

首启时控制台会打印一段随机超管密码，账号固定 superAdmin，密码只打印这一次：

════════════════════════════════════════════
  SmartAdmin 首次启动,已创建超级管理员
  账号: superAdmin
  密码: xxxxxxxxxxxxxxxx
  此密码仅本次显示,请登录后立即修改!
════════════════════════════════════════════

想要固定密码，配 SmartAdmin:Seed:AdminPassword，只对空库生效。三个探针：/health（存活）、/health/ready（数据库 + 缓存就绪）、/openapi/v1.json（仅 Development 挂载，前端生成类型的数据源）。

换数据库

// appsettings.json
"SmartAdmin": {
  "Database": {
    "DbType": "MySql",                 // Sqlite | MySql | SqlServer | PostgreSQL
    "ConnectionString": "...",
    "CodeFirstVersion": "2026.09.06"   // 可选：版本号不变就跳过建表扫描，表多、库远时启动更快
  }
}

在本仓库里跑一遍

git clone https://github.com/SmartCode-X/SmartAdmin.git
cd SmartAdmin
dotnet run --project backend/samples/MinimalHost   # 后端 → http://localhost:5100
cd web && npm install && npm run dev               # 前端 → http://localhost:5173

Windows 上双击 dev-start.bat 一键起前后端，dev-stop.bat 停。要一条命令起全栈（MySQL + Redis + 后端 + Caddy 托管前端）用 docker compose up，双副本验证用 docker-compose.scale.yml。

功能清单

后端内核

NuGet 包

全部包共用一个版本号，主版本跟随内核所用的 .NET 主版本（10.x 对应 .NET 10）。

前端模板

web/ 是一套自包含的管理端模板，不发 npm 包，拷一份归你自己改：

ProTable、IconPicker 已拆成独立 npm 包（tenon-naive-pro-table、tenon-naive-iconify-picker），任意 Vue 3 + Naive UI 项目都能单装。

运行时架构

一次管理端请求自上而下走过四层：前端 → 宿主（控制器、鉴权管道）→ 领域服务 → SqlSugar 与数据库，每层对应一个 NuGet 包，四层都建在 SmartAdmin.Core 契约层上。缓存、外部登录、实时推送、定时任务与可选的 Worker 进程挂在旁路。

<p align="center"> <a href="docs/architecture/smart-runtime.zh-CN.svg"> <img src="docs/architecture/smart-runtime.zh-CN.readme.png" alt="SmartAdmin 运行时架构" width="100%"> </a> </p>

<p align="center"> <a href="docs/architecture/smart-runtime.zh-CN.svg"><strong>查看矢量图（SVG）</strong></a> </p>

替换与扩展

内置实现不合用就换掉，先于 AddSmartAdmin 注册即可：

builder.Services.AddSingleton<IPasswordHasher, MyPasswordHasher>();   // 你的先注册，内置的让道
builder.Services.AddSmartAdmin(builder.Configuration);

只想改一步，继承内置服务覆写那个 virtual 方法。业务模块放在你自己的程序集里，经 options.ApplicationAssemblies 登记后实体自动建表、控制器自动挂路由。完整流程见文档站的新建业务模块与替换内置服务；仓库 skills/ 目录是同一套流程的 agent 版本（/new-module、/create-crud-backend、/replace-service、/create-job 等）。

仓库结构

版本与贡献

开发在 dev，发布在 main，v* tag 触发打包并发到 nuget.org。变更以 CHANGELOG 为准，破坏性变更在对应版本段落顶部加粗提示。欢迎 issue 与 PR，安全问题按 SECURITY.md 报告。

许可证

Apache License 2.0