docs: 添加 Gitea API 使用文档
记录了三个核心 API： - 获取用户仓库列表 - 创建新仓库 - 上传通用包 包含完整的请求示例和响应数据结构。
This commit is contained in:
root
260
gitea_api.md
Normal file
260
gitea_api.md
Normal file
@@ -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 <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 <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 <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 的使用方法
|
||||
Reference in New Issue
Block a user