第二章：环境搭建与项目运行

1. 开发环境需求

1.1 系统要求

Admin.NET支持多种操作系统进行开发：

Windows系统：

Windows 10 1607或更高版本
Windows 11
Windows Server 2016或更高版本

macOS系统：

macOS 10.15 Catalina或更高版本
推荐使用Apple Silicon芯片的Mac

Linux系统：

Ubuntu 18.04或更高版本
CentOS 7或更高版本
Debian 9或更高版本
其他主流Linux发行版

1.2 硬件要求

最低配置：

CPU：双核2.0GHz或更高
内存：8GB RAM
硬盘：50GB可用空间
网络：稳定的互联网连接

推荐配置：

CPU：四核3.0GHz或更高
内存：16GB RAM或更高
硬盘：SSD 100GB可用空间
网络：高速稳定的互联网连接

1.3 软件要求清单

软件	版本要求	用途
.NET SDK	6.0/7.0/8.0	后端开发运行环境
Visual Studio 2022 / Rider	最新版	后端IDE
Node.js	16.x/18.x/20.x	前端运行环境
pnpm	8.x/9.x	前端包管理器
VS Code	最新版	前端IDE
Git	最新版	版本控制
MySQL/SQL Server/PostgreSQL	见下文	数据库
Redis	5.x或更高	缓存服务（可选）

2. 后端开发环境搭建

2.1 安装.NET SDK

2.1.1 Windows安装

方式一：使用安装包

访问.NET官方下载页面：https://dotnet.microsoft.com/download
选择.NET 8.0（推荐）或.NET 6.0 LTS版本
下载Windows x64安装程序
运行安装程序，按照向导完成安装
验证安装：

# 打开PowerShell或命令提示符
dotnet --version
# 输出类似：8.0.100

dotnet --list-sdks
# 列出所有已安装的SDK版本

方式二：使用winget（Windows包管理器）

# 安装.NET 8 SDK
winget install Microsoft.DotNet.SDK.8

# 或安装.NET 6 SDK
winget install Microsoft.DotNet.SDK.6

方式三：使用Chocolatey

# 首先安装Chocolatey（如果没有）
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

# 安装.NET SDK
choco install dotnet-sdk -y

2.1.2 macOS安装

方式一：使用安装包

访问.NET官方下载页面
选择macOS版本（注意区分Intel和Apple Silicon）
下载.pkg安装包
双击运行安装

方式二：使用Homebrew

# 安装Homebrew（如果没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装.NET SDK
brew install --cask dotnet-sdk

# 验证安装
dotnet --version

2.1.3 Linux安装（Ubuntu/Debian）

# 添加Microsoft包仓库
wget https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

# 安装.NET SDK
sudo apt-get update
sudo apt-get install -y dotnet-sdk-8.0

# 验证安装
dotnet --version

2.1.4 Linux安装（CentOS/RHEL）

# 添加Microsoft仓库
sudo rpm -Uvh https://packages.microsoft.com/config/centos/7/packages-microsoft-prod.rpm

# 安装.NET SDK
sudo yum install -y dotnet-sdk-8.0

# 验证安装
dotnet --version

2.2 安装Visual Studio 2022

Visual Studio 2022是Windows平台上开发.NET项目的首选IDE。

安装步骤：

访问Visual Studio官网：https://visualstudio.microsoft.com/
下载Visual Studio 2022社区版（免费）
运行安装程序
在工作负载页面，选择以下组件：
- ASP.NET和Web开发
- .NET桌面开发
- 数据存储和处理
在单个组件页面，确保选择：
- .NET 6.0 Runtime
- .NET 8.0 Runtime
- NuGet包管理器
点击安装，等待安装完成

推荐扩展：

安装完成后，建议安装以下扩展提升开发效率：

CodeMaid：代码清理和格式化
ReSharper（付费）：代码分析和重构
GitHub Copilot：AI代码助手
Visual Studio IntelliCode：AI辅助编码

2.3 安装JetBrains Rider（可选）

Rider是JetBrains推出的跨平台.NET IDE，在macOS和Linux上是很好的选择。

安装步骤：

访问JetBrains官网：https://www.jetbrains.com/rider/
下载适合你操作系统的版本
运行安装程序完成安装
首次启动时配置.NET SDK路径

Rider优势：

跨平台支持
内置代码分析
更好的性能（对于大型项目）
统一的JetBrains开发体验

2.4 配置NuGet源

Admin.NET项目需要从NuGet获取依赖包。在国内环境下，建议配置镜像源以提高下载速度。

方式一：配置nuget.config文件

在用户目录下创建或修改nuget.config文件：

Windows位置：%APPDATA%\NuGet\NuGet.Config macOS/Linux位置：~/.nuget/NuGet/NuGet.Config

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="huaweicloud" value="https://repo.huaweicloud.com/repository/nuget/v3/index.json" />
    <add key="cnblogs" value="https://nuget.cnblogs.com/v3/index.json" />
  </packageSources>
</configuration>

方式二：使用dotnet命令

# 添加华为云镜像
dotnet nuget add source https://repo.huaweicloud.com/repository/nuget/v3/index.json -n huaweicloud

# 查看已配置的源
dotnet nuget list source

3. 前端开发环境搭建

3.1 安装Node.js

3.1.1 Windows安装

方式一：官网下载

访问Node.js官网：https://nodejs.org/
下载LTS版本（推荐20.x）
运行安装程序，全部使用默认选项
验证安装：

node --version
# v20.x.x

npm --version
# 10.x.x

方式二：使用nvm-windows（推荐）

nvm允许你管理多个Node.js版本：

# 下载nvm-windows
# https://github.com/coreybutler/nvm-windows/releases

# 安装完成后
nvm install 20
nvm use 20

# 验证
node --version

3.1.2 macOS/Linux安装

使用nvm（推荐）

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重启终端后安装Node.js
nvm install 20
nvm use 20
nvm alias default 20

# 验证
node --version
npm --version

使用Homebrew（macOS）

brew install node@20

3.2 安装pnpm

Admin.NET前端项目使用pnpm作为包管理器，相比npm有更快的安装速度和更小的磁盘占用。

安装方式：

# 使用npm安装（推荐）
npm install -g pnpm

# 使用Homebrew（macOS）
brew install pnpm

# 验证安装
pnpm --version
# 9.x.x

配置pnpm镜像：

# 配置淘宝镜像
pnpm config set registry https://registry.npmmirror.com

# 验证配置
pnpm config get registry

3.3 安装VS Code

Visual Studio Code是前端开发的首选编辑器。

安装步骤：

访问VS Code官网：https://code.visualstudio.com/
下载对应系统的安装包
完成安装

推荐扩展：

安装以下扩展以获得最佳Vue3开发体验：

{
  "recommendations": [
    "Vue.volar",                    // Vue语言服务
    "Vue.vscode-typescript-vue-plugin", // TypeScript Vue插件
    "dbaeumer.vscode-eslint",       // ESLint
    "esbenp.prettier-vscode",       // Prettier代码格式化
    "antfu.iconify",               // Iconify图标预览
    "lokalise.i18n-ally",          // 国际化支持
    "bradlc.vscode-tailwindcss",   // TailwindCSS智能提示
    "formulahendry.auto-rename-tag", // 自动重命名标签
    "usernamehw.errorlens"         // 错误高亮显示
  ]
}

VS Code配置：

在VS Code设置中添加以下配置：

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "[vue]": {
    "editor.defaultFormatter": "Vue.volar"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

3.4 安装Git

3.4.1 Windows安装

访问Git官网：https://git-scm.com/download/win
下载并运行安装程序
安装选项保持默认即可
配置Git：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

3.4.2 macOS/Linux安装

# macOS
brew install git

# Ubuntu/Debian
sudo apt-get install git

# CentOS
sudo yum install git

# 配置
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

4. 数据库环境配置

Admin.NET支持多种数据库，以下介绍常用数据库的安装配置。

4.1 MySQL安装与配置

4.1.1 Windows安装

方式一：MySQL Installer

访问MySQL官网：https://dev.mysql.com/downloads/installer/
下载MySQL Installer
运行安装程序，选择”Developer Default”模式
设置root密码（请牢记）
完成安装

方式二：使用Docker

# 拉取MySQL镜像
docker pull mysql:8.0

# 运行MySQL容器
docker run -d --name mysql8 -p 3306:3306 -e MYSQL_ROOT_PASSWORD=Admin.NET -e MYSQL_DATABASE=AdminNET mysql:8.0

4.1.2 Linux安装（Ubuntu）

# 安装MySQL Server
sudo apt-get update
sudo apt-get install mysql-server

# 启动MySQL服务
sudo systemctl start mysql
sudo systemctl enable mysql

# 安全配置
sudo mysql_secure_installation

# 创建数据库用户
sudo mysql -u root -p

-- 创建数据库
CREATE DATABASE AdminNET DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

-- 创建用户
CREATE USER 'admin'@'%' IDENTIFIED BY 'Admin.NET';

-- 授权
GRANT ALL PRIVILEGES ON AdminNET.* TO 'admin'@'%';
FLUSH PRIVILEGES;

4.1.3 MySQL配置优化

编辑my.cnf（Linux）或my.ini（Windows）：

[mysqld]
# 字符集设置
character-set-server=utf8mb4
collation-server=utf8mb4_general_ci

# 连接数设置
max_connections=500

# 缓存设置
innodb_buffer_pool_size=1G
query_cache_size=128M

# 日志设置
slow_query_log=1
slow_query_log_file=/var/log/mysql/slow.log
long_query_time=2

[client]
default-character-set=utf8mb4

4.2 SQL Server安装与配置

4.2.1 Windows安装

访问SQL Server下载页面：https://www.microsoft.com/sql-server/sql-server-downloads
下载Developer版本（免费）或Express版本
运行安装程序
选择”基本”安装类型
接受许可条款，选择安装位置
等待安装完成

安装SSMS（管理工具）：

下载SQL Server Management Studio
安装SSMS
使用SSMS连接数据库

4.2.2 Linux安装（Ubuntu）

# 添加Microsoft仓库
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
sudo add-apt-repository "$(wget -qO- https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/mssql-server-2022.list)"

# 安装SQL Server
sudo apt-get update
sudo apt-get install -y mssql-server

# 配置SQL Server
sudo /opt/mssql/bin/mssql-conf setup
# 选择版本：2 (Developer)
# 设置sa密码

# 启动服务
sudo systemctl start mssql-server
sudo systemctl enable mssql-server

4.2.3 使用Docker安装SQL Server

# 拉取镜像
docker pull mcr.microsoft.com/mssql/server:2022-latest

# 运行容器
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=Admin.NET123" \
   -p 1433:1433 --name sqlserver2022 \
   -d mcr.microsoft.com/mssql/server:2022-latest

4.3 PostgreSQL安装与配置

4.3.1 Windows安装

访问PostgreSQL官网：https://www.postgresql.org/download/windows/
下载安装程序
运行安装程序
设置超级用户密码
默认端口5432
完成安装

4.3.2 Linux安装

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# 启动服务
sudo systemctl start postgresql
sudo systemctl enable postgresql

# 创建用户和数据库
sudo -u postgres psql

-- 创建用户
CREATE USER admin WITH PASSWORD 'Admin.NET';

-- 创建数据库
CREATE DATABASE "AdminNET" OWNER admin;

-- 授权
GRANT ALL PRIVILEGES ON DATABASE "AdminNET" TO admin;

4.4 Redis安装与配置（可选）

Admin.NET支持使用Redis作为缓存服务器，推荐在生产环境中使用。

4.4.1 Windows安装

Windows没有官方Redis，可以使用以下方式：

方式一：使用Docker

docker run -d --name redis -p 6379:6379 redis:7

方式二：使用WSL2

# 在WSL2中
sudo apt-get install redis-server
sudo service redis-server start

4.4.2 Linux安装

# Ubuntu/Debian
sudo apt-get install redis-server

# 启动服务
sudo systemctl start redis
sudo systemctl enable redis

# 验证
redis-cli ping
# 返回PONG

4.4.3 Redis配置

编辑redis.conf：

# 绑定地址（生产环境建议绑定具体IP）
bind 0.0.0.0

# 端口
port 6379

# 密码
requirepass Admin.NET

# 最大内存
maxmemory 512mb

# 内存淘汰策略
maxmemory-policy allkeys-lru

# 持久化
appendonly yes

5. 获取Admin.NET源码

5.1 通过Git克隆

从Gitee克隆（推荐国内用户）：

# 克隆完整仓库
git clone https://gitee.com/zuohuaijun/Admin.NET.git

# 或者只克隆最新版本（更快）
git clone --depth 1 https://gitee.com/zuohuaijun/Admin.NET.git

# 进入项目目录
cd Admin.NET

从GitHub克隆：

git clone https://github.com/zuohuaijun/Admin.NET.git

从GitCode克隆：

git clone https://gitcode.com/zuohuaijun/Admin.NET.git

5.2 下载ZIP包

如果不熟悉Git，也可以直接下载源码包：

访问Gitee仓库页面
点击”克隆/下载”按钮
选择”下载ZIP”
解压到合适的目录

5.3 项目目录结构

克隆完成后，项目目录结构如下：

Admin.NET/
├── Admin.NET/                    # 后端解决方案
│   ├── Admin.NET.Application/    # 应用层（示例）
│   ├── Admin.NET.Core/           # 核心层（核心功能）
│   ├── Admin.NET.Test/           # 测试项目
│   ├── Admin.NET.Web.Core/       # Web核心配置
│   ├── Admin.NET.Web.Entry/      # Web启动入口
│   ├── Plugins/                  # 插件目录
│   └── Admin.NET.sln            # 解决方案文件
├── Web/                          # 前端项目
│   ├── src/                      # 源代码
│   ├── public/                   # 静态资源
│   ├── package.json             # 包配置
│   └── vite.config.ts           # Vite配置
├── docker/                       # Docker配置
├── doc/                          # 文档和图片
└── README.md                     # 项目说明

6. 后端项目配置与运行

6.1 配置数据库连接

打开配置文件Admin.NET/Admin.NET.Web.Entry/appsettings.json，修改数据库连接字符串：

MySQL配置：

{
  "DbSettings": {
    "EnableInitDb": true,
    "EnableInitSeed": true,
    "EnableDiffLog": false,
    "EnableUnderLine": true,
    "DbConfigs": [
      {
        "ConfigId": "1300000000001",
        "DbType": "MySql",
        "ConnectionString": "Data Source=localhost;Database=AdminNET;User ID=root;Password=Admin.NET;pooling=true;port=3306;sslmode=none;CharSet=utf8mb4;AllowLoadLocalInfile=true",
        "IsAutoCloseConnection": true,
        "EnableSqlLog": true
      }
    ]
  }
}

SQL Server配置：

{
  "DbSettings": {
    "EnableInitDb": true,
    "EnableInitSeed": true,
    "DbConfigs": [
      {
        "ConfigId": "1300000000001",
        "DbType": "SqlServer",
        "ConnectionString": "Data Source=localhost;Initial Catalog=AdminNET;User ID=sa;Password=Admin.NET123;TrustServerCertificate=true",
        "IsAutoCloseConnection": true,
        "EnableSqlLog": true
      }
    ]
  }
}

PostgreSQL配置：

{
  "DbSettings": {
    "EnableInitDb": true,
    "EnableInitSeed": true,
    "DbConfigs": [
      {
        "ConfigId": "1300000000001",
        "DbType": "PostgreSQL",
        "ConnectionString": "Host=localhost;Port=5432;Database=AdminNET;Username=admin;Password=Admin.NET",
        "IsAutoCloseConnection": true,
        "EnableSqlLog": true
      }
    ]
  }
}

6.2 配置Redis（可选）

如果使用Redis作为缓存，修改配置：

{
  "Cache": {
    "CacheType": "Redis",
    "Redis": {
      "ConnectionString": "localhost:6379,password=Admin.NET,defaultDatabase=0"
    }
  }
}

如果不使用Redis，保持默认的内存缓存：

{
  "Cache": {
    "CacheType": "Memory"
  }
}

6.3 使用Visual Studio运行

双击打开Admin.NET/Admin.NET.sln解决方案文件
等待Visual Studio加载项目和恢复NuGet包
将Admin.NET.Web.Entry设为启动项目（右键 -> 设为启动项目）
按F5或点击”开始调试”运行项目
浏览器自动打开Swagger API文档页面

首次运行说明：

首次运行时，系统会自动：

创建数据库（如果不存在）
创建所有表结构
插入种子数据

6.4 使用命令行运行

# 进入后端项目目录
cd Admin.NET/Admin.NET

# 还原NuGet包
dotnet restore

# 运行项目
cd Admin.NET.Web.Entry
dotnet run

# 或者指定环境
dotnet run --environment Development

运行成功后，可以访问：

Swagger文档：http://localhost:5005/swagger
健康检查：http://localhost:5005/health

6.5 验证后端运行

打开浏览器访问Swagger文档页面，可以看到所有API接口列表。

测试登录接口：

找到/api/sysAuth/login接口
点击”Try it out”

输入登录信息：

{
  "account": "superAdmin",
  "password": "123456"
}

点击Execute
获得成功响应，包含Token

7. 前端项目配置与运行

7.1 安装依赖

# 进入前端项目目录
cd Web

# 安装依赖（使用pnpm）
pnpm install

# 如果安装失败，尝试清除缓存后重试
pnpm store prune
pnpm install

常见依赖安装问题：

如果遇到网络问题，可以使用镜像：

# 设置镜像
pnpm config set registry https://registry.npmmirror.com

# 重新安装
pnpm install

7.2 配置后端接口地址

打开Web/.env.development文件，确认后端接口地址：

# 开发环境配置
VITE_PORT = 2800
VITE_OPEN = true
VITE_API_URL = http://localhost:5005

7.3 启动开发服务器

# 启动开发服务器
pnpm run dev

# 或者
pnpm dev

启动成功后，控制台会显示：

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:2800/
  ➜  Network: http://192.168.x.x:2800/

7.4 访问前端页面

浏览器打开 http://localhost:2800/
进入登录页面
输入默认账号密码：
- 账号：superAdmin
- 密码：123456
点击登录
成功进入系统首页

7.5 前端项目命令

# 开发环境运行
pnpm dev

# 生产环境构建
pnpm build

# 预览生产构建
pnpm preview

# 代码格式检查
pnpm lint

# 代码格式修复
pnpm lint:fix

# 生成API接口代码
pnpm api:build

8. 常见问题与解决方案

8.1 后端问题

问题1：NuGet包还原失败

症状：提示找不到包或网络超时

解决方案：

# 清除NuGet缓存
dotnet nuget locals all --clear

# 添加镜像源
dotnet nuget add source https://repo.huaweicloud.com/repository/nuget/v3/index.json -n huaweicloud

# 重新还原
dotnet restore

问题2：数据库连接失败

症状：启动时提示无法连接数据库

解决方案：

确认数据库服务已启动
检查连接字符串是否正确
检查防火墙是否阻止了端口
测试使用数据库客户端能否连接

问题3：端口被占用

症状：提示端口5005已被占用

解决方案：

修改launchSettings.json中的端口：

{
  "profiles": {
    "Admin.NET.Web.Entry": {
      "applicationUrl": "http://localhost:5006"
    }
  }
}

或者结束占用端口的进程：

# Windows
netstat -ano | findstr :5005
taskkill /PID <进程ID> /F

# Linux/macOS
lsof -i :5005
kill -9 <进程ID>

问题4：首次运行没有自动创建数据库

症状：提示数据库不存在

解决方案：

确认appsettings.json中EnableInitDb设置为true
确认数据库用户有创建数据库的权限
手动创建空数据库后重新运行

8.2 前端问题

问题1：pnpm install失败

症状：依赖安装报错或超时

解决方案：

# 清除缓存
pnpm store prune
rm -rf node_modules
rm pnpm-lock.yaml

# 使用镜像
pnpm config set registry https://registry.npmmirror.com

# 重新安装
pnpm install

问题2：Node.js版本不兼容

症状：运行时提示Node版本过低

解决方案：

# 查看当前版本
node --version

# 使用nvm切换版本
nvm install 20
nvm use 20

问题3：跨域请求失败

症状：浏览器控制台显示CORS错误

解决方案：

确认后端已正确配置CORS
检查.env.development中的API地址是否正确
确认后端服务正在运行

问题4：登录后跳转失败

症状：登录成功但页面空白或报错

解决方案：

清除浏览器缓存和localStorage
检查浏览器控制台错误信息
确认后端接口返回的数据格式正确

8.3 开发环境检查清单

在开始开发前，确认以下环境已正确配置：

.NET SDK安装成功（dotnet --version）
Node.js安装成功（node --version）
pnpm安装成功（pnpm --version）
Git安装成功（git --version）
数据库服务运行正常
后端项目能够正常启动
前端项目能够正常启动
能够成功登录系统

总结

本章详细介绍了Admin.NET开发环境的搭建过程，包括：

后端环境：.NET SDK、Visual Studio/Rider、NuGet配置
前端环境：Node.js、pnpm、VS Code及其扩展
数据库环境：MySQL、SQL Server、PostgreSQL的安装配置
Redis缓存：可选的缓存服务配置
源码获取：Git克隆或下载ZIP包
项目运行：后端和前端的配置与启动
常见问题：各种问题的排查与解决

完成本章的环境搭建后，你应该能够成功运行Admin.NET项目，并访问系统的登录页面。在下一章中，我们将深入了解Admin.NET的项目架构和核心模块。