SCForge 开放 API

更新: 10/5/2026 字数: 0 字 时长: 0 分钟

SCForge（生存战争插件 / 模组资源平台）对第三方开放的接口：资源（插件 / 模组）与版本的目录查询、发布、评论与投票。资源用 kind 区分插件与模组。

鉴权方式、作用域划分、错误形状与调用约定见对外开放 API 总览。要把发布流程接进 CI（打 tag 后自动把插件发到本平台），见 开发与自动化参考 —— 里面含 GitHub / Gitee / CNB 三个平台的密钥配置教程与完整工作流示例。

v1.0.0

SCForge 开放 API

下载 OpenAPI 文档

JSON

下载 OpenAPI 文档

YAML

SCForge（生存战争插件 / 模组资源平台）的对外开放接口。

鉴权：读接口匿名可用；与「我的资源」相关的读写需要 API Key —— 请求头 Authorization: Bearer scf_。签发与作用域见接入指南。

错误形状：所有错误响应统一为 { "detail": "中文说明" }（见 ApiError.cs），HTTP 状态码即语义（400 参数或规则不合法、401 未登录、403 作用域不足、404 资源不存在、409 状态冲突）。

时间：所有时间字段按北京时间（UTC+8，+08:00）输出。

服务器

https://api.cldery.com生产环境

---

ScforgeAddons

资源目录与发布接口（路由前缀 /scforge/addons）。

「资源」= 插件（kind=plugin，仅服务端）与模组（kind=mod，会下发到客户端）两类，
共用同一棵资源树与同一套接口，靠 kind 字段（查询参数 / 响应字段）区分；
界面上的「插件」「模组」两个板块只是对 kind 的预设筛选。

读取接口匿名可用（只看已通过审核的内容），登录后额外回传「我的投票」；
写入接口要求 Cookie 会话，发布与编辑只属于作者本人；
管理员的内容管理走 /scforge/admin。

操作

GET/scforge/addonsPOST/scforge/addonsGET/scforge/addons/featuredGET/scforge/addons/recentGET/scforge/addons/mineGET/scforge/addons/mine/summaryGET/scforge/addons/{idOrSlug}PUT/scforge/addons/{id}DELETE/scforge/addons/{id}POST/scforge/addons/{id}/versionsPOST/scforge/addons/{id}/resubmitGET/scforge/addons/{id}/voteDELETE/scforge/addons/{id}/votePUT/scforge/addons/{id}/vote/upPUT/scforge/addons/{id}/vote/down

---

分页搜索：q / category / tag / gameVersion / sort / kind / page / pageSize。kind 省略即插件与模组都返回。

GET

/scforge/addons

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

查询参数

q

类型

string

category

类型

string

tag

类型

string

gameVersion

类型

string

sort

类型

string

kind

类型

string

page

类型

integer

格式

"int32"

默认

1

pageSize

类型

integer

格式

"int32"

默认

24

响应

OK

GET

/scforge/addons

试验场

授权

ScforgeApiKey

变量

键

值

q

category

tag

gameVersion

sort

kind

page

pageSize

示例

---

发布新资源（multipart/form-data）。提交后进入待审核，管理员通过后才对公众可见。 kind 决定是插件（plugin）还是模组（mod），创建后不可更改，包文件按 kind 校验扩展名。 请求体上限按「资源包上限 + 图片预算」放宽，否则大包会被 Kestrel 的 30MB 默认值挡下。

POST

/scforge/addons

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

请求体

multipart/form-data

资源包（必填）：.dll（插件）或 .netmod（模组，会下发到客户端）。

格式"binary"

资源类型：plugin（插件，仅服务端）或 mod（模组，会下发到客户端）。创建后不可更改。

标签键；同名多值可在表单里重复出现。

资源图标（可选）：JPG / PNG / WebP / GIF。

格式"binary"

截图（可选，最多 6 张）。

响应

OK

POST

/scforge/addons

试验场

授权

ScforgeApiKey

主体

Package

Kind

Name

Slug

Summary

Description

Readme

Category

GameVersion

Tags

SourceUrl

IssuesUrl

License

LicenseUrl

DonationUrl

DiscordUrl

Icon

Gallery

Version

Channel

Changelog

GameVersions

Dependencies

示例

---

首页精选：显式精选优先，不足时按净评分补齐；kind 可限定只看插件或只看模组。

GET

/scforge/addons/featured

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

查询参数

limit

类型

integer

格式

"int32"

默认

6

kind

类型

string

响应

OK

GET

/scforge/addons/featured

试验场

授权

ScforgeApiKey

变量

键

值

limit

kind

示例

---

最近更新；kind 可限定只看插件或只看模组。

GET

/scforge/addons/recent

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

查询参数

limit

类型

integer

格式

"int32"

默认

8

kind

类型

string

响应

OK

GET

/scforge/addons/recent

试验场

授权

ScforgeApiKey

变量

键

值

limit

kind

示例

---

当前用户发布的资源（含待审核与已驳回）。

GET

/scforge/addons/mine

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

响应

OK

GET

/scforge/addons/mine

试验场

授权

ScforgeApiKey

示例

---

「我的资源」页的统计卡（含三种审核状态的数量）。

GET

/scforge/addons/mine/summary

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

响应

OK

GET

/scforge/addons/mine/summary

试验场

授权

ScforgeApiKey

示例

---

详情：idOrSlug 接受 GUID 或 slug。

GET

/scforge/addons/{idOrSlug}

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

idOrSlug*

类型

string

必填

响应

OK

GET

/scforge/addons/{idOrSlug}

试验场

授权

ScforgeApiKey

变量

键

值

idOrSlug*

示例

---

编辑资源资料（作者，multipart）：编辑会重新进入待审核。

PUT

/scforge/addons/{id}

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

请求体

multipart/form-data

传入即替换图标。

格式"binary"

传入即整体替换截图列表（最多 6 张）。

清空图标。

清空截图。

响应

OK

PUT

/scforge/addons/{id}

试验场

授权

ScforgeApiKey

变量

键

值

id*

主体

Summary

Description

Readme

Category

GameVersion

Tags

SourceUrl

IssuesUrl

License

LicenseUrl

DonationUrl

DiscordUrl

Icon

Gallery

ClearIcon

ClearGallery

示例

---

删除资源（连同版本、评论与投票）。

DELETE

/scforge/addons/{id}

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

DELETE

/scforge/addons/{id}

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

追加一个版本（multipart）：新版本进入待审核。

POST

/scforge/addons/{id}/versions

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

请求体

multipart/form-data

格式"binary"

缺省时沿用资源的主游戏版本。

响应

OK

POST

/scforge/addons/{id}/versions

试验场

授权

ScforgeApiKey

变量

键

值

id*

主体

Package

Version

Channel

Changelog

GameVersions

Dependencies

GameVersion

示例

---

把被驳回的资源重新提交审核。

POST

/scforge/addons/{id}/resubmit

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

POST

/scforge/addons/{id}/resubmit

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

当前用户对某资源的投票状态（匿名可调，恒为 0）。

GET

/scforge/addons/{id}/vote

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

GET

/scforge/addons/{id}/vote

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

撤销投票（幂等：没有票也算成功）。

DELETE

/scforge/addons/{id}/vote

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

DELETE

/scforge/addons/{id}/vote

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

PUT /scforge/addons/{id}/vote/up

PUT

/scforge/addons/{id}/vote/up

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

PUT

/scforge/addons/{id}/vote/up

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

PUT /scforge/addons/{id}/vote/down

PUT

/scforge/addons/{id}/vote/down

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

PUT

/scforge/addons/{id}/vote/down

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

ScforgeApiKeys

API Key 的自助管理（路由前缀 /scforge/api-keys）。

与后台的 /scforge/admin/api-keys 分开：这里只管「登录用户管自己的 Key」，
后台是超管巡检全站（含他人 Key 的吊销）。

认证方式与 SCForge 其余写端点一致：不挂 [Authorize]，由
ClouderyApi.Modules.Scforge.Api.ScforgeControllerBase 的异常翻译产出
{"detail":"…"}（统一错误体）；调用者身份由 Cookie 会话或 API Key 两条通道之一提供。

操作

GET/scforge/api-keys/scopesGET/scforge/api-keysPOST/scforge/api-keysPOST/scforge/api-keys/{id}/revokePOST/scforge/api-keys/{id}/rotate

---

可授予的作用域清单（含中文名与说明），供界面渲染勾选项。

GET

/scforge/api-keys/scopes

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

响应

OK

GET

/scforge/api-keys/scopes

试验场

授权

ScforgeApiKey

示例

---

我的 Key 列表（含已吊销，便于确认"那把旧的真的失效了"）。

GET

/scforge/api-keys

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

响应

OK

GET

/scforge/api-keys

试验场

授权

ScforgeApiKey

示例

---

签发一把新 Key。**响应里的 token 只出现这一次** —— 请立刻保存，之后无法再取回。

POST

/scforge/api-keys

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

请求体

{

  

"name": "string",

  

"scopes": [

  

  

"string"

  

],

  

"expiresAt": "string"

}

响应

OK

POST

/scforge/api-keys

试验场

授权

ScforgeApiKey

主体

示例

---

吊销自己的某把 Key。

POST

/scforge/api-keys/{id}/revoke

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

请求体

{

  

"reason": "string"

}

响应

OK

POST

/scforge/api-keys/{id}/revoke

试验场

授权

ScforgeApiKey

变量

键

值

id*

主体

示例

---

轮换：吊销旧的、签发一把同权限的新 Key（用于泄露后一键换锁）。 响应同样只带一次明文。

POST

/scforge/api-keys/{id}/rotate

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

POST

/scforge/api-keys/{id}/rotate

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

ScforgeComments

评论与评论投票（路由前缀 /scforge）。

读取匿名可用（未登录时 myVote 恒为 0、canEdit / canDelete 为 false）；
写入要求 Cookie 会话；编辑仅限作者，删除允许作者或管理员（巡查）。
只有已通过审核的资源（插件 / 模组）对公众开放评论。

操作

GET/scforge/addons/{addonId}/commentsPOST/scforge/addons/{addonId}/commentsDELETE/scforge/comments/{id}PATCH/scforge/comments/{id}PUT/scforge/comments/{id}/vote/upPUT/scforge/comments/{id}/vote/downDELETE/scforge/comments/{id}/vote

---

资源的评论树（顶层评论 + 嵌套回复）。

GET

/scforge/addons/{addonId}/comments

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

addonId*

类型

string

必填

格式

"uuid"

响应

OK

GET

/scforge/addons/{addonId}/comments

试验场

授权

ScforgeApiKey

变量

键

值

addonId*

示例

---

发表评论；带 parentId 时是对某条评论的回复。

POST

/scforge/addons/{addonId}/comments

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

addonId*

类型

string

必填

格式

"uuid"

请求体

{

  

"body": "string",

  

"parentId": "string"

}

响应

OK

POST

/scforge/addons/{addonId}/comments

试验场

授权

ScforgeApiKey

变量

键

值

addonId*

主体

示例

---

删除评论及其全部回复。

DELETE

/scforge/comments/{id}

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

DELETE

/scforge/comments/{id}

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

编辑自己的评论。

PATCH

/scforge/comments/{id}

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

请求体

{

  

"body": "string"

}

响应

OK

PATCH

/scforge/comments/{id}

试验场

授权

ScforgeApiKey

变量

键

值

id*

主体

示例

---

PUT /scforge/comments/{id}/vote/up

PUT

/scforge/comments/{id}/vote/up

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

PUT

/scforge/comments/{id}/vote/up

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

PUT /scforge/comments/{id}/vote/down

PUT

/scforge/comments/{id}/vote/down

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

PUT

/scforge/comments/{id}/vote/down

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

DELETE /scforge/comments/{id}/vote

DELETE

/scforge/comments/{id}/vote

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

DELETE

/scforge/comments/{id}/vote

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

ScforgeGameVersions

受支持的游戏版本（公开只读）：发布页与筛选面板的取值来源。

操作

GET/scforge/game-versions

---

GET /scforge/game-versions

GET

/scforge/game-versions

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

响应

OK

GET

/scforge/game-versions

试验场

授权

ScforgeApiKey

示例

---

ScforgeVersions

版本接口（路由前缀 /scforge/versions）：
下载 + 作者侧维护（改元数据 / 换文件 / 删除 / 重新提交审核）。
维护动作只属于作者，且改动后版本会回到待审核。

操作

GET/scforge/versions/{id}/downloadDELETE/scforge/versions/{id}PATCH/scforge/versions/{id}POST/scforge/versions/{id}/filePOST/scforge/versions/{id}/resubmit

---

下载某个版本。下载入口统一走这里（而不是静态目录）， 这样未通过审核的版本不会被直接拿到，下载次数也才有唯一口径。

GET

/scforge/versions/{id}/download

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

GET

/scforge/versions/{id}/download

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

删除一个版本（仅作者）。删除是下架动作，不需要审核。

DELETE

/scforge/versions/{id}

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

DELETE

/scforge/versions/{id}

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

编辑版本元数据（仅作者）：重新进入待审核。

PATCH

/scforge/versions/{id}

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

请求体

{

  

"channel": "string",

  

"changelog": "string",

  

"gameVersion": "string",

  

"gameVersions": [

  

  

"string"

  

],

  

"dependencies": [

  

  

"string"

  

]

}

响应

OK

PATCH

/scforge/versions/{id}

试验场

授权

ScforgeApiKey

变量

键

值

id*

主体

示例

---

替换版本的插件包文件（仅作者）：重新进入待审核。

POST

/scforge/versions/{id}/file

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

请求体

multipart/form-data

格式"binary"

响应

OK

POST

/scforge/versions/{id}/file

试验场

授权

ScforgeApiKey

变量

键

值

id*

主体

示例

---

把被驳回的版本重新提交审核。

POST

/scforge/versions/{id}/resubmit

授权

ScforgeApiKey

SCForge API Key（scf_ 开头）。读接口匿名也可调用，带上 Key 才能访问「我的资源」与写接口。

类型

HTTP (bearer)

参数

路径参数

id*

类型

string

必填

格式

"uuid"

响应

OK

POST

/scforge/versions/{id}/resubmit

试验场

授权

ScforgeApiKey

变量

键

值

id*

示例

---

技术支持 VitePress OpenAPI