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 回滚方式
# 在部署服务器上修改 docker-compose.yml 中镜像标签为指定 commit SHA
cd /disk/docker-compose/live-forum-new
# 修改镜像标签，例如 :latest → :a1b2c3d4
docker compose up -d
八、本地开发
小程序 API
cd server/webapi/LiveForum
dotnet restore LiveForum.sln
dotnet build LiveForum.sln
dotnet run --project LiveForum.WebApi
# Swagger: http://localhost:{port}/swagger
后台管理 API
cd server/admin/ZrAdminNetCore
dotnet restore ZRAdmin.sln
dotnet run --project ZR.Admin.WebApi
后台管理前端
cd server/admin/ZrAdminNetCore/ZR.Vue
npm install
npm run dev
运行测试
cd server/webapi/LiveForum
dotnet test LiveForum.Tests
爬虫
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 已知问题
十二、注意事项
- 数据库实体类统一使用
T_ 前缀
- Autofac 自动扫描注册服务，新增 Service 无需手动注册（单例除外）
- 基础镜像已迁移到内网 Harbor，更新基础镜像需手动 pull → tag → push
- 部署服务器 Docker 需配置
insecure-registries 信任 Harbor
- 配置中心 AgileConfig 支持热更新，敏感配置不要写在代码仓库中
- SQL 迁移脚本需手动执行，注意区分业务库和管理库
- 爬虫需要先手动登录获取 Cookie，再启动 daemon 模式
