CNB 后端 API 速查手册

本文档基于 CNB OpenAPI（https://api.cnb.cool/swagger.json）整理，涵盖所有可用的后端相关端点。

基础信息

• API 地址：https://api.cnb.cool
• 鉴权方式：Authorization: Bearer {token}
• 返回格式：Accept: application/json 或 application/vnd.cnb.api+json
• 仓库路径：{org}/{repo}，例如 cnbnn/my-project

端点列表

文件与内容

方法	端点	说明	备注
GET	/{repo}/-/git/contents	列出根目录文件	返回 entries 数组
GET	/{repo}/-/git/contents/{path}	列出指定目录或获取文件信息	path 支持多级，如 data/users.json
GET	/{repo}/-/git/raw/{ref}/{path}	获取文件原始内容	ref 可以是分支名、tag 名或 commit SHA
POST	/{repo}/-/git/blobs	创建 Blob（数据块）	不产生 commit，返回 SHA
POST	/{repo}/-/upload/files	获取文件上传 URL	返回 upload_url，需 PUT 上传
POST	/{repo}/-/upload/imgs	获取图片上传 URL	返回 upload_url，需 PUT 上传
DELETE	/{repo}/-/files/{filePath}	删除已上传的附件	仅限 UploadFiles 上传的

Commit 与分支

方法	端点	说明
GET	/{repo}/-/git/head	获取默认分支
GET	/{repo}/-/git/commits	获取 commit 列表
GET	/{repo}/-/git/commits/{ref}	获取指定 commit 详情
GET	/{repo}/-/git/compare/{base_head}	比较两个 ref 的差异（base..head 格式）
GET	/{repo}/-/git/branches	列出所有分支
POST	/{repo}/-/git/branches	创建新分支
GET	/{repo}/-/git/branches/{branch}	获取指定分支信息
DELETE	/{repo}/-/git/branches/{branch}	删除分支
GET	/{repo}/-/git/tags	列出所有 Tag
POST	/{repo}/-/git/tags	创建 Tag
GET	/{repo}/-/git/tags/{tag}	获取指定 Tag 信息
DELETE	/{repo}/-/git/tags/{tag}	删除 Tag

Issue 系统（当作数据表使用）

方法	端点	说明
GET	/{repo}/-/issues	查询 Issue 列表
POST	/{repo}/-/issues	创建 Issue
GET	/{repo}/-/issues/{number}	获取指定 Issue
PATCH	/{repo}/-/issues/{number}	更新 Issue
GET	/{repo}/-/issues/{number}/labels	获取 Issue 标签
POST	/{repo}/-/issues/{number}/labels	添加标签
DELETE	/{repo}/-/issues/{number}/labels/{name}	删除标签
GET	/{repo}/-/issues/{number}/comments	获取 Issue 评论
POST	/{repo}/-/issues/{number}/comments	创建评论
GET	/{repo}/-/labels	获取仓库标签列表
POST	/{repo}/-/labels	创建标签

仓库信息

方法	端点	说明
GET	/{repo}	获取仓库详细信息
PATCH	/{repo}	更新仓库信息（简介、站点、主题、许可证）
DELETE	/{repo}	删除仓库
GET	/{slug}/-/repos	列出组织/用户下的仓库
POST	/{slug}/-/repos	在组织/用户下创建仓库

Release（版本发布）

方法	端点	说明
GET	/{repo}/-/releases	列出 Release
POST	/{repo}/-/releases	创建 Release
GET	/{repo}/-/releases/latest	获取最新 Release
GET	/{repo}/-/releases/tags/{tag}	按 Tag 获取 Release

仓库动态

方法	端点	说明
GET	/events/{repo}/-/{date}	获取仓库动态

组织

方法	端点	说明
GET	/user/groups	获取当前用户加入的组织列表
GET	/user/repos	获取有权限的仓库列表
POST	/groups	创建新组织

请求/响应格式

通用请求头

Authorization: Bearer {token}
Accept: application/json
Content-Type: application/json

GET /-/git/contents 响应

{
  "type": "tree",
  "path": "",
  "sha": "abc123...",
  "entries": [
    {
      "type": "blob",
      "path": "README.md",
      "name": "README.md",
      "sha": "def456...",
      "size": 1234
    },
    {
      "type": "tree",
      "path": "docs",
      "name": "docs",
      "sha": "ghi789...",
      "size": 0
    }
  ]
}

GET /-/git/contents/{file} 响应

{
  "type": "blob",
  "path": "data/config.json",
  "name": "config.json",
  "sha": "abc123...",
  "size": 256,
  "encoding": "base64",
  "content": "eyJuYW1lIjoi..."
}

POST /-/git/blobs 请求与响应

请求：

{
  "content": "文件内容",
  "encoding": "utf-8"
}

响应：

{
  "sha": "3f3571faa3b7454a3ce63e71ef5c909b1b58766a"
}

POST /-/issues 请求与响应

请求：

{
  "title": "Issue 标题",
  "body": "Issue 内容（支持 Markdown）",
  "labels": ["bug", "urgent"]
}

POST /{slug}/-/repos（创建仓库）请求

{
  "name": "my-repo",
  "description": "仓库描述",
  "visibility": "public"
}

visibility 可选值：public、private、secret

错误码

errcode	说明
5	资源不存在
7	Token 权限不足
16	用户未登录
10009	路径冲突（仓库已存在）

Git Push 写入

完整的数据写入（产生 commit）只能通过 Git Push：

# Git remote URL 格式（无需 .git 后缀）
https://{username}:{token}@cnb.cool/{org}/{repo}

# 示例
git clone https://user:TOKEN@cnb.cool/myorg/myrepo
cd myrepo

# 写入数据
echo '{"users":[]}' > data/users.json
git add data/users.json
git commit -m "feat: init users data"
git push origin main

注意：CNB Git URL 不需要 .git 后缀。