folder
.agent
folder-github
.github
folder-vscode
.vscode
folder-docs
docs
folder-src
src
git
.gitattributes
git
.gitignore
markdown
AGENTS.md
json
architecture-runtime.architecture.json
html
architecture-runtime.html
readme
README.md
lock
SECURITY.md
powershell
video-fragment.ps1
Root / README.md

dpz.core

dpz.core 是基于 .NET 10 / ASP.NET Core 构建的个人综合平台和 CMS，包含内容管理、统一认证、REST API、实时通讯、多媒体处理、后台任务和 CI/CD 发布流水线等能力

在线入口

快速开始

前置条件

  • .NET 10 SDK
  • Node.js（前端资源构建）
  • MongoDB
  • Redis
  • RabbitMQ
  • Docker（容器化部署时需要）

MongoDB 事务相关测试需要使用副本集，单实例 MongoDB 默认不支持事务

克隆与配置

git clone https://github.com/pengqian089/dpz.core.git
cd dpz.core

运行各应用前，需要提供对应的配置中心、MongoDB、Redis、RabbitMQ 和认证中心配置 敏感配置不要提交到公开文件中

常用配置结构如下，真实配置以各应用的 appsettings*.json、AgileConfig 和启动代码为准：

{
  "ConnectionStrings": {
    "mongodb": "mongodb://localhost:27017/YourDatabase",
    "hangfireMongodb": "mongodb://localhost:27017/YourHangfireDatabase",
    "redis": "localhost:6379"
  },
  "AgileConfig": {
    "appId": "your-app-id",
    "secret": "your-secret",
    "nodes": "https://your-agile-config-server",
    "env": "DEV"
  },
  "RabbitMQ": {
    "HostName": "localhost",
    "Port": 5672,
    "UserName": "guest",
    "Password": "guest",
    "VirtualHost": "/"
  }
}

支持的 AgileConfig 环境标识为 DEV、TEST、STAGING 和 PROD

前端开发

前端位于 src/Dpz.Core.Web，使用 TypeScript、esbuild 和 clean-css

cd src/Dpz.Core.Web
.\build.ps1 init       # 首次运行：安装依赖并执行检查
.\build.ps1 dev        # 开发模式
.\build.ps1 build      # 生产构建

也可以直接使用 npm 脚本：

npm install
npm run dev:app
npm run build:app
npm run lint
npm run format:check

本地运行

所有 .NET 命令建议从 src/ 目录执行

cd src
dotnet build .\Dpz.Core.slnx
dotnet run --project .\Dpz.Core.Web\Dpz.Core.Web.csproj

本地启动地址由各项目的 Properties/launchSettings.json 决定，当前主要地址如下：

应用HTTPSHTTP
Dpz.Core.Webhttps://localhost:37701http://localhost:37702
Dpz.Core.WebApihttps://localhost:53381-
Dpz.Core.Authhttps://localhost:7183http://localhost:5239
Dpz.Core.Web.Jobshttps://localhost:7164http://localhost:5078

API 文档入口为 /scalar/v1，Web 的 Hangfire 面板为 /runtask，Jobs 的 Hangfire 面板为 /jobs

测试

cd src
dotnet test .\Dpz.Core.slnx
dotnet test .\Dpz.Core.Backup.Test\Dpz.Core.Backup.Test.csproj

集成测试通常需要可用的 MongoDB、Redis 或 RabbitMQ，涉及 IUnitOfWork 的测试需要 MongoDB副本集

C# 格式化

工具清单位于 src/dotnet-tools.json，格式化命令必须从 src/ 执行：

cd src
dotnet tool restore
dotnet csharpier .

项目结构

应用层

项目说明
Dpz.Core.WebMVC 主站，负责页面渲染、交互和站点功能
Dpz.Core.Auth基于 OpenIddict 的 OAuth2/OIDC 认证中心
Dpz.Core.WebApiREST API，支持 JSON、XML 和 MessagePack
Dpz.Core.Web.JobsHangfire 任务宿主、消息消费者、文件传输和发布流水线

业务与基础设施

  • Dpz.Core.Service：领域服务和业务逻辑
  • Dpz.Core.Service.Mediator：基于 martinothamar Mediator 的 CQRS 请求处理器
  • Dpz.Core.Service.Network：邮件等网络服务
  • Dpz.Core.Service.ObjectStorage：对象存储操作，包含 Upyun/S3 兼容能力
  • Dpz.Core.Backup：数据库备份与恢复
  • Dpz.Core.MessageQueue：RabbitMQ、消息消费者和 MongoDB Outbox
  • Dpz.Core.Hangfire：Hangfire 与 MongoDB 存储集成
  • Dpz.Core.MongodbAccess：MongoDB Repository 和 Unit of Work
  • Dpz.Core.Infrastructure：通用基础设施、中间件、缓存和配置支持
  • Dpz.Core.AspNetCore：Web、Auth、WebApi 共用的 ASP.NET Core 基础设施
  • Dpz.Core.Shard.Service / Dpz.Core.Shard.Implement.Service：共享服务接口和实现，用于聚合服务

公共模型与辅助项目

  • Dpz.Core.Public.Entity：持久化实体
  • Dpz.Core.Public.ViewModel：API 和应用层 DTO、ViewModel、消息模型
  • Dpz.Core.Entity.Base：实体和响应基础库
  • Dpz.Core.EnumLibrary：公共枚举，可独立打包为 NuGet
  • Dpz.Core.MvcPager：MVC 分页组件
  • Dpz.Core.Authenticator：双因素认证支持
  • Dpz.Core.SourceGenerator / Dpz.Core.SourceGenerator.Attributes：源生成服务注册支持

功能概览

  • 内容管理：文章、Markdown、分类、标签、评论、动态、代码浏览和时间线
  • 多媒体：音乐、视频、弹幕、图片、图片元信息和 Steam 游戏库
  • 实时能力：SignalR 聊天、文件传输和后台任务状态推送
  • 认证与安全：OpenIddict SSO、JWT、2FA、权限、IP 限流、爬虫拦截和日志审计
  • 异步处理：RabbitMQ 消息消费、Outbox 可靠投递和 Hangfire 周期任务
  • 运维能力：MongoDB 数据库备份、程序目录备份、对象存储空目录清理和 CI/CD 发布

详细文档

部署

核心应用的容器端口约定为：

应用容器端口映射
Dpz.Core.Web2372:8080
Dpz.Core.WebApi2376:8080
Dpz.Core.Auth2377:8080

手动构建核心镜像

从 src/ 目录执行：

docker build -t dpz.core -f Dpz.Core.Web/Dockerfile .
docker build -t dpz.webapi -f Dpz.Core.WebApi/Dockerfile .
docker build -t dpz.core.auth -f Dpz.Core.Auth/Dockerfile .

非生产环境可以通过环境变量覆盖 AgileConfig 环境，例如：

docker run -e "AgileConfig:env=STAGING" ...

技术栈

  • .NET 10 / ASP.NET Core / Kestrel
  • MongoDB / Redis / RabbitMQ
  • Hangfire.Mongo / FusionCache
  • OpenIddict / JWT / Cookie Authentication
  • Mediator source generator
  • Mapster
  • SignalR
  • Serilog / Seq
  • TypeScript / esbuild / clean-css
  • Markdig / AngleSharp
  • Caddy 反向代理

编码约定

  • 使用文件作用域命名空间、4 个空格缩进和必需的大括号
  • 私有字段使用 _camelCase，参数和局部变量使用 camelCase，公开成员使用 PascalCase
  • 异步方法以 Async 结尾，并接受 CancellationToken cancellationToken = default
  • 使用结构化日志，禁止在日志调用中拼接或内插字符串
  • Service 公开接口不直接返回 Dpz.Core.Public.Entity 实体，统一返回 DTO、ViewModel 或 Response
  • 运行时对象映射使用注入的 Mapster IMapper，不要调用静态 Adapt
  • 使用源生成的服务注册和 Mediator handler 注册，不要重复手写自动注册代码

分支命名

<type>/<issue-id>-<short-description>

常用前缀：feature/、bugfix/、fix/、hotfix/、release/、chore/、 docs/、refactor/、test/