From 62f050a4f1e63c28c931111e80550044b9bf6870 Mon Sep 17 00:00:00 2001 From: sam Date: Fri, 13 Feb 2026 19:13:23 +0800 Subject: [PATCH] =?UTF-8?q?chore(docs):=20=E6=B7=BB=E5=8A=A0=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E5=AE=8C=E6=95=B4=E6=96=87=E6=A1=A3=E4=B8=8E=E5=BF=AB?= =?UTF-8?q?=E9=80=9F=E5=90=AF=E5=8A=A8=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增详细的 Fengling 项目文档，涵盖项目结构、技术栈、环境准备 - 包含后端与前端开发指南与规范说明 - 提供丰富的第三方组件安装及 Docker 容器部署示例 - 描述本地开发流程、测试策略及调试技巧 - 详细介绍生产环境部署、CI/CD 集成及云平台部署方案 - 增加监控、性能优化及故障排查的最佳实践 - 新建管理后台前端 Dockerfile 和对应 nginx 配置文件 - 新增项目快速启动的 README 指南，方便开发者快速上手 --- Frontend/Fengling.Backend.Admin/Dockerfile | 33 + Frontend/Fengling.Backend.Admin/nginx.conf | 62 + PROJECT_DOCUMENTATION.md | 1418 ++++++++++++++++++++ README.md | 178 +++ deploy.ps1 | 66 + deploy.sh | 60 + 6 files changed, 1817 insertions(+) create mode 100644 Frontend/Fengling.Backend.Admin/Dockerfile create mode 100644 Frontend/Fengling.Backend.Admin/nginx.conf create mode 100644 PROJECT_DOCUMENTATION.md create mode 100644 README.md create mode 100644 deploy.ps1 create mode 100644 deploy.sh diff --git a/Frontend/Fengling.Backend.Admin/Dockerfile b/Frontend/Fengling.Backend.Admin/Dockerfile new file mode 100644 index 0000000..e4bf4ce --- /dev/null +++ b/Frontend/Fengling.Backend.Admin/Dockerfile @@ -0,0 +1,33 @@ +# Frontend/Fengling.Backend.Admin/Dockerfile +FROM node:18-alpine AS build + +# 设置工作目录 +WORKDIR /app + +# 复制 package 文件 +COPY package.json pnpm-lock.yaml ./ + +# 安装 pnpm 和依赖 +RUN npm install -g pnpm +RUN pnpm install --frozen-lockfile + +# 复制源代码 +COPY . . + +# 构建应用 +RUN pnpm build + +# 生产阶段 +FROM nginx:alpine AS runtime + +# 复制构建产物 +COPY --from=build /app/dist /usr/share/nginx/html + +# 复制 nginx 配置 +COPY nginx.conf /etc/nginx/nginx.conf + +# 暴露端口 +EXPOSE 80 + +# 启动 nginx +CMD ["nginx", "-g", "daemon off;"] \ No newline at end of file diff --git a/Frontend/Fengling.Backend.Admin/nginx.conf b/Frontend/Fengling.Backend.Admin/nginx.conf new file mode 100644 index 0000000..646fa36 --- /dev/null +++ b/Frontend/Fengling.Backend.Admin/nginx.conf @@ -0,0 +1,62 @@ +# nginx.conf for Vue applications +events { + worker_connections 1024; +} + +http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + + # 日志格式 + log_format main '$remote_addr - $remote_user [$time_local] "$request" ' + '$status $body_bytes_sent "$http_referer" ' + '"$http_user_agent" "$http_x_forwarded_for"'; + + access_log /var/log/nginx/access.log main; + error_log /var/log/nginx/error.log; + + sendfile on; + tcp_nopush on; + tcp_nodelay on; + keepalive_timeout 65; + types_hash_max_size 2048; + + # Gzip 压缩 + gzip on; + gzip_vary on; + gzip_min_length 1024; + gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json; + + server { + listen 80; + server_name localhost; + + # 根路径 + location / { + root /usr/share/nginx/html; + index index.html index.htm; + try_files $uri $uri/ /index.html; # 支持 Vue Router history 模式 + } + + # 静态资源缓存 + location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { + expires 1y; + add_header Cache-Control "public, immutable"; + } + + # API 代理 (开发时可能需要) + location /api/ { + proxy_pass http://backend:80; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + + # 错误页面 + error_page 500 502 503 504 /50x.html; + location = /50x.html { + root /usr/share/nginx/html; + } + } +} \ No newline at end of file diff --git a/PROJECT_DOCUMENTATION.md b/PROJECT_DOCUMENTATION.md new file mode 100644 index 0000000..ecaff1a --- /dev/null +++ b/PROJECT_DOCUMENTATION.md @@ -0,0 +1,1418 @@ +# Fengling 项目完整文档 + +## 目录 + +1. [项目概述](#项目概述) +2. [技术栈](#技术栈) +3. [环境准备](#环境准备) +4. [后端开发](#后端开发) +5. [前端开发](#前端开发) +6. [第三方组件安装](#第三方组件安装) +7. [本地开发](#本地开发) +8. [测试](#测试) +9. [部署发布](#部署发布) +10. [CI/CD](#cicd) +11. [监控与维护](#监控与维护) +12. [常见问题](#常见问题) + +--- + +## 项目概述 + +Fengling 是一个基于 Clean Architecture 和 DDD 设计的企业级应用系统，包含管理后台和 H5 会员端两个前端应用，以及一个功能完善的后端服务。 + +### 项目结构 + +``` +Demo/ +├── Backend/ # 后端项目 (.NET 10) +│ ├── src/ +│ │ ├── Fengling.Backend.Domain/ # 领域层 +│ │ ├── Fengling.Backend.Infrastructure/ # 基础设施层 +│ │ └── Fengling.Backend.Web/ # Web 层 +│ ├── test/ # 测试项目 +│ └── scripts/ # 基础设施脚本 +├── Frontend/ +│ ├── Fengling.Backend.Admin/ # 管理后台 (Vue 3 + TypeScript) +│ └── Fengling.H5/ # H5会员端 (Vue 3 + TypeScript) +├── docs/ # 文档 +└── tests/ # 集成测试 +``` + +--- + +## 技术栈 + +### 后端技术栈 + +| 组件 | 版本 | 用途 | +|------|------|------| +| .NET | 10.0 | 运行时框架 | +| ASP.NET Core | 10.0 | Web 框架 | +| Entity Framework Core | 10.0 | ORM 框架 | +| SQLite | 内置 | 开发数据库 | +| Redis | 7.2 | 缓存和分布式锁 | +| FastEndpoints | 最新 | 高性能 Web API 框架 | +| MediatR | 最新 | 命令查询中介者模式 | +| FluentValidation | 最新 | 模型验证 | +| CAP | 最新 | 分布式事务和事件总线 | +| Hangfire | 最新 | 后台任务调度 | +| Serilog | 最新 | 日志记录 | +| Swagger | 最新 | API 文档 | +| Prometheus | 最新 | 监控指标 | + +### 前端技术栈 + +#### 管理后台 (Fengling.Backend.Admin) + +| 组件 | 版本 | 用途 | +|------|------|------| +| Vue | 3.5.25 | 前端框架 | +| TypeScript | 5.9.3 | 类型系统 | +| Vite | 7.3.1 | 构建工具 | +| Tailwind CSS | 4.1.18 | CSS 框架 | +| shadcn-vue | 2.8.0 | UI 组件库 | +| Pinia | 3.0.4 | 状态管理 | +| Vue Router | 4.6.4 | 路由管理 | +| Axios | 1.13.5 | HTTP 客户端 | + +#### H5会员端 (Fengling.H5) + +| 组件 | 版本 | 用途 | +|------|------|------| +| Vue | 3.5.13 | 前端框架 | +| TypeScript | 5.7.2 | 类型系统 | +| Vite | 6.0.5 | 构建工具 | +| Tailwind CSS | 3.4.17 | CSS 框架 | +| Radix Vue | 1.9.11 | UI 组件库 | +| Pinia | 2.3.0 | 状态管理 | +| Vue Router | 4.5.0 | 路由管理 | +| Axios | 1.7.9 | HTTP 客户端 | + +### 开发工具 + +| 工具 | 用途 | +|------|------| +| Visual Studio 2022 | 后端开发 IDE | +| VS Code | 前端开发 IDE | +| Docker Desktop | 容器化部署 | +| Node.js | 前端构建运行时 | +| pnpm | 前端包管理器 | +| Git | 版本控制 | + +--- + +## 环境准备 + +### 系统要求 + +- **操作系统**: Windows 10/11, macOS 12+, Ubuntu 20.04+ +- **内存**: 至少 8GB RAM (推荐 16GB) +- **磁盘空间**: 至少 20GB 可用空间 + +### 必需软件安装 + +#### 1. .NET SDK + +```bash +# 下载并安装 .NET 10 SDK +# 访问 https://dotnet.microsoft.com/download/dotnet/10.0 +# 或使用包管理器安装 + +# Windows (Chocolatey) +choco install dotnet-10.0-sdk + +# macOS (Homebrew) +brew install dotnet + +# Ubuntu/Debian +wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb +sudo dpkg -i packages-microsoft-prod.deb +sudo apt-get update +sudo apt-get install -y dotnet-sdk-10.0 +``` + +验证安装： +```bash +dotnet --version # 应显示 10.0.xxx +``` + +#### 2. Node.js 和 pnpm + +```bash +# 安装 Node.js (推荐 LTS 版本 18.x 或 20.x) +# 访问 https://nodejs.org/ + +# 安装 pnpm (比 npm/yarn 更快的包管理器) +npm install -g pnpm + +# 验证安装 +node --version +pnpm --version +``` + +#### 3. Docker Desktop + +```bash +# 下载并安装 Docker Desktop +# Windows/macOS: https://www.docker.com/products/docker-desktop/ +# Linux: https://docs.docker.com/engine/install/ + +# 验证安装 +docker --version +docker-compose --version +``` + +#### 4. Git + +```bash +# 下载并安装 Git +# https://git-scm.com/downloads + +# 配置 Git +git config --global user.name "Your Name" +git config --global user.email "your.email@example.com" +``` + +#### 5. IDE 配置 + +**Visual Studio 2022** (后端): +- 安装工作负载: ASP.NET 和 Web 开发 +- 安装扩展: ReSharper (可选但推荐) + +**VS Code** (前端): +```bash +# 推荐安装的扩展 +code --install-extension bradlc.vscode-tailwindcss +code --install-extension Vue.volar +code --install-extension ms-vscode.vscode-typescript-next +code --install-extension esbenp.prettier-vscode +code --install-extension ms-vscode.vscode-eslint +``` + +--- + +## 后端开发 + +### 项目结构说明 + +``` +Backend/ +├── src/ +│ ├── Fengling.Backend.Domain/ # 领域层 +│ │ ├── AggregatesModel/ # 聚合根 +│ │ ├── DomainEvents/ # 领域事件 +│ │ └── IntegrationEvents/ # 集成事件 +│ ├── Fengling.Backend.Infrastructure/ # 基础设施层 +│ │ ├── EntityConfigurations/ # EF Core 配置 +│ │ ├── Migrations/ # 数据库迁移 +│ │ └── Repositories/ # 仓储实现 +│ └── Fengling.Backend.Web/ # Web 层 +│ ├── Application/ # 应用服务 +│ ├── Endpoints/ # API 端点 +│ ├── Services/ # 业务服务 +│ └── Program.cs # 程序入口 +└── test/ # 测试项目 +``` + +### 启动基础设施服务 + +#### 方式一：使用 Docker Compose (推荐) + +```bash +# 进入脚本目录 +cd Backend/scripts + +# 启动基础设施 (Redis + MySQL) +docker-compose up -d + +# 或选择其他数据库 +docker-compose --profile sqlserver up -d # SQL Server +docker-compose --profile postgres up -d # PostgreSQL +docker-compose --profile kafka up -d # Kafka (包含 Zookeeper) + +# 查看运行状态 +docker-compose ps + +# 停止服务 +docker-compose down + +# 完全清理 (包括数据卷) +docker-compose down -v +``` + +#### 方式二：使用初始化脚本 + +```bash +# Windows PowerShell +cd Backend/scripts +.\init-infrastructure.ps1 + +# Linux/macOS +cd Backend/scripts +chmod +x init-infrastructure.sh +./init-infrastructure.sh + +# 清理环境 +./clean-infrastructure.sh # Linux/macOS +.\clean-infrastructure.ps1 # Windows +``` + +#### 方式三：Aspire (如果启用) + +```bash +# 如果项目启用了 Aspire +cd Backend/src/Fengling.Backend.AppHost +dotnet run +``` + +### 数据库配置 + +项目默认使用 SQLite 数据库进行开发，生产环境建议使用 MySQL/PostgreSQL。 + +#### 数据库连接配置 + +```json +// appsettings.json +{ + "ConnectionStrings": { + "SQLite": "Data Source=fengling.db", + "Redis": "localhost:6379" + } +} +``` + +#### 数据库迁移 + +```bash +# 安装 EF Core 工具 +dotnet tool install --global dotnet-ef + +# 添加新的迁移 +cd Backend/src/Fengling.Backend.Infrastructure +dotnet ef migrations add MigrationName + +# 更新数据库 +dotnet ef database update + +# 查看迁移历史 +dotnet ef migrations list +``` + +### 启动后端服务 + +```bash +# 进入 Web 项目目录 +cd Backend/src/Fengling.Backend.Web + +# 还原 NuGet 包 +dotnet restore + +# 构建项目 +dotnet build + +# 运行开发服务器 (端口 5511) +dotnet run + +# 或使用 watch 模式 (文件更改时自动重启) +dotnet watch run +``` + +### API 文档访问 + +启动后端服务后，可通过以下地址访问： + +- **Swagger UI**: http://localhost:5511/swagger +- **CAP Dashboard**: http://localhost:5511/cap +- **Hangfire Dashboard**: http://localhost:5511/hangfire +- **健康检查**: http://localhost:5511/health +- **监控指标**: http://localhost:5511/metrics +- **代码分析**: http://localhost:5511/code-analysis + +### 代码生成器配置 + +项目提供丰富的代码片段模板，提高开发效率： + +#### Visual Studio 配置 + +```powershell +# 自动安装代码片段 +cd Backend/vs-snippets +.\Install-VSSnippets.ps1 +``` + +#### VS Code 配置 + +代码片段已预配置在 `.vscode/csharp.code-snippets` 文件中。 + +#### 常用代码片段 + +| 快捷键 | 描述 | 生成内容 | +|--------|------|----------| +| `ncpcmd` | NetCorePal 命令 | ICommand 实现 | +| `ncpar` | 聚合根 | Entity 和 IAggregateRoot | +| `epp` | FastEndpoint | 完整端点实现 | +| `epreq` | 请求端点 | Endpoint | + +--- + +## 前端开发 + +### 管理后台 (Fengling.Backend.Admin) + +#### 项目初始化 + +```bash +# 进入项目目录 +cd Frontend/Fengling.Backend.Admin + +# 安装依赖 +pnpm install + +# 启动开发服务器 (端口 3000) +pnpm dev + +# 构建生产版本 +pnpm build + +# 预览生产构建 +pnpm preview +``` + +#### 环境变量配置 + +```bash +# 开发环境变量 (.env.development) +VITE_API_BASE_URL=http://localhost:5511 +VITE_APP_TITLE=Fengling 管理后台 + +# 生产环境变量 (.env.production) +VITE_API_BASE_URL=https://your-production-api.com +VITE_APP_TITLE=Fengling 管理后台 +``` + +#### 目录结构 + +``` +Fengling.Backend.Admin/ +├── src/ +│ ├── api/ # API 接口定义 +│ ├── components/ # 公共组件 +│ ├── layouts/ # 页面布局 +│ ├── pages/ # 页面组件 +│ ├── router/ # 路由配置 +│ ├── stores/ # 状态管理 (Pinia) +│ ├── styles/ # 全局样式 +│ └── utils/ # 工具函数 +├── public/ # 静态资源 +└── components.json # shadcn-vue 配置 +``` + +### H5会员端 (Fengling.H5) + +#### 项目初始化 + +```bash +# 进入项目目录 +cd Frontend/Fengling.H5 + +# 安装依赖 +pnpm install + +# 启动开发服务器 (端口 3001) +pnpm dev + +# 构建生产版本 +pnpm build + +# 预览生产构建 +pnpm preview +``` + +#### 环境变量配置 + +```bash +# 开发环境变量 (.env.development) +VITE_API_BASE_URL=http://localhost:5511 +VITE_APP_TITLE=Fengling 会员中心 + +# 生产环境变量 (.env.production) +VITE_API_BASE_URL=https://your-production-api.com +VITE_APP_TITLE=Fengling 会员中心 +``` + +#### 目录结构 + +``` +Fengling.H5/ +├── src/ +│ ├── api/ # API 接口定义 +│ ├── components/ # 公共组件 +│ ├── composables/ # Composition API 函数 +│ ├── layouts/ # 页面布局 +│ ├── pages/ # 页面组件 +│ ├── router/ # 路由配置 +│ ├── stores/ # 状态管理 (Pinia) +│ ├── styles/ # 全局样式 +│ └── utils/ # 工具函数 +├── public/ # 静态资源 +└── components.json # radix-vue 配置 +``` + +### 前端开发规范 + +#### 代码规范 + +- 使用 TypeScript 严格模式 +- 遵循 Composition API 风格 +- 组件使用 PascalCase 命名 +- 文件使用 kebab-case 命名 +- API 接口使用 camelCase 命名 + +#### 代码质量工具 + +```bash +# ESLint 检查 +pnpm lint + +# Prettier 格式化 +pnpm format + +# TypeScript 类型检查 +pnpm build # 或 vue-tsc +``` + +#### UI 组件库 + +- **管理后台**: 使用 shadcn-vue (基于 Tailwind CSS) +- **H5会员端**: 使用 radix-vue (基于 Tailwind CSS) + +添加新组件： +```bash +# shadcn-vue +npx shadcn-vue@latest add button + +# radix-vue +# 直接从 @radix-ui/vue-icons 导入图标 +``` + +--- + +## 第三方组件安装 + +### 后端组件 + +#### 数据库驱动 + +```xml + + + + + + + + +``` + +#### 缓存和分布式锁 + +```xml + + + + + +``` + +#### 消息队列 + +```xml + + + + + +``` + +#### 对象存储 + +```xml + + + + + + + + +``` + +#### 第三方服务集成 + +```xml + + + + + + + + + +``` + +### 前端组件 + +#### UI 组件库扩展 + +```bash +# 图标库 +pnpm add lucide-vue-next # 管理后台 +pnpm add @radix-icons/vue # H5会员端 + +# 表格组件 +pnpm add @tanstack/vue-table + +# 日期处理 +pnpm add date-fns + +# 工具库 +pnpm add class-variance-authority clsx tailwind-merge +``` + +#### 状态管理和工具 + +```bash +# 状态管理 (已包含) +pnpm add pinia + +# 路由 (已包含) +pnpm add vue-router + +# HTTP 客户端 (已包含) +pnpm add axios + +# 通知组件 +pnpm add vue-sonner + +# 实用工具 +pnpm add @vueuse/core +``` + +#### 开发工具 + +```bash +# 类型检查 +pnpm add -D vue-tsc typescript + +# 代码格式化 +pnpm add -D prettier eslint + +# 构建工具 (已包含) +pnpm add -D vite @vitejs/plugin-vue + +# CSS 框架 (已包含) +pnpm add -D tailwindcss autoprefixer postcss +``` + +### Docker 相关组件 + +#### 容器化部署 + +```dockerfile +# 后端 Dockerfile (已存在) +# Backend/src/Fengling.Backend.Web/Dockerfile + +# 前端 Dockerfile (需要创建) +# Frontend/Fengling.Backend.Admin/Dockerfile +# Frontend/Fengling.H5/Dockerfile +``` + +#### Nginx 配置 + +```nginx +# nginx.conf +server { + listen 80; + server_name your-domain.com; + + location / { + root /usr/share/nginx/html/admin; + try_files $uri $uri/ /index.html; + } + + location /h5/ { + alias /usr/share/nginx/html/h5/; + try_files $uri $uri/ /h5/index.html; + } + + location /api/ { + proxy_pass http://backend-service:80; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + } +} +``` + +--- + +## 本地开发 + +### 完整开发环境启动 + +#### 1. 启动基础设施 + +```bash +# 终端 1: 启动 Docker 服务 +cd Backend/scripts +docker-compose up -d +``` + +#### 2. 启动后端服务 + +```bash +# 终端 2: 启动后端 +cd Backend/src/Fengling.Backend.Web +dotnet watch run +``` + +#### 3. 启动前端服务 + +```bash +# 终端 3: 启动管理后台 +cd Frontend/Fengling.Backend.Admin +pnpm dev + +# 终端 4: 启动 H5会员端 +cd Frontend/Fengling.H5 +pnpm dev +``` + +### 开发环境访问地址 + +- **管理后台**: http://localhost:3000 +- **H5会员端**: http://localhost:3001 +- **后端 API**: http://localhost:5511 +- **Swagger 文档**: http://localhost:5511/swagger +- **Redis**: localhost:6379 +- **数据库**: fengling.db (SQLite 文件) + +### 开发调试技巧 + +#### 后端调试 + +```bash +# 使用 Visual Studio 调试 +# 设置断点 -> F5 启动调试 + +# 使用 VS Code 调试 +# 创建 .vscode/launch.json 配置 +``` + +#### 前端调试 + +```bash +# 浏览器开发者工具 +# F12 打开 -> Console 查看日志 +# Network 查看 API 请求 +# Vue DevTools 查看组件状态 + +# VS Code 调试配置 +# 创建 .vscode/launch.json +``` + +#### 数据库调试 + +```bash +# SQLite 浏览器工具 +# 下载 DB Browser for SQLite + +# 查看数据库内容 +sqlite3 fengling.db +.tables +.schema table_name +SELECT * FROM table_name LIMIT 10; +``` + +--- + +## 测试 + +### 后端测试 + +#### 单元测试 + +```bash +# 运行所有单元测试 +cd Backend +dotnet test + +# 运行特定项目测试 +dotnet test test/Fengling.Backend.Domain.Tests + +# 生成测试覆盖率报告 +dotnet test --collect:"XPlat Code Coverage" +``` + +#### 集成测试 + +```bash +# 运行集成测试 (包含 Testcontainers) +dotnet test test/Fengling.Backend.Web.Tests + +# 运行特定测试 +dotnet test --filter "FullyQualifiedName~YourTestName" +``` + +#### 测试项目结构 + +``` +test/ +├── Fengling.Backend.Domain.Tests/ # 领域层测试 +├── Fengling.Backend.Infrastructure.Tests/ # 基础设施层测试 +└── Fengling.Backend.Web.Tests/ # Web 层集成测试 +``` + +### 前端测试 + +#### 单元测试 + +```bash +# 管理后台测试 +cd Frontend/Fengling.Backend.Admin +pnpm test + +# H5会员端测试 +cd Frontend/Fengling.H5 +pnpm test +``` + +#### E2E 测试 + +```bash +# 安装 Cypress +pnpm add -D cypress + +# 运行 E2E 测试 +pnpm run test:e2e +``` + +#### 测试最佳实践 + +1. **后端测试**: + - 使用 Arrange-Act-Assert 模式 + - Mock 外部依赖 + - 测试边界条件和异常情况 + - 保持测试独立性 + +2. **前端测试**: + - 组件测试使用 Vue Test Utils + - 端到端测试使用 Cypress + - 测试用户交互场景 + - 模拟 API 响应 + +--- + +## 部署发布 + +### 生产环境配置 + +#### 后端生产配置 + +```json +// appsettings.Production.json +{ + "Logging": { + "LogLevel": { + "Default": "Warning", + "Microsoft.AspNetCore": "Warning" + } + }, + "ConnectionStrings": { + "SQLite": "Data Source=/app/data/fengling.db", + "Redis": "redis-host:6379,password=your-password" + }, + "AppConfiguration": { + "Secret": "YourProductionSecretKeyHere!!!", + "TokenExpiryInMinutes": 1440, + "JwtIssuer": "FenglingBackend", + "JwtAudience": "FenglingBackend" + } +} +``` + +#### 前端生产配置 + +```bash +# 管理后台 .env.production +VITE_API_BASE_URL=https://api.yourdomain.com +VITE_APP_TITLE=Fengling 管理后台 + +# H5会员端 .env.production +VITE_API_BASE_URL=https://api.yourdomain.com +VITE_APP_TITLE=Fengling 会员中心 +``` + +### Docker 部署 + +#### 后端 Docker 部署 + +```dockerfile +# Backend/src/Fengling.Backend.Web/Dockerfile +FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base +WORKDIR /app +EXPOSE 80 + +FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build +# ... 构建步骤 + +FROM base AS final +WORKDIR /app +COPY --from=publish /app/publish . +ENTRYPOINT ["dotnet", "Fengling.Backend.Web.dll"] +``` + +构建和运行： +```bash +# 构建镜像 +cd Backend +docker build -t fengling-backend:latest -f src/Fengling.Backend.Web/Dockerfile . + +# 运行容器 +docker run -d \ + --name fengling-backend \ + -p 8080:80 \ + -e ASPNETCORE_ENVIRONMENT=Production \ + fengling-backend:latest +``` + +#### 前端 Docker 部署 + +创建前端 Dockerfile： + +```dockerfile +# Frontend/Fengling.Backend.Admin/Dockerfile +FROM node:18-alpine AS build +WORKDIR /app +COPY package.json pnpm-lock.yaml ./ +RUN npm install -g pnpm +RUN pnpm install +COPY . . +RUN pnpm build + +FROM nginx:alpine AS runtime +COPY --from=build /app/dist /usr/share/nginx/html +COPY nginx.conf /etc/nginx/nginx.conf +EXPOSE 80 +CMD ["nginx", "-g", "daemon off;"] +``` + +构建和运行： +```bash +# 构建管理后台 +cd Frontend/Fengling.Backend.Admin +docker build -t fengling-admin:latest . + +# 构建 H5会员端 +cd Frontend/Fengling.H5 +docker build -t fengling-h5:latest . + +# 运行容器 +docker run -d -p 3000:80 fengling-admin:latest +docker run -d -p 3001:80 fengling-h5:latest +``` + +### Kubernetes 部署 (推荐生产环境) + +#### Helm Chart 结构 + +``` +helm-chart/ +├── Chart.yaml +├── values.yaml +├── templates/ +│ ├── deployment.yaml +│ ├── service.yaml +│ ├── ingress.yaml +│ ├── configmap.yaml +│ └── secret.yaml +└── README.md +``` + +#### 部署命令 + +```bash +# 添加 Helm 仓库 +helm repo add fengling https://your-helm-repo.com + +# 部署应用 +helm install fengling-app fengling/fengling \ + --set image.tag=v1.0.0 \ + --set replicaCount=3 \ + --set service.type=LoadBalancer + +# 升级应用 +helm upgrade fengling-app fengling/fengling --set image.tag=v1.0.1 + +# 回滚 +helm rollback fengling-app 1 + +# 卸载 +helm uninstall fengling-app +``` + +### 云平台部署 + +#### Azure App Service + +```bash +# 部署后端 +az webapp deploy \ + --resource-group myResourceGroup \ + --name fengling-backend \ + --src-path ../Backend/src/Fengling.Backend.Web/bin/Release/net10.0/publish.zip + +# 配置应用设置 +az webapp config appsettings set \ + --resource-group myResourceGroup \ + --name fengling-backend \ + --settings ASPNETCORE_ENVIRONMENT=Production +``` + +#### AWS Elastic Beanstalk + +```bash +# 初始化 EB 应用 +eb init -p docker fengling-backend + +# 部署应用 +eb create fengling-backend-env +eb deploy +``` + +#### 阿里云容器服务 + +```bash +# 构建并推送镜像 +docker build -t registry.cn-hangzhou.aliyuncs.com/your-namespace/fengling-backend:v1.0.0 . +docker push registry.cn-hangzhou.aliyuncs.com/your-namespace/fengling-backend:v1.0.0 + +# 使用阿里云 ACK 部署 +kubectl apply -f k8s-manifests/ +``` + +--- + +## CI/CD + +### GitHub Actions 示例 + +```yaml +# .github/workflows/ci-cd.yml +name: CI/CD Pipeline + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + +jobs: + build-and-test: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + # 后端构建测试 + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 10.0.x + + - name: Restore dependencies + run: dotnet restore + + - name: Build + run: dotnet build --no-restore + + - name: Test + run: dotnet test --no-build --verbosity normal + + # 前端构建测试 + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Install pnpm + run: npm install -g pnpm + + - name: Install frontend dependencies + run: | + cd Frontend/Fengling.Backend.Admin + pnpm install + cd ../Fengling.H5 + pnpm install + + - name: Build frontend + run: | + cd Frontend/Fengling.Backend.Admin + pnpm build + cd ../Fengling.H5 + pnpm build + + deploy: + needs: build-and-test + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' + + steps: + - name: Deploy to production + run: | + # 部署脚本 + echo "Deploying to production..." +``` + +### Jenkins Pipeline + +```groovy +pipeline { + agent any + + stages { + stage('Checkout') { + steps { + checkout scm + } + } + + stage('Backend Build') { + steps { + sh 'dotnet restore' + sh 'dotnet build --configuration Release' + sh 'dotnet test' + } + } + + stage('Frontend Build') { + steps { + dir('Frontend/Fengling.Backend.Admin') { + sh 'pnpm install' + sh 'pnpm build' + } + dir('Frontend/Fengling.H5') { + sh 'pnpm install' + sh 'pnpm build' + } + } + } + + stage('Docker Build') { + steps { + sh 'docker build -t fengling-backend:${BUILD_NUMBER} .' + sh 'docker push fengling-backend:${BUILD_NUMBER}' + } + } + + stage('Deploy') { + steps { + sh './deploy.sh ${BUILD_NUMBER}' + } + } + } +} +``` + +### 部署策略 + +1. **蓝绿部署**: 准备两套环境，切换流量 +2. **滚动更新**: 逐步替换实例 +3. **金丝雀发布**: 小范围用户先行体验 +4. **A/B 测试**: 对比不同版本效果 + +--- + +## 监控与维护 + +### 日志管理 + +#### 后端日志配置 + +```csharp +// Program.cs +builder.Host.UseSerilog((context, configuration) => configuration + .ReadFrom.Configuration(context.Configuration) + .Enrich.FromLogContext() + .WriteTo.Console() + .WriteTo.File("logs/app-.txt", rollingInterval: RollingInterval.Day)); +``` + +#### 结构化日志 + +```csharp +// 使用 Serilog 结构化日志 +logger.Information("User {UserId} logged in from {IpAddress}", userId, ipAddress); +logger.Error(ex, "Failed to process order {OrderId}", orderId); +``` + +### 性能监控 + +#### Prometheus 指标 + +```csharp +// 内置指标端点 +// http://localhost:5511/metrics + +// 自定义指标 +var counter = Metrics.CreateCounter("myapp_orders_total", "Total orders processed"); +counter.Inc(); +``` + +#### 应用性能监控 (APM) + +```xml + + +``` + +### 健康检查 + +```csharp +// Program.cs +builder.Services.AddHealthChecks() + .AddDbContextCheck() + .AddRedis(builder.Configuration.GetConnectionString("Redis")) + .ForwardToPrometheus(); +``` + +访问健康检查端点： +- http://localhost:5511/health + +### 数据备份 + +#### 数据库备份脚本 + +```bash +#!/bin/bash +# backup-db.sh + +DATE=$(date +%Y%m%d_%H%M%S) +BACKUP_DIR="/backups" +DB_FILE="fengling.db" + +# SQLite 备份 +cp "$DB_FILE" "$BACKUP_DIR/fengling_$DATE.db" + +# 压缩备份 +gzip "$BACKUP_DIR/fengling_$DATE.db" + +# 删除 7 天前的备份 +find "$BACKUP_DIR" -name "fengling_*.db.gz" -mtime +7 -delete +``` + +#### 自动化备份 + +```cron +# crontab -e +0 2 * * * /path/to/backup-db.sh # 每天凌晨 2 点备份 +``` + +### 故障排除 + +#### 常见问题诊断 + +1. **数据库连接失败**: + ```bash + # 检查连接字符串 + # 验证数据库服务状态 + docker-compose ps + ``` + +2. **Redis 连接问题**: + ```bash + # 测试 Redis 连接 + redis-cli ping + ``` + +3. **API 响应慢**: + ```bash + # 查看性能指标 + curl http://localhost:5511/metrics + ``` + +4. **前端白屏**: + ```bash + # 检查控制台错误 + # 验证 API 连接 + # 检查环境变量配置 + ``` + +--- + +## 常见问题 + +### 开发环境问题 + +**Q: 后端启动时报数据库连接错误？** +A: 确保 Docker 服务已启动，并且数据库容器正在运行： +```bash +docker-compose ps +docker-compose up -d mysql redis +``` + +**Q: 前端无法连接到后端 API？** +A: 检查以下几点： +1. 后端服务是否正常运行 (http://localhost:5511/health) +2. Vite 代理配置是否正确 +3. CORS 配置是否允许跨域请求 + +**Q: 缺少某些 NuGet 包？** +A: 还原包依赖： +```bash +dotnet restore +``` + +### 部署问题 + +**Q: Docker 镜像构建失败？** +A: 检查 Dockerfile 路径和上下文： +```bash +docker build -t app-name . # 注意最后的点 +``` + +**Q: 容器启动后立即退出？** +A: 查看容器日志： +```bash +docker logs container-name +``` + +**Q: 环境变量未生效？** +A: 确认环境变量传递方式： +```bash +# Docker run +docker run -e ENV_VAR=value image-name + +# Docker Compose +environment: + - ENV_VAR=value +``` + +### 性能优化 + +**Q: 如何优化数据库查询性能？** +A: +1. 添加适当的索引 +2. 使用 Include 预加载关联数据 +3. 分页查询大数据集 +4. 启用查询缓存 + +**Q: 前端打包体积过大？** +A: +1. 启用代码分割 +2. 移除未使用的依赖 +3. 使用 CDN 加载大型库 +4. 启用 gzip/brotli 压缩 + +### 安全考虑 + +**Q: 如何保护 API 接口？** +A: +1. 实施 JWT 身份验证 +2. 添加请求频率限制 +3. 验证所有输入参数 +4. 启用 HTTPS +5. 配置 CORS 策略 + +**Q: 敏感信息如何管理？** +A: +1. 使用 Secret Manager (开发) +2. 环境变量 (生产) +3. Azure Key Vault/AWS Secrets Manager +4. 不在代码中硬编码密码 + +--- + +## 附录 + +### 有用的命令集合 + +#### 后端常用命令 + +```bash +# 项目管理 +dotnet new sln # 创建解决方案 +dotnet sln add **/*.csproj # 添加项目到解决方案 +dotnet restore # 还原 NuGet 包 +dotnet build # 构建项目 +dotnet run # 运行项目 +dotnet watch run # 热重载运行 + +# 测试 +dotnet test # 运行测试 +dotnet test --filter "Category=Unit" # 运行特定类别测试 + +# EF Core +dotnet ef migrations add Name # 添加迁移 +dotnet ef database update # 更新数据库 +dotnet ef database drop # 删除数据库 + +# 发布 +dotnet publish -c Release # 发布项目 +dotnet publish -r win-x64 --self-contained # 自包含发布 +``` + +#### 前端常用命令 + +```bash +# 依赖管理 +pnpm install # 安装依赖 +pnpm add package-name # 添加依赖 +pnpm remove package-name # 移除依赖 +pnpm update # 更新依赖 + +# 开发 +pnpm dev # 启动开发服务器 +pnpm build # 构建生产版本 +pnpm preview # 预览构建结果 + +# 代码质量 +pnpm lint # ESLint 检查 +pnpm format # Prettier 格式化 +pnpm type-check # TypeScript 检查 +``` + +#### Docker 常用命令 + +```bash +# 镜像操作 +docker build -t image-name . # 构建镜像 +docker images # 查看镜像列表 +docker rmi image-name # 删除镜像 + +# 容器操作 +docker run -d -p 8080:80 image-name # 运行容器 +docker ps # 查看运行中的容器 +docker ps -a # 查看所有容器 +docker logs container-name # 查看容器日志 +docker exec -it container-name sh # 进入容器 + +# Compose +docker-compose up -d # 后台启动服务 +docker-compose down # 停止服务 +docker-compose logs # 查看日志 +``` + +### 参考资料 + +- [.NET 10 官方文档](https://learn.microsoft.com/zh-cn/dotnet/) +- [Vue 3 官方文档](https://vuejs.org/) +- [Tailwind CSS 文档](https://tailwindcss.com/) +- [Docker 官方文档](https://docs.docker.com/) +- [Kubernetes 官方文档](https://kubernetes.io/) + +--- + +*文档最后更新时间: 2026年2月13日* +*版本: 1.0.0* \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..7302221 --- /dev/null +++ b/README.md @@ -0,0 +1,178 @@ +# Fengling 项目快速开始指南 + +## 🚀 5分钟快速启动 + +### 1. 环境检查 + +确保已安装以下软件： +- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) +- [Node.js 18+](https://nodejs.org/) +- [Docker Desktop](https://www.docker.com/products/docker-desktop/) +- [Git](https://git-scm.com/) + +验证安装： +```bash +dotnet --version # 应显示 10.0.xxx +node --version # 应显示 18.x 或 20.x +docker --version # 应显示 Docker 版本 +``` + +### 2. 获取代码 + +```bash +git clone +cd Demo +``` + +### 3. 启动基础设施 + +```bash +# 启动 Redis 和其他依赖服务 +cd Backend/scripts +docker-compose up -d +``` + +### 4. 启动后端服务 + +```bash +# 新终端窗口 +cd Backend/src/Fengling.Backend.Web +dotnet run +``` + +后端将在 `http://localhost:5511` 启动 + +### 5. 启动前端 + +```bash +# 管理后台 - 新终端窗口 +cd Frontend/Fengling.Backend.Admin +pnpm install +pnpm dev + +# H5会员端 - 新终端窗口 +cd Frontend/Fengling.H5 +pnpm install +pnpm dev +``` + +### 6. 访问应用 + +- **管理后台**: http://localhost:3000 +- **H5会员端**: http://localhost:3001 +- **API 文档**: http://localhost:5511/swagger + +--- + +## 📁 项目结构速览 + +``` +Demo/ +├── Backend/ # 后端服务 (.NET 10) +│ ├── src/ # 源代码 +│ ├── test/ # 测试代码 +│ └── scripts/ # 基础设施脚本 +├── Frontend/ +│ ├── Fengling.Backend.Admin/ # 管理后台 (Vue 3) +│ └── Fengling.H5/ # H5会员端 (Vue 3) +├── docs/ # 详细文档 +└── PROJECT_DOCUMENTATION.md # 完整文档 +``` + +--- + +## 🔧 常用命令 + +### 后端开发 +```bash +# 还原依赖 +dotnet restore + +# 构建项目 +dotnet build + +# 运行开发模式 +dotnet watch run + +# 运行测试 +dotnet test + +# 数据库迁移 +dotnet ef database update +``` + +### 前端开发 +```bash +# 安装依赖 +pnpm install + +# 启动开发服务器 +pnpm dev + +# 构建生产版本 +pnpm build + +# 代码检查 +pnpm lint +``` + +### 基础设施管理 +```bash +# 启动所有服务 +docker-compose up -d + +# 查看服务状态 +docker-compose ps + +# 停止服务 +docker-compose down + +# 完全清理 +docker-compose down -v +``` + +--- + +## 🎯 开发约定 + +### 后端 +- 使用 Clean Architecture 分层架构 +- 遵循 DDD 领域驱动设计原则 +- API 使用 FastEndpoints 框架 +- 数据验证使用 FluentValidation +- 使用 MediatR 处理命令查询 + +### 前端 +- 使用 Composition API 风格 +- TypeScript 严格模式 +- Tailwind CSS 样式系统 +- Pinia 状态管理 +- Vue Router 路由管理 + +--- + +## 📚 学习资源 + +详细文档请查看: [PROJECT_DOCUMENTATION.md](PROJECT_DOCUMENTATION.md) + +主要技术栈文档： +- [.NET 10 官方文档](https://learn.microsoft.com/zh-cn/dotnet/) +- [Vue 3 官方文档](https://vuejs.org/) +- [Tailwind CSS](https://tailwindcss.com/) + +--- + +## ❓ 常见问题 + +**Q: 后端启动失败，提示数据库连接错误？** +A: 确保 Docker 服务已启动：`docker-compose up -d` + +**Q: 前端页面空白？** +A: 检查控制台是否有错误，确认后端 API 是否正常运行 + +**Q: 需要帮助？** +A: 查看完整文档或联系项目维护者 + +--- + +*Happy Coding! 🎉* \ No newline at end of file diff --git a/deploy.ps1 b/deploy.ps1 new file mode 100644 index 0000000..a8e2977 --- /dev/null +++ b/deploy.ps1 @@ -0,0 +1,66 @@ +# deploy.ps1 - Windows 部署脚本 + +param( + [string]$Version = "latest", + [string]$Registry = "your-registry.com", + [string]$Namespace = "your-namespace" +) + +$ErrorActionPreference = "Stop" + +$ProjectName = "fengling" +Write-Host "🚀 开始部署 $ProjectName 版本 $Version" -ForegroundColor Green + +try { + # 1. 构建后端镜像 + Write-Host "📦 构建后端镜像..." -ForegroundColor Yellow + Set-Location Backend + docker build -t "$Registry/$Namespace/fengling-backend:$Version" -f src/Fengling.Backend.Web/Dockerfile . + docker push "$Registry/$Namespace/fengling-backend:$Version" + Set-Location .. + + # 2. 构建前端镜像 + Write-Host "🎨 构建前端镜像..." -ForegroundColor Yellow + + # 管理后台 + Set-Location Frontend/Fengling.Backend.Admin + docker build -t "$Registry/$Namespace/fengling-admin:$Version" . + docker push "$Registry/$Namespace/fengling-admin:$Version" + Set-Location ../.. + + # H5会员端 + Set-Location Frontend/Fengling.H5 + docker build -t "$Registry/$Namespace/fengling-h5:$Version" . + docker push "$Registry/$Namespace/fengling-h5:$Version" + Set-Location ../.. + + # 3. 部署到 Kubernetes (如果使用) + if (Test-Path "k8s") { + Write-Host "☸️ 部署到 Kubernetes..." -ForegroundColor Yellow + kubectl set image deployment/fengling-backend fengling-backend="$Registry/$Namespace/fengling-backend:$Version" + kubectl set image deployment/fengling-admin fengling-admin="$Registry/$Namespace/fengling-admin:$Version" + kubectl set image deployment/fengling-h5 fengling-h5="$Registry/$Namespace/fengling-h5:$Version" + + # 等待部署完成 + kubectl rollout status deployment/fengling-backend + kubectl rollout status deployment/fengling-admin + kubectl rollout status deployment/fengling-h5 + } + + # 4. 部署到 Docker Compose (如果使用) + if (Test-Path "docker-compose.prod.yml") { + Write-Host "🐳 部署到 Docker Compose..." -ForegroundColor Yellow + docker-compose -f docker-compose.prod.yml pull + docker-compose -f docker-compose.prod.yml up -d + } + + Write-Host "✅ 部署完成！" -ForegroundColor Green + Write-Host "应用查看地址：" -ForegroundColor Cyan + Write-Host "- 管理后台: http://your-admin-domain.com" -ForegroundColor White + Write-Host "- H5会员端: http://your-h5-domain.com" -ForegroundColor White + Write-Host "- API 文档: http://your-api-domain.com/swagger" -ForegroundColor White + +} catch { + Write-Host "❌ 部署失败: $($_.Exception.Message)" -ForegroundColor Red + exit 1 +} \ No newline at end of file diff --git a/deploy.sh b/deploy.sh new file mode 100644 index 0000000..aa3c13f --- /dev/null +++ b/deploy.sh @@ -0,0 +1,60 @@ +#!/bin/bash +# deploy.sh - 自动化部署脚本 + +set -e # 遇到错误立即退出 + +# 配置变量 +PROJECT_NAME="fengling" +VERSION=${1:-"latest"} +REGISTRY="your-registry.com" +NAMESPACE="your-namespace" + +echo "🚀 开始部署 $PROJECT_NAME 版本 $VERSION" + +# 1. 构建后端镜像 +echo "📦 构建后端镜像..." +cd Backend +docker build -t $REGISTRY/$NAMESPACE/fengling-backend:$VERSION -f src/Fengling.Backend.Web/Dockerfile . +docker push $REGISTRY/$NAMESPACE/fengling-backend:$VERSION +cd .. + +# 2. 构建前端镜像 +echo "🎨 构建前端镜像..." + +# 管理后台 +cd Frontend/Fengling.Backend.Admin +docker build -t $REGISTRY/$NAMESPACE/fengling-admin:$VERSION . +docker push $REGISTRY/$NAMESPACE/fengling-admin:$VERSION +cd ../.. + +# H5会员端 +cd Frontend/Fengling.H5 +docker build -t $REGISTRY/$NAMESPACE/fengling-h5:$VERSION . +docker push $REGISTRY/$NAMESPACE/fengling-h5:$VERSION +cd ../.. + +# 3. 部署到 Kubernetes (如果使用) +if [ -d "k8s" ]; then + echo "☸️ 部署到 Kubernetes..." + kubectl set image deployment/fengling-backend fengling-backend=$REGISTRY/$NAMESPACE/fengling-backend:$VERSION + kubectl set image deployment/fengling-admin fengling-admin=$REGISTRY/$NAMESPACE/fengling-admin:$VERSION + kubectl set image deployment/fengling-h5 fengling-h5=$REGISTRY/$NAMESPACE/fengling-h5:$VERSION + + # 等待部署完成 + kubectl rollout status deployment/fengling-backend + kubectl rollout status deployment/fengling-admin + kubectl rollout status deployment/fengling-h5 +fi + +# 4. 部署到 Docker Compose (如果使用) +if [ -f "docker-compose.prod.yml" ]; then + echo "🐳 部署到 Docker Compose..." + docker-compose -f docker-compose.prod.yml pull + docker-compose -f docker-compose.prod.yml up -d +fi + +echo "✅ 部署完成！" +echo "应用查看地址：" +echo "- 管理后台: http://your-admin-domain.com" +echo "- H5会员端: http://your-h5-domain.com" +echo "- API 文档: http://your-api-domain.com/swagger" \ No newline at end of file