资源更新与 Webhook
服务器和启动器可以轮询更新接口;有公网 HTTPS 接收地址的机器人和托管服务也可以使用 Webhook。安装文件前应重新查询当前兼容构建。
用阅读器订阅版本更新
在资源详情页点击“订阅更新”,复制链接到支持 Atom 的阅读器。订阅地址使用主站域名:
/resources/example-performance/releases.atom
/resources/example-performance/releases.atom?loader=fabric&mc=1.20.1
详情页的订阅链接保留当前加载器、游戏版本和类型筛选。每条订阅内容对应一条原始发布记录,包含版本、兼容信息、发布时间、修订时间和更新说明;同版本号的不同构建可能分别出现。更新说明以纯文本保留 Markdown,超过 32768 个字符时明确标注截断。
默认订阅稳定版、最近 20 条;可使用 releaseType=release,beta,alpha 包含预发布版本,用 limit=50 调整条数(最大 50)。loader、mc、type 的联合匹配规则与下方更新查询一致。无匹配构建时返回有效的空订阅。
此订阅匿名读取,不需要账户或令牌。支持 ETag/304,每次读取都会复核当前公开状态;资源不再公开时返回 404。订阅提供当前快照,不能用于完整历史追赶,阅读器已保存的旧条目也不会被远程删除。全站内容订阅仍使用 /atom.xml。
查询当前构建
curl -i 'http://127.0.0.1:4520/v1/site/resources/example-performance/updates?loader=fabric&mc=1.20.1&releaseType=release&limit=20'
loader、mc、type 在同一条原始发布记录匹配。同维度多选为 OR,跨维度为 AND;例如 loader=fabric&loader=quilt。releaseType 可选 release、beta、alpha,默认只有 release。多选可重复参数或用英文逗号连接。limit 默认 20、最大 50。
items 按发布时间倒序,保留原始发布 ID、加载器、游戏版本和文件信息。同版本号可能有多条精确兼容记录,不能把不同记录的加载器和版本自由组合。hasMore 表示还有更旧构建;本接口是当前快照,没有历史追赶游标。映射 API 的文件 url 使用明确的网站 origin 转为绝对地址;不持久保存下载跳转得到的短期签名地址。
保存响应 ETag,后续请求带 If-None-Match,未变化返回无正文的 304。404 表示资源当前不可公开读取,应停止使用旧快照;旧 ETag 不能使它返回 304。网络/服务错误不等于资源删除,不应覆盖最后成功快照。轮询使用合理间隔和失败退避,429 时降低频率。
该接口可匿名访问,PAT/OAuth access token 需要 resource:read:feed,不需要 profile/email scope。当前 OAuth 客户端为 confidential client,不要把 client secret 放入启动器或浏览器。完整参数、文件字段与响应见匿名更新查询和带令牌更新查询。
创建订阅
登录网站,进入「账号设置 → Webhook」,按正常安全验证创建接收地址,再输入资源标识添加订阅。可选加载器、游戏版本、发布渠道和事件。每个账户最多 10 个地址,每个地址最多 100 个订阅。
订阅任意公开资源不要求维护者授权,从创建之后开始,不补发历史。私有、草稿和未到期发布不会推送。可以暂停地址、取消订阅、轮换签名密钥、查看投递状态,并重试仍符合当前授权和端点版本的失败投递。
管理接口仅接受网站 Cookie,会话敏感写入同时要求 api-token 强验证和 CSRF。PAT、OAuth access token、OAuth client secret 不能管理 Webhook。签名密钥独立于 OAuth secret,只在创建/轮换时显示一次;保存到接收端私密配置,不放入 URL、前端或日志。
接收地址必须是公网域名的 HTTPS/443,不能带用户名、密码或片段,不接受 IP literal、内网或 HTTP 重定向。URL 最长 2048 个字符;每次发送重新验证全部 A/AAAA 记录,任何非公网地址都会导致拒绝发送,并固定实际连接目标。服务需在 10 秒内完成响应,响应正文最多 64 KiB,建议成功时直接返回无正文的 204。
管理接口参考
每个管理操作的参数与响应可在 Webhook API 参考中单独查看;完整事件 schema 见 webhooks.json 的 webhooks.resourceRelease。下面是账户设置使用的 Cookie 管理接口。调用方必须拥有当前网站会话;GET 不要求二次验证,所有写操作都要求匹配 csrf_token Cookie 的 x-csrf-token 请求头,以及当前会话下用途为 api-token 的二次验证。二次验证由网站安全流程完成,有效期为 300 秒,服务器保存验证结果,无须另传 proof token。
如果自行实现同源管理界面,可通过 POST /api/auth/strong-action/verify-2fa 提交 { "scope": "api-token", "code": "当前验证码" },或通过 POST /api/auth/strong-action/verify-double-password 提交 { "scope": "api-token", "password": "双层密码" }。两者同样要求 Cookie/CSRF,成功返回 { "verified": true, "scope": "api-token", "expiresIn": 300 }。应使用账户已经绑定的认证方式;此流程不颁发 PAT,也不要求接收服务器持有网站 Cookie。
管理路径中的 id 是端点 ID。成功统一为 HTTP 200,直接返回下表结构,没有额外的 data 包装。创建、轮换与重试的请求正文必须是 JSON 对象;无参数时发送 {}。请求正文中的未知字段会被拒绝。
| 方法与路径 | 请求正文 / 查询 | 成功响应 |
|---|---|---|
GET /api/webhooks/endpoints | 无 | { items: Endpoint[], quota: 10 } |
POST /api/webhooks/endpoints | { name, url, clientId? } | { endpoint: Endpoint, signingSecret } |
PATCH /api/webhooks/endpoints/:id | { name?, url?, enabled? },至少一个字段 | { endpoint: Endpoint } |
DELETE /api/webhooks/endpoints/:id | 无 | { success: true } |
POST /api/webhooks/endpoints/:id/rotate-secret | {} | { endpoint: Endpoint, signingSecret } |
GET /api/webhooks/endpoints/:id/subscriptions | 无 | { items: Subscription[], quota: 100 } |
POST /api/webhooks/endpoints/:id/subscriptions | { resourceSlug, events?, loaders?, mcVersions?, releaseTypes? } | { subscription: Subscription } |
DELETE /api/webhooks/endpoints/:id/subscriptions/:subscriptionId | 无 | { success: true } |
GET /api/webhooks/endpoints/:id/deliveries | limit:1–50,默认 20;cursor:上页的 nextCursor | { items: Delivery[], hasMore, nextCursor } |
POST /api/webhooks/endpoints/:id/deliveries/:deliveryId/retry | {} | { success: true } |
name 去首尾空格后须为 1–100 个字符。clientId 可省略;提供时必须是本人当前启用的 OAuth 应用 ID,只用于关联应用状态,不提供 OAuth client secret。创建后不能修改这项关联。
订阅参数为数组,单个数组最多 100 项,单项为 1–100 个字符的字符串,重复值会去重。events 默认三种事件,且不能为空;releaseTypes 默认 ["release"],可选 release、beta、alpha,且不能为空。loaders、mcVersions 默认 [],表示该维度不限;非空时必须使用平台已有的字典值,同维度 OR、跨维度 AND,并在同一条发布记录上同时满足。不接受 type 或加载器族筛选。
同一端点对同一资源只能有一个有效订阅。修改筛选条件须删除旧订阅后重新创建,新订阅仍从创建时开始。新增订阅要求端点已启用且资源当前公开。资源之后不再公开时,列表中的 resourceSlug 为 null,resourceId 仍保留。
返回对象的字段如下;所有 ID 都按不透明字符串保存,时间为 ISO 日期时间,version 为十进制字符串:
type EventType = 'release.published' | 'release.updated' | 'release.withdrawn'
type ReleaseType = 'release' | 'beta' | 'alpha'
type Endpoint = {
id: string
name: string
url: string
clientId: string | null
enabled: boolean
version: string
createdAt: string
updatedAt: string
}
type Subscription = {
id: string
resourceId: string
resourceSlug: string | null
events: EventType[]
loaders: string[]
mcVersions: string[]
releaseTypes: ReleaseType[]
createdAt: string
}
type Delivery = {
id: string
eventId: string
eventType: EventType
releaseId: string
resourceId: string
status: 'pending' | 'sending' | 'succeeded' | 'failed' | 'cancelled'
attempts: number
httpStatus: number | null
lastError: string | null
createdAt: string
availableAt: string
finishedAt: string | null
}
端点与订阅列表不分页,分别受 10 和 100 的配额限制。投递列表按创建时间倒序分页,nextCursor 为字符串或 null;原样传回,不能自己生成游标。httpStatus 在未收到有效 HTTP 响应时可为 null;lastError 是脱敏分类,例如 http_error、dns_error、timeout、network_error、non_public_address 或 revoked,不含对端响应正文。
下面的 Fetch 示例适用于已登录网站的同源页面。先在网站完成 api-token 二次验证,再调用;不要复制会话 Cookie 到机器人或启动器中:
async function manageWebhook(path, { method = 'GET', body } = {}) {
const headers = {}
if (method !== 'GET') {
const csrf = document.cookie.split('; ')
.find(value => value.startsWith('csrf_token='))?.slice('csrf_token='.length)
if (!csrf) throw new Error('请刷新网站后重试')
headers['x-csrf-token'] = decodeURIComponent(csrf)
}
if (body !== undefined) headers['content-type'] = 'application/json'
const response = await fetch(`/api/webhooks/endpoints${path}`, {
method, credentials: 'same-origin', headers,
...(body === undefined ? {} : { body: JSON.stringify(body) }),
})
const result = await response.json()
if (!response.ok) {
throw new Error(result.data?.message ?? result.error ?? `HTTP ${response.status}`)
}
return result
}
const created = await manageWebhook('', {
method: 'POST', body: { name: '构建通知', url: 'https://receiver.example.com/webhooks/nexusmc' },
})
// created.signingSecret 仅本次响应可读,安全交付给接收端的私密配置,不写入日志。
await manageWebhook(`/${encodeURIComponent(created.endpoint.id)}/subscriptions`, {
method: 'POST',
body: {
resourceSlug: 'example-performance',
events: ['release.published', 'release.updated', 'release.withdrawn'],
loaders: ['fabric'], mcVersions: ['1.20.1'], releaseTypes: ['release'],
},
})
管理接口失败时先看 HTTP 状态,再读取响应中的 data.code 或 error:
| 状态 | 常见原因与处理 |
|---|---|
| 400 | { ok: false, error: "…" }:参数、URL、配额、重复订阅、端点停用或重试条件不满足。混用 Cookie/Bearer 会返回 MIXED_CREDENTIALS。修正输入,不自动重试创建或轮换。 |
| 401 | UNAUTHENTICATED:网站会话失效,先重新登录。 |
| 403 | CSRF_INVALID:刷新并使用当前 CSRF;STRONG_ACTION_VERIFICATION_REQUIRED:完成用途为 api-token 的二次验证;FORBIDDEN:来源或账户不允许;机器令牌可能为 TOKEN_SCOPE_REQUIRED。 |
| 404 | 端点、订阅或投递不存在,或不属于当前账户;创建订阅时也可能是资源当前不可公开读取。 |
| 409 | CONFLICT:并发操作触发唯一约束,重新读取当前列表。 |
| 429 / 5xx | 降低频率或稍后读取状态。写请求的结果未知时,先检查列表,不盲目重复创建或轮换。 |
一般错误结构为 { statusCode, statusMessage, data: { code, message, ... } },与特定 400 的结构不同。请求还受网站 Origin/Fetch Metadata 校验;跨站调用不能通过加 CSRF 请求头绕过。所有管理响应均禁止缓存。
事件与顺序
事件为 release.published、release.updated、release.withdrawn。首次公开包括定时到期和资源从草稿公开;撤回包括资源或发布不再公开。普通事件结构如下,ID 示例仅说明字段,应用应将 ID 视为不透明字符串:
{
"schemaVersion": 1,
"id": "resource-id.1",
"type": "release.published",
"sequence": "1",
"occurredAt": "2026-10-15T00:00:00.000Z",
"resource": { "id": "resource-id", "slug": "example-performance", "title": "示例资源" },
"release": {
"id": "release-id", "batchId": "batch-id", "versionNumber": "1.0.0",
"name": null, "releaseType": "release", "publishedAt": "2026-10-15T00:00:00.000Z",
"loaders": ["fabric"], "mcVersions": ["1.20.1"]
}
}
schemaVersion 是载荷协议版本;id 对应请求头的 webhook-id,同一事件重试时保持不变;occurredAt 是事件发生时间,不是本次尝试的签名时间。sequence 是资源内十进制序号,比较时使用 BigInt 或十进制整数比较,不能假设跨资源全局排序。一次发布的多个兼容配对保留各自 release ID,可按 batchId 合并通知。筛选和订阅范围会造成序号空隙,不能把空隙直接解释为丢失。
撤回只保留外层字段、resource: { id } 和 release: { id },没有旧标题、正文、文件或签名下载链接。安装事实始终以当前查询为准。端点停用/删除、订阅删除、关联应用停用,或地址/密钥变更,会取消相关旧代未完成投递;重新启用后接收新事件,使用当前快照补齐状态。已经发出的请求无法召回,仍应在接收端校验签名与当前安装事实。修改端点名称不改变版本;轮换密钥会立即推进版本,没有双密钥重叠期。
验证签名与防重放
平台向接收地址发送 POST,Content-Type: application/json,正文最多 256 KiB。请求头为 webhook-id、webhook-timestamp、webhook-signature。签名格式 v1,<base64>,HMAC-SHA256 输入为事件 ID、Unix 秒时间戳、原始正文,以两个英文句点连接:eventId.timestamp.rawBody。密钥就是创建/轮换返回的 signingSecret 字符串,按 UTF-8 使用,不做 Base64 解码。必须先保留原始正文再解析 JSON,不能重新序列化对象来验签;代理和中间件也不能改写正文。
以下完整示例使用 Node.js 内置模块,无第三方依赖。保存为 webhook-receiver.mjs。它只做本地联调:接收并保存到最多 100 条的内存 inbox,进程重启即丢失;满时返回 503,不淘汰旧事件伪装成持久去重。生产中的持久保存方法见下一节。
import { createHmac, timingSafeEqual } from 'node:crypto'
import { createServer } from 'node:http'
const secret = process.env.WEBHOOK_SIGNING_SECRET
if (!secret) throw new Error('请设置 WEBHOOK_SIGNING_SECRET')
const MAX_BYTES = 256 * 1024
const inbox = new Map() // 仅演示;生产替换为持久事务和队列。
const eventTypes = new Set(['release.published', 'release.updated', 'release.withdrawn'])
class HttpError extends Error {
constructor(status) { super(`HTTP ${status}`); this.status = status }
}
function verifyWebhook(headers, rawBody, secret) {
const id = headers['webhook-id']
const timestamp = headers['webhook-timestamp']
const signature = headers['webhook-signature']
if (typeof id !== 'string' || !/^[a-zA-Z0-9._-]{1,128}$/.test(id) ||
typeof timestamp !== 'string' || !/^\d{1,16}$/.test(timestamp) ||
typeof signature !== 'string' ||
!/^v1,[A-Za-z0-9+/]{43}=$/.test(signature)) return false
const seconds = Number(timestamp)
if (!Number.isSafeInteger(seconds) ||
Math.abs(Math.floor(Date.now() / 1000) - seconds) > 300) return false
const expected = createHmac('sha256', secret)
.update(`${id}.${timestamp}.`).update(rawBody).digest()
const received = Buffer.from(signature.slice(3), 'base64')
return received.length === expected.length && timingSafeEqual(received, expected)
}
function readRawBody(request) {
return new Promise((resolve, reject) => {
let size = 0
const chunks = []
const timer = setTimeout(() => reject(new HttpError(408)), 5000)
const finish = (error, body) => {
clearTimeout(timer)
if (error) reject(error)
else resolve(body)
}
request.on('data', chunk => {
size += chunk.length
if (size > MAX_BYTES) {
chunks.length = 0
finish(new HttpError(413))
return
}
chunks.push(chunk)
})
request.once('end', () => finish(null, Buffer.concat(chunks)))
request.once('error', () => finish(new HttpError(400)))
request.once('aborted', () => finish(new HttpError(400)))
})
}
const server = createServer({
maxHeaderSize: 16 * 1024, headersTimeout: 5000, requestTimeout: 8000,
}, async (request, response) => {
const reply = status => {
response.writeHead(status, { Connection: 'close' })
response.end()
request.resume()
}
try {
if (request.url !== '/webhooks/nexusmc') throw new HttpError(404)
if (request.method !== 'POST') throw new HttpError(405)
const contentType = request.headers['content-type']?.split(';', 1)[0].trim().toLowerCase()
if (contentType !== 'application/json' || request.headers['content-encoding']) {
throw new HttpError(415)
}
const contentLength = request.headers['content-length']
if (contentLength !== undefined && Number(contentLength) > MAX_BYTES) throw new HttpError(413)
const rawBody = await readRawBody(request) // 先限制原始字节,再验签、解析。
if (!verifyWebhook(request.headers, rawBody, secret)) throw new HttpError(401)
let event
try { event = JSON.parse(rawBody.toString('utf8')) }
catch { throw new HttpError(400) }
if (!event || typeof event !== 'object' || Array.isArray(event) ||
event.id !== request.headers['webhook-id']) throw new HttpError(400)
if (event.schemaVersion !== 1 || !eventTypes.has(event.type)) throw new HttpError(422)
if (typeof event.sequence !== 'string' || !/^\d+$/.test(event.sequence) ||
typeof event.resource?.id !== 'string' || typeof event.release?.id !== 'string') {
throw new HttpError(400)
}
if (inbox.has(event.id)) return reply(204) // 已保存的重复事件同样确认。
if (inbox.size >= 100) throw new HttpError(503)
inbox.set(event.id, event) // 生产必须等持久事务提交成功后才能返回 2xx。
reply(204)
} catch (error) {
reply(error instanceof HttpError ? error.status : 503)
}
})
server.maxConnections = 100
server.listen(8080, '127.0.0.1', () => console.log('Webhook 联调接收器已启动'))
在 shell 中通过环境变量注入真实签名密钥后启动:
WEBHOOK_SIGNING_SECRET='创建或轮换时显示的 signingSecret' node webhook-receiver.mjs
PowerShell 使用 $env:WEBHOOK_SIGNING_SECRET = '创建或轮换时显示的 signingSecret',然后运行 node ./webhook-receiver.mjs。本地监听地址是 http://127.0.0.1:8080/webhooks/nexusmc,不能直接登记为平台端点;实际接入时由公网域名的 HTTPS/443 反向代理转发,并保留原始正文与三个签名头。接收器中的 300 秒时间窗是接入方选择的防重放策略,需要保持系统时间准确;每次投递尝试会使用新的签名时间戳。
示例返回 404(路径不匹配)、405(非 POST)、415(非 JSON 或压缩正文)、413(超出 256 KiB)、408(读取正文超时)、401(签名或时间窗不合法)、400(JSON/字段/头部 ID 不一致)、422(不支持的协议版本或事件)、503(inbox 满或处理异常)。204 只表示这个演示进程已保存到内存。示例不打印密钥、签名、事件载荷或资源 ID。
持久去重与处理
生产接收端应把验签后的事件写入持久 inbox,并在同一个数据库事务内完成以下两步,再返回 2xx:
- 按
(接入来源, event.id)唯一约束插入 inbox;重复且已成功提交的事件直接确认。 - 为新事件写入自己的持久任务来源,或在同一事务中完成本地业务变更。事务失败返回 5xx,让平台重试。
唯一约束的来源应是同一平台环境,不能只用某一次接收进程的内存或可轮换密钥。若多个端点触发独立业务动作,可把本地逻辑消费者加入唯一键。先标记“已处理”再异步调用外部机器人会留下丢消息窗口;先调用再标记则可能重复,外部副作用还需使用其幂等键或可恢复任务。持久 inbox 本身不承诺外部副作用 exactly-once。
按事件 ID 去重与按序号保护状态是两件事。事件可能重复、乱序,时间窗不能代替去重;同一发布记录的旧 sequence 不得覆盖该发布记录的新状态。不同发布记录的通知不能仅因某个资源已见到更大序号就全部丢弃。较简单的做法是把通知作为“当前快照可能已变化”的信号,合并后重新查询更新接口,而不是用通知正文直接安装文件。
需要自动安装时重新读取当前兼容构建与文件,处理撤回后使旧缓存失效;查询 404 时停止使用旧资源快照。订阅不会补发历史、停用期间的变化也不会补发,因此首次订阅、接收端恢复、轮换后应主动同步当前快照。长期去重记录的保留应覆盖自身的恢复与人工重试窗口,不能只保留五分钟。
投递重试与排查
平台将 2xx 视为已接收;网络/DNS 错误、超时及 HTTP 408、429、5xx 最多尝试 8 次(包含首次),采用指数退避和抖动。第 1–7 次失败后的等待分别约为 1、2、4、8、16、32、64 秒,另加不足一秒随机抖动;实际投递时间可能延后,不保证固定时刻,也不按 Retry-After 另行排程。其它 HTTP 状态(包括重定向)或不可重试的传输校验错误进入失败终态。
接收端可靠保存事件后及时返回成功。返回 200 但响应正文过大或迟迟不结束,仍可能被平台视为失败;用无正文 204 最简单。网络结果未知时可能重复发送,不承诺 exactly-once。
在账户设置或投递列表检查 status、attempts、httpStatus 与 lastError。修复接收端后,只能人工重试当前端点版本的 failed 投递,且订阅仍存在、端点与关联应用仍有效、普通事件对应的发布仍处在相同公开代次;重试成功仅表示已重置为待发送,响应不是对端已接收的证明。轮换、URL/启停变更后旧版本失败投递不能重试,cancelled 也不能重试,应同步当前快照。
已结束投递在结束 30 天后可被清理;事件在创建 30 天后、完成分发且已无关联投递时可被清理,未完成来源会保留。投递列表不是永久审计日志。完整离线变化日志和 changes API 不在本版范围内。