# 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 的使用方法