POST/api/v1/admin/versions
管理员Cookie/HTTPS/JWE,ADMIN_VERSIONS_WRITE及CSRFJSON 响应接入指南 ↗

创建并发布App版本

请求参数

仅OWNER可写。所有请求发送八项公共头,固定admin/web/admin_web;身份使用独立Secure HttpOnly Cookie,不接受App Bearer。必须HTTPS与真实JWE,写操作验证Origin及X-Admin-CSRF。请求由后台安全协议封装,不通过地址栏直接读取。

无路径或查询参数。请求为完整发布对象,必须显式发送publish=true,不能提交expectedVersion。旧后台“保存草稿”请求没有publish标记,返回400 INVALID_APP_VERSION且不创建记录,避免旧页面被误当成发布操作。

字段 类型 必填 说明
publish boolean 是 必须为true,表示本次创建立即发布;缺省、null、false或字符串均拒绝
channel string 是 九个发行渠道代码之一
versionName string 是 三段数字,例如1.4.0,每段1–4位,不允许前导零、预发布或构建后缀;不能低于该渠道历史最高已发布构建的展示版本
buildNumber integer(int64) 是 1–999999999;必须大于该渠道所有曾发布构建号,迁移保留的从未发布历史不占用该构建号
minimumVersion string 是 与versionName相同格式,数值比较不能高于本版本
forceUpdate boolean 是 true表示所有可升级的旧构建均要求更新;false时低于最低版本仍要求更新
packageSizeBytes integer(int64) 是 声明的安装包字节数,1–2147483648;网页用MiB输入,1MiB=1048576字节
downloadUrl string 是 不超过2048字符,公开HTTPS下载/商店地址;不得有用户密码、fragment、IP主机或非443端口
releaseNotes object 是 必须恰好包含zh-CN、en、ja、ko四个键,每个值为非空纯文本,原输入最多1000个UTF-16代码单元

所有字段完整提交,不支持部分更新。平台、地区、状态、时间和并发版本均由服务器生成,不接受额外字段。Google Play必须使用play.google.com/store/apps/details且包含id参数;App Store必须使用apps.apple.com的app/id页面;其他渠道使用公开HTTPS域名。服务器不下载、探测或代理该URL;管理员发布前负责确认真实安装包、签名和商店状态。

请求示例

以下使用后台已有统一request封装(自动带语言、八项元数据、Cookie、CSRF及JWE)。UUID、下载地址和版本均为合成示例,不能直接作为实际发布内容。

const body = {
  "publish": true,
  "channel": "xiaomi",
  "versionName": "1.4.0",
  "buildNumber": 140,
  "minimumVersion": "1.0.0",
  "forceUpdate": false,
  "packageSizeBytes": 25165824,
  "downloadUrl": "https://downloads.example.test/budyoo-1.4.0.apk",
  "releaseNotes": {
    "zh-CN": "修复已知问题",
    "en": "Fix known issues",
    "ja": "既知の問題を修正",
    "ko": "알려진 문제 수정"
  }
};
await request("versions", "POST", body);

成功响应

HTTP200表示版本已经发布,返回status=PUBLISHED、version=0及非空publishedAt;Cache-Control:no-store;JWE认证解密后的正文示例:

{
  "code": "SUCCESS",
  "message": "操作成功。",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "channel": "xiaomi",
    "versionName": "1.4.0",
    "buildNumber": 140,
    "minimumVersion": "1.0.0",
    "forceUpdate": false,
    "packageSizeBytes": 25165824,
    "downloadUrl": "https://downloads.example.test/budyoo-1.4.0.apk",
    "releaseNotes": {
      "zh-CN": "修复已知问题",
      "en": "Fix known issues",
      "ja": "既知の問題を修正",
      "ko": "알려진 문제 수정"
    },
    "platform": "android",
    "region": "domestic",
    "status": "PUBLISHED",
    "version": 0,
    "createdAt": "2026-11-03T12:00:00Z",
    "updatedAt": "2026-11-03T12:00:00Z",
    "publishedAt": "2026-11-03T12:00:00Z"
  },
  "errors": []
}
data字段 类型 可空 说明
id string(UUID) 否 版本记录ID
channel/platform/region string 否 渠道与服务器派生的平台、发行分类(domestic/overseas/global);app_store为global,与用户IP布局独立
versionName/minimumVersion string 否 展示版本及最低支持版本
buildNumber integer(int64) 否 渠道内构建号
forceUpdate boolean 否 对可升级旧构建的强制策略
packageSizeBytes integer(int64) 否 声明安装包大小,单位字节
downloadUrl string 否 管理员填写并通过格式校验的HTTPS地址
releaseNotes object 否 四语纯文本更新说明,zh-CN/en/ja/ko
status string 否 PUBLISHED当前发布;WITHDRAWN停用、被替换或迁移保留的未生效历史
version integer(int64) 否 非负乐观并发版本,新建为0;停用以expectedVersion回传
createdAt/updatedAt string(date-time) 否 带时区ISO8601时间
publishedAt string(date-time) 是 创建发布的时间;停用后保留;仅迁移保留的从未发布历史为null

失败响应

HTTP code 原因
400 INVALID_CLIENT_HEADERS 公共头缺失、重复或格式非法
400 INVALID_APP_VERSION/BAD_REQUEST 字段、URL、渠道、筛选或JSON格式非法;未知字段拒绝
401 UNAUTHORIZED 缺少或失效的管理员Cookie,或使用App Bearer
403 FORBIDDEN/ADMIN_CSRF_INVALID 角色无权限、客户端类型或来源/CSRF非法
409 APP_VERSION_DUPLICATE 同渠道已有曾发布的相同构建号;不覆盖原记录
409 APP_VERSION_STATE 构建号或展示版本倒退;当前目标保持不变
426 HTTPS_REQUIRED 未使用HTTPS
503 SERVICE_UNAVAILABLE 数据库、Redis或审计存储暂不可用

加密失败沿用公共加密错误码,提示支持四语,code不翻译。示例:

{"code":"INVALID_APP_VERSION","message":"版本字段、发行渠道或下载地址不合法。","data":null,"errors":[]}

接入说明

苹果渠道app_store的region现为global(全球),国内Android仍domestic,Google Play仍overseas;后台类型、分组、筛选需支持global。苹果不拆成两条发布渠道,原UUID/构建及发布状态保持,展示分类从同一渠道清单派生,无数据库迁移。

创建版本成功即发布,原子替换同渠道旧目标;校验、创建、旧目标停用和管理员审计同事务,任一步失败全部回滚。曾发布构建号必须严格递增,展示版本不能倒退。所有记录只读;停用后不自动恢复旧版本,也不提供编辑、删除或再次发布入口。

状态只有PUBLISHED(当前发布)和WITHDRAWN(停用、被替换或迁移保留的未生效历史)。V18将旧DRAFT原内容及UUID保留为WITHDRAWN,publishedAt仍为null,绝不自动发布占位地址;这些从未发布的历史不占用真实发布构建号。新建成功的publishedAt必有值,version初始为0。

App继续使用升级检查的原请求和返回字段,无需改代码。下载链接的可用性、包签名和商店状态仍须管理员确认;本接口不上传安装包、不代替商店提交或安装。

2026-11-04最终381项服务器Java回归全部通过(0失败/0跳过),包含24项版本管理、筛选、App升级与迁移用例;服务器TypeScript/Vite及7项环境/归档检查通过。验证覆盖创建即发布、旧页面缺少publish=true拒绝、历史保留、并发创建、旧快照停用、发布/替换审计回滚、升级兼容及V17→V18迁移。116份MD链接和141段JSON示例检查通过。API、V18与新版网页已配套部署。候选产物的12项真实浏览器加密夹具检查覆盖立即发布/替换/停用、确认取消、重复提交保护、只读角色、409及响应丢失后完整内容核对,实际渠道写请求0;另13项四语桌面/手机、渠道预览、强更、筛选和重置检查通过。发布前备份在独立数据库恢复验证,运行库迁移后原九条记录UUID与业务内容保持,全部为WITHDRAWN/publishedAt=null且当前发布为0。超时先点击“核对发布结果”查询渠道/构建号及完整内容,核对失败保留输入,不自动重试创建。