Dpz.Core.WebApi

一个基于 ASP.NET Core 的综合性 RESTful Web API 服务，为个人内容管理系统提供完整的后端支持，包含文章、视频、音乐、图片、代码、书签等多种内容类型的管理功能。

📋 项目简介

本项目是一个功能完善的个人内容管理平台的 Web API 服务，提供了丰富的内容管理接口、用户认证授权、后台任务调度、对象存储集成等企业级功能。

在线文档：https://core.dpangzi.com/code

✨ 主要特性

核心功能

• ✅ 多类型内容管理：文章、视频、音乐、图片、代码片段、书签、时间线、动态页面等
• ✅ 用户系统：完整的账号管理、JWT 认证、权限授权
• ✅ 互动功能：评论系统、弹幕支持、碎碎念
• ✅ 社区功能：Banner 管理、汇总信息、SEO 优化
• ✅ 第三方集成：Steam 游戏数据集成

技术特性

• ✅ 多格式支持：JSON、XML、MessagePack 序列化格式
• ✅ 性能优化：响应压缩（Brotli、Gzip）、输出缓存、分布式缓存
• ✅ 安全保护：JWT Bearer 认证、基于权限的授权、API 限流
• ✅ API 文档：集成 Scalar API 文档，支持 OpenAPI 规范
• ✅ 后台任务：Hangfire 任务调度，支持定时任务和周期任务
• ✅ 日志系统：Serilog 结构化日志，支持日志中心集成
• ✅ 配置中心：AgileConfig 分布式配置管理
• ✅ 对象存储：又拍云对象存储集成，支持视频处理
• ✅ 备份恢复：数据库备份和恢复功能
• ✅ 容器化部署：完整的 Docker 支持
• ✅ 跨域支持：CORS 配置，支持多域名访问

🔧 技术栈

• .NET: 10.0
• 认证: Microsoft.AspNetCore.Authentication.JwtBearer 10.0.1
• 文档: Scalar.AspNetCore 2.11.6
• 序列化: MessagePack 3.1.4
• Markdown: Markdig 0.44.0
• 配置中心: AgileConfig.Client 1.8.0
• 任务调度: Hangfire
• 日志: Serilog
• 版本控制: LibGit2Sharp 0.29.0

📦 快速开始

配置文件

在 appsettings.json 中配置基本信息：

{
  "ConnectionStrings": {
    "mongodb": "mongodb://localhost:27017/YourDatabase"
  },
  "Server": {
    "Issuer": "https://your-auth-server.com"
  },
  "Origins": [
    "https://your-frontend.com"
  ],
  "WebApiHangfireCollectionPrefix": "WebAPI",
  "AgileConfig": {
    "appId": "Dpz.Core.WebApi",
    "secret": "your-secret",
    "nodes": "https://your-config-server.com",
    "name": "接口",
    "env": "PROD"
  },
  "LogSeq": {
    "ServerUrl": "https://your-seq-server.com",
    "ApiKey": "your-api-key"
  }
}

本地运行

cd src/Dpz.Core.WebApi
dotnet restore
dotnet run

访问 API 文档：http://localhost:5000/scalar/v1

Docker 部署

构建镜像

cd /home/ubuntu/project/dpz.core/src

# 生产环境
sudo docker build -t dpz.webapi -f Dpz.Core.WebApi/Dockerfile .

运行容器

生产环境：

sudo docker run --restart=always \
  --name dpz.webapi \
  -e TZ=Asia/Shanghai \
  -v /home/ubuntu/project/dpz.core:/app/code \
  -p 2376:8080 \
  -d dpz.webapi:latest

预发布环境：

sudo docker build -t dpz.webapi.staging -f Dpz.Core.WebApi/Dockerfile .

sudo docker run --restart=always \
  --name dpz.webapi.staging \
  -e "AgileConfig:env=STAGING" \
  -e "WebApiHangfireCollectionPrefix=STAGING_WebAPI" \
  -e TZ=Asia/Shanghai \
  -v /home/ubuntu/project/dpz.core:/app/code \
  -p 3509:8080 \
  -d dpz.webapi.staging:latest

测试环境：

sudo docker network create dpz.core
sudo docker build -t dpz.webapi.test -f Dpz.Core.WebApi/Dockerfile .

sudo docker run --restart=always \
  --name dpz.webapi.test \
  -e "AgileConfig:env=TEST" \
  -e TZ=Asia/Shanghai \
  -v /home/ubuntu/project/dpz.core:/app/code \
  -p 3510:8080 \
  -d dpz.webapi.test:latest

Nginx 反向代理

server {
  listen        80;
  server_name   api.dpangzi.com;
  
  if ( $host != 'api.dpangzi.com' ) {
    return 403;
  }
  
  location / {
    proxy_pass         http://localhost:2376;
    proxy_http_version 1.1;
    proxy_set_header   Upgrade $http_upgrade;
    proxy_set_header   Connection $connection_upgrade;
    proxy_set_header   Host $host;
    proxy_cache_bypass $http_upgrade;
    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
  }
}

📚 API 模块说明

内容管理

互动功能

系统管理

第三方集成

🔐 认证与授权

认证方式

使用 JWT Bearer 认证，需要在请求头中携带 Token：

Authorization: Bearer {your_jwt_token}

权限策略

• System：系统管理员权限，用于访问管理接口
• 基于自定义的权限授权系统，支持细粒度权限控制

获取 Token

通过认证服务器（Server:Issuer 配置）获取 JWT Token，详见认证服务文档。

📄 API 格式支持

多格式输出

支持三种序列化格式，通过以下方式指定：

1. HTTP Header

# JSON (默认)
Accept: application/json

# XML
Accept: application/xml

# MessagePack
Accept: application/msgpack

2. QueryString

# XML 格式
GET /api/article?format=xml

# MessagePack 格式
GET /api/article?format=msgpack

日期格式化

通过 date_format 参数自定义日期格式：

# 中文日期时间格式：yyyy-MM-dd HH:mm:ss
GET /api/article?date_format=zh-cn

# 中文日期格式：yyyy-MM-dd
GET /api/article?date_format=zh-date

响应压缩

自动支持 Brotli 和 Gzip 压缩，浏览器会自动处理。

🎯 使用示例

获取文章列表

curl -X GET "https://api.dpangzi.com/api/Article?pageIndex=1&pageSize=10" \
  -H "Accept: application/json"

发布文章（需要认证）

curl -X POST "https://api.dpangzi.com/api/Article" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "示例文章",
    "content": "文章内容...",
    "tags": ["技术", ".NET"]
  }'

获取视频列表

curl -X GET "https://api.dpangzi.com/api/Video" \
  -H "Accept: application/json"

发送弹幕

curl -X POST "https://api.dpangzi.com/api/Video/danmaku" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "video-id",
    "text": "弹幕内容",
    "color": 16777215,
    "time": 30.5,
    "type": 0
  }'

获取音乐列表

curl -X GET "https://api.dpangzi.com/api/Music?pageIndex=1&pageSize=20" \
  -H "Accept: application/json"

🔧 开发指南

添加新控制器

[ApiController, Route("api/[controller]")]
public class YourController : ControllerBase
{
    /// <summary>
    /// 接口说明
    /// </summary>
    [HttpGet]
    [ProducesResponseType<YourResponse>(StatusCodes.Status200OK)]
    public async Task<IActionResult> GetData()
    {
        // 业务逻辑
        return Ok(result);
    }
}

使用限流保护

在需要限流的接口上添加 RequireRateLimiting 特性：

[HttpPost("comment")]
[RequireRateLimiting("comment")]
public async Task<IActionResult> PostComment([FromBody] CommentDto dto)
{
    // 评论接口受限流保护（1分钟内最多3次请求）
    return Ok();
}

添加权限控制

[HttpPost]
[Authorize(Policy = "System")]
[ProducesResponseType(StatusCodes.Status401Unauthorized)]
public async Task<IActionResult> AdminAction()
{
    // 仅系统管理员可访问
    return Ok();
}

📊 监控与管理

Hangfire 任务管理

在开发环境下可访问 Hangfire Dashboard：

http://localhost:5000/jobs

功能：

• 查看和管理后台任务
• 查看任务执行历史
• 手动触发任务
• 配置定时任务

API 文档

访问 Scalar API 文档：

http://localhost:5000/scalar/v1

特性：

• 交互式 API 文档
• 在线测试接口
• 请求/响应示例
• 支持暗色主题

健康检查

# Ping 测试
curl http://localhost:5000/ping
# 响应：pong

# 获取服务器时间和机器名
curl http://localhost:5000/datetime
# 响应：2025/12/30 15:30:45\r\nMACHINE-NAME

🔄 版本历史

详见 CHANGELOG.md

2.12.0.x

• 升级至 .NET 10
• 删除 Swagger 集成，改用 Minimal API 的内置 OpenAPI 支持
• 更新所有依赖包至最新版本

2.11.0.0

• 认证方式重构：从本地 JWT 验证改为外部认证服务器
• 授权机制简化：使用自定义权限授权扩展
• 移除数据保护配置，简化架构

⚠️ 注意事项

1. 环境变量：Docker 部署时通过 -e 参数传递环境变量，可覆盖配置文件设置
2. 时区设置：容器内默认使用 Asia/Shanghai 时区
3. 端口映射：生产环境使用 2376 端口，预发布使用 3509，测试使用 3510
4. 配置中心：生产环境依赖 AgileConfig 配置中心，确保配置中心可访问
5. 认证服务：需要部署独立的认证服务器（Dpz.Core.Auth）
6. 数据库：依赖 MongoDB 数据库，确保连接字符串正确配置
7. 对象存储：视频、图片等文件存储依赖又拍云服务
8. 日志中心：生产环境建议配置 Seq 日志中心进行日志聚合

📄 许可证

Copyright © dpangzi

🔗 相关项目

• 认证服务：Dpz.Core.Auth - 提供 OpenID Connect 认证
• Web 前端：Dpz.Core.Web - 管理后台
• 数据访问层：Dpz.Core.MongodbAccess - MongoDB 仓储

📞 联系方式

• 网站：https://core.dpangzi.com
• 项目文档：https://core.dpangzi.com/code