# 开发环境搭建指南

<cite>
**本文档引用的文件**
- [README.md](file://README.md)
- [starter/readme.md](file://starter/readme.md)
- [starter/00.auto-config-docker.cmd](file://starter/00.auto-config-docker.cmd)
- [starter/01.create database.cmd](file://starter/01.create database.cmd)
- [starter/02.migrate-db.cmd](file://starter/02.migrate-db.cmd)
- [starter/80.start-host.cmd](file://starter/80.start-host.cmd)
- [starter/91.install-node-module.cmd](file://starter/91.install-node-module.cmd)
- [starter/99.start-ui.cmd](file://starter/99.start-ui.cmd)
- [aspnet-core/create-database.bat](file://aspnet-core/create-database.bat)
- [aspnet-core/migrate-database.bat](file://aspnet-core/migrate-database.bat)
- [aspnet-core/migrate-db-cmd.bat](file://aspnet-core/migrate-db-cmd.bat)
- [docker-compose.yml](file://docker-compose.yml)
- [apps/vue/package.json](file://apps/vue/package.json)
- [apps/vue/vite.config.ts](file://apps/vue/vite.config.ts)
- [apps/vue/.env.development](file://apps/vue/.env.development)
</cite>

## 目录
1. [项目概述](#项目概述)
2. [前置要求](#前置要求)
3. [环境准备](#环境准备)
4. [后端开发环境搭建](#后端开发环境搭建)
5. [前端开发环境搭建](#前端开发环境搭建)
6. [自动化脚本详解](#自动化脚本详解)
7. [常见问题解决](#常见问题解决)
8. [故障排除指南](#故障排除指南)
9. [最佳实践建议](#最佳实践建议)

## 项目概述

本项目是一个基于 [vue-vben-admin](https://github.com/anncwb/vue-vben-admin) 的 ABP 框架后台管理界面，采用微服务架构设计。项目包含前后端分离的完整解决方案，支持多种数据库和部署方式。

### 技术栈概览

- **前端技术**: Vue 3, TypeScript, Vite, Ant Design Vue
- **后端技术**: .NET 6, ABP Framework, Entity Framework Core
- **数据库**: MySQL, PostgreSQL, SQL Server
- **消息队列**: RabbitMQ
- **缓存**: Redis
- **搜索引擎**: Elasticsearch
- **容器化**: Docker, Docker Compose

## 前置要求

### 系统要求

- **操作系统**: Windows 10/11, Linux, macOS
- **内存**: 至少 8GB RAM
- **磁盘空间**: 至少 20GB 可用空间
- **网络**: 稳定的互联网连接

### 必需软件

#### 1. 前端开发环境
- [Node.js](https://nodejs.org/) (版本 16+)
- [pnpm](https://pnpm.io/) 包管理器
- [Git](https://git-scm.com/)

#### 2. 后端开发环境
- [.NET 6 SDK](https://dotnet.microsoft.com/download/dotnet/6.0)
- [Visual Studio 2022](https://visualstudio.microsoft.com/) 或 [VS Code](https://code.visualstudio.com/)
- [Entity Framework Core Tools](https://docs.microsoft.com/en-us/ef/core/miscellaneous/cli/dotnet)

#### 3. 数据库和中间件
- [MySQL](https://www.mysql.com/) / [PostgreSQL](https://www.postgresql.org/) / [SQL Server](https://www.microsoft.com/sql-server)
- [RabbitMQ](https://www.rabbitmq.com/)
- [Redis](https://redis.io/)
- [Elasticsearch](https://www.elastic.co/elasticsearch/)

#### 4. 容器化环境（可选）
- [Docker Desktop](https://www.docker.com/products/docker-desktop)
- [Docker Compose](https://docs.docker.com/compose/)

## 环境准备

### 1. 设置 hosts 文件

**Windows 系统**:
编辑 `C:\Windows\System32\drivers\etc\hosts` 文件，添加以下内容：
```
127.0.0.1 host.docker.internal
```

**Linux/macOS 系统**:
编辑 `/etc/hosts` 文件，添加相同内容：
```
127.0.0.1 host.docker.internal
```

**Linux 系统后处理**:
修改完 hosts 文件后需要重启网络服务：
```bash
sudo /etc/init.d/network restart
```

### 2. 安装 .NET 工具

```bash
dotnet tool install --global LINGYUN.Abp.Cli
```

### 3. 安装 .NET 模板

```bash
dotnet new --install LINGYUN.Abp.MicroService.Templates
```

### 4. 创建项目（可选）

```bash
labp create MyCompanyName.MyProjectName \
  -pk MyPackageName \
  -o "D:\Project" \
  --dbms sqlserver \
  --cs "Server=127.0.0.1;Database=MyProject;User Id=sa;Password=123456" \
  --no-random-port
```

## 后端开发环境搭建

### 方法一：使用自动化脚本（推荐）

#### 步骤 1：自动配置 Docker 环境

```cmd
cd starter
00.auto-config-docker.cmd
```

该脚本会：
- 创建 Docker 网络 `nt`
- 启动 MySQL 数据库容器
- 启动 RabbitMQ 管理界面容器
- 启动 Redis 缓存容器
- 启动 Elasticsearch 搜索引擎容器
- 启动 Kibana 可视化工具

#### 步骤 2：创建数据库

```cmd
01.create database.cmd
```

该脚本会为以下服务创建数据库：
- 平台服务 (platform)
- 后台管理服务 (admin)
- 认证服务器 (auth-server)
- IdentityServer4 管理 (identityserver4-admin)
- 本地化管理 (localization)
- 实时消息 (messages)
- 任务管理 (task-management)
- Webhook 管理 (webhooks-management)

#### 步骤 3：迁移数据库

```cmd
02.migrate-db.cmd
```

该脚本会执行数据库迁移，创建所有必要的表结构和初始数据。

#### 步骤 4：启动后端服务

```cmd
80.start-host.cmd
```

该脚本会依次启动所有后端服务，每个服务之间有 12 秒的延迟。

### 方法二：手动启动服务

#### 1. 启动认证服务器

```cmd
cd aspnet-core/services/LY.MicroService.AuthServer.HttpApi.Host
dotnet run
```

#### 2. 启动平台管理服务

```cmd
cd aspnet-core/services/LY.MicroService.PlatformManagement.HttpApi.Host
dotnet run
```

#### 3. 启动其他服务

按照类似方式启动以下服务：
- LY.MicroService.IdentityServer.HttpApi.Host
- LY.MicroService.LocalizationManagement.HttpApi.Host
- LY.MicroService.RealtimeMessage.HttpApi.Host
- LY.MicroService.TaskManagement.HttpApi.Host
- LY.MicroService.WebhooksManagement.HttpApi.Host
- LY.MicroService.BackendAdmin.HttpApi.Host

### 方法三：使用 Docker Compose

```bash
docker-compose up --build -d
```

这将启动完整的微服务架构，包括所有后端服务和中间件。

## 前端开发环境搭建

### 步骤 1：安装 Node.js 依赖

```cmd
cd apps/vue
91.install-node-module.cmd
```

该脚本会：
- 切换到前端项目目录
- 使用 pnpm 安装所有依赖包
- 显示安装进度并暂停等待确认

### 步骤 2：启动前端开发服务器

```cmd
99.start-ui.cmd
```

该脚本会：
- 切换到前端项目目录
- 启动 Vite 开发服务器
- 监听热重载变化

### 步骤 3：访问应用

打开浏览器访问：
- 前端应用: http://localhost:3000
- 后端 API: http://localhost:30000
- RabbitMQ 管理界面: http://localhost:15672 (用户名: admin, 密码: admin)
- Elasticsearch: http://localhost:9200
- Kibana: http://localhost:5601

## 自动化脚本详解

### 后端脚本详解

#### 00.auto-config-docker.cmd

```cmd
docker network create --subnet=172.18.0.0/16 nt
```
创建自定义 Docker 网络，确保服务间通信正常。

#### 01.create database.cmd

```cmd
@echo off
cd ..\aspnet-core
create-database.bat
```
调用后端数据库创建脚本，为所有微服务创建对应的数据库实例。

#### 02.migrate-db.cmd

```cmd
@echo off
cd ..\aspnet-core
migrate-database.bat
```
执行数据库迁移，创建所有必要的表结构和初始数据。

#### 80.start-host.cmd

```cmd
@echo off
cls
title start-all
set stime=12
for /f "delims=" %%i in ('dir *.bat /b') do (
    echo %%i
    start %%i
    ping -n %stime% 127.1 >nul
)
```
批量启动所有后端服务，每个服务启动后等待 12 秒再启动下一个。

### 前端脚本详解

#### 91.install-node-module.cmd

```cmd
@echo off
cls
cd ../apps/vue/
title install-module
pnpm install
pause
```
安装前端项目的所有依赖包，使用 pnpm 提高安装效率。

#### 99.start-ui.cmd

```cmd
@echo off
cls
cd ../apps/vue/
title abp-next-admin-ui
pnpm run dev
```
启动前端开发服务器，启用热重载功能。

### 数据库管理脚本

#### migrate-db-cmd.bat

该脚本支持多种操作模式：

```cmd
migrate-db-cmd.bat [项目名称] [显示名称] [--参数]
```

- `--run`: 运行应用程序
- `--restore`: 恢复 NuGet 包
- `--ef-u`: 执行 Entity Framework 数据库更新

## 常见问题解决

### 1. Docker 相关问题

**问题**: Docker 容器启动失败
**解决方案**:
```bash
# 清理 Docker 环境
docker system prune -a
# 重新创建网络
docker network create --subnet=172.18.0.0/16 nt
```

**问题**: 端口冲突
**解决方案**:
修改 `docker-compose.yml` 中的端口映射，或停止占用端口的服务。

### 2. 数据库连接问题

**问题**: 数据库连接超时
**解决方案**:
- 检查数据库服务是否正常运行
- 验证连接字符串配置
- 确认防火墙设置允许连接

**问题**: 权限不足
**解决方案**:
```sql
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' IDENTIFIED BY 'password';
FLUSH PRIVILEGES;
```

### 3. 前端开发问题

**问题**: 依赖安装失败
**解决方案**:
```bash
# 清理缓存
pnpm store prune
# 重新安装
pnpm install
```

**问题**: 代理配置错误
**解决方案**:
检查 `.env.development` 文件中的代理配置：
```bash
VITE_PROXY=[["/connect","http://127.0.0.1:30000"],["/api","http://127.0.0.1:30000"]]
```

### 4. 后端编译问题

**问题**: EF 命令找不到
**解决方案**:
```bash
dotnet tool install --global dotnet-ef
```

**问题**: 端口被占用
**解决方案**:
修改 `appsettings.json` 中的端口配置，或使用随机端口：
```json
{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:0"
      }
    }
  }
}
```

## 故障排除指南

### 1. 环境检查清单

#### 基础环境检查
- [ ] Node.js 版本 >= 16
- [ ] .NET SDK 版本 >= 6.0
- [ ] Docker 服务已启动
- [ ] 网络连接正常

#### 数据库检查
- [ ] MySQL/PostgreSQL/SQL Server 服务运行
- [ ] 数据库用户权限正确
- [ ] 端口未被占用
- [ ] 连接字符串配置正确

#### 服务检查
- [ ] RabbitMQ 服务运行
- [ ] Redis 服务运行
- [ ] Elasticsearch 服务运行
- [ ] 各个微服务进程正常

### 2. 日志分析

#### 后端日志位置
```
aspnet-core/logs/
```

#### 前端日志位置
```
apps/vue/node_modules/.vite/
```

#### Docker 日志
```bash
# 查看特定容器日志
docker logs container_name

# 实时查看日志
docker logs -f container_name
```

### 3. 性能监控

#### CPU 和内存使用
```bash
# Windows
taskmgr

# Linux
top
htop

# Docker
docker stats
```

#### 网络连接检查
```bash
# 检查端口占用
netstat -an | findstr :30000

# 测试服务可用性
curl http://localhost:30000/healthz
```

## 最佳实践建议

### 1. 开发环境优化

#### 前端开发优化
- 使用 pnpm 替代 npm，提高安装速度
- 启用 Vite 的热重载功能
- 配置适当的代理设置

#### 后端开发优化
- 使用 Visual Studio 或 VS Code 的调试功能
- 启用 EF Core 的迁移功能
- 配置适当的日志级别

### 2. 性能优化建议

#### 数据库优化
- 定期清理日志表
- 优化查询语句
- 合理设置索引

#### 缓存策略
- 使用 Redis 缓存热点数据
- 配置合适的过期时间
- 监控缓存命中率

### 3. 安全考虑

#### 数据库安全
- 使用强密码
- 限制数据库访问权限
- 定期备份数据

#### 应用安全
- 启用 HTTPS
- 配置 CORS 策略
- 实施输入验证

### 4. 维护建议

#### 定期维护
- 更新依赖包
- 清理临时文件
- 监控系统资源

#### 备份策略
- 数据库定期备份
- 配置文件版本控制
- 日志轮转设置

通过遵循本指南，开发者可以快速搭建完整的开发环境，开始进行项目开发工作。如果遇到任何问题，请参考故障排除指南或寻求社区支持。