游戏盒子文档

Appearance

API 接口文档 ​

版本：v2.7.0
日期：2025-12-14
基础路径：/api
对应架构：若依 Boot 单体架构

1. 接口规范 ​

1.1 请求格式 ​

POST /api/v1/resource
Content-Type: application/json
Authorization: Bearer <token>

1.2 响应格式 ​

json
{
  "code": 200,
  "msg": "操作成功",
  "data": {},
  "timestamp": 1702454400000
}

1.3 状态码 ​

状态码说明
200成功
400参数错误
401未授权
403无权限
404资源不存在
500服务器错误

2. 网站管理接口 ​

2.1 网站列表 ​

请求

GET /site/list
参数类型必填说明
nameString否网站名称
siteTypeString否网站类型：game/drama/mixed
statusInteger否状态：0-禁用 1-启用
pageNumInteger否页码，默认1
pageSizeInteger否每页数量，默认20

响应

json
{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 5,
    "rows": [
      {
        "id": 1,
        "name": "游戏推广站A",
        "domain": "game-a.example.com",
        "siteType": "game",
        "logoUrl": "https://cdn.example.com/logo.png",
        "description": "游戏推广专用站点",
        "status": 1,
        "createdAt": "2025-01-01 12:00:00"
      }
    ]
  }
}

2.2 网站详情 ​

请求

GET /site/{id}

响应

json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "name": "游戏推广站A",
    "domain": "game-a.example.com",
    "siteType": "game",
    "logoUrl": "https://cdn.example.com/logo.png",
    "faviconUrl": "https://cdn.example.com/favicon.ico",
    "description": "游戏推广专用站点",
    "seoTitle": "最新游戏下载 - 游戏推广站",
    "seoKeywords": "游戏下载,破解游戏,BT游戏",
    "seoDescription": "提供最新游戏下载服务",
    "config": {
      "theme": "default",
      "enableComments": false,
      "analyticsId": "GA-XXXXX"
    },
    "storageConfigId": 1,
    "status": 1,
    "createdAt": "2025-01-01 12:00:00",
    "updatedAt": "2025-01-02 14:00:00"
  }
}

2.3 创建网站 ​

请求

POST /site

请求体

json
{
  "name": "短剧推广站",
  "domain": "drama.example.com",
  "siteType": "drama",
  "logoUrl": "https://cdn.example.com/drama-logo.png",
  "description": "短剧推广专用站点",
  "seoTitle": "热门短剧推荐",
  "seoKeywords": "短剧,热门短剧,短剧推荐",
  "seoDescription": "精选热门短剧推荐",
  "config": {
    "theme": "drama",
    "enableComments": true
  },
  "storageConfigId": 1
}

2.4 更新网站 ​

请求

PUT /site/{id}

2.5 删除网站 ​

请求

DELETE /site/{id}

2.6 网站多语言配置 ​

2.6.1 获取网站语言配置列表 ​

请求

GET /site/{siteId}/locales

响应

json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "siteId": 1,
      "locale": "zh-CN",
      "localeName": "简体中文",
      "nativeName": "简体中文",
      "isDefault": true,
      "isEnabled": true,
      "storagePathTemplate": "zh-CN/{category}/{slug}",
      "urlTemplate": "/{category}/{slug}",
      "urlPrefix": "",
      "aiPromptSuffix": null,
      "sortOrder": 0
    },
    {
      "id": 2,
      "siteId": 1,
      "locale": "en-US",
      "localeName": "English",
      "nativeName": "English",
      "isDefault": false,
      "isEnabled": true,
      "storagePathTemplate": "en-US/{category}/{slug}",
      "urlTemplate": "/en/{category}/{slug}",
      "urlPrefix": "/en",
      "aiPromptSuffix": "Please write the article in English.",
      "sortOrder": 1
    }
  ]
}

2.6.2 添加网站语言配置 ​

请求

POST /site/{siteId}/locales

请求体

json
{
  "locale": "ja-JP",
  "localeName": "日本語",
  "nativeName": "日本語",
  "isDefault": false,
  "storageConfigId": null,
  "storagePathTemplate": "ja-JP/{category}/{slug}",
  "urlTemplate": "/ja/{category}/{slug}",
  "urlPrefix": "/ja",
  "seoTitleTemplate": "{title} | ゲーム攻略",
  "seoDescriptionTemplate": "{description}",
  "aiPromptSuffix": "記事を日本語で書いてください。",
  "translationPrompt": "以下の中国語の文章を日本語に翻訳してください。"
}

2.6.3 更新网站语言配置 ​

请求

PUT /site/{siteId}/locales/{localeId}

2.6.4 删除网站语言配置 ​

请求

DELETE /site/{siteId}/locales/{localeId}

2.6.5 设置默认语言 ​

请求

PUT /site/{siteId}/locales/{localeId}/default

2.7 推广站点公开接口 ​

这些接口供推广站点（前端展示站）调用，用于获取内容数据。

2.7.1 根据域名获取网站配置 ​

请求

GET /public/site/config
参数类型必填说明
domainString是网站域名

响应

json
{
  "code": 200,
  "data": {
    "id": 1,
    "name": "游戏推广站A",
    "siteType": "game",
    "logoUrl": "https://cdn.example.com/logo.png",
    "faviconUrl": "https://cdn.example.com/favicon.ico",
    "seoTitle": "最新游戏下载",
    "seoKeywords": "游戏下载,破解游戏",
    "seoDescription": "提供最新游戏下载服务",
    "defaultLocale": "zh-CN",
    "supportedLocales": ["zh-CN", "en-US", "ja-JP"],
    "i18nMode": "subdirectory",
    "locales": [
      {
        "locale": "zh-CN",
        "localeName": "简体中文",
        "nativeName": "简体中文",
        "urlPrefix": "",
        "isDefault": true
      },
      {
        "locale": "en-US",
        "localeName": "English",
        "nativeName": "English",
        "urlPrefix": "/en",
        "isDefault": false
      }
    ],
    "config": {
      "theme": "default",
      "analyticsId": "GA-XXXXX"
    }
  }
}

2.7.2 获取站点文章列表 ​

请求

GET /public/site/{siteId}/articles
参数类型必填说明
localeString否语言代码，默认使用网站默认语言
categoryString否分类标识
pageNumInteger否页码
pageSizeInteger否每页数量

2.7.3 获取站点游戏盒子列表 ​

请求

GET /public/site/{siteId}/gameboxes
参数类型必填说明
platformString否平台：android/ios
pageNumInteger否页码
pageSizeInteger否每页数量

响应

json
{
  "code": 200,
  "data": {
    "total": 10,
    "rows": [
      {
        "id": 1,
        "name": "XX游戏盒",
        "packageName": "com.xx.gamebox",
        "platform": "android",
        "iconUrl": "https://cdn.example.com/icon.png",
        "downloadUrl": "https://download.example.com/xx.apk",
        "version": "1.2.0",
        "description": "最新游戏盒子"
      }
    ]
  }
}

2.7.4 获取站点游戏列表 ​

请求

GET /public/site/{siteId}/games
参数类型必填说明
gameTypeString否游戏类型
gameboxIdLong否关联的游戏盒子ID
pageNumInteger否页码
pageSizeInteger否每页数量

3. 文档服务接口 ​

3.1 文档列表 ​

请求

GET /document/list
参数类型必填说明
categoryIdLong否分类ID
keywordString否关键词
statusInteger否状态
pageNumInteger否页码，默认1
pageSizeInteger否每页数量，默认20

响应

json
{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 1000,
    "rows": [
      {
        "id": 1,
        "slug": "xianxia/jianlai",
        "title": "剑来破解版下载",
        "categoryName": "仙侠",
        "viewCount": 12345,
        "isPublished": 1,
        "publishedAt": "2025-01-01 12:00:00"
      }
    ]
  }
}

2.2 文档详情 ​

请求

GET /document/{id}

响应

json
{
  "code": 200,
  "data": {
    "id": 1,
    "slug": "xianxia/jianlai",
    "title": "剑来破解版下载",
    "content": "Markdown 内容...",
    "categoryId": 2,
    "keywords": "仙侠,无限元宝,破解版",
    "viewCount": 12345,
    "relatedGames": [
      {
        "id": 10,
        "name": "剑来",
        "iconUrl": "https://..."
      }
    ]
  }
}

2.3 同步文档到 ES ​

请求

POST /document/sync
参数类型必填说明
documentIdsLong[]否文档ID列表，空则全量同步
forceReindexBoolean否是否强制重建索引

响应

json
{
  "code": 200,
  "data": {
    "taskId": "sync-20250101-001",
    "totalCount": 1000,
    "status": "processing"
  }
}

2.4 从 R2 拉取文档 ​

请求

POST /document/pull
参数类型必填说明
prefixString否R2 路径前缀

4. 搜索服务接口 ​

3.1 全文搜索 ​

请求

GET /search
参数类型必填说明
qString是搜索关键词
categoryString否分类筛选
sortString否排序：relevance/date/views
pageInteger否页码
sizeInteger否每页数量

响应

json
{
  "code": 200,
  "data": {
    "total": 256,
    "took": 23,
    "hits": [
      {
        "id": 1,
        "slug": "xianxia/jianlai",
        "title": "<em>剑来</em>破解版下载",
        "highlight": "...<em>无限元宝</em>修改器...",
        "category": "仙侠",
        "score": 15.234
      }
    ],
    "aggregations": {
      "categories": {
        "仙侠": 100,
        "传奇": 80,
        "三国": 50
      }
    }
  }
}

3.2 搜索建议 ​

请求

GET /search/suggest
参数类型必填说明
qString是输入前缀
sizeInteger否建议数量

响应

json
{
  "code": 200,
  "data": {
    "suggestions": [
      "仙侠游戏",
      "仙侠破解版",
      "仙侠无限元宝"
    ]
  }
}

3.3 热门搜索 ​

请求

GET /search/hot
参数类型必填说明
limitInteger否数量限制，默认10

响应

json
{
  "code": 200,
  "data": {
    "keywords": [
      { "keyword": "传奇", "count": 5000 },
      { "keyword": "仙侠", "count": 4500 },
      { "keyword": "三国", "count": 3800 }
    ]
  }
}

5. 游戏服务接口 ​

4.1 游戏列表 ​

请求

GET /game/list
参数类型必填说明
categoryString否游戏分类
keywordString否搜索关键词
statusInteger否状态
pageNumInteger否页码
pageSizeInteger否每页数量

4.2 创建游戏 ​

请求

POST /game
json
{
  "name": "剑来",
  "category": "仙侠",
  "description": "一款仙侠类手游",
  "iconUrl": "https://...",
  "downloadUrl": "https://...",
  "features": ["无限元宝", "满V特权"]
}

4.3 游戏盒子列表 ​

请求

GET /gamebox/list

响应

json
{
  "code": 200,
  "data": {
    "rows": [
      {
        "id": 1,
        "name": "咪噜游戏",
        "logoUrl": "https://...",
        "discountRate": 0.3,
        "gameCount": 500,
        "features": ["3折充值", "海量福利"]
      }
    ]
  }
}

6. 关联服务接口 ​

5.1 自动关联 ​

请求

POST /relation/auto
参数类型必填说明
documentIdLong是文档ID
thresholdFloat否相关度阈值，默认0.5
limitInteger否最大关联数量

响应

json
{
  "code": 200,
  "data": {
    "relations": [
      {
        "gameId": 10,
        "gameName": "剑来",
        "relevanceScore": 0.92,
        "matchedKeywords": ["剑来", "仙侠", "修仙"]
      }
    ]
  }
}

5.2 手动关联 ​

请求

POST /relation/manual
json
{
  "documentId": 1,
  "gameId": 10,
  "isPrimary": true
}

5.3 获取文档关联 ​

请求

GET /relation/document/{documentId}

响应

json
{
  "code": 200,
  "data": {
    "relations": [
      {
        "id": 1,
        "gameId": 10,
        "gameName": "剑来",
        "relationType": "auto",
        "relevanceScore": 0.92,
        "isPrimary": true
      }
    ]
  }
}

7. 统计服务接口 ​

6.1 仪表盘数据 ​

请求

GET /analytics/dashboard

响应

json
{
  "code": 200,
  "data": {
    "overview": {
      "totalDocuments": 100000,
      "todayNewDocuments": 50,
      "totalGames": 500,
      "totalPageViews": 1000000,
      "todayPageViews": 5000
    },
    "categoryDistribution": [
      { "name": "仙侠", "count": 15000 },
      { "name": "传奇", "count": 12000 }
    ],
    "viewTrend": [
      { "date": "2025-01-01", "pv": 5000, "uv": 2000 }
    ],
    "hotKeywords": [
      { "keyword": "传奇", "count": 500 }
    ]
  }
}

6.2 内容统计 ​

请求

GET /analytics/content
参数类型必填说明
startDateString否开始日期
endDateString否结束日期
groupByString否分组：day/week/month

6.3 搜索统计 ​

请求

GET /analytics/search
参数类型必填说明
startDateString否开始日期
endDateString否结束日期

响应

json
{
  "code": 200,
  "data": {
    "totalSearches": 50000,
    "avgSearchTime": 45,
    "zeroResultRate": 0.05,
    "topKeywords": [
      { "keyword": "仙侠", "count": 5000, "ctr": 0.65 }
    ],
    "zeroResultKeywords": [
      { "keyword": "未知游戏", "count": 100 }
    ]
  }
}

6.4 记录浏览 ​

请求

POST /analytics/pageview
json
{
  "documentId": 1,
  "pagePath": "/pojie/xianxia/jianlai",
  "referer": "https://google.com",
  "sessionId": "abc123"
}

8. 提示词模板接口 ​

7.1 模板列表 ​

请求

GET /prompt-template/list
参数类型必填说明
siteIdLong否站点ID
templateTypeString否模板类型：game_intro/game_guide/drama_intro等
statusInteger否状态
pageNumInteger否页码
pageSizeInteger否每页数量

响应

json
{
  "code": 200,
  "data": {
    "total": 50,
    "rows": [
      {
        "id": 1,
        "templateName": "游戏介绍通用模板",
        "templateType": "game_intro",
        "description": "用于生成游戏介绍文章",
        "variables": ["game_name", "game_type", "features"],
        "status": 1,
        "usageCount": 1500
      }
    ]
  }
}

7.2 创建模板 ​

请求

POST /prompt-template
json
{
  "siteId": 1,
  "templateName": "游戏攻略模板",
  "templateType": "game_guide",
  "description": "用于生成游戏攻略文章",
  "systemPrompt": "你是一名专业的游戏攻略作者...",
  "userPromptTemplate": "请为{game_name}生成一篇攻略文章，包含以下要点：{key_points}",
  "variables": ["game_name", "key_points", "target_audience"],
  "defaultValues": {
    "target_audience": "新手玩家"
  }
}

7.3 预览模板 ​

请求

POST /prompt-template/preview
json
{
  "templateId": 1,
  "variables": {
    "game_name": "剑来",
    "game_type": "仙侠",
    "features": ["无限元宝", "满V特权"]
  }
}

响应

json
{
  "code": 200,
  "data": {
    "systemPrompt": "你是一名专业的游戏攻略作者...",
    "userPrompt": "请为剑来生成一篇游戏介绍..."
  }
}

9. 文章资源接口 ​

8.1 资源列表 ​

请求

GET /article-resource/list
参数类型必填说明
articleIdLong否文章ID
resourceTypeString否资源类型：image/video/audio/file
migrationStatusString否迁移状态
pageNumInteger否页码
pageSizeInteger否每页数量

响应

json
{
  "code": 200,
  "data": {
    "total": 500,
    "rows": [
      {
        "id": 1,
        "articleId": 100,
        "resourceType": "image",
        "originalUrl": "https://old-cdn.com/img/001.jpg",
        "currentUrl": "https://new-cdn.com/img/001.jpg",
        "storageConfigId": 2,
        "fileSize": 102400,
        "migrationStatus": "completed"
      }
    ]
  }
}

8.2 上传资源 ​

请求

POST /article-resource/upload
Content-Type: multipart/form-data
参数类型必填说明
fileFile是上传文件
articleIdLong是文章ID
storageConfigIdLong否存储配置ID
resourceTypeString否资源类型

响应

json
{
  "code": 200,
  "data": {
    "id": 1,
    "url": "https://cdn.example.com/articles/100/img001.jpg",
    "fileName": "img001.jpg",
    "fileSize": 102400,
    "mimeType": "image/jpeg"
  }
}

8.3 批量迁移资源 ​

请求

POST /article-resource/migrate
json
{
  "ruleId": 1,
  "articleIds": [100, 101, 102],
  "dryRun": false
}

响应

json
{
  "code": 200,
  "data": {
    "taskId": "migrate-20251214-001",
    "totalCount": 150,
    "status": "processing"
  }
}

10. 存储配置接口 ​

10.1 存储配置列表 ​

请求

GET /storage-config/list
参数类型必填说明
siteIdLong否网站ID（不传返回全局配置）
storageTypeString否存储类型：github/minio/r2/oss/cos/s3
storagePurposeString否存储用途：article/resource/mixed
statusInteger否状态：0-禁用 1-启用
pageNumInteger否页码，默认1
pageSizeInteger否每页数量，默认20

响应

json
{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 3,
    "rows": [
      {
        "id": 1,
        "siteId": null,
        "name": "主存储-R2",
        "code": "r2-main",
        "storageType": "r2",
        "storagePurpose": "mixed",
        "isDefault": 1,
        "priority": 10,
        "cdnUrl": "https://cdn.example.com",
        "capacityLimit": 10737418240,
        "usedCapacity": 2147483648,
        "capacityPercent": 20.0,
        "fileCount": 1520,
        "isCapacityFull": 0,
        "healthStatus": "healthy",
        "fallbackStorageId": 2,
        "status": 1,
        "createdAt": "2025-01-01 12:00:00"
      },
      {
        "id": 2,
        "siteId": null,
        "name": "备用存储-OSS",
        "code": "oss-backup",
        "storageType": "oss",
        "storagePurpose": "resource",
        "isDefault": 0,
        "priority": 20,
        "cdnUrl": "https://oss-cdn.example.com",
        "capacityLimit": null,
        "usedCapacity": 0,
        "capacityPercent": 0,
        "fileCount": 0,
        "isCapacityFull": 0,
        "healthStatus": "healthy",
        "fallbackStorageId": null,
        "status": 1,
        "createdAt": "2025-01-01 12:00:00"
      }
    ]
  }
}

10.2 存储配置详情 ​

请求

GET /storage-config/{id}

响应

json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "siteId": null,
    "name": "主存储-R2",
    "code": "r2-main",
    "storageType": "r2",
    "storagePurpose": "mixed",
    "isDefault": 1,
    "priority": 10,
    "r2AccountId": "xxxxx",
    "r2AccessKey": "xxxxx",
    "r2Bucket": "game-content",
    "r2PublicUrl": "https://pub-xxxxx.r2.dev",
    "cdnUrl": "https://cdn.example.com",
    "customDomain": "cdn.example.com",
    "basePath": "articles",
    "maxFileSize": 10485760,
    "allowedExtensions": "md,json,txt,jpg,png,gif,webp,mp4",
    "capacityLimit": 10737418240,
    "usedCapacity": 2147483648,
    "fileCount": 1520,
    "fileCountLimit": null,
    "capacityWarningThreshold": 80.00,
    "isCapacityFull": 0,
    "capacityFullAt": null,
    "fallbackStorageId": 2,
    "autoSwitchOnFull": 1,
    "lastHealthCheck": "2025-12-14 10:00:00",
    "healthStatus": "healthy",
    "healthMessage": "连接正常，读写测试通过",
    "description": "主要存储，用于存放文章和资源文件",
    "status": 1,
    "createdBy": 1,
    "createdAt": "2025-01-01 12:00:00",
    "updatedAt": "2025-12-14 10:00:00"
  }
}

10.3 新增存储配置 ​

请求

POST /storage-config
json
{
  "siteId": null,
  "name": "备用存储-COS",
  "code": "cos-backup",
  "storageType": "cos",
  "storagePurpose": "resource",
  "priority": 30,
  "cosSecretId": "AKIDxxxxx",
  "cosSecretKey": "xxxxx",
  "cosBucket": "game-resource-1250000000",
  "cosRegion": "ap-guangzhou",
  "cdnUrl": "https://cos-cdn.example.com",
  "basePath": "resources",
  "maxFileSize": 52428800,
  "allowedExtensions": "jpg,png,gif,webp,mp4,webm",
  "capacityLimit": 53687091200,
  "capacityWarningThreshold": 85.00,
  "fallbackStorageId": null,
  "autoSwitchOnFull": 1,
  "description": "腾讯云COS备用存储"
}

10.4 修改存储配置 ​

请求

PUT /storage-config/{id}

10.5 删除存储配置 ​

请求

DELETE /storage-config/{id}

10.6 设置默认存储 ​

请求

PUT /storage-config/{id}/default
参数类型必填说明
siteIdLong否网站ID（设置该网站的默认存储）
storagePurposeString否存储用途（按用途设置默认）

10.7 测试存储连接 ​

请求

POST /storage-config/{id}/test

响应

json
{
  "code": 200,
  "msg": "success",
  "data": {
    "connected": true,
    "readTest": true,
    "writeTest": true,
    "deleteTest": true,
    "latencyMs": 120,
    "message": "连接正常，所有测试通过"
  }
}

10.8 刷新存储容量 ​

手动刷新存储的实际容量信息。

请求

POST /storage-config/{id}/refresh-capacity

响应

json
{
  "code": 200,
  "msg": "success",
  "data": {
    "previousCapacity": 2147483648,
    "currentCapacity": 2200000000,
    "previousFileCount": 1520,
    "currentFileCount": 1535,
    "capacityPercent": 20.48,
    "refreshedAt": "2025-12-14 10:30:00"
  }
}

10.9 获取可用存储 ​

根据用途和网站获取可用的存储配置（自动排除已满和不健康的存储）。

请求

GET /storage-config/available
参数类型必填说明
siteIdLong否网站ID
storagePurposeString否存储用途：article/resource/mixed

响应

json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "name": "主存储-R2",
      "code": "r2-main",
      "storageType": "r2",
      "priority": 10,
      "capacityPercent": 20.0,
      "isDefault": 1
    },
    {
      "id": 2,
      "name": "备用存储-OSS",
      "code": "oss-backup",
      "storageType": "oss",
      "priority": 20,
      "capacityPercent": 0,
      "isDefault": 0
    }
  ]
}

10.10 容量使用记录 ​

请求

GET /storage-config/{id}/capacity-logs
参数类型必填说明
logTypeString否日志类型：upload/delete/sync/manual
startTimeString否开始时间
endTimeString否结束时间
pageNumInteger否页码，默认1
pageSizeInteger否每页数量，默认20

响应

json
{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 100,
    "rows": [
      {
        "id": 1,
        "storageConfigId": 1,
        "logType": "upload",
        "fileCountChange": 1,
        "capacityChange": 1024000,
        "fileCountAfter": 1521,
        "capacityAfter": 2148507648,
        "capacityPercent": 20.01,
        "articleId": 123,
        "resourceId": 456,
        "filePath": "articles/2025/12/game-guide.md",
        "fileSize": 1024000,
        "triggerSource": "api",
        "triggerUserId": 1,
        "createdAt": "2025-12-14 11:00:00"
      }
    ]
  }
}

11. 存储迁移规则接口 ​

11.1 规则列表 ​

请求

GET /storage-migration-rule/list
参数类型必填说明
ruleTypeString否规则类型：url_replace/storage_move等
statusInteger否状态
pageNumInteger否页码
pageSizeInteger否每页数量

响应

json
{
  "code": 200,
  "data": {
    "total": 10,
    "rows": [
      {
        "id": 1,
        "ruleName": "旧CDN迁移到R2",
        "ruleType": "storage_move",
        "sourcePattern": "https://old-cdn.com/*",
        "targetTemplate": "https://r2.example.com/{path}",
        "sourceStorageId": 1,
        "targetStorageId": 2,
        "status": 1,
        "executedCount": 5000
      }
    ]
  }
}

11.2 创建规则 ​

请求

POST /storage-migration-rule
json
{
  "ruleName": "图床迁移到OSS",
  "ruleType": "storage_move",
  "description": "将所有图床资源迁移到阿里云OSS",
  "sourcePattern": "https://imgbed.com/**",
  "targetTemplate": "https://oss.example.com/images/{filename}",
  "sourceStorageId": 1,
  "targetStorageId": 3,
  "scopeType": "all",
  "priority": 10
}

11.3 执行规则 ​

请求

POST /storage-migration-rule/{id}/execute
json
{
  "dryRun": true,
  "batchSize": 100,
  "articleIds": []
}

响应

json
{
  "code": 200,
  "data": {
    "taskId": "rule-exec-20251214-001",
    "matchedCount": 1500,
    "estimatedTime": "15分钟",
    "dryRunResults": [
      {
        "resourceId": 1,
        "originalUrl": "https://imgbed.com/a.jpg",
        "targetUrl": "https://oss.example.com/images/a.jpg"
      }
    ]
  }
}

11.4 迁移日志 ​

请求

GET /storage-migration-log/list
参数类型必填说明
ruleIdLong否规则ID
resourceIdLong否资源ID
migrationStatusString否迁移状态
startTimeDateTime否开始时间
endTimeDateTime否结束时间

响应

json
{
  "code": 200,
  "data": {
    "total": 5000,
    "rows": [
      {
        "id": 1,
        "ruleId": 1,
        "resourceId": 100,
        "originalUrl": "https://old.com/a.jpg",
        "targetUrl": "https://new.com/a.jpg",
        "migrationStatus": "completed",
        "executedAt": "2025-12-14 10:00:00",
        "executedBy": "system"
      }
    ]
  }
}

12. 前端专用接口 ​

以下接口供 Next.js 前端调用，无需认证

12.1 获取文章内容 ​

请求

GET /public/article/{slug}

响应

json
{
  "code": 200,
  "data": {
    "title": "剑来破解版下载",
    "content": "Markdown 内容",
    "category": "仙侠",
    "publishedAt": "2025-01-01",
    "readingTime": 5,
    "relatedGames": [],
    "relatedArticles": []
  }
}

10.2 获取分类列表 ​

请求

GET /public/categories

10.3 获取游戏盒子 ​

请求

GET /public/gameboxes

13. 接口流程图 ​

11.1 搜索流程 ​

11.2 文档同步流程 ​

14. AI 生成任务接口 ​

12.1 批量任务列表 ​

请求

GET /ai-task/batch/list
参数类型必填说明
taskNameString否任务名称
taskTypeString否任务类型：single/batch
scheduleTypeString否调度类型：manual/once/cron
statusInteger否状态
pageNumInteger否页码
pageSizeInteger否每页数量

响应

json
{
  "code": 200,
  "data": {
    "total": 5,
    "rows": [
      {
        "id": 1,
        "taskName": "每日仙侠游戏文章生成",
        "taskType": "batch",
        "scheduleType": "cron",
        "cronExpression": "0 0 2 * * ?",
        "totalCount": 5,
        "status": 2,
        "isEnabled": true,
        "nextExecutionTime": "2025-12-15T02:00:00",
        "lastExecutionTime": "2025-12-14T02:00:00"
      }
    ]
  }
}

12.2 创建批量任务 ​

请求

POST /ai-task/batch
json
{
  "taskName": "每日游戏文章生成",
  "taskType": "batch",
  "scheduleType": "cron",
  "cronExpression": "0 0 2 * * ?",
  "batchConfig": {
    "tasks": [
      {
        "gameName": "剑来",
        "category": "xianxia",
        "template": "game-intro",
        "customPrompt": "重点介绍修炼体系",
        "keywords": "仙侠,修仙",
        "imageEnabled": true,
        "imageEngine": "unsplash"
      },
      {
        "gameName": "传奇世界",
        "category": "chuanqi",
        "template": "game-intro"
      }
    ],
    "options": {
      "aiProvider": "deepseek",
      "imageSearchEnabled": true,
      "imageSearchEngine": "unsplash",
      "maxConcurrent": 2
    }
  },
  "githubRepoId": 1
}

响应

json
{
  "code": 200,
  "data": {
    "id": 1,
    "taskName": "每日游戏文章生成",
    "totalCount": 2,
    "nextExecutionTime": "2025-12-15T02:00:00"
  }
}

12.3 立即执行任务 ​

请求

POST /ai-task/batch/{id}/execute

响应

json
{
  "code": 200,
  "data": {
    "executionId": 100,
    "executionNo": "exec-20251214-001",
    "workflowRunId": 12345678,
    "workflowRunUrl": "https://github.com/user/repo/actions/runs/12345678",
    "status": "triggered"
  }
}

12.4 查询执行记录 ​

请求

GET /ai-task/execution/list
参数类型必填说明
batchTaskIdLong否批量任务ID
statusInteger否状态
startDateString否开始日期
endDateString否结束日期
pageNumInteger否页码
pageSizeInteger否每页数量

响应

json
{
  "code": 200,
  "data": {
    "total": 10,
    "rows": [
      {
        "id": 100,
        "batchTaskId": 1,
        "executionNo": "exec-20251214-001",
        "workflowRunId": 12345678,
        "workflowRunUrl": "https://github.com/user/repo/actions/runs/12345678",
        "workflowStatus": "completed",
        "workflowConclusion": "success",
        "totalArticles": 5,
        "completedArticles": 5,
        "failedArticles": 0,
        "totalTokens": 15000,
        "totalImages": 12,
        "status": 3,
        "startedAt": "2025-12-14T02:00:05",
        "completedAt": "2025-12-14T02:15:30",
        "executionDuration": 925
      }
    ]
  }
}

12.5 查询执行详情（实时监控） ​

请求

GET /ai-task/execution/{id}

响应

json
{
  "code": 200,
  "data": {
    "id": 100,
    "batchTaskId": 1,
    "executionNo": "exec-20251214-001",
    "workflowRunId": 12345678,
    "workflowStatus": "in_progress",
    "totalArticles": 5,
    "completedArticles": 3,
    "failedArticles": 0,
    "status": 2,
    "progress": 60,
    "items": [
      {
        "id": 1,
        "itemIndex": 0,
        "gameName": "剑来",
        "category": "xianxia",
        "status": 2,
        "articleId": 1001,
        "generatedFilePath": "src/docs/pojie/xianxia/jianlai.md",
        "tokensUsed": 3200,
        "imagesProcessed": 3,
        "executionTimeMs": 45000,
        "completedAt": "2025-12-14T02:03:00"
      },
      {
        "id": 2,
        "itemIndex": 1,
        "gameName": "传奇世界",
        "category": "chuanqi",
        "status": 2,
        "articleId": 1002,
        "tokensUsed": 2800,
        "imagesProcessed": 2,
        "completedAt": "2025-12-14T02:06:00"
      },
      {
        "id": 3,
        "itemIndex": 2,
        "gameName": "三国志战略版",
        "category": "sanguo",
        "status": 1,
        "startedAt": "2025-12-14T02:06:05"
      },
      {
        "id": 4,
        "itemIndex": 3,
        "gameName": "原神",
        "category": "erciyuan",
        "status": 0
      },
      {
        "id": 5,
        "itemIndex": 4,
        "gameName": "明日方舟",
        "category": "celue",
        "status": 0
      }
    ]
  }
}

12.6 刷新 Workflow 状态 ​

从 GitHub API 同步最新的 Workflow 执行状态。

请求

POST /ai-task/execution/{id}/refresh

响应

json
{
  "code": 200,
  "data": {
    "id": 100,
    "workflowStatus": "completed",
    "workflowConclusion": "success",
    "completedArticles": 5,
    "status": 3,
    "updatedAt": "2025-12-14T02:15:30"
  }
}

12.7 取消执行中的任务 ​

请求

POST /ai-task/execution/{id}/cancel

响应

json
{
  "code": 200,
  "data": {
    "id": 100,
    "status": 5,
    "cancelledAt": "2025-12-14T02:10:00"
  }
}

12.8 重试失败的文章 ​

请求

POST /ai-task/execution/{id}/retry-failed

响应

json
{
  "code": 200,
  "data": {
    "newExecutionId": 101,
    "executionNo": "exec-20251214-002",
    "retryCount": 2,
    "workflowRunId": 12345679
  }
}

12.9 Webhook 回调接口 ​

接收 GitHub Action 执行完成的回调通知。

请求

POST /ai-task/webhook
X-Webhook-Secret: <签名>

单篇完成回调

json
{
  "event": "article_complete",
  "taskId": "exec-20251214-001",
  "runId": 12345678,
  "itemIndex": 0,
  "gameName": "剑来",
  "status": "success",
  "generatedFile": "src/docs/pojie/xianxia/jianlai.md",
  "tokensUsed": 3200,
  "imagesProcessed": 3,
  "executionTimeMs": 45000,
  "completedAt": "2025-12-14T02:03:00Z"
}

批量完成回调

json
{
  "event": "batch_complete",
  "taskId": "exec-20251214-001",
  "runId": 12345678,
  "status": "success",
  "totalArticles": 5,
  "completedArticles": 5,
  "failedArticles": 0,
  "totalTokens": 15000,
  "completedAt": "2025-12-14T02:15:30Z"
}

响应

json
{
  "code": 200,
  "message": "ok"
}

15. GitHub 集成接口 ​

13.1 获取 OAuth 授权 URL ​

请求

GET /github/oauth/authorize

响应

json
{
  "code": 200,
  "data": {
    "authUrl": "https://github.com/login/oauth/authorize?client_id=xxx&scope=repo,workflow&state=xxx"
  }
}

13.2 OAuth 回调 ​

请求

GET /github/oauth/callback?code=xxx&state=xxx

响应

json
{
  "code": 200,
  "data": {
    "connected": true,
    "username": "user123",
    "avatarUrl": "https://avatars.githubusercontent.com/u/xxx"
  }
}

13.3 Fork 生成器仓库 ​

请求

POST /github/fork-generator

响应

json
{
  "code": 200,
  "data": {
    "repoId": 1,
    "fullName": "user123/game-box-ai-generator",
    "htmlUrl": "https://github.com/user123/game-box-ai-generator"
  }
}

13.4 同步 Secrets ​

请求

POST /github/sync-secrets
json
{
  "repoId": 1,
  "secrets": {
    "DEEPSEEK_API_KEY": "sk-xxx",
    "UNSPLASH_ACCESS_KEY": "xxx"
  }
}

响应

json
{
  "code": 200,
  "data": {
    "synced": ["DEEPSEEK_API_KEY", "UNSPLASH_ACCESS_KEY"],
    "failed": []
  }
}

13.5 查询 Workflow 状态 ​

请求

GET /github/workflow/{runId}/status

响应

json
{
  "code": 200,
  "data": {
    "runId": 12345678,
    "status": "in_progress",
    "conclusion": null,
    "createdAt": "2025-12-14T02:00:00Z",
    "updatedAt": "2025-12-14T02:05:00Z",
    "jobs": [
      {
        "id": 1,
        "name": "prepare",
        "status": "completed",
        "conclusion": "success"
      },
      {
        "id": 2,
        "name": "generate (剑来, xianxia, game-intro)",
        "status": "completed",
        "conclusion": "success"
      },
      {
        "id": 3,
        "name": "generate (传奇世界, chuanqi, game-intro)",
        "status": "in_progress",
        "conclusion": null
      }
    ]
  }
}

16. 接口调用流程 ​

14.1 AI 文章生成流程 ​

17. 版本历史 ​

版本日期修改内容
v1.0.02025-12-13初始版本，基础CRUD接口
v2.2.02025-12-14新增提示词模板接口、文章资源接口、存储迁移规则接口
v2.3.02025-12-14新增AI生成任务接口、GitHub集成接口、Webhook回调接口
v2.6.02025-12-14新增网站多语言配置API，更新推广站点公开接口支持locale参数
v2.7.02025-12-14新增存储配置管理接口（包括容量管理、健康检查、存储轮换、容量日志查询）

游戏盒子内容管理系统

Copyright © 2025