message/gitea_api.md

Gitea API 使用文档

概述

本文档总结了在本次项目中成功使用的 Gitea API。

Gitea 地址： http://gitea.xieyao.vip/ 用户名： xieyao Token： 1ce08e3ca5d94641e0a243f374bba450f7639147 API 版本： v1

---

1. 获取用户仓库列表

接口信息

• URL： /api/v1/user/repos
• 方法： GET
• 认证： Authorization: token <token>

请求示例

curl -s -H "Authorization: token 1ce08e3ca5d94641e0a243f374bba450f7639147" \
  http://gitea.xieyao.vip/api/v1/user/repos

响应数据结构

{
  "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

请求示例

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	否	是否私有

响应示例

{
  "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

请求示例

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：认证失败

验证包是否成功上传

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）

获取仓库列表

get_repos() {
  curl -s -H "Authorization: token $GITEA_TOKEN" \
    $GITEA_API_URL/api/v1/user/repos
}

创建仓库

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
    }"
}

上传通用包

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

   unset https_proxy all_proxy
   

---

测试环境

• Gitea 服务器： http://gitea.xieyao.vip/
• API 版本： v1
• 测试时间： 2026-02-18
• 操作人： Geliebte

---

更新日志

• 2026-02-18 - 初始版本，记录了三个核心 API 的使用方法