admin-net-backend · diff
git:20260922.e0d0947 to git:20261015.d1665a3
41 added, 5 removed. Audit A to A.
---
name: admin-net-backend
description: "Use when building .NET admin/backend management systems with Furion framework — user/role/permission management, CRUD code generation, API documentation. Admin.NET: Furion-based enterprise admin backend scaffold."
tags:
- dotnet
- webapi
- rbac
- multitenant
- furion
- sqlsugar
---
> **项目地址（上游）：** <https://github.com/zuohuaijun/Admin.NET>
>
> **znlgis 维护分支：** <https://github.com/znlgis/Admin.NET>
>
> **后端代码目录：** `Admin.NET/`（.NET 解决方案）
>
- > **当前版本：** v2.4.x（截至2026-09，upstream master `Web/package.json` 为 2.4.33；TFM `net8.0;net10.0`）
+ > **当前版本：** v2.4.x（upstream 分支 `v2` 的 `Web/package.json` 为 2.4.33，仓库最近推送 2026-03-30；后端 TFM `net8.0;net10.0`）
>
> **在线文档：** <https://adminnet.top/>
>
> **演示环境：** <https://demo.adminnet.top>（账号：superAdmin.NET / 密码：Admin.NET++010101）
>
> **许可证：** Apache-2.0（upstream 仓库 LICENSE）
## 概述
Admin.NET 后端基于 **.NET 8 / .NET 10** 构建，核心依赖 **Furion** 框架（动态 API、依赖注入、事件总线、远程请求等）和 **SqlSugar** ORM（自动建库建表、多租户、多数据库支持）。框架采用分层架构 + 插件式开发，适用于中小企业快速搭建权限管理系统。
**核心技术栈：**
- **运行时：** .NET 8.0 / .NET 10.0
- **Web 框架：** ASP.NET Core + Furion
- **ORM：** SqlSugar（支持 MySQL、SQL Server、PostgreSQL、Oracle、SQLite、达梦等）
- **缓存：** NewLife.Redis / MemoryCache
- **认证：** JWT Bearer（Furion.Extras.Authentication.JwtBearer）
- **实时通讯：** SignalR（支持 Redis 背板）
- **任务调度：** Sundial
- **日志：** log4net / Elasticsearch
- **对象映射：** Mapster
---
## 项目结构
- ```
+ ```text
Admin.NET/ # 后端解决方案根目录
├── Admin.NET.sln # Visual Studio 解决方案文件
├── Admin.NET.Core/ # 核心框架层
│ ├── Attribute/ # 自定义特性
│ ├── Cache/ # 缓存工具
│ ├── Const/ # 常量定义
│ ├── Entity/ # 核心实体（EntityBase 等基类）
│ ├── Enum/ # 枚举定义
│ ├── EventBus/ # 事件总线
│ ├── Extension/ # 扩展方法
│ ├── Hub/ # SignalR Hub
│ ├── Job/ # 定时任务
│ ├── Logging/ # 日志组件
│ ├── Option/ # 配置选项类
│ ├── SeedData/ # 种子数据
│ ├── Service/ # 核心服务（见下方服务模块表）
│ ├── SignalR/ # SignalR 配置
│ ├── SignatureAuth/ # 签名认证
│ ├── SqlSugar/ # SqlSugar 配置与仓储
│ ├── ElasticSearch/ # ES 日志集成
│ ├── Update/ # 数据库更新脚本
│ └── Utils/ # 工具类
├── Admin.NET.Application/ # 应用层（业务示例）
│ ├── Configuration/ # 应用配置
│ ├── Const/ # 应用常量
│ ├── Entity/ # 业务实体
│ ├── EventBus/ # 业务事件
│ ├── OpenApi/ # 开放 API
│ ├── Startup.cs # 应用层启动配置
│ └── GlobalUsings.cs # 全局 using
├── Admin.NET.Web.Core/ # Web 中间件与配置
├── Admin.NET.Web.Entry/ # 启动入口
│ ├── Controllers/ # 控制器
│ ├── appsettings.json # 配置文件
│ └── wwwroot/ # 静态资源
├── Admin.NET.Test/ # 单元测试
└── Plugins/ # 插件目录
├── Admin.NET.Plugin.GoView/ # GoView 数据大屏
├── Admin.NET.Plugin.DingTalk/ # 钉钉集成
├── Admin.NET.Plugin.ApprovalFlow/ # 审批流程
├── Admin.NET.Plugin.K3Cloud/ # 金蝶 K3 Cloud
├── Admin.NET.Plugin.ReZero/ # ReZero 零代码
└── Admin.NET.Plugin.WorkWeixin/ # 企业微信
```
---
## 环境准备与运行
### 前置要求
- .NET 8 SDK 或 .NET 10 SDK
- 数据库（SQLite 默认 / MySQL / SQL Server / PostgreSQL / Oracle / 达梦等）
- Redis（可选，用于缓存和 SignalR 背板）
### 运行后端
```bash
cd Admin.NET
dotnet restore Admin.NET.sln
dotnet run --project Admin.NET.Web.Entry
```
启动后默认访问 `https://localhost:5005`，Swagger 文档地址：`https://localhost:5005/api`
### 配置文件
主配置文件为 `Admin.NET.Web.Entry/appsettings.json`，关键配置节点：
```json
{
"DbConnection": {
"DbType": "Sqlite",
"ConnectionString": "DataSource=./admin.net.db"
},
"Cache": {
"CacheType": "Memory"
},
"JWTSettings": {
"ValidateIssuerSigningKey": true,
"IssuerSigningKey": "your-secret-key",
"ValidIssuer": "Admin.NET",
"ValidAudience": "Admin.NET",
"ExpiredTime": 120
}
}
```
---
## 核心服务模块
`Admin.NET.Core/Service/` 目录下按业务领域划分服务模块：
| 服务目录 | 说明 | 关键类 |
|---------|------|--------|
| `Auth/` | 登录认证、Token 管理 | `SysAuthService` |
| `User/` | 用户管理 | `SysUserService` |
| `Role/` | 角色管理、权限分配 | `SysRoleService` |
| `Org/` | 机构 / 组织架构管理 | `SysOrgService` |
| `Menu/` | 菜单与按钮权限管理 | `SysMenuService` |
| `Pos/` | 职位管理 | `SysPosService` |
| `Dict/` | 数据字典管理 | `SysDictTypeService` / `SysDictDataService` |
| `Config/` | 系统参数配置 | `SysConfigService` |
| `Tenant/` | 多租户管理 | `SysTenantService` |
| `Log/` | 访问日志 / 操作日志 | `SysLogVisService` / `SysLogOpService` |
| `File/` | 文件上传下载管理 | `SysFileService` |
| `Job/` | 任务调度管理 | `SysJobService` |
| `Notice/` | 通知公告（SignalR 推送） | `SysNoticeService` |
| `OnlineUser/` | 在线用户管理（SignalR） | `SysOnlineUserService` |
| `Message/` | 站内消息 | `SysMessageService` |
| `CodeGen/` | 代码生成器 | `SysCodeGenService` |
| `Cache/` | 缓存管理 | `SysCacheService` |
| `Server/` | 服务器监控 | `SysServerService` |
| `DataBase/` | 数据库管理 | `SysDatabaseService` |
| `Wechat/` | 微信小程序 / 支付 | `SysWechatService` |
| `Alipay/` | 支付宝支付 | `SysAlipayService` |
| `OAuth/` | 第三方 OAuth 登录 | `SysOAuthService` |
| `OpenAccess/` | 开放接口签名认证 | `SysOpenAccessService` |
| `Print/` | 打印模板管理 | `SysPrintService` |
| `Region/` | 行政区域 | `SysRegionService` |
| `APIJSON/` | APIJSON 协议支持 | `ApiJsonService` |
| `Lang/` | 多语言管理 | `SysLangService` |
| `Template/` | 模板管理 | `SysTemplateService` |
| `Plugin/` | 插件管理 | `SysPluginService` |
| `Enum/` | 枚举查询服务 | `SysEnumService` |
| `Const/` | 常量查询服务 | `SysConstService` |
| `Common/` | 通用服务 | `CommonService` |
| `Schedule/` | 计划任务管理 | - |
---
## 实体基类
所有业务实体继承自 `EntityBase` 或其变体：
```csharp
/// 实体基类 - 含主键 Id
[SugarTable(null)]
public abstract class EntityBase
{
[SugarColumn(ColumnDescription = "主键Id", IsPrimaryKey = true, IsIdentity = false)]
public virtual long Id { get; set; }
}
/// 带审计字段的实体基类
public abstract class EntityBaseData : EntityBase
{
public virtual long? CreateUserId { get; set; }
public virtual DateTime? CreateTime { get; set; }
public virtual long? UpdateUserId { get; set; }
public virtual DateTime? UpdateTime { get; set; }
public virtual bool IsDelete { get; set; } // 软删除
}
/// 带租户的实体基类
public abstract class EntityTenant : EntityBaseData
{
public virtual long? TenantId { get; set; }
}
```
---
> 服务开发模式与关键模式约定的完整说明见 [reference/service-patterns.md](reference/service-patterns.md)
## 认证与鉴权
### JWT 登录流程
- ```
+ ```http
POST /api/sysAuth/login
Content-Type: application/json
{
"account": "admin",
"password": "加密后的密码"
}
返回：{ "accessToken": "...", "refreshToken": "..." }
```
### 使用 Token
- ```
+ ```http
Authorization: Bearer {accessToken}
```
### 权限控制
- **菜单权限**：通过角色绑定菜单控制页面可见性
- **按钮权限**：通过菜单上的按钮权限标识（如 `sysUser:add`）做细粒度控制
- **数据权限**：角色可绑定数据范围（全部 / 本部门 / 本部门及以下 / 仅本人 / 自定义）
---
## 文件管理
```csharp
// 上传文件
POST /api/sysFile/uploadFile
Content-Type: multipart/form-data
// 文件存储支持：
// - Local（本地存储）
// - Aliyun（阿里云 OSS）
// - Tencent（腾讯云 COS）
// - Minio
// - QiNiu（七牛云）
```
---
## 代码生成
代码生成器根据数据库表结构自动生成前后端代码：
1. 在 Swagger 或管理界面中选择数据库表
2. 配置字段对应的前端控件类型
3. 一键生成：后端 Service / Entity / DTO + 前端 Vue 页面
---
## 插件开发
新建类库项目引用 `Admin.NET.Core`，在 `Plugins/` 目录下组织：
```csharp
// 1. 新建项目 Admin.NET.Plugin.MyPlugin
// 2. 引用 Admin.NET.Core
// 3. 实现服务
[ApiDescriptionSettings("MyPlugin", Order = 100)]
public class MyPluginService : IDynamicApiController, ITransient
{
// 业务代码
}
// 4. 在 Admin.NET.Web.Entry 中引用该插件项目即可自动注册
```
---
## 常用第三方集成
| 功能 | NuGet 包 | 用途 |
|------|---------|------|
| 微信小程序/支付 | `SKIT.FlurlHttpClient.Wechat.*` | 微信 API 对接 |
| 支付宝支付 | `AlipaySDKNet.Standard` | 支付宝 API 对接 |
| 导入导出 | `Magicodes.IE.Excel` / `MiniExcel` | Excel/Word/PDF 导入导出 |
| 二维码 | `QRCoder` | 二维码生成 |
| 国密算法 | `BouncyCastle.Cryptography` | SM2/SM3/SM4 加密 |
| LDAP | `Novell.Directory.Ldap.NETStandard` | LDAP/AD 域认证 |
| 短信 | `AlibabaCloud.SDK.Dysmsapi20170525` | 阿里云短信 |
| 邮件 | `MailKit` / `NETCore.MailKit` | 邮件发送 |
| IP 定位 | `IPTools.China` / `IPTools.International` | IP 地址解析 |
| 限流 | `AspNetCoreRateLimit` | API 访问限流 |
| ES 日志 | `Elastic.Clients.Elasticsearch` | Elasticsearch 日志 |
| OAuth | `AspNet.Security.OAuth.*` | 第三方登录（微信/Gitee） |
---
+ ## 典型工作流
+
+ ### 工作流一：从零跑起来
+
+ 1. 克隆仓库，按 `appsettings.json` 配置数据库连接（及 Redis/JWT）
+ 2. `dotnet run` 启动：首次启动自动建库建表并写入种子数据，无需手工执行 SQL
+ 3. 用种子账号登录 `/api/sysAuth/login` 拿 `accessToken`，在 Swagger 里验证接口
+
+ ### 工作流二：新增一个业务模块
+
+ 1. 在应用层新建实体：按需要继承 `EntityBase` / `EntityBaseData` / `EntityTenant`
+ 2. 新建服务：继承 `BaseService<T>` 或实现 `IDynamicApiController`，方法加 `[DisplayName("操作名")]` 自动注册权限
+ 3. 新建 DTO，接口打 `[ApiDescriptionSettings("GroupName")]` 分组
+ 4. 用代码生成：Swagger 或管理界面选表 → 一键生成 Entity/Service/DTO + 前端页面，再按业务改
+
+ ### 工作流三：打包与部署
+
+ 1. 确认 `appsettings.json` 的数据库、Redis、JWT 配置
+ 2. `dotnet publish` 产出发布包
+ 3. 用仓库自带的 Dockerfile 容器化，或部署到 IIS / Nginx
+
+ ---
+
## 开发流程最佳实践
- ```
+ ```text
1. 建议每个业务系统单独创建一个工程（参考 Admin.NET.Application 层的结构）
2. 自建应用层引用 Admin.NET.Core 层（不修改核心工程名）
3. Admin.NET.Web.Entry 引用新建的应用层工程
4. 接口 / 服务 / 控制器采用合并模式，不影响自建应用层的使用
5. 可随主仓库升级而升级，避免冲突
```
+
+ ---
+
+ ## 常见问题
+
+ | 问题 | 解决 |
+ |------|------|
+ | 首次启动要不要手工建库 | 不需要：启动时自动建库建表并注入种子数据，只要连接串有建库权限 |
+ | 主键设了数据库自增导致冲突 | Admin.NET 主键用 `Yitter.IdGenerator` 雪花 ID，实体主键不要配自增列 |
+ | 调用 `Delete` 后数据还在库里 | 继承 `EntityBaseData` 的实体默认软删除（`IsDelete`），要真删用 `DeleteByIdAsync` |
+ | 接口没进 Swagger 分组 | 服务/方法上补 `[ApiDescriptionSettings("GroupName", Order = 100)]` |
+ | 前端按钮权限不生效 | 后端方法上要有 `[DisplayName("操作名")]`，前端配合 `v-auth` 指令使用 |
+ | 多租户数据串了 | 实体需继承 `EntityTenant`，才会按 `TenantId` 自动隔离 |
---
## AI 使用建议
### 推荐工作流
1. **快速搭建**：克隆仓库 → 配置数据库连接 → `dotnet run` → 自动建库建表 + 种子数据
2. **新增业务模块**：参考 `Admin.NET.Application` 结构，新建实体 → 新建 Service（继承 `BaseService<T>` 或实现 `IDynamicApiController`）→ 新建 DTO
3. **代码生成**：在 Swagger 或管理界面选表 → 配置字段控件 → 一键生成后端 Service/Entity/DTO + 前端 Vue 页面
4. **插件开发**：`Plugins/` 下新建类库 → 引用 `Admin.NET.Core` → 实现 `IDynamicApiController` → 被主项目引用即自动注册
5. **部署**：配置 `appsettings.json`（数据库/Redis/JWT）→ `dotnet publish` → Docker 或 IIS/Nginx 部署
### 关键模式与常见陷阱
- **实体继承链**：`EntityBase`（仅 Id）→ `EntityBaseData`（+审计字段/软删除）→ `EntityTenant`（+租户隔离），按需选择
- **雪花 ID**：主键使用 `Yitter.IdGenerator` 生成 long 型雪花 ID，不要设置数据库自增
- **软删除**：继承 `EntityBaseData` 的实体 `Delete` 默认是软删除（设 `IsDelete = true`），物理删除用 `DeleteByIdAsync`
- **动态 API 分组**：`[ApiDescriptionSettings("GroupName", Order = 100)]` 控制 Swagger 分组
- **权限控制**：`[DisplayName("操作名")]` 自动注册为权限标识，前端配合 `v-auth` 指令使用
- **多租户**：实体继承 `EntityTenant` 后自动按 `TenantId` 隔离，切换租户用 `_rep.Context.AsTenant().GetConnection(tenantDbConfigId)`
### 如何选择正确方案
| 场景 | 推荐方案 |
|------|---------|
| 从零搭建后台 | Admin.NET（Furion + SqlSugar 全家桶） |
| 已有 Furion 项目加权限 | 参考 Admin.NET 的 Auth/User/Role/Menu 模块 |
| 仅需 ORM | 直接用 SqlSugar，不引入 Admin.NET |
| 微服务架构 | RuoYi-Cloud（Java 生态） |
---
## 注意事项
1. **数据库自动迁移**：首次启动会自动创建数据库和种子数据，无需手动执行 SQL
2. **雪花 ID**：主键使用 `Yitter.IdGenerator` 生成雪花 ID（long 类型）
3. **软删除**：继承 `EntityBaseData` 的实体默认使用软删除（`IsDelete` 字段）
4. **多租户**：实体继承 `EntityTenant` 自动按 `TenantId` 隔离数据
5. **API 分组**：通过 `[ApiDescriptionSettings("GroupName")]` 对 Swagger 接口分组
6. **权限控制**：方法上 `[DisplayName("操作名")]` 会注册为权限标识，搭配 `[Authorize]` 使用
7. **国密支持**：通过 `BouncyCastle.Cryptography` 和 `sm-crypto` 实现 SM2/SM3/SM4 算法
8. **Docker 部署**：后端目录包含 `.dockerignore`，可直接用 Dockerfile 容器化部署
---
## 相关技能
- **furion** — Admin.NET 后端核心依赖的 Web 框架：[../furion/SKILL.md](../furion/SKILL.md)
- **sqlsugar** — Admin.NET 后端核心依赖的 ORM：[../sqlsugar/SKILL.md](../sqlsugar/SKILL.md)
- **admin-net-frontend** — Admin.NET 配套前端（Vue3 + Element Plus）：[../admin-net-frontend/SKILL.md](../admin-net-frontend/SKILL.md)
---
## 参考资源
- **GitHub：** <https://github.com/znlgis/Admin.NET>
- **GitHub 镜像：** <https://github.com/zuohuaijun/Admin.NET>
- **Gitee 镜像：** <https://gitee.com/zuohuaijun/Admin.NET>
- **GitCode 镜像：** <https://gitcode.com/zuohuaijun/Admin.NET>
- **在线文档：** <https://adminnet.top/>
- **Furion 框架：** <https://gitee.com/dotnetchina/Furion>
- **SqlSugar 文档：** <https://www.donet5.com/Home/Doc>
- **vue-next-admin：** <https://vue-next-admin-doc.vercel.app/>