API 文档

通过 RESTful API 集成 GitShip，实现自动化上传和仓库管理

认证方式

所有 API 请求需要在 HTTP Header 中携带 Bearer Token 进行认证。Token 可以在用户仪表盘中创建 API 密钥获取。

Authorization: Bearer <your-api-token>

示例请求头：

GET /api/config HTTP/1.1
Host: your-domain.com
Authorization: Bearer gup_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

接口目录

文件管理
POST /api/upload 上传 ZIP 代码包 ▾

请求参数（multipart/form-data）

参数名类型必填说明
fileFile必填ZIP 格式的代码包文件
repoIdString必填目标仓库 ID
previewBoolean可选设为 true 时仅预览不上传，默认 false
batchReposString可选批量上传到多个仓库，逗号分隔仓库 ID
commitMsgString可选自定义 Git 提交信息，默认自动生成
请求示例 
curl -X POST https://your-domain.com/api/upload \
  -H "Authorization: Bearer gup_xxxxxxxxxx" \
  -F "file=@my-project.zip" \
  -F "repoId=repo_abc123" \
  -F "commitMsg=feat: add new module"
200 OK
响应示例 
{
  "ok": true,
  "url": "https://github.com/user/repo/commit/abc123",
  "sha": "abc123def456",
  "message": "上传成功",
  "files": 12,
  "size": 1024000
}
仓库配置
GET /api/config 获取仓库列表 ▾

请求参数（Query String）

参数名类型必填说明
无--使用 Token 自动获取对应用户的仓库列表
请求示例 
curl -X GET https://your-domain.com/api/config \
  -H "Authorization: Bearer gup_xxxxxxxxxx"
200 OK
响应示例 
{
  "ok": true,
  "repos": [
    {
      "id": "repo_abc123",
      "name": "生产仓库",
      "repo": "user/production-repo",
      "branch": "main"
    },
    {
      "id": "repo_def456",
      "name": "测试仓库",
      "repo": "user/test-repo",
      "branch": "develop"
    }
  ]
}
POST /api/config 添加/更新/删除仓库 ▾

请求参数（application/json）

参数名类型必填说明
actionString必填操作类型：add / update / delete
repoIdString必填仓库 ID（update/delete 时需要）
nameString可选仓库显示名称
repoString可选GitHub 仓库路径，如 user/repo
branchString可选目标分支，默认 main
添加仓库示例 
curl -X POST https://your-domain.com/api/config \
  -H "Authorization: Bearer gup_xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"action":"add","name":"生产仓库","repo":"user/prod","branch":"main"}'
200 OK
响应示例 
{
  "ok": true,
  "message": "仓库已添加",
  "repo": {
    "id": "repo_new001",
    "name": "生产仓库",
    "repo": "user/prod",
    "branch": "main"
  }
}
上传记录
GET /api/history 获取上传历史 ▾

请求参数（Query String）

参数名类型必填说明
pageNumber可选页码，默认 1
limitNumber可选每页条数，默认 20
请求示例 
curl -X GET "https://your-domain.com/api/history?page=1&limit=10" \
  -H "Authorization: Bearer gup_xxxxxxxxxx"
200 OK
响应示例 
{
  "ok": true,
  "records": [
    {
      "id": "hist_001",
      "time": "2024-12-01T10:30:00Z",
      "fileName": "project-v2.zip",
      "fileCount": 15,
      "size": 2048000,
      "repo": "user/prod",
      "branch": "main",
      "status": "success",
      "commitSha": "abc123"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 10
}
用户认证
GET /api/auth/me 获取当前用户信息 ▾

说明

返回当前 Token 对应的用户信息、套餐和用量情况。无额外参数。

请求示例 
curl -X GET https://your-domain.com/api/auth/me \
  -H "Authorization: Bearer gup_xxxxxxxxxx"
200 OK
响应示例 
{
  "ok": true,
  "user": {
    "id": "user_abc",
    "username": "developer",
    "brandName": "MyBrand",
    "plan": "pro",
    "email": "dev@example.com",
    "createdAt": "2024-01-15T00:00:00Z"
  }
}
GET /api/auth/plan 获取套餐详情 ▾

说明

返回当前用户的套餐信息、用量配额和到期时间。

请求示例 
curl -X GET https://your-domain.com/api/auth/plan \
  -H "Authorization: Bearer gup_xxxxxxxxxx"
200 OK
响应示例 
{
  "ok": true,
  "plan": {
    "name": "专业版",
    "type": "pro",
    "uploadsLimit": 500,
    "reposLimit": 20,
    "maxZipSize": 52428800,
    "expiresAt": "2025-01-15T00:00:00Z",
    "usage": {
      "uploads": 128,
      "files": 1520,
      "size": 104857600
    }
  }
}
POST /api/auth/api-keys 创建 API 密钥 ▾

请求参数（application/json）

参数名类型必填说明
nameString可选密钥名称/备注，如 "CI/CD" 或 "自动化脚本"
expiresInNumber可选有效期天数，默认 90 天
请求示例 
curl -X POST https://your-domain.com/api/auth/api-keys \
  -H "Authorization: Bearer gup_xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI/CD","expiresIn":180}'
200 OK
响应示例 
{
  "ok": true,
  "key": {
    "id": "key_abc123",
    "name": "CI/CD",
    "token": "gup_xxxxxxxxxxxxxxxxxxxx",
    "createdAt": "2024-12-01T00:00:00Z",
    "expiresAt": "2025-05-30T00:00:00Z"
  },
  "message": "请妥善保存此 Token，创建后将无法再次查看"
}
OAuth 与 Webhook
GET /api/oauth/auth-url 获取 OAuth 授权链接 ▾

请求参数（Query String）

参数名类型必填说明
无--使用当前 Token 关联的账号生成 GitHub OAuth 授权链接
请求示例 
curl -X GET https://your-domain.com/api/oauth/auth-url \
  -H "Authorization: Bearer gup_xxxxxxxxxx"
200 OK
响应示例 
{
  "ok": true,
  "url": "https://github.com/login/oauth/authorize?client_id=xxx&state=yyy&scope=repo",
  "state": "random_state_string"
}
POST /api/webhook/create 创建 Webhook ▾

请求参数（application/json）

参数名类型必填说明
urlString必填Webhook 回调地址（HTTPS）
eventsArray可选监听事件类型，如 ["upload"]，默认监听所有
secretString可选签名密钥，用于验证回调来源
请求示例 
curl -X POST https://your-domain.com/api/webhook/create \
  -H "Authorization: Bearer gup_xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://my-server.com/webhook","events":["upload"],"secret":"my_secret"}'
200 OK
响应示例 
{
  "ok": true,
  "webhook": {
    "id": "wh_abc123",
    "url": "https://my-server.com/webhook",
    "events": ["upload"],
    "createdAt": "2024-12-01T00:00:00Z"
  }
}

GitShip API 文档 · 如有疑问请联系管理员