# 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*