开放接口文档 · 仓库访问令牌

本文档面向外部开发者：介绍如何在 GitSource 上为仓库签发访问令牌，并以只读方式在自己的应用或网站中读取该仓库的公开内容。

一、概述

仓库访问令牌（Access Token）是由仓库所有者或管理员签发的只读凭证，用于授权外部应用与网站读取指定仓库的内容，而无需用户登录。

单仓绑定：一枚令牌只对签发它的那个仓库生效，无法用于其他仓库。
单一只读权限：令牌不携带登录态，无法上传、发版、修改或删除任何内容。
不含文件下载：令牌可读取文件清单等元数据，但不签发任何文件下载链接；需要文件时请引导用户访问仓库主页。
可撤销、可审计：随时撤销即时失效，签发与撤销均记录在仓库操作日志中。

二、获取访问令牌

令牌由仓库所有者签发，外部开发者需向仓库所有者索取：

打开目标仓库主页，进入「设置」标签页（仅所有者与站点管理员可见）；
找到「访问令牌」卡片，点击「新建令牌」；
填写令牌名称（建议填写用途，如「官网小组件」），选择有效期（30 / 90 / 365 天或永不过期）；
生成后立即复制并保存——明文仅展示一次，列表中此后只显示掩码。

令牌格式为 gs_rat_ 前缀加 40 位随机字符（如 gs_rat_YosILh…）。服务端只保存其 SHA-256 哈希，遗失明文无法找回，只能重新签发。

三、调用方式

接口基地址：

https://git.rivulet.org.cn/api

三种携带令牌的方式任选其一：

方式	示例
Authorization 请求头（推荐）	`Authorization: Bearer gs_rat_xxxx`
X-Repo-Token 请求头	`X-Repo-Token: gs_rat_xxxx`
查询参数	`?token=gs_rat_xxxx`

安全提示：查询参数方式会把令牌带入服务器访问日志、浏览器历史与 Referer 头，仅在无法设置请求头的场景（如 <img> 直链）使用，并优先选择请求头方式。

cURL 示例（读取版本列表）：

curl -H "Authorization: Bearer gs_rat_xxxx" \
  https://git.rivulet.org.cn/api/repos/16/releases

浏览器 / Node 示例：

const res = await fetch(
  'https://git.rivulet.org.cn/api/repos/16/releases',
  { headers: { Authorization: `Bearer ${TOKEN}` } }
);
if (!res.ok) throw new Error(`请求失败：${res.status}`);
const { releases } = await res.json();

四、可读取的数据

下表端点均可凭令牌访问（无需登录，私有仓库同样放行）。:repoId 为仓库数字 ID，可从首个端点的 repo.id 字段取得；:owner / :name 为所有者用户名与仓库名。

方法	路径	返回内容
GET	`/repos/:owner/:name`	仓库基础信息、当前文件清单与版本列表（含 `htmlUrl` 仓库主页地址）
GET	`/repos/:repoId/readme`	仓库 README（Markdown 原文）
GET	`/repos/:repoId/releases`	正式版本列表（版本 tag、说明、文件清单、总大小、发布者）
GET	`/repos/:repoId/compare?from=&to=`	两个版本之间的文件级差异（新增 / 更新 / 移除）
GET	`/repos/:repoId/stats?days=30`	近 N 天（7-90）下载 / Star / Fork 每日趋势
GET	`/repos/:repoId/issues`	仓库 Issues 列表（公开仓库匿名可读，私有仓库需成员或本仓令牌）

五、返回示例

GET /repos/:owner/:name 的响应结构（节选）：

{
  "repo": {
    "id": 16,
    "name": "MengQiongOS_Series",
    "fullName": "Luca/MengQiongOS_Series",
    "description": "一套面向发布会的产品演示文稿",
    "htmlUrl": "https://git.rivulet.org.cn/Luca/MengQiongOS_Series",
    "tags": ["发布会", "极简"],
    "license": "MIT",
    "starCount": 12,
    "forkCount": 3,
    "watchCount": 5,
    "releaseCount": 4,
    "fileCount": 6,
    "totalSize": 10485760,
    "latestTag": "v2.0",
    "owner": { "id": 9, "username": "Luca" },
    "commits": [
      {
        "id": 128,
        "fileName": "main.pptx",
        "fileSize": 2097152,
        "createdAt": "2026-09-01T08:00:00.000Z"
      }
    ],
    "releases": [
      {
        "id": 31,
        "tag": "v2.0",
        "isBeta": false,
        "isCurrent": true,
        "createdAt": "2026-09-01T08:00:00.000Z"
      }
    ]
  }
}

字段可能随版本演进增减，请按「缺失即忽略」的方式解析，避免强依赖某个可选字段。

六、权限边界

令牌可以：

读取仓库基础信息、描述与标签、Star / Fork / Watch 计数、文件数与总大小；
读取当前工作区的文件清单（文件名、大小、更新时间）与版本列表；
读取 README、版本对比与每日统计；
读取处于删除保留期（3 日）内的仓库。

令牌不可以：

下载任何文件——批量签名 URL、单文件下载、文件内容预览均返回 403；
执行任何写操作——上传、发版、编辑 README、Issue 评论等一律返回 401；
访问其他仓库——跨仓调用返回 403；
读取暂存区文件、协作者名单、操作日志与令牌管理接口（这些仅登录用户可见）。

需要文件时，请使用响应中的 htmlUrl 引导用户前往仓库主页下载。

七、错误与限流

状态码	含义	处理建议
401	令牌缺失、无效、已过期或已撤销	联系仓库所有者重新签发并更新配置
403	令牌不属于该仓库（跨仓调用）或端点不在授权范围内	核对 `repoId` 与端点
404	仓库、版本或资源不存在	核对路径参数
429	触发限流	降低频率，按指数退避重试
500	服务端异常	稍后重试，持续出现请联系我们

错误响应统一为 { "error": "错误描述" }，可直接展示 error 字段。

限流策略：全局每 IP 每分钟 200 次请求。请在自己的服务端做缓存（建议 ≥ 1 分钟），避免高频轮询同一仓库。

八、跨域调用

携带令牌的请求，跨域策略会放宽为回显请求方 Origin（响应同时携带 Vary: Origin），且不携带 Cookie 凭证，因此外部网站可在浏览器端直接 fetch。未携带令牌的请求仍仅限站点自身域名。

浏览器端直连意味着令牌会出现在前端代码中、对所有访客可见。请仅在令牌泄露无所谓的场景（如只读公开数据）下这么做，其余场景请在自己的服务端转发。

九、安全建议

把令牌当作只读密码：不要提交到公开仓库，不要硬编码在前端源码中。
按用途分别签发，避免一枚令牌被多处复用；不再使用时立即撤销。
尽量设置有效期并定期轮换。
服务端调用时请将令牌放在环境变量或密钥管理服务中。
怀疑泄露时，请仓库所有者在设置页撤销该令牌并重新签发。