217 lines
8.1 KiB
Markdown
217 lines
8.1 KiB
Markdown
# LiveForum 项目交接文档
|
||
|
||
## 一、项目概述
|
||
|
||
LiveForum（论坛社区）是一个直播机构的粉丝社区平台，面向中文用户，主要通过微信小程序提供服务。核心功能包括论坛发帖/评论/点赞、主播档案与送花排行、CDK 激活码、手机号登录与实名认证、身份权限管理、防沉迷系统等。
|
||
|
||
当前版本：v1.2.0（已完成）
|
||
|
||
## 二、技术栈总览
|
||
|
||
| 模块 | 技术 |
|
||
|------|------|
|
||
| 小程序 API | .NET 8、FreeSql（SQL Server）、Redis、Hangfire、AgileConfig、Serilog、JWT、Autofac |
|
||
| 后台管理 API | .NET 8、SqlSugar、Mapster、NLog |
|
||
| 后台管理前端 | Vue 3 + Vite + Element Plus + Pinia |
|
||
| 微信小程序 | uni-app（Vue 3）、uview-plus、dayjs |
|
||
| 数据库 | SQL Server（主库）、Redis（缓存/消息队列/JWT Token 存储） |
|
||
| 文件存储 | 腾讯云 COS |
|
||
| 配置中心 | AgileConfig（支持热更新） |
|
||
| 微信 SDK | SKIT.FlurlHttpClient.Wechat.Api |
|
||
| 爬虫 | Python + Playwright |
|
||
| 压测 | k6 |
|
||
|
||
## 三、项目结构
|
||
|
||
```
|
||
├── server/
|
||
│ ├── webapi/LiveForum/ # 小程序 API（主业务）
|
||
│ │ ├── LiveForum.WebApi/ # 入口、Controllers、BackgroundServices
|
||
│ │ ├── LiveForum.Service/ # 业务逻辑（按领域分文件夹）
|
||
│ │ ├── LiveForum.IService/ # 服务接口
|
||
│ │ ├── LiveForum.Model/ # DTO、实体（T_ 前缀）、枚举、领域事件
|
||
│ │ ├── LiveForum.Code/ # 基础设施（JWT、Redis、中间件、缓存、工具类）
|
||
│ │ ├── LiveForum.Repository/ # 数据访问（FreeSql）
|
||
│ │ ├── LiveForum.Tests/ # 单元测试（xUnit + FsCheck + Moq）
|
||
│ │ └── DatabaseScripts/ # SQL 迁移脚本
|
||
│ ├── admin/ZrAdminNetCore/ # 后台管理
|
||
│ │ ├── ZR.Admin.WebApi/ # 后台 API 入口
|
||
│ │ ├── ZR.Service/Liveforum/ # 后台业务逻辑
|
||
│ │ ├── ZR.LiveForum.Model/ # 后台论坛模型
|
||
│ │ └── ZR.Vue/ # 后台前端
|
||
│ ├── crawler/ # Python 爬虫（commerce / entertainment）
|
||
│ └── k6/ # 压测脚本
|
||
├── 前端/live-forum/ # 微信小程序
|
||
├── docs/ # 需求文档（按版本）
|
||
└── mcp/ # 开发工具（MCP 数据库服务器）
|
||
```
|
||
|
||
## 四、核心业务模块
|
||
|
||
| 模块 | 路径（Service 层） | 说明 |
|
||
|------|-------------------|------|
|
||
| 登录认证 | Auth/ | 微信登录、手机号登录、JWT Token 管理（Redis 存储） |
|
||
| 帖子 | Posts/ | 发帖、评论、点赞、分类、回复权限控制 |
|
||
| 主播 | Streamers/ | 主播档案、数据来源为爬虫 |
|
||
| 送花 | Flowers/ | 送花（礼物）、排行榜、每日重置（Hangfire） |
|
||
| CDK | Cdk/ | CDK 激活码系统，激活后才能互动 |
|
||
| 实名认证 | RealName/ | 首次互动前需实名验证 |
|
||
| 身份权限 | Permission/ | 身份组 + SK 认证等级，控制发帖/回复/送花/点赞/删帖权限 |
|
||
| 防沉迷 | （Admin 配置） | 按时间段限制发帖、回复、送花 |
|
||
| 消息推送 | Messages/ | 点赞、回复、自定义消息通知 |
|
||
| 敏感词 | SensitiveWord/ | 内容过滤引擎 |
|
||
| 首页 | Home/ | Banner 管理、弹窗配置 |
|
||
| 用户 | Users/ | 用户资料、关注关系、认证信息 |
|
||
| 文件上传 | Others/ | 腾讯 COS 上传 |
|
||
|
||
## 五、关键架构设计
|
||
|
||
### 5.1 DI 容器
|
||
- 使用 Autofac，通过程序集扫描自动注册 `LiveForum.Service` 中的服务
|
||
- 单例服务在 `Program.cs` 中手动注册
|
||
|
||
### 5.2 异步处理
|
||
- 领域事件驱动：点赞、浏览、送花、消息等通过 `LiveForum.Model/Events/` 定义事件
|
||
- Redis 消费者 + 批量同步服务（BackgroundServices/）处理异步写入
|
||
- Hangfire 处理定时任务（如每日送花重置）
|
||
|
||
### 5.3 缓存策略
|
||
- Redis 用于 JWT Token 管理、消息队列、批量同步缓冲
|
||
- SystemCache/ 提供字段级和系统级缓存层
|
||
|
||
### 5.4 中间件
|
||
- 异常处理中间件、执行时间中间件、签名验证中间件、响应缓存中间件
|
||
|
||
## 六、数据库
|
||
|
||
### 6.1 SQL Server
|
||
- 实体类使用 `T_` 前缀（如 `T_Users`、`T_Posts`、`T_IdentityGroups`）
|
||
- WebAPI 使用 FreeSql ORM
|
||
- Admin 使用 SqlSugar ORM
|
||
- 迁移脚本位于：
|
||
- `server/webapi/LiveForum/DatabaseScripts/`
|
||
- `server/webapi/数据库脚本/`（v1.2.0 升级脚本）
|
||
|
||
### 6.2 Redis
|
||
- 缓存、消息队列、批量同步缓冲、JWT Token 存储
|
||
- 使用 StackExchange.Redis
|
||
|
||
## 七、CI/CD 部署
|
||
|
||
### 7.1 流水线
|
||
```
|
||
代码推送 (master) → Drone CI → 构建 Docker 镜像 → 推送 Harbor → SSH 部署
|
||
```
|
||
|
||
### 7.2 关键地址
|
||
|
||
| 组件 | 地址 |
|
||
|------|------|
|
||
| Drone CI | `192.168.195.25:13080` |
|
||
| Harbor 镜像仓库 | `192.168.195.25:19900`（HTTP） |
|
||
| 部署服务器 | `192.168.195.15` |
|
||
| 部署目录 | `/disk/docker-compose/live-forum-new` |
|
||
|
||
### 7.3 构建镜像
|
||
|
||
| 镜像 | 说明 |
|
||
|------|------|
|
||
| `live-forum/webapi` | 小程序 API |
|
||
| `live-forum/admin-api` | 后台管理 API |
|
||
| `live-forum/admin-web` | 后台管理前端（Nginx） |
|
||
|
||
每个镜像打两个标签：`latest` + commit SHA 前 8 位（用于回滚）。
|
||
|
||
### 7.4 Drone Secrets
|
||
|
||
| Secret | 说明 |
|
||
|--------|------|
|
||
| `harbor_username` | Harbor 用户名 |
|
||
| `harbor_password` | Harbor 密码 |
|
||
| `ssh_username` | 部署服务器 SSH 用户名 |
|
||
| `ssh_password` | 部署服务器 SSH 密码 |
|
||
|
||
### 7.5 回滚方式
|
||
```bash
|
||
# 在部署服务器上修改 docker-compose.yml 中镜像标签为指定 commit SHA
|
||
cd /disk/docker-compose/live-forum-new
|
||
# 修改镜像标签，例如 :latest → :a1b2c3d4
|
||
docker compose up -d
|
||
```
|
||
|
||
## 八、本地开发
|
||
|
||
### 小程序 API
|
||
```bash
|
||
cd server/webapi/LiveForum
|
||
dotnet restore LiveForum.sln
|
||
dotnet build LiveForum.sln
|
||
dotnet run --project LiveForum.WebApi
|
||
# Swagger: http://localhost:{port}/swagger
|
||
```
|
||
|
||
### 后台管理 API
|
||
```bash
|
||
cd server/admin/ZrAdminNetCore
|
||
dotnet restore ZRAdmin.sln
|
||
dotnet run --project ZR.Admin.WebApi
|
||
```
|
||
|
||
### 后台管理前端
|
||
```bash
|
||
cd server/admin/ZrAdminNetCore/ZR.Vue
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
### 运行测试
|
||
```bash
|
||
cd server/webapi/LiveForum
|
||
dotnet test LiveForum.Tests
|
||
```
|
||
|
||
### 爬虫
|
||
```bash
|
||
cd server/crawler/commerce # 或 entertainment
|
||
pip install -r requirements.txt
|
||
playwright install chromium
|
||
python main.py login # 手动浏览器登录
|
||
python main.py daemon # 定时爬取
|
||
```
|
||
|
||
## 九、外部依赖与账号
|
||
|
||
| 服务 | 说明 |
|
||
|------|------|
|
||
| AgileConfig | 远程配置中心，支持热更新，连接信息在 `appsettings.json` |
|
||
| 腾讯云 COS | 文件存储，密钥在配置中心 |
|
||
| 微信小程序 | AppId/AppSecret 在配置中心 |
|
||
| SQL Server | 连接字符串在 `appsettings.json` / AgileConfig |
|
||
| Redis | 连接字符串在 `appsettings.json` / AgileConfig |
|
||
|
||
## 十、配置文件位置
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `server/webapi/LiveForum/LiveForum.WebApi/appsettings.json` | WebAPI 配置（含 AgileConfig 连接） |
|
||
| `server/admin/ZrAdminNetCore/ZR.Admin.WebApi/appsettings.json` | Admin API 配置 |
|
||
| `server/admin/ZrAdminNetCore/ZR.Vue/.env.production` | Admin 前端生产环境变量 |
|
||
| `server/admin/ZrAdminNetCore/ZR.Vue/nginx.conf` | Admin 前端 Nginx 配置 |
|
||
| `.drone.yml` | CI/CD 流水线配置 |
|
||
|
||
## 十一、需求文档
|
||
|
||
- `docs/1.0.1/需求文档.md` — v1.0.1 基础功能需求
|
||
- `docs/1.2.0/需求文档.md` — v1.2.0 需求（CDK、手机号登录、实名认证、权限等）
|
||
- `docs/1.2.0/bug.md` — v1.2.0 已知问题
|
||
|
||
## 十二、注意事项
|
||
|
||
1. 数据库实体类统一使用 `T_` 前缀
|
||
2. Autofac 自动扫描注册服务，新增 Service 无需手动注册（单例除外）
|
||
3. 基础镜像已迁移到内网 Harbor，更新基础镜像需手动 pull → tag → push
|
||
4. 部署服务器 Docker 需配置 `insecure-registries` 信任 Harbor
|
||
5. 配置中心 AgileConfig 支持热更新，敏感配置不要写在代码仓库中
|
||
6. SQL 迁移脚本需手动执行，注意区分业务库和管理库
|
||
7. 爬虫需要先手动登录获取 Cookie，再启动 daemon 模式
|