- 后端
- 前端
- 桌面应用
- CLI
- 游戏开发
【免费下载链接】ServerPackCreator
Create a server pack from a Minecraft Forge, NeoForge, Fabric, LegacyFabric or Quilt modpack!
ServerPackCreator 的 Web 服务（webservice）将「模组包 → 服务端包」的生成能力封装成了一组版本化的 REST API，前端界面本身只是这套 API 的一个客户端。本文以官方 API 参考文档 API-reference.md 为主线，结合仓库内由 springdoc 生成的 OpenAPI 规范 api-docs.yaml 与各 Controller 源码，完整讲解如何脱离浏览器、用脚本与程序直接驱动自己的 ServerPackCreator 实例完成上传、生成、轮询、下载全流程，并给出每个端点的参数、响应模型与 curl 示例。
阅读本文前请知悉：官方并未提供公开可用的 webservice 实例——出于安全考虑（该服务允许上传 zip 归档），如需使用 API，你必须自行托管一个实例。文中所有响应示例仅为示例，实际返回的字段可能更多或更少（例如更多版本、更多模组包或服务端包）。
1. 这组 API 是什么、解决什么问题
REST API 是 ServerPackCreator 网页模式的对外接口。官方文档明确了两件事：
- 你不必用浏览器访问网页模式。前端（
serverpackcreator-web-frontend）本身就是这组 REST API 的调用方，你完全可以像前端一样直接调用它； - 它的核心用途是自动化：通过脚本编排「上传模组包 → 触发服务端包生成 → 轮询进度 → 下载产物」的流程，从而在你自己的 webservice 实例上自动化部署服务端包。
这一点在源码中得到印证：前端引导文件 axios.ts 将所有实例的baseURL统一设置为/api/v2/，并分别封装了versions、settings、events、serverpacks、modpacks、runConfigs、stats七组客户端——它们对应的正是后端de.griefed.serverpackcreator.app.web包下的七个 Controller。
API 的完整、机器可读定义存放在 api-docs.yaml，这是一份 OpenAPI 3.1 规范，其头部声明所有 path、schema 与请求体均由 springdoc 依据 Controller 自动生成、禁止手工修改（重新生成的命令位于serverpackcreator-app/build.gradle.kts）。也就是说，这份 YAML 就是 REST API 的事实参考，下面各节的端点信息均来源于它及对应的 Controller 源码。
2. 自托管一个 webservice 实例
由于没有公共实例，使用 API 的第一步是自托管。仓库 docker/docker-compose.yml 提供了一键启动方案：
- 服务端镜像为
griefed/serverpackcreator:latest，端口映射8080:8080； - 持久化依赖 MongoDB（compose 中使用
mongodb/mongodb-community-server容器）； - 可通过
SPC_*环境变量对实例行为进行配置。
在serverpackcreator-app/src/main/resources/application.properties中，默认监听端口被固定为server.port=8080，与 compose 的映射一致。启动后，所有 API 都挂在http://localhost:8080/api/v2/之下。
启动命令：
docker compose -f docker/docker-compose.yml up -d3. 基础约定：路径、跨域、分页与状态机
3.1 路径前缀与数据格式
所有端点均以/api/v2为前缀，路径模板直接写在各 Controller 的@RequestMapping注解上，例如ModPackController是/api/v2/modpacks、ServerPackController是/api/v2/serverpacks。JSON 响应统一通过Content-Type: application/json返回，下载类端点返回application/zip。所有 Controller 都标注了@CrossOrigin(origins = ["*"])，因此从任意浏览器来源跨域调用都不受限。
3.2 分页参数
列表类端点通常同时提供「全量」与「分页」两个版本（如/all与/allpaginated）。分页端点的两个查询参数均为可选：
| 参数 | 默认值 | 说明 |
|---|---|---|
page | 0 | 从 0 开始的页码 |
size | 100 | 每页条数 |
源码中的实现统一为PageRequest.of(page, size)（见 ModPackController.kt）。官方建议优先使用分页端点，因为全量端点在数据量增长后会产生过大的响应。
3.3 生成状态机
上传、生成与事件系统中的status字段遵循同一个枚举，取值固定为：
QUEUED → CHECKING → CHECKED → GENERATING → GENERATED ↘ ERROR即：排队 → 校验中 → 校验完成 → 生成中 → 生成完成，任何阶段失败都会进入ERROR。该枚举同样出现在ModPack与QueueEvent的 schema 中。
4. 端点总览
按 Controller 归类，/api/v2下的全部端点如下（信息来自 api-docs.yaml）：
| 分类 | 方法与路径 | 说明 |
|---|---|---|
| Modpack | POST /modpacks/upload | 上传模组包 zip 并排队 |
| Modpack | POST /modpacks/generate | 为已上传的模组包按新配置排队生成 |
| Modpack | GET /modpacks/{id}、GET /modpacks/all、GET /modpacks/allpaginated | 查询模组包 |
| Modpack | GET /modpacks/download/{id} | 下载模组包归档 |
| Modpack | GET /modpacks/byserverpack/{id} | 由服务端包反查模组包 |
| ServerPack | GET /serverpacks/{id}、GET /serverpacks/all、GET /serverpacks/allpaginated | 查询服务端包 |
| ServerPack | GET /serverpacks/download/{id} | 按服务端包 ID 下载 zip |
| ServerPack | GET /serverpacks/download/{modPackId}&{runConfigurationId} | 按模组包 ID + 运行配置 ID 下载 zip |
| ServerPack | GET /serverpacks/vote/{id}&{vote} | 对服务端包投「可用 / 不可用」票 |
| RunConfigs | GET /runconfigs/{id}、GET /runconfigs/all | 查询已存储的运行配置 |
| Versions | GET /versions/minecraft、/versions/forge、/versions/forge/{mc}、/versions/neoforge、/versions/neoforge/{mc}、/versions/fabric、/versions/legacyfabric、/versions/quilt、/versions/all | 查询 Minecraft 与各加载器版本 |
| Events | GET /events/all、/events/allpaginated、/events/modpack/{id}、/events/serverpack/{id}、/events/status/{status} | 读取队列进度事件 |
| Stats | GET /stats/packs、/stats/disk、/stats/creation/serverpacks、/stats/creation/modpacks、/stats/downloads/serverpacks、/stats/downloads/modpacks及各自/history、/historypaginated变体 | 只读统计信息 |
| Settings | GET /settings/current | 读取实例设置快照 |
5. 核心流程一：上传模组包（upload）
5.1 请求参数
POST /api/v2/modpacks/upload的请求体是multipart/form-data，文件字段名为file（type: string, format: binary，必填）；其余参数按 OpenAPI 声明为查询参数，均必填：
| 参数 | 说明 |
|---|---|
minecraftVersion | 模组包的 Minecraft 版本，如1.20.1 |
modloader | 加载器，如Forge |
modloaderVersion | 加载器版本，如47.2.0 |
startArgs | 启动参数（可空字符串） |
clientMods | 客户端专用模组列表（可空字符串） |
whiteListMods | 白名单模组列表（可空字符串） |
curl 示例：
curl -X POST "http://localhost:8080/api/v2/modpacks/upload?minecraftVersion=1.20.1&modloader=Forge&modloaderVersion=47.2.0&startArgs=&clientMods=&whiteListMods=" \ -F "file=@/path/to/modpack.zip"5.2 响应：ZipResponse
成功（HTTP 200）与失败（HTTP 400）都会返回同一结构ZipResponse：
{ "message": "File is being stored and will be queued for checks.", "success": true, "modPackId": "abc123", "runConfigId": "42", "serverPackId": null, "status": "QUEUED" }| 字段 | 类型 | 说明 |
|---|---|---|
message | string | 人类可读的结果说明 |
success | boolean | 是否成功 |
modPackId/runConfigId/serverPackId | string | null | 相关对象 ID |
status | enum | 当前所处状态 |
5.3 源码行为细节
实现见 ModPackController.kt，有几个值得注意的工程细节：
- 空文件与空参数直接拒绝：
file.size == 0L或三个版本相关参数为空时返回 400。源码注释特别指出，这里刻意不使用file.bytes.isEmpty()，因为getBytes()会把整个上传物物化为ByteArray，而 Java 数组上限约 2 GB——在上传上限高达 5000MB 的配置下，大文件上传将直接 OOM； - 哈希去重：与已有上传内容哈希相同的归档会被识别并直接返回既有模组包，不会重复存储，响应中的 message 会说明属于哪种情况；
- 异步队列：上传成功后并不立即生成，而是构造
TaskDetail后调用taskExecutionServiceImpl.submitTaskInQueue(...)入队，所以返回的status是QUEUED，后续进度需要轮询事件端点。
6. 核心流程二：触发生成（generate）
POST /api/v2/modpacks/generate接收与 upload 相同的一组参数，外加modPackID（必填），用于对已上传的模组包以一套新的运行配置重新排队生成：
curl -X POST "http://localhost:8080/api/v2/modpacks/generate?modPackID=abc123&minecraftVersion=1.20.1&modloader=Forge&modloaderVersion=47.2.0&startArgs=&clientMods=&whiteListMods="源码逻辑（ModPackController.kt）会先查模组包是否存在，再检查「同一模组包 + 同一运行配置」是否已有服务端包：
- 模组包不存在 → 400，
status: ERROR； - 服务端包已存在 → 400，
success: false，并在serverPackId中给出既有服务端包 ID，status: GENERATED——用于幂等防重复； - 否则入队，返回
success: true, status: QUEUED。
「运行配置」（RunConfiguration）在这里是一个关键概念：minecraftVersion + modloader + modloaderVersion + startArgs + clientMods + whitelistedMods的六元组决定了一次生成的具体形态。上传时服务端会用这些参数自动创建一条运行配置，见 RunConfigurationController.kt。
7. 核心流程三：轮询进度（events）
生成是异步的，因此自动化脚本需要一个「状态推进」的观察渠道，这就是事件端点。事件模型QueueEvent包含：
| 字段 | 说明 |
|---|---|
id | 事件 ID |
modPackId/serverPackId | 关联对象 ID |
status | 状态枚举（QUEUED/CHECKING/CHECKED/GENERATING/GENERATED/ERROR） |
message | 状态说明 |
timestamp | 发生时间（date-time） |
errors | 错误条目数组（ErrorEntry，仅含error字段） |
按需选择查询维度（EventController.kt）：
# 某个模组包的完整生命周期 curl "http://localhost:8080/api/v2/events/modpack/abc123" # 某个服务端包的事件 curl "http://localhost:8080/api/v2/events/serverpack/xyz789" # 只看失败事件，快速定位问题 curl "http://localhost:8080/api/v2/events/status/ERROR"前端 SPA 正是通过轮询这些事件来驱动上传页面的进度条（EventController 的源码注释将其描述为 "the stream the SPA polls while an upload is processed"）。你的自动化脚本可以复用同一套轮询策略：先以QUEUED状态提交，随后按固定间隔轮询events/modpack/{id}，直到出现GENERATED或ERROR。
8. 核心流程四：下载产物（download）
服务端包生成完毕后，有两种下载路径（见 ServerPackController.kt）：
# 方式一：直接用服务端包 ID curl -OJ "http://localhost:8080/api/v2/serverpacks/download/xyz789" # 方式二：用模组包 ID + 运行配置 ID（路径中两个 ID 以 & 连接） curl -OJ "http://localhost:8080/api/v2/serverpacks/download/abc123&42"响应为application/zip流，Content-Disposition: attachment指定的文件名形如<fileName>_server_pack.zip。源码中文件名使用ContentDisposition.attachment().filename(...)构建而非字符串拼接，以规避文件名中的引号/分号对响应头的注入（见 ModPackController.kt 的注释）。每次下载都会累计下载统计（updateDownloadStats），这正是 stats 端点数据的来源之一。
模组包归档本身也可以下载：GET /api/v2/modpacks/download/{id}。
9. 版本查询端点（versions）
自动化脚本在提交生成前通常需要确认版本组合有效，versions控制器（VersionsController.kt）提供全部查询能力：
# 全部 Minecraft 正式版 curl "http://localhost:8080/api/v2/versions/minecraft" # 某个 Minecraft 版本可用的 Forge 版本（不存在时返回 404） curl "http://localhost:8080/api/v2/versions/forge/1.20.1" # 全部 Forge 版本（按 Minecraft 版本分组的对象） curl "http://localhost:8080/api/v2/versions/forge" # NeoForge / Fabric / LegacyFabric / Quilt 同理 curl "http://localhost:8080/api/v2/versions/neoforge/1.21.1" curl "http://localhost:8080/api/v2/versions/fabric" # 一键获取全量版本矩阵 curl "http://localhost:8080/api/v2/versions/all"/versions/all返回VersionMetaResponse，结构如下：
{ "minecraft": ["1.20.1", "1.21.1"], "fabric": ["0.15.11"], "legacyFabric": ["0.8.9"], "quilt": ["0.25.3"], "forge": { "1.20.1": ["47.2.0"] }, "neoForge": { "1.21.1": ["21.1.24"] } }其中forge与neoForge是「Minecraft 版本 → 加载器版本数组」的映射对象，而 Fabric/LegacyFabric/Quilt 的加载器版本不绑定 Minecraft 版本，所以是纯数组。这些数据直接来自 API 层的VersionMeta（即 serverpackcreator-api/README.md 中描述的 Mojang 与各加载器 manifest 缓存机制），并由VersionRefreshSchedule按配置的 cron 定时刷新（见 VersionRefreshSchedule.kt）。
10. 统计与设置端点
10.1 stats（只读仪表数据）
StatsController（路径前缀/api/v2/stats，见 StatsController.kt）把所有计算委托给 service 层，自身不做聚合：
GET /stats/packs：总量统计AmountStatsData（modPacks、serverPacks、runConfigurations，以及按 Minecraft 版本/加载器/加载器版本分组的计数对象）；GET /stats/disk：磁盘使用DiskStatsData（identifier、dirName、rootName、totalSpace、freeSpace、usedBySPC）；GET /stats/creation/serverpacks与GET /stats/creation/modpacks：按日期的创建量序列AmountPerDate（date+creations）；GET /stats/downloads/...：下载量序列、单个对象的全部下载记录（ServerPackDownload/ModPackDownload，含downloadedAt时间戳）、以及/history与/historypaginated明细历史。
10.2 settings/current（实例设置快照）
GET /api/v2/settings/current返回Settings，是 SPA 启动时读取的实例配置快照（SettingsController.kt）。自动化脚本可据此动态适配实例能力，例如用supportedModloaders而非硬编码加载器列表：
| 字段 | 说明 |
|---|---|
clientsideMods/whitelistMods | 内置客户端专用模组列表 / 白名单（可作为上传参数clientMods、whiteListMods的默认值） |
supportedModloaders | 实例支持的加载器列表 |
version/devBuild | 实例版本与是否为本地 dev 构建 |
directoriesToInclude/directoriesToExclude | 默认包含 / 排除的模组包目录 |
zipArchiveExclusions/isZipFileExclusionEnabled | ZIP 归档级排除清单及其开关 |
exclusionFilter | 排除匹配方式枚举：START/END/CONTAIN/REGEX/EITHER |
isAutoExcludingModsEnabled | 是否自动扫描并剔除客户端专用模组 |
isMinecraftPreReleasesAvailabilityEnabled | 是否提供快照/预发布版 Minecraft 版本 |
aikarsFlags | 推荐的 Aikar's Flags JVM 参数串 |
language | 实例语言 |
源码注释特别提醒：布尔字段通过@JsonProperty保留is前缀（如isZipFileExclusionEnabled），因为 Jackson 默认会从布尔 getter 上剥掉它——如果你自己写客户端，字段名必须带上is前缀。
11. 主要数据模型速查
除上文已列的ZipResponse、QueueEvent、Settings外，还有三个核心实体（schema 详见 api-docs.yaml 的components.schemas）：
ModPack（模组包）：id、projectID、versionID、dateCreated、name、size、downloads、status、source（枚举ZIP/MODRINTH/CURSEFORGE/DIRECTORY）、fileID、sha256、serverPacks（关联的服务端包数组）。
ServerPack（服务端包）：id、modpackId、size、downloads、confirmedWorking、dateCreated、fileID、fileName、sha256、runConfiguration（内嵌RunConfiguration）。
RunConfiguration（运行配置）：id、minecraftVersion、modloader、modloaderVersion、startArgs、clientMods、whitelistedMods。
12. 端到端自动化示例
把上述端点串起来，一个完整的「上传 → 等待 → 下载」脚本大致如下：
# 1. 上传模组包，解析出 modPackId（以 jq 解析 JSON） UPLOAD=$(curl -s -X POST "http://localhost:8080/api/v2/modpacks/upload?minecraftVersion=1.20.1&modloader=Forge&modloaderVersion=47.2.0&startArgs=&clientMods=&whiteListMods=" \ -F "file=@modpack.zip") MODPACK_ID=$(echo "$UPLOAD" | jq -r '.modPackId') echo "queued as $MODPACK_ID" # 2. 轮询事件直到 GENERATED 或 ERROR while true; do STATUS=$(curl -s "http://localhost:8080/api/v2/events/modpack/$MODPACK_ID" | jq -r '.[-1].status') echo "status: $STATUS" [ "$STATUS" = "GENERATED" ] && break [ "$STATUS" = "ERROR" ] && exit 1 sleep 5 done # 3. 取最新服务端包 ID 并下载 SERVERPACK_ID=$(curl -s "http://localhost:8080/api/v2/modpacks/$MODPACK_ID" | jq -r '.serverPacks[-1].id') curl -OJ "http://localhost:8080/api/v2/serverpacks/download/$SERVERPACK_ID"注意：脚本中的轮询间隔、状态取值（[-1]取最新事件）均可按需调整，但「以状态枚举为准、以事件为进度来源」的模式与前端实现一致。
13. 注意事项与已知边界
综合官方文档与源码，调用这组 API 时有几点务必留意：
- 安全边界是文档明确写明的：没有公共实例，上传 zip 归档的能力决定了它只适合自托管。
- 响应示例可变：文档提醒所有响应示例仅为示例，实际返回值可能更多或更少——版本列表、模组包列表、服务端包列表都会随时间增长。脚本应容忍未知字段，不要对字段集合做死假设。
- ID 的路径正则：所有
{id}路径参数均限制为[0-9a-zA-Z]+（数字与大小写字母），且模组包 ID 路径还可能是纯数字（/download/{modPackId:[0-9]+}&{runConfigurationId:[0-9]+}）。构造 URL 时需自行 URL 编码。 /serverpacks/vote/{id}&{vote}的路径格式特殊：投票端点把id与vote两个值放在同一路径段并以&分隔（例如服务端包 ID 与投票方向），这是 OpenAPI 规范里的既定形态，调用时按原样拼写。/runconfigs的接口命名沿用历史：RunConfigurationController中「查询全部」的方法名为getAllRUnConfigurations（含拼写错误），源码注释明确说明这个拼写属于已发布的 API 表面（API surface），不会被修正——客户端实现时无需在意方法名，只要按路径调用即可。- 异步语义：upload 与 generate 都只是入队（返回
QUEUED），真正的生成在队列任务中执行。不要期待同步完成，务必以 events 的状态推进为准。 - 设置会即时生效：
/settings/current是每次请求时从ApiProperties现场构建的快照（源码注释称其为 "a flat snapshot rather than a live view"），实例端配置的改动会在下一次调用中反映出来。
若需在自有代码中直接调用底层生成能力而非走 HTTP，可参考 serverpackcreator-api/README.md 的ApiWrapper+PackConfig编程式用法；而本组 REST API 适合那些「不想依赖 JVM 依赖、希望用任意语言脚本驱动生成」的部署场景——前端 axios.ts 就是这套 API 最完整、一直在维护的活样例。
- 后端
- 前端
- 桌面应用
- CLI
- 游戏开发
【免费下载链接】ServerPackCreator
Create a server pack from a Minecraft Forge, NeoForge, Fabric, LegacyFabric or Quilt modpack!
相关推荐
Apache Zeppelin REST API完整参考：自动化管理与集成开发
Apache Zeppelin REST API完整参考：自动化管理与集成开发 Apache Zeppelin REST API 是数据分析和协作开发的强大工具
数据分析数据可视化大数据后端GPT Researcher API 参考：REST、WebSocket 与 Python 客户端完整实战指南
GPT Researcher API 参考：REST、WebSocket 与 Python 客户端完整实战指南 GPT Researcher 对外提供三种集成方
人工智能AI Agent深度研究RAG多智能体后端Anthropic-Cybersecurity-Skills 实战指南：Windows ShellBag 取证 API 参考与自动化分析
Anthropic Cybersecurity Skills 实战指南：Windows ShellBag 取证 API 参考与自动化分析 本文是围绕本仓库中 a
网络安全AI 技能/插件渗透测试红蓝对抗
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
