完成文档部分内容

2025-07-29 20:56:05 +08:00
parent 1e3e4d18ae
commit 81217e1e64
68 changed files with 6384 additions and 71 deletions
--- a/docs/document/development/api-usage.md
+++ b/docs/document/development/api-usage.md
@@ -0,0 +1,63 @@
+---
+date: "2018-06-24:00:00+02:00"
+slug: "api-usage"
+sidebar_position: 40
+aliases:
+  - /zh-cn/api-usage
+---
+
+# API 使用指南
+
+## 开启/配置 API 访问
+
+通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。
+
+## 通过 API 认证
+
+Gitea 支持以下几种 API 认证方式：
+
+- HTTP basic authentication 方式
+- 通过指定 `token=...` URL 查询参数方式
+- 通过指定 `access_token=...` URL 查询参数方式
+- 通过指定 `Authorization: token ...` HTTP header 方式
+
+以上提及的认证方法接受相同的 apiKey token 类型，您可以在编码时通过查阅代码更好地理解这一点。
+Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。
+
+您可以通过您的 gitea web 界面来创建 apiKey token：
+`Settings | Applications | Generate New Token`.
+
+### 关于 `Authorization:` header
+
+由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 `token`，类似于如下形式：
+
+```
+Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
+```
+
+以 `curl` 命令为例，它会以如下形式携带在请求中：
+
+```
+curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
+    -H "accept: application/json" \
+    -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
+    -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
+```
+
+正如上例所示，您也可以在 GET 请求中使用同一个 token 并以 `token=` 的查询参数形式携带 token 来进行认证。
+
+## 通过 API 列出您发布的令牌
+
+`/users/:name/tokens` 是一个特殊的接口，需要您使用 basic authentication 进行认证，具体原因在 issue 中
+[#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及，使用方法如下所示：
+
+### 使用 Basic authentication 认证
+
+```
+$ curl --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
+[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
+```
+
+## 使用 Sudo 方式请求 API
+
+此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。
--- a/docs/document/development/hacking-on-gitea.md
+++ b/docs/document/development/hacking-on-gitea.md
@@ -0,0 +1,334 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+slug: "hacking-on-gitea"
+sidebar_position: 10
+aliases:
+  - /zh-cn/hacking-on-gitea
+---
+
+# 玩转 Gitea
+
+## 快速入门
+
+要获得快速工作的开发环境，您可以使用 Gitpod。
+
+[![在 Gitpod 中打开](../../static/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/go-gitea/gitea)
+
+## 安装 Golang
+
+您需要 [安装 go](https://go.dev/doc/install) 并设置您的 go 环境。
+
+接下来，[使用 npm 安装 Node.js](https://nodejs.org/en/download/) ，这是构建
+JavaScript 和 CSS 文件的必要工具。最低支持的 Node.js 版本是 @minNodeVersion@
+并且推荐使用最新的 LTS 版本。
+
+**注意** ：当执行需要外部工具的 make 任务时，比如
+`make watch-backend`，Gitea 会自动下载并构建这些必要的组件。为了能够使用这些，你必须
+将 `"$GOPATH"/bin` 目录加入到可执行路径上。如果你不把 go bin 目录添加到可执行路径你必须手动
+指定可执行程序路径。
+
+**注意 2** ：Go 版本 @minGoVersion@ 或更高版本是必须的。Gitea 使用 `gofmt` 来
+格式化源代码。然而，`gofmt` 的结果可能因 `go` 的版本而有差异。因此推荐安装我们持续集成使用
+的 Go 版本。截至上次更新，Go 版本应该是 @goVersion@。
+
+## 安装 Make
+
+Gitea 大量使用 `Make` 来自动化任务和改进开发。本指南涵盖了如何安装 Make。
+
+### 在 Linux 上
+
+使用包管理器安装。
+
+在 Ubuntu/Debian 上：
+
+```bash
+sudo apt-get install make
+```
+
+在 Fedora/RHEL/CentOS 上：
+
+```bash
+sudo yum install make
+```
+
+### 在 Windows 上
+
+Make 的这三个发行版都可以在 Windows 上运行：
+
+- [单个二进制构建](http://www.equation.com/servlet/equation.cmd?fa=make)。复制到某处并添加到 `PATH`。
+  - [32 位版本](http://www.equation.com/ftpdir/make/32/make.exe)
+  - [64 位版本](http://www.equation.com/ftpdir/make/64/make.exe)
+- [MinGW-w64](https://www.mingw-w64.org) / [MSYS2](https://www.msys2.org/)。
+  - MSYS2 是一个工具和库的集合，为您提供一个易于使用的环境来构建、安装和运行本机 Windows 软件，它包括 MinGW-w64。
+  - 在 MingGW-w64 中，二进制文件称为 `mingw32-make.exe` 而不是 `make.exe`。将 `bin` 文件夹添加到 `PATH`。
+  - 在 MSYS2 中，您可以直接使用 `make`。请参阅 [MSYS2 移植](https://www.msys2.org/wiki/Porting/)。
+  - 要使用 CGO_ENABLED（例如：SQLite3）编译 Gitea，您可能需要使用 [tdm-gcc](https://jmeubank.github.io/tdm-gcc/) 而不是 MSYS2 gcc，因为 MSYS2 gcc 标头缺少一些 Windows -只有 CRT 函数像 \_beginthread 一样。
+- [Chocolatey 包管理器](https://chocolatey.org/packages/make)。运行`choco install make`
+
+**注意** ：如果您尝试在 Windows 命令提示符下使用 make 进行构建，您可能会遇到问题。建议使用上述提示（Git bash 或 MinGW），但是如果您只有命令提示符（或可能是 PowerShell），则可以使用 [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) 命令，例如 `set TAGS=bindata`。
+
+## 下载并克隆 Gitea 源代码
+
+获取源代码的推荐方法是使用 `git clone`。
+
+```bash
+git clone https://github.com/go-gitea/gitea
+```
+
+（自从 go modules 出现后，不再需要构建 go 项目从 `$GOPATH` 中获取，因此不再推荐使用 `go get` 方法。）
+
+## 派生 Gitea
+
+如上所述下载主要的 Gitea 源代码。然后，派生 [Gitea 仓库](https://github.com/go-gitea/gitea)，
+并为您的本地仓库切换 git 远程源，或添加另一个远程源：
+
+```bash
+# 将原来的 Gitea origin 重命名为 upstream
+git remote rename origin upstream
+git remote add origin "git@github.com:$GITHUB_USERNAME/gitea.git"
+git fetch --all --prune
+```
+
+或者：
+
+```bash
+# 为我们的 fork 添加新的远程
+git remote add "$FORK_NAME" "git@github.com:$GITHUB_USERNAME/gitea.git"
+git fetch --all --prune
+```
+
+为了能够创建合并请求，应将分叉存储库添加为 Gitea 本地仓库的远程，否则无法推送更改。
+
+## 构建 Gitea（基本）
+
+看看我们的
+[说明](installation/from-source.md)
+关于如何[从源代码构建](installation/from-source.md) 。
+
+从源代码构建的最简单推荐方法是：
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make build
+```
+
+`build` 目标将同时执行 `frontend` 和 `backend` 子目标。如果存在 `bindata` 标签，资源文件将被编译成二进制文件。建议在进行前端开发时省略 `bindata` 标签，以便实时反映更改。
+
+有关所有可用的 `make` 目标，请参阅 `make help`。另请参阅 [`.drone.yml`](https://github.com/go-gitea/gitea/blob/main/.drone.yml) 以了解我们的持续集成是如何工作的。
+
+## 持续构建
+
+要在源文件更改时运行并持续构建：
+
+```bash
+# 对于前端和后端
+make watch
+
+# 或者：只看前端文件（html/js/css）
+make watch-frontend
+
+# 或者：只看后端文件 (go)
+make watch-backend
+```
+
+在 macOS 上，监视所有后端源文件可能会达到默认的打开文件限制，这可以通过当前 shell 的 `ulimit -n 12288` 或所有未来 shell 的 shell 启动文件来增加。
+
+### 格式化、代码分析和拼写检查
+
+我们的持续集成将拒绝未通过代码检查（包括格式检查、代码分析和拼写检查）的 PR。
+
+你应该格式化你的代码：
+
+```bash
+make fmt
+```
+
+并检查源代码：
+
+```bash
+# lint 前端和后端代码
+make lint
+# 仅 lint 后端代码
+make lint-backend
+```
+
+**注意** ：`gofmt` 的结果取决于 `go` 的版本。您应该运行与持续集成相同的 go 版本。
+
+### 处理 JS 和 CSS
+
+前端开发应遵循 [Guidelines for Frontend Development](contributing/guidelines-frontend.md)。
+
+要使用前端资源构建，请使用上面提到的“watch-frontend”目标或只构建一次：
+
+```bash
+make build && ./gitea
+```
+
+在提交之前，确保 linters 通过：
+
+```bash
+make lint-frontend
+```
+
+### 配置本地 ElasticSearch 实例
+
+使用 docker 启动本地 ElasticSearch 实例：
+
+```sh
+mkdir -p $(pwd) /data/elasticsearch
+sudo chown -R 1000:1000 $(pwd) /data/elasticsearch
+docker run --rm --memory= "4g" -p 127.0.0.1:9200:9200 -p 127.0.0.1:9300:9300 -e "discovery.type=single-node" -v "$(pwd)/data /elasticsearch:/usr/share/elasticsearch/data" docker.elastic.co/elasticsearch/elasticsearch:7.16.3
+```
+
+配置`app.ini`：
+
+```ini
+[indexer]
+ISSUE_INDEXER_TYPE = elasticsearch
+ISSUE_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
+REPO_INDEXER_ENABLED = true
+REPO_INDEXER_TYPE = elasticsearch
+REPO_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
+```
+
+### 构建和添加 SVGs
+
+SVG 图标是使用 `make svg` 命令构建的，该命令将图标资源编译到输出目录 `public/assets/img/svg` 中。可以在 `web_src/svg` 目录中添加自定义图标。
+
+### 构建 Logo
+
+Gitea Logo 的 PNG 和 SVG 版本是使用 `TAGS="gitea" make generate-images` 目标从单个 SVG 源文件 assets/logo.svg 构建的。要运行它，Node.js 和 npm 必须可用。
+
+通过更新 `assets/logo.svg` 并运行 `make generate-images`，同样的过程也可用于从 SVG 源文件生成自定义 Logo PNG。忽略 gitea 编译选项将仅更新用户指定的 LOGO 文件。
+
+### 更新 API
+
+创建新的 API 路由或修改现有的 API 路由时，您**必须**
+更新和/或创建 [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)
+这些使用 [go-swagger](https://goswagger.io/) 评论的文档。
+[规范](https://goswagger.io/use/spec.html#annotation-syntax)中描述了这些注释的结构。
+如果您想了解更多有关 Swagger 结构的信息，可以查看
+[Swagger 2.0 文档](https://swagger.io/docs/specification/2-0/basic-structure/)
+或与添加新 API 端点的先前 PR 进行比较，例如 [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
+
+您应该注意不要破坏下游用户依赖的 API。在稳定的 API 上，一般来说添加是可以接受的，但删除
+或对 API 进行根本性更改将会被拒绝。
+
+创建或更改 API 端点后，请用以下命令重新生成 Swagger 文档：
+
+```bash
+make generate-swagger
+```
+
+您应该验证生成的 Swagger 文件：
+
+```bash
+make swagger-validate
+```
+
+您应该提交更改后的 swagger JSON 文件。持续集成服务器将使用以下方法检查是否已完成：
+
+```bash
+make swagger-check
+```
+
+**注意** ：请注意，您应该使用 Swagger 2.0 文档，而不是 OpenAPI 3 文档。
+
+### 创建新的配置选项
+
+创建新的配置选项时，将它们添加到 `modules/setting` 的对应文件。您应该将信息添加到 `custom/conf/app.ini`
+并到[配置备忘单](../administration/config-cheat-sheet.md)
+在 `docs/content/doc/advanced/config-cheat-sheet.zh-cn.md` 中找到
+
+### 更改 Logo
+
+更改 Gitea Logo SVG 时，您将需要运行并提交结果的：
+
+```bash
+make generate-images
+```
+
+这将创建必要的 Gitea 图标和其他图标。
+
+### 数据库迁移
+
+如果您对数据库中的任何数据库持久结构进行重大更改
+`models/` 目录，您将需要进行新的迁移。可以找到这些
+在 `models/migrations/` 中。您可以确保您的迁移适用于主要
+数据库类型使用：
+
+```bash
+make test-sqlite-migration # 将 SQLite 切换为适当的数据库
+```
+
+## 测试
+
+Gitea 运行两种类型的测试：单元测试和集成测试。
+
+### 单元测试
+
+`go test` 系统中的`*_test.go` 涵盖了单元测试。
+您可以设置环境变量 `GITEA_UNIT_TESTS_LOG_SQL=1` 以在详细模式下运行测试时显示所有 SQL 语句（即设置`GOTESTFLAGS=-v` 时）。
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
+```
+
+### 集成测试
+
+单元测试不会也不能完全单独测试 Gitea。因此，我们编写了集成测试；但是，这些依赖于数据库。
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
+```
+
+将在 SQLite 环境中运行集成测试。集成测试需要安装 `git lfs`。其他数据库测试可用，但
+可能需要适应当地环境。
+
+看看 [`tests/integration/README.md`](https://github.com/go-gitea/gitea/blob/main/tests/integration/README.md) 有关更多信息以及如何运行单个测试。
+
+### 测试 PR
+
+我们的持续集成将测试代码是否通过了单元测试，并且所有支持的数据库都将在 Docker 环境中通过集成测试。
+还将测试从几个最新版本的 Gitea 迁移。
+
+请在 PR 中附带提交适当的单元测试和集成测试。
+
+## 网站文档
+
+该网站的文档位于 `docs/` 中。如果你改变了文档内容，你可以使用以下测试方法进行持续集成：
+
+```bash
+make lint-md
+```
+
+## Visual Studio Code
+
+`contrib/ide/vscode` 中为 Visual Studio Code 提供了 `launch.json` 和 `tasks.json`。查看
+[`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/main/contrib/ide/README.md) 了解更多信息。
+
+## Goland
+
+单击 `/main.go` 中函数 `func main()` 上的 `Run Application` 箭头
+可以快速启动一个可调试的 Gitea 实例。
+
+`Run/Debug Configuration` 中的 `Output Directory` 必须设置为
+gitea 项目目录（包含 `main.go` 和 `go.mod`），
+否则，启动实例的工作目录是 GoLand 的临时目录
+并防止 Gitea 在开发环境中加载动态资源（例如：模板）。
+
+要在 GoLand 中使用 SQLite 运行单元测试，请设置 `-tags sqlite,sqlite_unlock_notify`
+在 `运行/调试配置` 的 `Go 工具参数` 中。
+
+## 提交 PR
+
+对更改感到满意后，将它们推送并打开拉取请求。它建议您允许 Gitea Managers 和 Owners 修改您的 PR
+分支，因为我们需要在合并之前将其更新为 main 和/或可能是能够直接帮助解决问题。
+
+任何 PR 都需要 Gitea 维护者的两次批准，并且需要通过持续集成。看看我们的
+[CONTRIBUTING.md](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md)
+文档。
+
+如果您需要更多帮助，请访问 [Discord](https://discord.gg/gitea) #Develop 频道
+并在那里聊天。
+
+现在，您已准备好 Hacking Gitea。
--- a/docs/document/development/integrations.md
+++ b/docs/document/development/integrations.md
@@ -0,0 +1,37 @@
+---
+date: "2023-05-25T17:29:00+08:00"
+slug: "integrations"
+sidebar_position: 65
+aliases:
+  - /zh-cn/integrations
+---
+
+# 集成
+
+Gitea 拥有一个出色的第三方集成社区，以及在其他各种项目中的一流支持。
+
+我们正在[awesome-gitea](https://gitea.com/gitea/awesome-gitea)上整理一个列表来跟踪这些集成！
+
+如果你正在寻找[CI/CD](https://gitea.com/gitea/awesome-gitea#user-content-devops)，
+一个[SDK](https://gitea.com/gitea/awesome-gitea#user-content-sdk)，
+甚至一些额外的[主题](https://gitea.com/gitea/awesome-gitea#user-content-themes)，
+你可以在[awesome-gitea](https://gitea.com/gitea/awesome-gitea)中找到它们的列表！
+
+## 预填新文件名和内容
+
+如果你想打开一个具有给定名称和内容的新文件，
+你可以使用查询参数来实现：
+
+```txt
+GET /{{org}}/{{repo}}/_new/{{filepath}}
+    ?filename={{filename}}
+    &value={{content}}
+```
+
+例如：
+
+```txt
+GET https://git.example.com/johndoe/bliss/_new/articles/
+    ?filename=hello-world.md
+    &value=Hello%2C%20World!
+```
--- a/docs/document/development/migrations.md
+++ b/docs/document/development/migrations.md
@@ -0,0 +1,31 @@
+---
+date: "2023-05-25T17:29:00+08:00"
+slug: "migrations-interfaces"
+sidebar_position: 55
+aliases:
+  - /zh-cn/migrations-interfaces
+---
+
+# 迁移接口
+
+完整迁移功能在 Gitea 1.9.0 版本中引入。它定义了两个接口，用于支持从其他 Git 托管平台迁移存储库数据到 Gitea，或者在将来将 Gitea 数据迁移到其他 Git 托管平台。
+
+目前已实现了从 GitHub、GitLab 和其他 Gitea 实例的迁移。
+
+首先，Gitea 在包[modules/migration](https://github.com/go-gitea/gitea/tree/main/modules/migration)中定义了一些标准对象。它们是`Repository`、`Milestone`、`Release`、`ReleaseAsset`、`Label`、`Issue`、`Comment`、`PullRequest`、`Reaction`、`Review`、`ReviewComment`。
+
+## 下载器接口
+
+要从新的 Git 托管平台迁移，需要进行两个步骤的更新。
+
+- 您应该实现一个`Downloader`，用于获取存储库信息。
+- 您应该实现一个`DownloaderFactory`，用于检测 URL 是否匹配，并创建上述的`Downloader`。
+  - 您需要在`init()`中通过`RegisterDownloaderFactory`注册`DownloaderFactory`。
+
+您可以在[downloader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/downloader.go)中找到这些接口。
+
+## 上传器接口
+
+目前，只实现了`GiteaLocalUploader`，因此我们只能通过此 Uploader 将下载的数据保存到本地的 Gitea 实例。目前不支持其他上传器。
+
+您可以在[uploader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/uploader.go)中找到这些接口。
--- a/docs/document/development/oauth2-provider.md
+++ b/docs/document/development/oauth2-provider.md
@@ -0,0 +1,128 @@
+---
+date: "2019-04-19:44:00+01:00"
+slug: "oauth2-provider"
+sidebar_position: 41
+aliases:
+  - /zh-cn/oauth2-provider
+---
+
+# OAuth2 提供者
+
+Gitea 支持作为 OAuth2 提供者，允许第三方应用程序在用户同意的情况下访问其资源。此功能自 1.8.0 版起可用。
+
+## 端点
+
+| 端点                     | URL                                 |
+| ------------------------ | ----------------------------------- |
+| OpenID Connect Discovery | `/.well-known/openid-configuration` |
+| Authorization Endpoint   | `/login/oauth/authorize`            |
+| Access Token Endpoint    | `/login/oauth/access_token`         |
+| OpenID Connect UserInfo  | `/login/oauth/userinfo`             |
+| JSON Web Key Set         | `/login/oauth/keys`                 |
+
+## 支持的 OAuth2 授权
+
+目前 Gitea 仅支持 [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) 标准，并额外支持以下扩展：
+
+- [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636)
+- [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
+
+要将 Authorization Code Grant 作为第三方应用程序，您需要通过在设置中添加一个新的 "应用程序" (`/user/settings/applications`)。
+
+## 范围
+
+Gitea 支持以下令牌范围:
+
+| 名称                                     | 介绍                                                            |
+| ---------------------------------------- | --------------------------------------------------------------- |
+| **(no scope)**                           | 授予对公共用户配置文件和公共存储库的只读访问权限                |
+| **repo**                                 | 完全控制所有存储库                                              |
+| &nbsp;&nbsp;&nbsp; **repo:status**       | 授予对所有存储库中提交状态的读/写访问权限                       |
+| &nbsp;&nbsp;&nbsp; **public_repo**       | 仅授予对公共存储库的读/写访问权限                               |
+| **admin:repo_hook**                      | 授予对所有存储库的 Hooks 访问权限，该权限已包含在 `repo` 范围中 |
+| &nbsp;&nbsp;&nbsp; **write:repo_hook**   | 授予对存储库 Hooks 的读/写访问权限                              |
+| &nbsp;&nbsp;&nbsp; **read:repo_hook**    | 授予对存储库 Hooks 的只读访问权限                               |
+| **admin:org**                            | 授予对组织设置的完全访问权限                                    |
+| &nbsp;&nbsp;&nbsp; **write:org**         | 授予对组织设置的读/写访问权限                                   |
+| &nbsp;&nbsp;&nbsp; **read:org**          | 授予对组织设置的只读访问权限                                    |
+| **admin:public_key**                     | 授予公钥管理的完全访问权限                                      |
+| &nbsp;&nbsp;&nbsp; **write:public_key**  | 授予对公钥的读/写访问权限                                       |
+| &nbsp;&nbsp;&nbsp; **read:public_key**   | 授予对公钥的只读访问权限                                        |
+| **admin:org_hook**                       | 授予对组织级别 Hooks 的完全访问权限                             |
+| **admin:user_hook**                      | 授予对用户级别 Hooks 的完全访问权限                             |
+| **notification**                         | 授予对通知的完全访问权限                                        |
+| **user**                                 | 授予对用户个人资料信息的完全访问权限                            |
+| &nbsp;&nbsp;&nbsp; **read:user**         | 授予对用户个人资料的读取权限                                    |
+| &nbsp;&nbsp;&nbsp; **user:email**        | 授予对用户电子邮件地址的读取权限                                |
+| &nbsp;&nbsp;&nbsp; **user:follow**       | 授予访问权限以关注/取消关注用户                                 |
+| **delete_repo**                          | 授予删除存储库的权限                                            |
+| **package**                              | 授予对托管包的完全访问权限                                      |
+| &nbsp;&nbsp;&nbsp; **write:package**     | 授予对包的读/写访问权限                                         |
+| &nbsp;&nbsp;&nbsp; **read:package**      | 授予对包的读取权限                                              |
+| &nbsp;&nbsp;&nbsp; **delete:package**    | 授予对包的删除权限                                              |
+| **admin:gpg_key**                        | 授予 GPG 密钥管理的完全访问权限                                 |
+| &nbsp;&nbsp;&nbsp; **write:gpg_key**     | 授予对 GPG 密钥的读/写访问权限                                  |
+| &nbsp;&nbsp;&nbsp; **read:gpg_key**      | 授予对 GPG 密钥的只读访问权限                                   |
+| **admin:application**                    | 授予应用程序管理的完全访问权限                                  |
+| &nbsp;&nbsp;&nbsp; **write:application** | 授予应用程序管理的读/写访问权限                                 |
+| &nbsp;&nbsp;&nbsp; **read:application**  | 授予应用程序管理的读取权限                                      |
+| **sudo**                                 | 允许以站点管理员身份执行操作                                    |
+
+## 客户端类型
+
+Gitea 支持私密和公共客户端类型，[参见 RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1).
+
+对于公共客户端, 允许在本地回环地址的重定向 URI 中使用任意端口，例如 `http://127.0.0.1/`。根据 [RFC 8252 的建议](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3)，请避免使用 `localhost`。
+
+## 示例
+
+**注意：** 该示例中尚未使用 PKCE。
+
+1. 将用户重定向到授权端点，以获得他们的访问资源授权:
+
+   ```curl
+   https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
+   ```
+
+   在设置中注册应用程序以获得 `CLIENT_ID`。`STATE` 是一个随机字符串，它将在获得用户授权后发送回您的应用程序。`state` 参数是可选的，但您应该使用它来防止 CSRF 攻击。
+
+   ![Authorization Page](../../static/authorize.png)
+
+   用户将会被询问是否授权给您的应用程序。如果他们同意了授权，用户将会被重定向到 `REDIRECT_URL`，例如：
+
+   ```curl
+   https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
+   ```
+
+2. 使用重定向提供的 `code`，您可以请求一个新的应用程序和 Refresh Token。Access Token Endpoint 接受 `application/json` 或 `application/x-www-form-urlencoded` 类型的 POST 请求，例如：
+
+   ```curl
+   POST https://[YOUR-GITEA-URL]/login/oauth/access_token
+   ```
+
+   ```json
+   {
+     "client_id": "YOUR_CLIENT_ID",
+     "client_secret": "YOUR_CLIENT_SECRET",
+     "code": "RETURNED_CODE",
+     "grant_type": "authorization_code",
+     "redirect_uri": "REDIRECT_URI"
+   }
+   ```
+
+   返回：
+
+   ```json
+   {
+     "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
+     "token_type": "bearer",
+     "expires_in": 3600,
+     "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
+   }
+   ```
+
+   `CLIENT_SECRET` 是生成给应用程序的唯一密钥。请注意，该密钥只会在您使用 Gitea 创建/注册应用程序后出现一次。如果您丢失了密钥，您必须在应用程序设置中重新生成密钥。
+
+   `access_token` 请求中的 `REDIRECT_URI` 必须与 `authorize` 请求中的 `REDIRECT_URI` 相符。
+
+3. 使用 `access_token` 来构造 [API 请求](development/api-usage.md#oauth2-provider) 以读写用户的资源。