★ FEATURED ARTICLE 后端前端桌面应用CLI游戏开发【免费下载链接】ServerPackCreatorCreate a server pack from a Minecraft Forge, NeoForge, Fabric, LegacyFabric or Quilt modpack!项目地址https://gitcode.com/gh_mirrors/se/ServerPackCreator点击查看免费下载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持久化依赖 MongoDBcompose 中使用mongodb/mongodb-community-server容器可通过SPC_*环境变量对实例行为进行配置。在serverpackcreator-app/src/main/resources/application.properties中默认监听端口被固定为server.port8080与 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。分页端点的两个查询参数均为可选参数默认值说明page0从 0 开始的页码size100每页条数源码中的实现统一为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分类方法与路径说明ModpackPOST /modpacks/upload上传模组包 zip 并排队ModpackPOST /modpacks/generate为已上传的模组包按新配置排队生成ModpackGET /modpacks/{id}、GET /modpacks/all、GET /modpacks/allpaginated查询模组包ModpackGET /modpacks/download/{id}下载模组包归档ModpackGET /modpacks/byserverpack/{id}由服务端包反查模组包ServerPackGET /serverpacks/{id}、GET /serverpacks/all、GET /serverpacks/allpaginated查询服务端包ServerPackGET /serverpacks/download/{id}按服务端包 ID 下载 zipServerPackGET /serverpacks/download/{modPackId}{runConfigurationId}按模组包 ID 运行配置 ID 下载 zipServerPackGET /serverpacks/vote/{id}{vote}对服务端包投「可用 / 不可用」票RunConfigsGET /runconfigs/{id}、GET /runconfigs/all查询已存储的运行配置VersionsGET /versions/minecraft、/versions/forge、/versions/forge/{mc}、/versions/neoforge、/versions/neoforge/{mc}、/versions/fabric、/versions/legacyfabric、/versions/quilt、/versions/all查询 Minecraft 与各加载器版本EventsGET /events/all、/events/allpaginated、/events/modpack/{id}、/events/serverpack/{id}、/events/status/{status}读取队列进度事件StatsGET /stats/packs、/stats/disk、/stats/creation/serverpacks、/stats/creation/modpacks、/stats/downloads/serverpacks、/stats/downloads/modpacks及各自/history、/historypaginated变体只读统计信息SettingsGET /settings/current读取实例设置快照5. 核心流程一上传模组包upload5.1 请求参数POST /api/v2/modpacks/upload的请求体是multipart/form-data文件字段名为filetype: string, format: binary必填其余参数按 OpenAPI 声明为查询参数均必填参数说明minecraftVersion模组包的 Minecraft 版本如1.20.1modloader加载器如ForgemodloaderVersion加载器版本如47.2.0startArgs启动参数可空字符串clientMods客户端专用模组列表可空字符串whiteListMods白名单模组列表可空字符串curl 示例curl -X POST http://localhost:8080/api/v2/modpacks/upload?minecraftVersion1.20.1modloaderForgemodloaderVersion47.2.0startArgsclientModswhiteListMods \ -F file/path/to/modpack.zip5.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 }字段类型说明messagestring人类可读的结果说明successboolean是否成功modPackId/runConfigId/serverPackIdstring | null相关对象 IDstatusenum当前所处状态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. 核心流程二触发生成generatePOST /api/v2/modpacks/generate接收与 upload 相同的一组参数外加modPackID必填用于对已上传的模组包以一套新的运行配置重新排队生成curl -X POST http://localhost:8080/api/v2/modpacks/generate?modPackIDabc123minecraftVersion1.20.1modloaderForgemodloaderVersion47.2.0startArgsclientModswhiteListMods源码逻辑ModPackController.kt会先查模组包是否存在再检查「同一模组包 同一运行配置」是否已有服务端包模组包不存在 → 400status: ERROR服务端包已存在 → 400success: false并在serverPackId中给出既有服务端包 IDstatus: GENERATED——用于幂等防重复否则入队返回success: true, status: QUEUED。「运行配置」RunConfiguration在这里是一个关键概念minecraftVersion modloader modloaderVersion startArgs clientMods whitelistedMods的六元组决定了一次生成的具体形态。上传时服务端会用这些参数自动创建一条运行配置见 RunConfigurationController.kt。7. 核心流程三轮询进度events生成是异步的因此自动化脚本需要一个「状态推进」的观察渠道这就是事件端点。事件模型QueueEvent包含字段说明id事件 IDmodPackId/serverPackId关联对象 IDstatus状态枚举QUEUED/CHECKING/CHECKED/GENERATING/GENERATED/ERRORmessage状态说明timestamp发生时间date-timeerrors错误条目数组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/abc12342响应为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总量统计AmountStatsDatamodPacks、serverPacks、runConfigurations以及按 Minecraft 版本/加载器/加载器版本分组的计数对象GET /stats/disk磁盘使用DiskStatsDataidentifier、dirName、rootName、totalSpace、freeSpace、usedBySPCGET /stats/creation/serverpacks与GET /stats/creation/modpacks按日期的创建量序列AmountPerDatedatecreationsGET /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/isZipFileExclusionEnabledZIP 归档级排除清单及其开关exclusionFilter排除匹配方式枚举START/END/CONTAIN/REGEX/EITHERisAutoExcludingModsEnabled是否自动扫描并剔除客户端专用模组isMinecraftPreReleasesAvailabilityEnabled是否提供快照/预发布版 Minecraft 版本aikarsFlags推荐的 Aikars Flags JVM 参数串language实例语言源码注释特别提醒布尔字段通过JsonProperty保留is前缀如isZipFileExclusionEnabled因为 Jackson 默认会从布尔 getter 上剥掉它——如果你自己写客户端字段名必须带上is前缀。11. 主要数据模型速查除上文已列的ZipResponse、QueueEvent、Settings外还有三个核心实体schema 详见 api-docs.yaml 的components.schemasModPack模组包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?minecraftVersion1.20.1modloaderForgemodloaderVersion47.2.0startArgsclientModswhiteListMods \ -F filemodpack.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 的ApiWrapperPackConfig编程式用法而本组 REST API 适合那些「不想依赖 JVM 依赖、希望用任意语言脚本驱动生成」的部署场景——前端 axios.ts 就是这套 API 最完整、一直在维护的活样例。赞分享后端前端桌面应用CLI游戏开发【免费下载链接】ServerPackCreatorCreate a server pack from a Minecraft Forge, NeoForge, Fabric, LegacyFabric or Quilt modpack!项目地址https://gitcode.com/gh_mirrors/se/ServerPackCreator点击查看免费下载相关推荐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 技能/插件渗透测试红蓝对抗上一篇WarcraftHelper技术解析魔兽争霸III兼容性与性能优化全方案下一篇魔兽争霸3终极优化指南如何让经典游戏在现代电脑上流畅运行创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
