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

停用App版本

请求参数

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

路径id为当前发布UUID,无查询参数。正文仅expectedVersion(必填非负integer int64)。只允许PUBLISHED;成功后状态WITHDRAWN,停止向App返回该目标,不自动恢复其他旧版本。

请求示例

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

const body = {
  "expectedVersion": 0
};
await request("versions/11111111-1111-4111-8111-111111111111/withdraw", "POST", body);

成功响应

HTTP200,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": "WITHDRAWN",
    "version": 1,
    "createdAt": "2026-11-03T12:00:00Z",
    "updatedAt": "2026-11-03T12:02: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非法
404 NOT_FOUND 目标版本不存在
409 APP_VERSION_CONFLICT 乐观版本已变化,保留输入并主动重读后处理
409 APP_VERSION_STATE 目标已停用或属于从未发布的迁移历史
426 HTTPS_REQUIRED 未使用HTTPS
503 SERVICE_UNAVAILABLE 数据库、Redis或审计存储暂不可用

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

{"code":"APP_VERSION_CONFLICT","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。超时先点击“核对发布结果”查询渠道/构建号及完整内容,核对失败保留输入,不自动重试创建。