# HzyAdmin

**Repository Path**: hzy6/HzyAdmin

## Basic Information

- **Project Name**: HzyAdmin
- **Description**: 通用管理平台！基于【.Net10、HZY.Framework】兼容【模块化、Winforms、Wpf】基础功能：【AOP、数据权限、按钮权限、动态菜单、动态任务调度、动态WebApi、定时标记 [Scheduled("0/5 * * * * ?")] 、代码生成】
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: http://47.98.179.56/docs
- **GVP Project**: No

## Statistics

- **Stars**: 1352
- **Forks**: 468
- **Created**: 2018-03-12
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: backend

**Tags**: Net10, Winforms, EF10, React, vue3

## README

# HzyAdmin 通用管理平台

📚 **二次开发指南**：完整的架构说明、特性讲解与上手教程见 [**`docs/index.html`**](docs/index.html)（启动后端后访问 <http://localhost:5500/docs>）。涵盖模块化启动、ApplicationService 继承链、动态 API、三层认证授权、数据权限、字典翻译、Quartz 定时任务、MCP 集成、EFCore 监控等内容，并提供「新增业务模块」的完整实战示例。

[English](README.en.md) | [Issues](https://gitee.com/hzy6/HzyAdmin/issues/new)

> .slnx 文件无法打开时，请使用 Rider 或 Visual Studio 2022，并开启 `.slnx` 预览功能。

![HzyAdmin](gitee/images/image_cover.png)
![输入图片说明](gitee/agents.png)

HzyAdmin 是一个基于 **.NET 10 + React 19** 的前后端分离权限管理后台。项目采用模块化后端架构和 Ant Design Pro 前端方案，内置用户、角色、菜单、API、数据权限、定时任务、操作日志、文件管理、国际化等常见后台能力。

## 核心特性

- 前后端分离：后端提供 Web API，React 前端通过 `/api/v1/*` 代理访问。
- 模块化后端：基于启动模块、动态 API、仓储、AOP、过滤器和中间件组织业务能力。
- 权限体系完整：JWT 登录、菜单权限、按钮权限、API 权限、角色数据权限。
- React-only 前端：保留 `hzy-frontend-admin-react/`，Vue 版本已移除。
- 多数据库支持：默认 PostgreSQL，可切换 SqlServer、MySQL、Oracle。
- 工程配套齐全：Docker Compose、Swagger、NUnit 后端测试、Playwright 前端 E2E 测试。

## 技术栈

### 后端

| 技术 | 说明 |
| --- | --- |
| .NET 10 | Web API 基础框架 |
| Entity Framework Core 10 | ORM |
| HZY.Framework | DI、动态 API、仓储、实体基类等 |
| Rougamo.Fody | AOP 编程 |
| JWT | 身份认证 |
| Redis / FreeRedis | 分布式缓存 |
| Quartz.NET | 定时任务调度 |
| Mapster | 对象映射 |
| MiniExcel | Excel 导入导出 |
| Swagger / Knife4j | API 文档 |
| NUnit / Moq / FluentAssertions | 后端测试 |

### 前端

| 技术 | 说明 |
| --- | --- |
| React 19 | 前端框架 |
| Umi Max 4 | 应用框架、路由、构建 |
| Ant Design 5 | UI 组件库 |
| Ant Design Pro / ProComponents | 后台布局、高级表格和表单 |
| TypeScript 5 | 类型系统 |
| Biome | 代码检查 |
| Playwright | E2E 测试 |
| ECharts / AntV | 图表可视化 |

## 项目结构

```text
HzyAdmin/
├── src/
│   ├── HZY.Host.Admin/           # Web API 主机、控制器、ApplicationServices
│   ├── HZY.Repository.Admin/     # EF Core 仓储层、实体、DbContext
│   ├── HZY.Shared.Admin/         # 后台共享层、DTO、过滤器、中间件、基类
│   ├── HZY.Shared/               # 基础共享模块
│   ├── HZY.Core/                 # 核心模块
│   ├── HZY.Core.EntityFramework/ # EF Core 扩展
│   ├── HZY.Core.Identity/        # JWT 身份认证
│   ├── HZY.Core.Redis/           # Redis 缓存
│   ├── HZY.Core.Quartz/          # 定时任务
│   ├── HZY.Core.UploadFile/      # 文件上传
│   ├── HZY.Core.Swagger/         # Swagger 文档
│   └── HZY.Core.*                # 其他扩展模块
├── hzy-frontend-admin-react/     # React 19 + Ant Design Pro 前端
├── tests/                        # 后端 NUnit 测试
├── doc/                          # 数据库初始化脚本
├── admin-generate-ef-seed-data/  # 种子数据生成工具
├── gitee/                        # README 图片资源
└── HZY.Admin.slnx                # .NET 解决方案
```

## 功能模块

| 模块 | 说明 |
| --- | --- |
| 用户管理 | 用户增删改查、分配角色、重置密码 |
| 角色管理 | 角色配置、菜单权限、功能权限、数据权限 |
| 菜单管理 | 菜单、路由、按钮权限、图标管理 |
| API 管理 | API 资源维护和接口权限控制 |
| 组织机构 | 部门树形结构管理 |
| 岗位管理 | 岗位信息管理 |
| 字典管理 | 系统字典数据维护 |
| 文件管理 | 文件上传和文件信息管理 |
| 操作日志 | 用户操作日志记录与查询 |
| 数据权限 | 基于角色的行级数据过滤 |
| 多语言 | 国际化语言配置 |
| 服务器监控 | 服务器运行状态查看 |
| 定时任务 | Quartz 任务调度管理 |
| EF Core 监控 | EF Core 运行状态监控 |
| 个人中心 | 个人资料和密码修改 |

## 环境要求

- .NET 10.0 SDK
- Node.js 20+
- PostgreSQL 16+（默认）
- Redis 7+
- Rider 或 Visual Studio 2022
- VS Code 或 WebStorm（前端开发）

默认开发端口：

| 服务 | 地址 |
| --- | --- |
| 后端 API | `http://localhost:5500` |
| Swagger | `http://localhost:5500/swagger` |
| 离线文档 | `http://localhost:5500/docs` |
| React 前端 | `http://localhost:8000` |
| PostgreSQL | `localhost:5432` |
| Redis | `localhost:6379` |

默认账号：

| 登录名 | 密码 |
| --- | --- |
| `admin` | `123456` |

## 快速开始

### 1. 准备数据库和 Redis

开发配置位于 `src/HZY.Host.Admin/appsettings.Development.json`，默认连接：

```text
PostgreSQL: User ID=root;Password=123456;Host=localhost;Port=5432;Database=hzy_admin_2026
Redis:      127.0.0.1:6379,password=123456,defaultDatabase=0
```

初始化脚本：

```bash
psql -U root -d hzy_admin_2026 -f doc/hzy_admin_2026_pgsql.sql
```

如果使用 Docker，可以先启动数据库和缓存：

```bash
cd src/HZY.Host.Admin
docker-compose up -d postgres redis
```

### 2. 启动后端

```bash
# 在仓库根目录执行
dotnet restore
dotnet run --project src/HZY.Host.Admin
```

### 3. 启动 React 前端

```bash
cd hzy-frontend-admin-react

npm install
npm run dev
```

React 开发服务器默认代理 `/api/v1/*` 到 `http://localhost:5500`。

## 常用命令

### 后端

```bash
# 构建
dotnet build HZY.Admin.slnx

# 运行测试
dotnet test

# 运行单个测试
dotnet test --filter "FullyQualifiedName~Test1"

# EF Core 迁移
dotnet ef migrations add <MigrationName> --project src/HZY.Host.Admin
dotnet ef database update --project src/HZY.Host.Admin
```

### 前端

```bash
cd hzy-frontend-admin-react

# 开发服务器
npm run dev

# 生产构建
npm run build

# 类型检查
npm run tsc

# 代码检查（Biome + TypeScript）
npm run lint

# 单元测试
npm run test

# E2E 测试
npx playwright test
```

## React 前端说明

React 前端位于 `hzy-frontend-admin-react/`：

```text
hzy-frontend-admin-react/
├── config/
│   ├── config.ts          # Umi Max 主配置
│   ├── defaultSettings.ts # ProLayout 默认主题
│   ├── proxy.ts           # /api/v1 代理配置
│   └── routes.ts          # 静态路由
├── mock/                  # 示例 Mock
├── src/
│   ├── app.tsx            # 运行时入口、layout、request
│   ├── access.ts          # 权限控制
│   ├── components/        # 共享组件
│   ├── pages/             # 页面
│   ├── services/          # API 服务
│   └── utils/             # token、request、菜单转换等工具
├── e2e/                   # Playwright E2E 测试
└── package.json
```

后端菜单表中的 `react_url` 和 `react_router` 字段用于关联 React 页面：

- `react_url`：组件路径，例如 `./system/sys_user`
- `react_router`：路由路径，例如 `/system/sys_user`

## 后端架构说明

启动流程：

```text
Program.cs
└── HzyApplication.RunAsync<ApiAdminStartup>()
    └── ImportStartupModule
        ├── CoreQuartzStartup
        ├── CoreRedisStartup
        ├── CoreIdentityStartup
        ├── CoreFileStartup
        ├── AdminRepositoryStartup
        ├── CoreSwaggerJwtStartup
        └── SharedAdminStartup
```

关键约定：

- 后端动态 API 路由保持原始大小写，统一前缀为 `/api/v1/admin/`。
- ASP.NET Core 会移除 Action 方法名的 `Async` 后缀，前端调用时不要带 `Async`。
- `AdminControllerBase` 默认启用 `[Authorize]`。
- `IndentityControllerBase` 使用 `/api/v1/identity/` 前缀，登录和刷新 Token 为公开端点。
- `ApiAuthorizationMiddleware` 负责 JWT 验证和 URL 权限检查。
- `TakeUpTimeMiddleware` 记录 API 执行耗时并写入 `SysOperationLog`。

## 数据权限

数据权限是基于角色的行级数据过滤机制，支持：

| 类型 | 说明 |
| --- | --- |
| 全部数据 | 不受限制 |
| 仅看本人 | 只查看自己创建的数据 |
| 仅看本组织 | 只查看所属组织数据 |
| 本组织及下属 | 查看所属组织及下级组织数据 |
| 自定义 | 手动选择可访问组织 |

权限判断优先级：

1. 管理员 `IsAdministrator=true` 跳过过滤。
2. 任一角色拥有“全部数据”则不过滤。
3. 任一角色配置“仅看本人”则按用户过滤。
4. 组织权限按多角色并集计算。

后端服务继承 `ApplicationService<TEntity, TKey>` 后，默认会在标准查询中集成数据权限。实体没有 `CreateBy` 或 `OrganizationId` 字段时，可通过 `DataPermissionConfig` 跳过或指定自定义字段名。

## Docker 部署

```bash
cd src/HZY.Host.Admin

# 启动 API、PostgreSQL、Redis
docker-compose up -d

# 查看 API 日志
docker-compose logs -f hzy-admin

# 停止服务
docker-compose down
```

Docker Compose 默认服务：

| 服务 | 端口 | 说明 |
| --- | --- | --- |
| `hzy-admin` | `5500` | 后端 API |
| `postgres` | `5432` | PostgreSQL |
| `redis` | `6379` | Redis |

可通过环境变量覆盖配置：

- `AdminRepositoryOptions__ConnectionString`
- `AdminRepositoryOptions__DefaultDatabaseType`
- `ConnectionStrings__Redis`

> **建库说明**：EF 迁移里**没有**智能体、审批工作流、数据字典 v2 的表，
> `dotnet ef database update` 建不出来。完整建库入口是 `docs/hzy_admin_2026_pgsql.sql`
> （MySQL 用 `_mysql.sql`）。compose 已配好在 PostgreSQL 首次启动时自动导入。

## 智能体模块部署

智能体模块会为每个智能体拉起一个独立的 **opencode 容器**，因此比其它模块多几步。

### 一次性准备

```bash
# 1. 构建 opencode 运行时镜像
docker build -t opencode-runtime:latest agent-runtime/opencode

# 2. 准备工作区目录与环境变量
cd src/HZY.Host.Admin
mkdir -p /absolute/path/to/agent-workspace
cp .env.example .env      # 按注释填写 AGENT_WORKSPACE_HOST 与两个密钥
```

> `agentnet` 网络**不要手工创建**，compose 会自己建。
> 若之前手工建过，compose 会因为网络标签不符而拒绝接管，先 `docker network rm agentnet`。

### 启动

```bash
# 在 docker-compose.yml 之上叠加智能体运行时
docker compose -f docker-compose.yml -f docker-compose.agent.yml up -d
```

多起来的服务：

| 服务 | 端口 | 说明 |
| --- | --- | --- |
| `hzy-mcp-server` | `5510` | 本系统对外暴露的 MCP 服务（独立进程） |
| `hzy-oc-<智能体编码>` | 动态 | 由后端编排器按需拉起的 opencode 容器 |

### 配置到能用

后台依次配好，缺一步都会在部署时报错：

1. **模型配置** → 新建，填网关地址、模型名、API Key（AES 加密入库，界面只回掩码）
2. **MCP 管理** → 登记 MCP 服务。用本系统自带的那个就填 `http://hzy-mcp-server:5510/mcp`
   （容器间按服务名互访；填 `localhost` 在 opencode 容器里指向的是它自己）
3. **智能体管理** → 新建，绑定模型与提示词，状态置「已发布」，再绑 MCP / 技能
4. 点**部署** → 卡片上的实例状态变「运行中」即成功
5. **智能体对话** → 左栏选中它开始对话；右栏能看到可用 MCP 与实时调用链

改了模型/提示词/MCP 绑定后，卡片会显示「配置已变更」，点**重新部署**才生效。

### 三个最容易踩的坑

1. **后端在容器里就必须挂 `docker.sock`**。编排器要指挥宿主 Docker 拉起 opencode 容器，
   不挂则「部署」直接失败。`docker-compose.agent.yml` 已挂好 —— 但这等于把宿主 Docker 的
   完全控制权交给后端容器，所以它是单独的叠加文件，由你显式选择。
2. **工作区的两个路径必须指向同一块物理目录**：`WorkspaceLocal` 是后端进程可写视角
   （容器内路径），`WorkspaceHost` 是 daemon 宿主视角（宿主机绝对路径）。
   配错的话 opencode 容器挂到的是空目录，而它**读不到配置时会静默 fail-open**
   （放行 bash + 连匿名云端模型）—— 表现为「能聊天但工具全不对」，极难排查。
3. **MCP 服务地址要用容器可达的地址**。后台「MCP 管理」里的地址是给 opencode 容器用的，
   不是给你浏览器用的。同理，消息附图的 `OpenCode:ImageBaseUrl` 也必须是模型侧可达的地址。

### 不用容器编排也能跑

只想先体验对话、不想起容器：保持 `OpenCode:Docker:Enabled=false`（默认值）即可。
此时聊天走**演示模式**，回复是占位文本并在页面顶部明确提示，不会真正调用模型与 MCP。

## 前端生产部署

React 构建产物默认输出到 `hzy-frontend-admin-react/dist/`。如果需要由后端统一托管：

```bash
cd hzy-frontend-admin-react
npm run build

# 将 dist 内容复制到后端静态目录
rsync -a --delete dist/ ../src/HZY.Host.Admin/wwwroot/client/
```

后端根路径 `/` 会重定向到 `/client/index.html`。React 生产构建的 `publicPath` 已配置为 `/client/`，用于匹配后端静态托管目录。

## 数据库脚本

`doc/` 目录提供初始化脚本：

| 文件 | 说明 |
| --- | --- |
| `hzy_admin_2026_pgsql.sql` | PostgreSQL 初始化脚本 |
| `hzy_admin_2026_mysql.sql` | MySQL 初始化脚本 |

其他数据库可通过 EF Core 迁移创建结构，再按需要导入基础数据。

## 相关链接

- 文档/演示地址：http://47.98.179.56/docs
- Bilibili 视频介绍：https://www.bilibili.com/video/BV1tt4y157qH
- MVC 版本：https://gitee.com/hzy6/hzy-admin-mvc
- WebApi 任务调度平台：https://gitee.com/hzy6/hzy-quartz
- NuGet 包：https://www.nuget.org/packages?q=hzy

## 截图展示

### 模块化工程结构

![项目结构](gitee/images/project_map.jpg)

### 功能列表

![功能列表](gitee/images/menu_map_2023-2-3.jpg)

### 微服务案例模块化工程结构

![微服务结构](gitee/images/project_1.jpg)

### 属性注入

![属性注入](gitee/images/attr_inj.png)

### 界面截图

![界面](gitee/images/winform.png)

| ![深色主题](gitee/images/theme_dark.png) | ![深色主题](gitee/images/theme_dark_1.png) |
|---|---|

| ![数据权限](gitee/images/DataAuthority.png) | ![功能权限](gitee/images/function.png) |
|---|---|

| ![菜单信息](gitee/images/MenuInfo.png) | ![菜单功能](gitee/images/menu_function.png) |
|---|---|

| ![首页](gitee/images/home.png) | ![图标](gitee/images/icons.png) |
|---|---|

| ![图表](gitee/images/chart.png) | ![更多图表](gitee/images/%E6%9B%B4%E5%A4%9A%E5%9B%BE%E8%A1%A8.png) |
|---|---|

| ![用户列表](gitee/images/user_list.png) | ![富文本](gitee/images/wangeditor.png) |
|---|---|

| ![代码生成](gitee/images/code_gen.png) | ![个人中心](gitee/images/user_center.png) |
|---|---|

| ![接口文档](gitee/images/api_doc.png) | ![EF Core 监控](gitee/images/Efcore%20%E7%9B%91%E6%8E%A7.png) |
|---|---|

![首页](gitee/images/home1.png)

## 贡献指南

1. Fork 本仓库。
2. 新建功能分支，例如 `feat_xxx`。
3. 提交代码并确保 `dotnet test`、`npm run tsc`、`npm run lint` 通过。
4. 新建 Pull Request。

## 开源协议

本项目基于 [MIT](LICENSE) 协议开源。