Demo/Project.Fengling.QoderVersion

sam 62f050a4f1 chore(docs): 添加项目完整文档与快速启动指南

- 新增详细的 Fengling 项目文档，涵盖项目结构、技术栈、环境准备
- 包含后端与前端开发指南与规范说明
- 提供丰富的第三方组件安装及 Docker 容器部署示例
- 描述本地开发流程、测试策略及调试技巧
- 详细介绍生产环境部署、CI/CD 集成及云平台部署方案
- 增加监控、性能优化及故障排查的最佳实践
- 新建管理后台前端 Dockerfile 和对应 nginx 配置文件
- 新增项目快速启动的 README 指南，方便开发者快速上手

2026-02-13 19:13:23 +08:00

29 KiB

Raw Blame History

Fengling 项目完整文档

项目概述

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

# 下载并安装 .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

验证安装：

dotnet --version  # 应显示 10.0.xxx

2. Node.js 和 pnpm

# 安装 Node.js (推荐 LTS 版本 18.x 或 20.x)
# 访问 https://nodejs.org/

# 安装 pnpm (比 npm/yarn 更快的包管理器)
npm install -g pnpm

# 验证安装
node --version
pnpm --version

3. Docker Desktop

# 下载并安装 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

# 下载并安装 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 (前端):

# 推荐安装的扩展
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 (推荐)

# 进入脚本目录
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

方式二：使用初始化脚本

# 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 (如果启用)

# 如果项目启用了 Aspire
cd Backend/src/Fengling.Backend.AppHost
dotnet run

数据库配置

项目默认使用 SQLite 数据库进行开发，生产环境建议使用 MySQL/PostgreSQL。

数据库连接配置

// appsettings.json
{
  "ConnectionStrings": {
    "SQLite": "Data Source=fengling.db",
    "Redis": "localhost:6379"
  }
}

数据库迁移

# 安装 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

启动后端服务

# 进入 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 配置

# 自动安装代码片段
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)

项目初始化

# 进入项目目录
cd Frontend/Fengling.Backend.Admin

# 安装依赖
pnpm install

# 启动开发服务器 (端口 3000)
pnpm dev

# 构建生产版本
pnpm build

# 预览生产构建
pnpm preview

环境变量配置

# 开发环境变量 (.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)

项目初始化

# 进入项目目录
cd Frontend/Fengling.H5

# 安装依赖
pnpm install

# 启动开发服务器 (端口 3001)
pnpm dev

# 构建生产版本
pnpm build

# 预览生产构建
pnpm preview

环境变量配置

# 开发环境变量 (.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 命名

代码质量工具

# ESLint 检查
pnpm lint

# Prettier 格式化
pnpm format

# TypeScript 类型检查
pnpm build  # 或 vue-tsc

UI 组件库

管理后台: 使用 shadcn-vue (基于 Tailwind CSS)
H5会员端: 使用 radix-vue (基于 Tailwind CSS)

添加新组件：

# shadcn-vue
npx shadcn-vue@latest add button

# radix-vue
# 直接从 @radix-ui/vue-icons 导入图标

第三方组件安装

后端组件

数据库驱动

<!-- MySQL -->
<PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="8.0.2" />

<!-- PostgreSQL -->
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="8.0.4" />

<!-- SQL Server -->
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.8" />

缓存和分布式锁

<!-- Redis (已包含) -->
<PackageReference Include="StackExchange.Redis" Version="2.8.16" />

<!-- 分布式锁 -->
<PackageReference Include="NetCorePal.Extensions.DistributedLocks.Redis" Version="1.0.0" />

消息队列

<!-- RabbitMQ (已包含) -->
<PackageReference Include="DotNetCore.CAP.RabbitMQ" Version="8.3.0" />

<!-- Kafka -->
<PackageReference Include="DotNetCore.CAP.Kafka" Version="8.3.0" />

对象存储

<!-- 阿里云 OSS -->
<PackageReference Include="Aliyun.OSS.SDK.NetCore" Version="2.13.0" />

<!-- AWS S3 -->
<PackageReference Include="AWSSDK.S3" Version="3.7.307.27" />

<!-- Azure Blob Storage -->
<PackageReference Include="Azure.Storage.Blobs" Version="12.21.2" />

第三方服务集成

<!-- 微信支付 -->
<PackageReference Include="WeihanLi.WechatPay" Version="1.0.0" />

<!-- 支付宝 -->
<PackageReference Include="Alipay.AopSdk.Core" Version="4.4.0" />

<!-- 短信服务 -->
<PackageReference Include="Aliyun.Acs.Core" Version="4.5.15" />
<PackageReference Include="Aliyun.Acs.Dysmsapi" Version="2.2.3" />

前端组件

UI 组件库扩展

# 图标库
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

状态管理和工具

# 状态管理 (已包含)
pnpm add pinia

# 路由 (已包含)
pnpm add vue-router

# HTTP 客户端 (已包含)
pnpm add axios

# 通知组件
pnpm add vue-sonner

# 实用工具
pnpm add @vueuse/core

开发工具

# 类型检查
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 (已存在)
# Backend/src/Fengling.Backend.Web/Dockerfile

# 前端 Dockerfile (需要创建)
# Frontend/Fengling.Backend.Admin/Dockerfile
# Frontend/Fengling.H5/Dockerfile

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. 启动基础设施

# 终端 1: 启动 Docker 服务
cd Backend/scripts
docker-compose up -d

2. 启动后端服务

# 终端 2: 启动后端
cd Backend/src/Fengling.Backend.Web
dotnet watch run

3. 启动前端服务

# 终端 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 文件)

开发调试技巧

后端调试

# 使用 Visual Studio 调试
# 设置断点 -> F5 启动调试

# 使用 VS Code 调试
# 创建 .vscode/launch.json 配置

前端调试

# 浏览器开发者工具
# F12 打开 -> Console 查看日志
# Network 查看 API 请求
# Vue DevTools 查看组件状态

# VS Code 调试配置
# 创建 .vscode/launch.json

数据库调试

# SQLite 浏览器工具
# 下载 DB Browser for SQLite

# 查看数据库内容
sqlite3 fengling.db
.tables
.schema table_name
SELECT * FROM table_name LIMIT 10;

测试

后端测试

单元测试

# 运行所有单元测试
cd Backend
dotnet test

# 运行特定项目测试
dotnet test test/Fengling.Backend.Domain.Tests

# 生成测试覆盖率报告
dotnet test --collect:"XPlat Code Coverage"

集成测试

# 运行集成测试 (包含 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 层集成测试

前端测试

单元测试

# 管理后台测试
cd Frontend/Fengling.Backend.Admin
pnpm test

# H5会员端测试
cd Frontend/Fengling.H5
pnpm test

E2E 测试

# 安装 Cypress
pnpm add -D cypress

# 运行 E2E 测试
pnpm run test:e2e

测试最佳实践

后端测试:
- 使用 Arrange-Act-Assert 模式
- Mock 外部依赖
- 测试边界条件和异常情况
- 保持测试独立性
前端测试:
- 组件测试使用 Vue Test Utils
- 端到端测试使用 Cypress
- 测试用户交互场景
- 模拟 API 响应

部署发布

生产环境配置

后端生产配置

// 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"
  }
}

前端生产配置

# 管理后台 .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 部署

# 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"]

构建和运行：

# 构建镜像
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：

# 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;"]

构建和运行：

# 构建管理后台
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

部署命令

# 添加 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

# 部署后端
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

# 初始化 EB 应用
eb init -p docker fengling-backend

# 部署应用
eb create fengling-backend-env
eb deploy

阿里云容器服务

# 构建并推送镜像
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 示例

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

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}'
            }
        }
    }
}

部署策略

蓝绿部署: 准备两套环境，切换流量
滚动更新: 逐步替换实例
金丝雀发布: 小范围用户先行体验
A/B 测试: 对比不同版本效果

监控与维护

日志管理

后端日志配置

// Program.cs
builder.Host.UseSerilog((context, configuration) => configuration
    .ReadFrom.Configuration(context.Configuration)
    .Enrich.FromLogContext()
    .WriteTo.Console()
    .WriteTo.File("logs/app-.txt", rollingInterval: RollingInterval.Day));

结构化日志

// 使用 Serilog 结构化日志
logger.Information("User {UserId} logged in from {IpAddress}", userId, ipAddress);
logger.Error(ex, "Failed to process order {OrderId}", orderId);

性能监控

Prometheus 指标

// 内置指标端点
// http://localhost:5511/metrics

// 自定义指标
var counter = Metrics.CreateCounter("myapp_orders_total", "Total orders processed");
counter.Inc();

应用性能监控 (APM)

<!-- 添加 Application Insights -->
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.22.0" />

健康检查

// Program.cs
builder.Services.AddHealthChecks()
    .AddDbContextCheck<ApplicationDbContext>()
    .AddRedis(builder.Configuration.GetConnectionString("Redis"))
    .ForwardToPrometheus();

访问健康检查端点：

http://localhost:5511/health

数据备份

数据库备份脚本

#!/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

自动化备份

# crontab -e
0 2 * * * /path/to/backup-db.sh  # 每天凌晨 2 点备份

故障排除

常见问题诊断

数据库连接失败:

# 检查连接字符串
# 验证数据库服务状态
docker-compose ps

Redis 连接问题:
```
# 测试 Redis 连接
redis-cli ping
```

API 响应慢:

# 查看性能指标
curl http://localhost:5511/metrics

前端白屏:

# 检查控制台错误
# 验证 API 连接
# 检查环境变量配置

常见问题

开发环境问题

Q: 后端启动时报数据库连接错误？ A: 确保 Docker 服务已启动，并且数据库容器正在运行：

docker-compose ps
docker-compose up -d mysql redis

Q: 前端无法连接到后端 API？ A: 检查以下几点：

后端服务是否正常运行 (http://localhost:5511/health)
Vite 代理配置是否正确
CORS 配置是否允许跨域请求

Q: 缺少某些 NuGet 包？ A: 还原包依赖：

dotnet restore

部署问题

Q: Docker 镜像构建失败？ A: 检查 Dockerfile 路径和上下文：

docker build -t app-name .  # 注意最后的点

Q: 容器启动后立即退出？ A: 查看容器日志：

docker logs container-name

Q: 环境变量未生效？ A: 确认环境变量传递方式：

# Docker run
docker run -e ENV_VAR=value image-name

# Docker Compose
environment:
  - ENV_VAR=value

性能优化

Q: 如何优化数据库查询性能？ A:

添加适当的索引
使用 Include 预加载关联数据
分页查询大数据集
启用查询缓存

Q: 前端打包体积过大？ A:

启用代码分割
移除未使用的依赖
使用 CDN 加载大型库
启用 gzip/brotli 压缩

安全考虑

Q: 如何保护 API 接口？ A:

实施 JWT 身份验证
添加请求频率限制
验证所有输入参数
启用 HTTPS
配置 CORS 策略

Q: 敏感信息如何管理？ A:

使用 Secret Manager (开发)
环境变量 (生产)
Azure Key Vault/AWS Secrets Manager
不在代码中硬编码密码

附录

有用的命令集合

后端常用命令

# 项目管理
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  # 自包含发布

前端常用命令

# 依赖管理
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 常用命令

# 镜像操作
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               # 查看日志

参考资料

文档最后更新时间: 2026年2月13日 版本: 1.0.0

29 KiB Raw Blame History Unescape Escape

Fengling 项目完整文档

目录

项目概述

项目结构

技术栈

后端技术栈

前端技术栈

管理后台 (Fengling.Backend.Admin)

H5会员端 (Fengling.H5)

开发工具

环境准备

系统要求

必需软件安装

1. .NET SDK

2. Node.js 和 pnpm

3. Docker Desktop

4. Git

5. IDE 配置

后端开发

项目结构说明

启动基础设施服务

方式一：使用 Docker Compose (推荐)

方式二：使用初始化脚本

方式三：Aspire (如果启用)

数据库配置

数据库连接配置

数据库迁移

启动后端服务

API 文档访问

代码生成器配置

Visual Studio 配置

VS Code 配置

常用代码片段

前端开发

管理后台 (Fengling.Backend.Admin)

项目初始化

环境变量配置

目录结构

H5会员端 (Fengling.H5)

项目初始化

环境变量配置

目录结构

前端开发规范

代码规范

代码质量工具

UI 组件库

第三方组件安装

后端组件

数据库驱动

缓存和分布式锁

消息队列

对象存储

第三方服务集成

前端组件

UI 组件库扩展

状态管理和工具

开发工具

Docker 相关组件

容器化部署

Nginx 配置

本地开发

完整开发环境启动

1. 启动基础设施

2. 启动后端服务

3. 启动前端服务

开发环境访问地址

开发调试技巧

后端调试

前端调试

数据库调试

测试

后端测试

单元测试

集成测试

测试项目结构

前端测试

单元测试

E2E 测试

测试最佳实践

29 KiB

Raw Blame History