study-plan/api使用和版本发布.md

接口：https://git.ewancle.com/api/swagger 和使用教程：https://docs.gitea.com/zh-cn/development/api-usage

全部作用列表https://docs.gitea.com/zh-cn/development/oauth2-provider

activitypub	activitypub API routes: ActivityPub related operations.
    read:activitypub	Grants read access for ActivityPub operations.
    write:activitypub	Grants read/write/delete access for ActivityPub operations.
admin	/admin/* API routes: Site-wide administrative operations (hidden for non-admin accounts).
    read:admin	Grants read access for admin operations, such as getting cron jobs or registered user emails.
    write:admin	Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts.
issue	issues/*, labels/*, milestones/* API routes: Issue-related operations.
    read:issue	Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones.
    write:issue	Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones.
misc	Reserved for future usage.
    read:misc	Reserved for future usage.
    write:misc	Reserved for future usage.
notification	notification/* API routes: user notification operations.
    read:notification	Grants read access to user notifications, such as which notifications users are subscribed to and read new notifications.
    write:notification	Grants read/write/delete access to user notifications, such as marking notifications as read.
organization	orgs/* and teams/* API routes: Organization and team management operations.
    read:organization	Grants read access to org and team status, such as listing all orgs a user has visibility to, teams, and team members.
    write:organization	Grants read/write/delete access to org and team status, such as creating and updating teams and updating org settings.
package	/packages/* API routes: Packages operations
    read:package	Grants read access to package operations, such as reading and downloading available packages.
    write:package	Grants read/write/delete access to package operations. Currently the same as read:package.
repository	/repos/* API routes except /repos/issues/*: Repository file, pull-request, and release operations.
    read:repository	Grants read access to repository operations, such as getting repository files, releases, collaborators.
    write:repository	Grants read/write/delete access to repository operations, such as getting updating repository files, creating pull requests, updating collaborators.
user	/user/* and /users/* API routes: User-related operations.
    read:user	Grants read access to user operations, such as getting user repo subscriptions and user settings.
    write:user	Grants read/write/delete access to user operations, such as updating user repo subscriptions, followed users, and user settings.

curl -X POST "https://git.ewancle.com/api/v1/users/xiehaijun/tokens"
-H "Authorization: token f5856ff0aecd675b72c1910bd4a19679927a6ba0"
-H "Content-Type: application/json"
-d '{ "name": "full-access-token", "scopes": [ "repo", "repo:status", "admin:repo_hook", "admin:org", "write:issue", "write:repository", "read:repository" ] }'

管理员账号进行作用域token创建

curl -X 'POST'
'https://git.ewancle.com/api/v1/users/xiehaijun/tokens'
-u 'xiehaijun:Xiehaijun945'
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d '{ "name": "full-access-token", "scopes": [ "write:repository", "read:repository", "read:user", "write:user", "read:organization", "write:organization" ] }'

全部的权限token :"sha1":"ec5e01f597b42492c1c7a73f9997435fc83c1093"

curl -X 'POST'
'https://git.ewancle.com/api/v1/users/xiehaijun/tokens'
-u 'xiehaijun:Xiehaijun945'
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d '{ "name": "full-super-token", "scopes": [ "read:activitypub", "write:activitypub", "read:admin", "write:admin", "read:issue", "write:issue", "read:misc", "write:misc", "read:admin", "write:admin", "read:notification", "write:notification", "read:package", "write:package", "write:repository", "read:repository", "read:user", "write:user", "read:organization", "write:organization" ] }'

获取token，需要read:admin，write:admin

curl -X 'GET'
'https://git.ewancle.com/api/v1/users/xiehaijun/tokens'
-H "Authorization: token a94110b4fa993133ceb0e04fdabfd70626e02405"
-H 'accept: application/json'

EOF 前有空格或 Tab → 会导致闭合失败（命令行就和run: |下面的行平齐） 你写的是 <<EOF，但忘了在最后一行独占写 EOF

• name: Create Gitea Release run: | curl -s -X POST "{GITEA_API_URL}/repos/{GITEA_USER}/${GITEA_REPO}/releases"
  -H "Authorization: token ${{ secrets.GITEA_PAT }}"
  -H "Content-Type: application/json"
  -d @- <<EOF { "tag_name": "${{ env.TAG_NAME }}", "name": "Release ${{ env.TAG_NAME }}", "body": "This is an automated release", "draft": false, "prerelease": false } EOF

将 JSON 拆成变量拼接，避免复杂嵌套：

• name: Create Gitea Release run: | JSON=$(jq -n --arg tag "$TAG_NAME" --arg name "Release $TAG_NAME" --arg body "Auto release" '{ tag_name: $tag, name: $name, body: $body, draft: false, prerelease: false }')

  echo "$JSON"

  curl -s -X POST "{GITEA_API_URL}/repos/{GITEA_USER}/${GITEA_REPO}/releases"
  -H "Authorization: token ${{ secrets.GITEA_PAT }}"
  -H "Content-Type: application/json"
  -d "$JSON"

非常棒的问题！为了确保 Gitea Release 上传附件正确识别 MIME 类型（Content-Type），你在使用 curl 上传文件时，应当为不同文件类型设置合适的 Content-Type。

---

✅ 常见类型对应的 Content-Type 设置

文件类型	示例文件名	推荐 Content-Type
.txt	README.txt	text/plain
.zip	release.zip	application/zip
.tar.gz / .tgz	release.tar.gz	application/gzip
.exe	app.exe	application/vnd.microsoft.portable-executable 或 application/octet-stream（通用）
.md5 / .sha256	release.zip.sha256	text/plain 或 application/octet-stream（兼容性更好）

---

💡 推荐策略

❗ 通用、安全的 fallback 类型： application/octet-stream 可用于所有二进制文件上传，兼容性最强。

---

🧪 示例上传命令

# 上传 zip 文件
curl -X POST "$GITEA_API_URL/repos/$OWNER/$REPO/releases/$RELEASE_ID/assets?name=release.zip" \
  -H "Authorization: token $GITEA_PAT" \
  -H "Content-Type: application/zip" \
  --data-binary @"dist/release.zip"

# 上传 sha256 文件
curl -X POST "$GITEA_API_URL/repos/$OWNER/$REPO/releases/$RELEASE_ID/assets?name=release.zip.sha256" \
  -H "Authorization: token $GITEA_PAT" \
  -H "Content-Type: text/plain" \
  --data-binary @"dist/release.zip.sha256"

---

✅ 生成验证文件示例（Shell）

# 生成 sha256 验证文件
sha256sum dist/release.zip > dist/release.zip.sha256

# 可选：生成 md5 验证文件
md5sum dist/release.zip > dist/release.zip.md5

---

🔄 自动 Content-Type 映射 Bash 函数（可嵌入 GitHub Actions）

detect_content_type() {
  case "$1" in
    *.zip) echo "application/zip" ;;
    *.tar.gz|*.tgz) echo "application/gzip" ;;
    *.exe) echo "application/octet-stream" ;;
    *.txt) echo "text/plain" ;;
    *.md5|*.sha256) echo "text/plain" ;;
    *) echo "application/octet-stream" ;;  # fallback
  esac
}

然后你就可以这样调用：

CONTENT_TYPE=$(detect_content_type "$FILENAME")

---

✅ 总结

文件扩展名	推荐 Content-Type
.zip	application/zip
.tar.gz	application/gzip
.exe	application/octet-stream
.txt	text/plain
.sha256	text/plain 或 octet-stream
其他未知类型	application/octet-stream

---

如你希望我将这些自动识别上传逻辑封装为 GitHub Actions 步骤或脚本，并上传多个文件到 Gitea，我可以帮你生成一套模板。是否继续？

你的问题分成两大部分，我们逐一系统回答：

---

✅ 一、.xz、.pdf、.jpg、.mp4 等常见文件的 Content-Type 设置

文件扩展名	示例文件	推荐 Content-Type
.xz	data.tar.xz	application/x-xz
.pdf	manual.pdf	application/pdf
.jpg / .jpeg	cover.jpg	image/jpeg
.png	image.png	image/png
.mp4	video.mp4	video/mp4
.json	data.json	application/json
.csv	data.csv	text/csv
.xml	data.xml	application/xml

✅ 如果不确定，可使用通用 application/octet-stream，但推荐精确设置 MIME 类型，便于 Release 页面或浏览器识别。

---

✅ 二、GitHub 与 Gitee 发布 Release 并上传文件（API 对比）

---

✅ GitHub：创建 Release 并上传 Asset 附件

🔗 GitHub API 文档：

• Create Release
• Upload Release Asset

📦 步骤 1：创建 Release

response=$(curl -s -X POST "https://api.github.com/repos/OWNER/REPO/releases" \
  -H "Authorization: token $GITHUB_PAT" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "tag_name": "v1.2.3",
  "name": "Release v1.2.3",
  "body": "This is an automated release",
  "draft": false,
  "prerelease": false
}
EOF
)

upload_url=$(echo "$response" | jq -r '.upload_url' | sed 's/{?name,label}//')

---

📦 步骤 2：上传附件

curl -X POST "$upload_url?name=manual.pdf" \
  -H "Authorization: token $GITHUB_PAT" \
  -H "Content-Type: application/pdf" \
  --data-binary @"./build/manual.pdf"

---

✅ Gitee：创建 Release 并上传文件（非标准，需曲线实现）

🔗 官方文档（不完善）：

• Gitee Releases API

Gitee 的限制：

• ✅ 可以创建 Release（相当于发布 Tag）
• ❌ 不支持上传附件到 Release（没有像 GitHub 的 assets 接口）
• ✅ 可上传文件到 repo 或 wiki，或额外建专用仓库存文件

---

🟡 Gitee 创建 Release 示例（只含 tag 和说明）：

curl -X POST "https://gitee.com/api/v5/repos/OWNER/REPO/releases" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "access_token": "$GITEE_TOKEN",
  "tag_name": "v1.2.3",
  "name": "Release v1.2.3",
  "body": "Changelog here"
}
EOF

---

🔴 Gitee 上传文件：无直接 API 可传文件到 Release 页面

替代方案：

1. 把文件上传到仓库某个目录：

   curl -X POST https://gitee.com/api/v5/repos/OWNER/REPO/contents/path/to/file \
     -F access_token=$GITEE_TOKEN \
     -F content=$(base64 ./manual.pdf) \
     -F message="upload file"
   

   ⚠️ 支持 txt, md 等文本文件（base64 转码后大小限制），不推荐上传大型二进制文件。

2. 使用专门的文件下载仓库或私有网盘存放链接，在 Release 中贴出 URL。

---

✅ 三、总结对比：GitHub vs Gitee 发布 Release 附件能力

操作	GitHub	Gitee
创建 Release	✅	✅
上传附件到 Release 页面	✅ assets 接口	❌ 不支持直接上传
支持多附件	✅	❌（建议提供外链）
自动化支持	✅ GitHub Actions / curl	❌ 需要 workaround

---

✅ 补充建议：构建通用上传脚本

你可以用如下结构自动上传任意构建产物：

file="release.tar.xz"
mime_type=$(file --mime-type -b "$file")

curl -X POST "$upload_url?name=$(basename $file)" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: $mime_type" \
  --data-binary @"$file"

file --mime-type 自动识别 MIME 类型，适合你上传 .xz, .pdf, .mp4 等任意格式。

---

✅ 可选扩展：GitHub Actions 中自动上传多个文件到 Release

如果你希望我写一份完整的 matrix + MIME 自动识别 + GitHub/Gitee 多仓同时发布的 Actions，我可以马上生成。

是否继续？你也可以告诉我具体构建产物目录和需要上传哪些类型，我直接帮你生成 YAML 或 Shell。