From 59942acdbbbf0b914413e669456c9dc633a5a207 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 18 Feb 2026 01:44:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20Gitea=20API=20?= =?UTF-8?q?=E4=BD=BF=E7=94=A8=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 记录了三个核心 API： - 获取用户仓库列表 - 创建新仓库 - 上传通用包 包含完整的请求示例和响应数据结构。 --- gitea_api.md | 260 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 gitea_api.md diff --git a/gitea_api.md b/gitea_api.md new file mode 100644 index 0000000..b00e4d7 --- /dev/null +++ b/gitea_api.md @@ -0,0 +1,260 @@ +# Gitea API 使用文档 + +## 概述 + +本文档总结了在本次项目中成功使用的 Gitea API。 + +**Gitea 地址：** http://gitea.xieyao.vip/ +**用户名：** xieyao +**Token：** 1ce08e3ca5d94641e0a243f374bba450f7639147 +**API 版本：** v1 + +--- + +## 1. 获取用户仓库列表 + +### 接口信息 + +- **URL：** `/api/v1/user/repos` +- **方法：** `GET` +- **认证：** `Authorization: token ` + +### 请求示例 + +```bash +curl -s -H "Authorization: token 1ce08e3ca5d94641e0a243f374bba450f7639147" \ + http://gitea.xieyao.vip/api/v1/user/repos +``` + +### 响应数据结构 + +```json +{ + "id": 6, + "name": "control", + "full_name": "xieyao/control", + "description": "", + "private": true, + "language": "Dart", + "size": 651, + "html_url": "http://192.168.1.6:3000/xieyao/control", + "clone_url": "http://192.168.1.6:3000/xieyao/control.git", + "ssh_url": "git@192.168.1.6:xieyao/control.git", + "default_branch": "main", + "created_at": "2026-02-16T15:16:10Z", + "updated_at": "2026-02-16T15:18:07Z" +} +``` + +### 关键字段说明 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | number | 仓库 ID | +| `name` | string | 仓库名称 | +| `full_name` | string | 完整名称 (owner/name) | +| `description` | string | 仓库描述 | +| `private` | boolean | 是否私有 | +| `language` | string | 主要编程语言 | +| `size` | number | 仓库大小（字节） | +| `html_url` | string | 仓库访问地址 | +| `clone_url` | string | HTTP 克隆地址 | +| `ssh_url` | string | SSH 克隆地址 | +| `default_branch` | string | 默认分支 | +| `created_at` | string | 创建时间 (ISO 8601) | +| `updated_at` | string | 更新时间 (ISO 8601) | + +--- + +## 2. 创建新仓库 + +### 接口信息 + +- **URL：** `/api/v1/user/repos` +- **方法：** `POST` +- **认证：** `Authorization: token ` +- **Header：** `Content-Type: application/json` + +### 请求示例 + +```bash +curl -s -X POST -H "Authorization: token 1ce08e3ca5d94641e0a243f374bba450f7639147" \ + -H "Content-Type: application/json" \ + http://gitea.xieyao.vip/api/v1/user/repos \ + -d '{ + "name": "message", + "description": "汪汪的message仓库", + "auto_init": true, + "private": false + }' +``` + +### 请求参数 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | string | 是 | 仓库名称 | +| `description` | string | 否 | 仓库描述 | +| `auto_init` | boolean | 否 | 是否自动初始化（创建 README） | +| `private` | boolean | 否 | 是否私有 | + +### 响应示例 + +```json +{ + "id": 9, + "name": "message", + "full_name": "xieyao/message", + "description": "汪汪的message仓库", + "private": false, + "language": "", + "size": 23, + "html_url": "http://192.168.1.6:3000/xieyao/message", + "clone_url": "http://192.168.1.6:3000/xieyao/message.git", + "ssh_url": "git@192.168.1.6:xieyao/message.git", + "default_branch": "main", + "created_at": "2026-02-17T16:37:59Z", + "updated_at": "2026-02-17T16:38:00Z" +} +``` + +--- + +## 3. 上传通用包（Generic Package Registry） + +### 接口信息 + +- **URL：** `/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}` +- **方法：** `PUT` +- **认证：** `Basic Auth` 或 `token` +- **Content-Type：** `application/octet-stream` + +### 请求示例 + +```bash +curl -s -X PUT -u "xieyao:1ce08e3ca5d94641e0a243f374bba450f7639147" \ + --upload-file devspec \ + http://gitea.xieyao.vip/api/packages/xieyao/generic/devspec/1.0.0/devspec \ + -w "\nHTTP Status: %{http_code}\n" +``` + +### 参数说明 + +| 参数 | 类型 | 说明 | +|------|------|------| +| `owner` | string | 用户名或组织名 | +| `package_name` | string | 包名称（只能包含小写字母、数字、点、减号、加号、下划线） | +| `package_version` | string | 版本号（不能为空，前后不能有空格） | +| `file_name` | string | 文件名（只能包含小写字母、数字、点、减号、加号、下划线） | + +### 响应 + +**成功：** +``` +HTTP/2 201 +``` + +**失败：** +- `400 Bad Request`：参数无效 +- `409 Conflict`：文件名已存在 +- `401 Unauthorized`：认证失败 + +### 验证包是否成功上传 + +```bash +curl -s -k -u "xieyao:1ce08e3ca5d94641e0a243f374bba450f7639147" \ + "http://gitea.xieyao.vip/api/packages/xieyao/generic/devspec/1.0.0/devspec" \ + -o downloaded_file \ + -w "\nHTTP Status: %{http_code}\n" +``` + +--- + +## 常用工具函数（bash） + +### 获取仓库列表 + +```bash +get_repos() { + curl -s -H "Authorization: token $GITEA_TOKEN" \ + $GITEA_API_URL/api/v1/user/repos +} +``` + +### 创建仓库 + +```bash +create_repo() { + local name="$1" + local description="${2:-}" + local auto_init="${3:-true}" + local private="${4:-false}" + + curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \ + -H "Content-Type: application/json" \ + $GITEA_API_URL/api/v1/user/repos \ + -d "{ + \"name\": \"$name\", + \"description\": \"$description\", + \"auto_init\": $auto_init, + \"private\": $private + }" +} +``` + +### 上传通用包 + +```bash +upload_generic_package() { + local owner="$1" + local package_name="$2" + local package_version="$3" + local file_path="$4" + + curl -s -k -X PUT -u "$GITEA_USERNAME:$GITEA_TOKEN" \ + --upload-file "$file_path" \ + "$GITEA_API_URL/api/packages/$owner/generic/$package_name/$package_version/$(basename $file_path)" \ + -w "\nHTTP Status: %{http_code}\n" +} +``` + +--- + +## 注意事项 + +1. **认证方式** + - 使用 Token 认证：`Authorization: token ` + - 使用 Basic Auth：`-u username:token` + +2. **HTTPS 证书** + - 如果 Gitea 使用自签名证书，需要添加 `-k` 参数跳过验证 + +3. **包命名规则** + - 包名和文件名只能包含小写字母、数字、点、减号、加号、下划线 + - 版本号不能为空，前后不能有空格 + +4. **包关联** + - 上传包后，需要在 Web UI 中手动关联到仓库 + - 访问：http://gitea.xieyao.vip/xieyao/packages + - 选择仓库进行关联 + +5. **代理设置** + - 如果使用了代理，需要取消代理后再访问 Gitea + ```bash + unset https_proxy all_proxy + ``` + +--- + +## 测试环境 + +- **Gitea 服务器：** http://gitea.xieyao.vip/ +- **API 版本：** v1 +- **测试时间：** 2026-02-18 +- **操作人：** Geliebte + +--- + +## 更新日志 + +- **2026-02-18** - 初始版本，记录了三个核心 API 的使用方法