hw-web/Admin.NET-v2/HW_PORTAL_本机环境配置与启动教程.md

# HW Portal 本机环境配置与启动教程

## 1. 文档目的

- 适用场景：当前电脑没有任何 C#/.NET 环境，也没有 Visual Studio。
- 目标：让你可以在当前仓库 `C:\D\WORK\NewP\Admin.NET-v2` 上完成本地环境准备、后端启动、前端启动、`hw-portal` 插件识别，以及数据库和其他配置修改。
- 说明：本仓库当前后端为 `net8.0;net10.0` 双目标，前端实际依赖以 `Web/package.json` 为准，当前为 `Node >= 18`、`pnpm 10.28.2`、`vite ^7.3.1`、`vue ^3.5.28`。

## 2. 必需环境

### 2.1 后端必需

1. 安装 `.NET SDK 10.x`
   - 这是当前项目的主目标框架之一，后续新增的 `hw-portal` 插件也已按 `net8.0;net10.0` 配置。
   - 推荐直接安装最新稳定版 `.NET 10 SDK`。
2. 建议同时安装 `.NET SDK 8.x`
   - 虽然通常高版本 SDK 可以处理低版本目标框架，但本项目是双目标，装上 8.x 能减少还原/构建时的目标框架兼容风险。
3. 安装 `ASP.NET Core Runtime`
   - 若已安装 SDK，通常已包含开发所需运行时。
4. 数据库
   - 当前默认配置是 `Sqlite`，不需要额外安装数据库服务。
   - 如果后续切换到 `MySql`、`PostgreSQL`、`SqlServer`，再安装对应数据库即可。

### 2.2 前端必需

1. 安装 `Node.js 18+`
2. 安装 `pnpm`
   - 推荐：`npm install -g pnpm`
3. 建议安装 `Git`

### 2.3 编辑器建议

- 不装 Visual Studio 也可以开发。
- 推荐最小组合：
  - `VS Code`
  - `C# Dev Kit`
  - `C#`
  - `Vue - Official`
  - `TypeScript Vue Plugin (Volar)`
  - `ESLint`

### 2.4 PowerShell

- 当前仓库部分前端脚本使用 `pwsh`，建议安装 `PowerShell 7`。
- 如果只跑最基本的前后端启动，Windows 自带 PowerShell 也基本够用。

## 3. Windows 新机器安装顺序

### 3.1 推荐顺序

1. 安装 `Git`
2. 安装 `Node.js 18+`
3. 执行 `npm install -g pnpm`
4. 安装 `.NET SDK 10.x`
5. 建议再安装 `.NET SDK 8.x`
6. 安装 `VS Code`
7. 安装 VS Code 扩展：`C# Dev Kit`、`C#`、`Vue - Official`

### 3.2 安装后自检命令

在 PowerShell 里执行：

```powershell
git --version
node -v
pnpm -v
dotnet --list-sdks
dotnet --info
```

至少应满足：

- `node` 版本 `>= 18`
- `pnpm` 可用
- `dotnet --list-sdks` 能看到 `8.x` 和/或 `10.x`

## 4. 项目启动教程

## 4.1 打开仓库

仓库根目录：

```text
C:\D\WORK\NewP\Admin.NET-v2
```

## 4.2 后端启动

后端解决方案目录：

```text
C:\D\WORK\NewP\Admin.NET-v2\Admin.NET
```

首次执行：

```powershell
cd C:\D\WORK\NewP\Admin.NET-v2
dotnet restore .\Admin.NET\Admin.NET.sln
dotnet build .\Admin.NET\Admin.NET.sln -c Debug
```

启动后端：

```powershell
dotnet run --project .\Admin.NET\Admin.NET.Web.Entry
```

默认监听地址来自：

```text
Admin.NET\Admin.NET.Application\Configuration\App.json
```

当前默认端口：

```json
"Urls": "http://*:5005"
```

也就是本机通常访问：

```text
http://localhost:5005
```

## 4.3 前端启动

前端目录：

```text
C:\D\WORK\NewP\Admin.NET-v2\Web
```

首次执行：

```powershell
cd C:\D\WORK\NewP\Admin.NET-v2
pnpm install --dir Web
```

启动前端：

```powershell
pnpm --dir Web dev
```

当前前端开发端口来自：

```text
Web\.env
```

默认是：

```text
VITE_PORT = 8888
```

所以前端开发地址通常是：

```text
http://localhost:8888
```

## 4.4 前后端联调

当前前端开发环境接口地址来自：

```text
Web\.env.development
```

默认值：

```text
VITE_API_URL = http://localhost:5005
```

因此标准联调顺序是：

1. 先启动后端 `5005`
2. 再启动前端 `8888`
3. 浏览器访问 `http://localhost:8888`

## 4.5 默认账号

前端开发环境默认登录信息来自：

```text
Web\.env.development
```

当前值：

```text
VITE_DEFAULT_USER = superAdmin.NET
VITE_DEFAULT_USER_PASSWORD = Admin.NET++010101
```

## 5. 数据库配置修改教程

## 5.1 当前默认数据库

当前后端默认数据库配置文件：

```text
Admin.NET\Admin.NET.Application\Configuration\Database.json
```

当前默认是：

- `DbType = Sqlite`
- `ConnectionString = DataSource=./Admin.NET.db`

这意味着：

- 默认直接在后端运行目录生成/使用 SQLite 文件
- 本机第一次启动时，如果初始化开关打开，会自动建库建表和种子

## 5.2 改成 MySQL / PostgreSQL / SQL Server

你主要只改这里：

```text
Admin.NET\Admin.NET.Application\Configuration\Database.json
```

重点字段：

- `DbConnection.ConnectionConfigs[0].DbType`
- `DbConnection.ConnectionConfigs[0].ConnectionString`
- `DbSettings`
- `TableSettings`
- `SeedSettings`

示例思路：

- MySQL：把 `DbType` 改成 `MySql`
- PostgreSQL：把 `DbType` 改成 `PostgreSQL`
- SQL Server：把 `DbType` 改成 `SqlServer`

首次迁移 `hw-portal` 数据时建议：

- 先确认连接串可用
- 首次导入已有业务库时，谨慎检查 `EnableInitDb`、`EnableInitTable`、`EnableInitSeed`
- 如果数据库表结构已经存在且不希望框架自动处理，建议酌情关闭初始化开关

## 5.3 与 `hw-portal` 相关的数据库说明

- `hw-portal` 当前是插件模块
- 其 SQL 原文保存在：

```text
Admin.NET\Plugins\Admin.NET.Plugin.HwPortal\Sql
```

- 这些 XML 是从 `ruoyi-portal` 原样拷贝过来的，当前迁移策略是：
  - 表结构不变
  - SQL 不变
  - C# 侧通过 XML 执行器读取并执行这些 SQL

## 6. 其余配置文件地址

## 6.1 后端核心启动与宿主

- 后端入口：
  - `Admin.NET\Admin.NET.Web.Entry\Program.cs`
- 后端核心装配：
  - `Admin.NET\Admin.NET.Web.Core\Startup.cs`

## 6.2 后端主要配置目录

统一配置目录：

```text
Admin.NET\Admin.NET.Application\Configuration
```

常用文件如下：

- 应用地址、端口、动态 API、CORS、异常：
  - `Admin.NET\Admin.NET.Application\Configuration\App.json`
- 数据库：
  - `Admin.NET\Admin.NET.Application\Configuration\Database.json`
- 缓存：
  - `Admin.NET\Admin.NET.Application\Configuration\Cache.json`
- JWT：
  - `Admin.NET\Admin.NET.Application\Configuration\JWT.json`
- 限流：
  - `Admin.NET\Admin.NET.Application\Configuration\Limit.json`
- 日志：
  - `Admin.NET\Admin.NET.Application\Configuration\Logging.json`
- 事件总线：
  - `Admin.NET\Admin.NET.Application\Configuration\EventBus.json`
- Swagger：
  - `Admin.NET\Admin.NET.Application\Configuration\Swagger.json`
- 上传：
  - `Admin.NET\Admin.NET.Application\Configuration\Upload.json`
- OAuth：
  - `Admin.NET\Admin.NET.Application\Configuration\OAuth.json`
- 邮件：
  - `Admin.NET\Admin.NET.Application\Configuration\Email.json`
- 短信：
  - `Admin.NET\Admin.NET.Application\Configuration\SMS.json`
- 验证码：
  - `Admin.NET\Admin.NET.Application\Configuration\Captcha.json`
- 微信：
  - `Admin.NET\Admin.NET.Application\Configuration\Wechat.json`
- 支付宝：
  - `Admin.NET\Admin.NET.Application\Configuration\Alipay.json`
- ElasticSearch：
  - `Admin.NET\Admin.NET.Application\Configuration\ElasticSearch.json`

## 6.3 前端配置入口

- 前端依赖与脚本：
  - `Web\package.json`
- Vite 配置：
  - `Web\vite.config.ts`
- 通用前端环境变量：
  - `Web\.env`
- 开发环境变量：
  - `Web\.env.development`
- 生产环境变量：
  - `Web\.env.production`

当前最常改的前端配置项：

- `VITE_PORT`
- `VITE_API_URL`
- `VITE_PUBLIC_PATH`
- `VITE_SM_PUBLIC_KEY`

## 6.4 `hw-portal` 模块接入文件

- 插件项目文件：
  - `Admin.NET\Plugins\Admin.NET.Plugin.HwPortal\Admin.NET.Plugin.HwPortal.csproj`
- 插件启动注册：
  - `Admin.NET\Plugins\Admin.NET.Plugin.HwPortal\Startup.cs`
- 解决方案挂载：
  - `Admin.NET\Admin.NET.sln`
- 应用层引用插件：
  - `Admin.NET\Admin.NET.Application\Admin.NET.Application.csproj`

## 7. `hw-portal` 插件模块结构

当前模块根目录：

```text
Admin.NET\Plugins\Admin.NET.Plugin.HwPortal
```

结构说明：

- `Common`
  - 放统一返回、基础实体、控制器基类、上下文辅助
- `Controllers`
  - 放与原 Spring Controller 对应的 ASP.NET Controller
- `Dto`
  - 放请求/返回 DTO、树结构 DTO、搜索 DTO
- `Entity`
  - 放 `hw_*` 实体模型
- `Infrastructure`
  - 放 MyBatis XML 渲染器与执行器
- `Service`
  - 放业务服务
- `Service\Analytics`
  - 放官网访问统计服务
- `Service\Search`
  - 放搜索服务、搜索索引重建接口、文本提取器
- `Sql`
  - 放从 `ruoyi-portal` 原样复制过来的 MyBatis XML

## 8. 推荐启动顺序

## 8.1 第一次启动

1. 安装 `.NET SDK`
2. 安装 `Node.js` 和 `pnpm`
3. 执行后端 `restore`
4. 执行后端 `build`
5. 执行后端 `run`
6. 执行前端 `pnpm install`
7. 执行前端 `pnpm --dir Web dev`

## 8.2 命令清单

```powershell
cd C:\D\WORK\NewP\Admin.NET-v2

dotnet restore .\Admin.NET\Admin.NET.sln
dotnet build .\Admin.NET\Admin.NET.sln -c Debug
dotnet run --project .\Admin.NET\Admin.NET.Web.Entry
```

另开一个终端：

```powershell
cd C:\D\WORK\NewP\Admin.NET-v2

pnpm install --dir Web
pnpm --dir Web dev
```

## 9. 当前已知注意事项

1. 你这台机器当前没有 .NET 环境，因此现在还不能直接运行后端命令。
2. 本仓库当前最省事的本地数据库是 `SQLite`，第一次跑通建议先不要切换到外部数据库。
3. `hw-portal` 目前已经接成插件模块，但后续仍建议在装好 SDK 后做一次完整编译和接口联调。
4. 若后续你要改端口，后端改 `App.json`，前端改 `.env` / `.env.development`。

## 10. 你下一步最小操作建议

1. 先安装 `Node.js 18+`
2. 安装 `pnpm`
3. 安装 `.NET SDK 10.x`
4. 建议补装 `.NET SDK 8.x`
5. 用 VS Code 打开仓库
6. 先跑后端，再跑前端
7. 能跑通后，再决定是否切换数据库

最自律帅气聪明的臧辰浩