zangch
/
hw-web
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '6d8d0cc5fb'
${ noResults }
hw-web/Admin.NET-v2/HW_PORTAL_本机环境配置与启动教程.md

9.6 KiB
Raw Blame History Unescape Escape

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 里执行：

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

至少应满足：

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

4. 项目启动教程

4.1 打开仓库

仓库根目录：

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

4.2 后端启动

后端解决方案目录：

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

首次执行：

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

默认监听地址来自：

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

当前默认端口：

"Urls": "http://*:5005"

也就是本机通常访问：

http://localhost:5005

4.3 前端启动

前端目录：

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

首次执行：

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

启动前端：

pnpm --dir Web dev

当前前端开发端口来自：

Web\.env

默认是：

VITE_PORT = 8888

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

http://localhost:8888

4.4 前后端联调

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

Web\.env.development

默认值：

VITE_API_URL = http://localhost:5005

因此标准联调顺序是：

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

4.5 默认账号

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

Web\.env.development

当前值：

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

5. 数据库配置修改教程

5.1 当前默认数据库

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

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

当前默认是：

  • DbType = Sqlite
  • ConnectionString = DataSource=./Admin.NET.db

这意味着：

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

5.2 改成 MySQL / PostgreSQL / SQL Server

你主要只改这里：

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 原文保存在：
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 后端主要配置目录

统一配置目录：

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 插件模块结构

当前模块根目录：

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 命令清单

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

另开一个终端：

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. 能跑通后，再决定是否切换数据库

最自律帅气聪明的臧辰浩