docs: add zh-tw folder (#195)

Signed-off-by: appleboy <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/195 Reviewed-by: Lunny Xiao <[email protected]> Co-authored-by: appleboy <[email protected]> Co-committed-by: appleboy <[email protected]>
2026-09-20 04:58:52 +00:00 · 2025-04-04 23:28:16 +00:00
parent 3275094871
commit dbfa0ba454
835 changed files with 72590 additions and 5155 deletions
@@ -0,0 +1,108 @@
+---
+date: "2018-06-24:00:00+02:00"
+slug: "api-usage"
+sidebar_position: 40
+aliases:
+  - /zh-tw/api-usage
+---
+
+# API 使用
+
+## 啟用/配置 API 訪問
+
+預設情況下，`ENABLE_SWAGGER` 是啟用的，`MAX_RESPONSE_ITEMS` 設定為 50。更多資訊請參閱 [配置速查表](../administration/config-cheat-sheet.md)。
+
+## 認證
+
+Gitea 支援以下 API 認證方法：
+
+- HTTP 基本認證
+- URL 查詢字串中的 `token=...` 參數
+- URL 查詢字串中的 `access_token=...` 參數
+- HTTP 標頭中的 `Authorization: token ...` 標頭
+
+所有這些方法都接受相同的 API 金鑰令牌類型。你可以通過查看代碼更好地理解這一點——截至撰寫本文時，Gitea 會解析查詢和標頭以找到令牌，詳見 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47)。
+
+## 生成和列出 API 令牌
+
+可以通過向 `/users/:name/tokens` 發送 `POST` 請求來生成新令牌。
+
+請注意，`/users/:name/tokens` 是一個特殊端點，需要使用 `BasicAuth` 和密碼進行認證，如下所示：
+
+```sh
+$ curl -H "Content-Type: application/json" -d '{"name":"test"}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
+{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
+```
+
+`sha1`（令牌）只會返回一次，並且不會以明文形式存儲。當使用 `GET` 請求列出令牌時，它不會顯示；例如：
+
+```sh
+$ curl --url https://yourusername:[email protected]/api/v1/users/<username>/tokens
+[{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
+```
+
+要在啟用雙因素認證的情況下使用基本認證 API，你需要發送一個包含一次性密碼（6 位數旋轉令牌）的額外標頭。標頭示例如 `X-Gitea-OTP: 123456`，其中 `123456` 是你從身份驗證器中獲取的代碼。以下是 curl 請求的示例：
+
+```sh
+$ curl -H "X-Gitea-OTP: 123456" --url https://yourusername:[email protected]/api/v1/users/yourusername/tokens
+```
+
+你也可以通過 Gitea 安裝的網頁界面創建 API 金鑰令牌：`Settings | Applications | Generate New Token`。
+
+## OAuth2 提供者
+
+從 Gitea 的 [OAuth2 提供者](development/oauth2-provider.md) 獲取的訪問令牌可以通過以下方法接受：
+
+- HTTP 標頭中的 `Authorization bearer ...` 標頭
+- URL 查詢字串中的 `token=...` 參數
+- URL 查詢字串中的 `access_token=...` 參數
+
+### 關於 `Authorization:` 標頭的更多資訊
+
+由於歷史原因，Gitea 需要在授權標頭中的 API 金鑰令牌前包含單詞 `token`，如下所示：
+
+```sh
+Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
+```
+
+例如，在 `curl` 命令中，這將如下所示：
+
+```sh
+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=` 字串中使用的令牌相同。
+
+## 分頁
+
+API 支援分頁。`page` 和 `limit` 參數用於指定頁碼和每頁的項目數量。如果有多頁，則返回 `Link` 標頭，其中包含下一頁、上一頁和最後一頁的鏈接。還返回 `x-total-count` 以指示項目總數。
+
+```sh
+curl -v "http://localhost/api/v1/repos/search?limit=1"
+...
+< link: <http://localhost/api/v1/repos/search?limit=1&page=2>; rel="next",<http://localhost/api/v1/repos/search?limit=1&page=5252>; rel="last"
+...
+< x-total-count: 5252
+```
+
+## API 指南
+
+API 參考指南由 swagger 自動生成，可在以下位置獲取：
+`https://gitea.your.host/api/swagger`
+或在
+[Gitea 實例](https://gitea.com/api/swagger)
+
+OpenAPI 文件位於：
+`https://gitea.your.host/swagger.v1.json`
+
+## Sudo
+
+API 允許管理員用戶以其他用戶的身份 sudo API 請求。只需添加 `sudo=` 參數或 `Sudo:` 請求標頭，並附上要 sudo 的用戶名。
+
+## SDKs
+
+- [官方 go-sdk](https://gitea.com/gitea/go-sdk)
+- [更多](https://gitea.com/gitea/awesome-gitea#user-content-sdk)
@@ -0,0 +1,309 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+slug: "hacking-on-gitea"
+sidebar_position: 10
+aliases:
+  - /zh-tw/hacking-on-gitea
+---
+
+# Gitea 開發
+
+## 快速開始
+
+要快速建立一個可用的開發環境，你可以使用 Gitpod。
+
+[![Open in Gitpod](/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/go-gitea/gitea)
+
+## 安裝 Go
+
+你應該[安裝 Go](https://go.dev/doc/install) 並正確設置你的 Go 環境。
+
+接下來，[安裝 Node.js 和 npm](https://nodejs.org/en/download/)，這是構建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建議使用最新的 LTS 版本。
+
+:::note
+當執行需要外部工具的 make 任務時，如 `make watch-backend`，Gitea 會自動下載並構建這些工具。要使用這些工具，你必須將 `"$GOPATH"/bin` 目錄添加到可執行路徑中。如果你不將 Go bin 目錄添加到可執行路徑中，你將需要自行管理這一點。
+:::
+
+:::note
+需要 Go 版本 @minGoVersion@ 或更高版本。Gitea 使用 `gofmt` 來格式化源代碼。然而，`gofmt` 的結果可能因 Go 的版本而異。因此，建議安裝我們持續集成運行的 Go 版本。截至最後更新，Go 版本應為 @goVersion@。
+:::
+
+要 lint 模板文件，請確保安裝 [Python](https://www.python.org/) 和 [Poetry](https://python-poetry.org/)。
+
+## 安裝 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 Porting](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`
+
+:::note
+如果你嘗試使用 Windows 命令提示符構建，你可能會遇到問題。建議使用上述提示（Git bash 或 MinGW），但如果你只有命令提示符（或可能是 PowerShell），你可以使用 [set](https://docs.microsoft.com/zh-tw/windows-server/administration/windows-commands/set_1) 命令設置環境變量，例如 `set TAGS=bindata`。
+:::
+
+## 下載和克隆 Gitea 源代碼
+
+推薦的方法是使用 `git clone` 獲取源代碼。
+
+```bash
+git clone https://github.com/go-gitea/gitea
+```
+
+（由於 go 模塊的出現，不再需要從 `$GOPATH` 內構建 go 項目，因此不再推薦使用 `go get` 方法。）
+
+## Fork Gitea
+
+如上所述下載主要的 Gitea 源代碼。然後，在 GitHub 上 fork [Gitea repository](https://github.com/go-gitea/gitea)，並將 git 遠程 origin 切換到你的 fork 或添加你的 fork 作為另一個遠程：
+
+```bash
+# 將原始 Gitea origin 重命名為 upstream
+git remote rename origin upstream
+git remote add origin "[email protected]:$GITHUB_USERNAME/gitea.git"
+git fetch --all --prune
+```
+
+或：
+
+```bash
+# 為我們的 fork 添加新遠程
+git remote add "$FORK_NAME" "[email protected]:$GITHUB_USERNAME/gitea.git"
+git fetch --all --prune
+```
+
+為了能夠創建 pull request，fork 的倉庫應該被添加為 Gitea 源代碼的遠程。否則，無法推送更改。
+
+## 構建 Gitea（基礎）
+
+查看我們的[從源代碼構建](installation/from-source.md)的[說明](installation/from-source.md)。
+
+從源代碼構建的最簡單推薦方法是：
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make build
+```
+
+`build` 目標將執行 `frontend` 和 `backend` 子目標。如果存在 `bindata` 標籤，前端文件將被編譯到二進制文件中。建議在進行前端開發時省略該標籤，以便更改能夠反映出來。
+
+查看 `make help` 以獲取所有可用的 `make` 目標。還可以查看 [`.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 上，監視所有後端源文件可能會達到默認的打開文件限制，可以通過 `ulimit -n 12288` 為當前 shell 或在你的 shell 啟動文件中為所有未來的 shell 增加此限制。
+
+### 格式化、代碼分析和拼寫檢查
+
+我們的持續集成將拒絕未通過代碼 linter（包括格式檢查、代碼分析和拼寫檢查）的 PR。
+
+你應該格式化你的代碼：
+
+```bash
+make fmt
+```
+
+並 lint 源代碼：
+
+```bash
+# lint 前端和後端代碼
+make lint
+# 僅 lint 後端代碼
+make lint-backend
+```
+
+**注意**：`gofmt` 的結果取決於當前的 Go 版本。你應該運行與持續集成服務器上相同版本的 Go，如上所述。
+
+### 處理 JS 和 CSS
+
+前端開發應遵循[前端開發指南](contributing/guidelines-frontend.md)
+
+要使用前端資源構建，可以使用上述的 `watch-frontend` 目標或僅構建一次：
+
+```bash
+make build && ./gitea
+```
+
+在提交之前，確保 linter 通過：
+
+```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
+```
+
+### 構建和添加 SVG
+
+SVG 圖標使用 `make svg` 目標構建，將圖標源編譯到輸出目錄 `public/assets/img/svg` 中。自定義圖標可以添加到 `web_src/svg` 目錄中。
+
+### 構建 Logo
+
+Gitea 標誌的 PNG 和 SVG 版本是從單個 SVG 源文件 `assets/logo.svg` 使用 `TAGS="gitea" make generate-images` 目標構建的。要運行它，必須有 Node.js 和 npm。
+
+同樣的過程也可以用來從 SVG 源文件生成自定義標誌 PNG，只需更新 `assets/logo.svg` 並運行 `make generate-images`。省略 `gitea` 標籤將僅更新用戶指定的標誌文件。
+
+### 更新 API
+
+在創建新 API 路由或修改現有 API 路由時，你**必須**使用 [go-swagger](https://goswagger.io/) 註釋更新和/或創建 [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/) 文檔。這些註釋的結構在[規範](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 端點，請使用以下命令重新生成 Swagger 文檔：
+
+```bash
+make generate-swagger
+```
+
+你應該驗證生成的 Swagger 文件：
+
+```bash
+make swagger-validate
+```
+
+你應該提交更改的 swagger JSON 文件。持續集成服務器將使用以下命令檢查是否已完成此操作：
+
+```bash
+make swagger-check
+```
+
+:::note
+請注意，你應該使用 Swagger 2.0 文檔，而不是 OpenAPI 3 文檔。
+:::
+
+### 創建新配置選項
+
+在創建新配置選項時，僅將它們添加到 `modules/setting` 文件中是不夠的。你應該將信息添加到 `custom/conf/app.ini` 和 `docs/content/doc/administer/config-cheat-sheet.zh-tw.md` 中的[配置速查表](../administration/config-cheat-sheet.md)。
+
+### 更改標誌
+
+在更改 Gitea 標誌 SVG 時，你需要運行並提交以下命令的結果：
+
+```bash
+make generate-images
+```
+
+這將創建必要的 Gitea favicon 和其他圖標。
+
+### 數據庫遷移
+
+如果你對 `models/` 目錄中的任何數據庫持久化結構進行了重大更改，你將需要進行新的遷移。這些可以在 `models/migrations/` 中找到。你可以使用以下命令確保你的遷移適用於主要數據庫類型：
+
+```bash
+make test-sqlite-migration # 使用 SQLite 進行測試，並根據需要切換到適當的數據庫
+```
+
+## 測試
+
+Gitea 運行兩種類型的測試：單元測試和集成測試。
+
+### 單元測試
+
+單元測試由 `*_test.go` 覆蓋在 `go test` 系統中。你可以設置環境變量 `GITEA_UNIT_TESTS_LOG_SQL=1` 以在詳細模式下運行測試時顯示所有 SQL 語句（即設置 `GOTESTFLAGS=-v`）。
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make test # 運行單元測試
+```
+
+### 集成測試
+
+單元測試無法完全測試 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` 中提供了 `launch.json` 和 `tasks.json` 用於 Visual Studio Code。查看 [`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 運行單元測試，請在 `Run/Debug Configuration` 的 `Go tool arguments` 中設置 `-tags sqlite,sqlite_unlock_notify`。
+
+## 提交 PR
+
+一旦你對更改感到滿意，請將它們推送並打開一個 pull request。建議允許 Gitea 管理員和所有者修改你的 PR 分支，因為我們需要在合併之前將其更新到 main，並且/或者可能能夠直接幫助修復問題。
+
+任何 PR 需要兩個 Gitea 維護者的批准，並且需要通過持續集成。查看我們的 [`CONTRIBUTING.md`](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md) 文檔。
+
+如果你需要更多幫助，請加入 [Discord](https://discord.gg/gitea) #Develop 聊天。
+
+就是這樣！你已經準備好開發 Gitea 了。
@@ -0,0 +1,33 @@
+---
+date: "2019-04-15T17:29:00+08:00"
+slug: "integrations"
+sidebar_position: 65
+aliases:
+  - /zh-tw/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!
+```
@@ -0,0 +1,31 @@
+---
+date: "2019-04-15T17:29:00+08:00"
+slug: "migrations-interfaces"
+sidebar_position: 55
+aliases:
+  - /zh-tw/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) 中找到這些介面。
@@ -0,0 +1,216 @@
+---
+date: "2023-06-01T08:40:00+08:00"
+slug: "oauth2-provider"
+sidebar_position: 41
+aliases:
+  - /zh-tw/oauth2-provider
+---
+
+# OAuth2 提供者
+
+Gitea 支援作為 OAuth2 提供者，允許第三方應用程式在用戶同意的情況下訪問其資源。
+
+當作為 OAuth2 提供者時，Gitea 會針對相關的 OAuth2 應用程式驗證每個授權請求。此應用程式可以由個別用戶、組織管理員或 Gitea 實例管理員設置。
+
+無論是誰配置的應用程式，第一次授權嘗試都會在用戶的網頁瀏覽器中打開一個新頁面，提示他們授權應用程式。
+
+## 配置
+
+Gitea 中的 OAuth2 應用程式需要以下兩步配置：
+
+### Gitea 步驟 1
+
+- 名稱 (`/admin/applications/`)
+- 重定向 URL (`/admin/applications/`)
+
+![](/development/gitea_oauth2_step1.png)
+
+### Gitea 步驟 2
+
+- 客戶端 ID (`/admin/applications/oauth2/_id_`)
+- 客戶端密鑰 (`/admin/applications/oauth2/_id_`)
+- 機密客戶端狀態 (`/admin/applications/oauth2/_id_`)
+
+![](/development/gitea_oauth2_step2.png)
+
+### 第三方步驟 3
+
+第三方（中繼方）應用程式的請求必須包括：
+
+- 憑證（客戶端 ID 和客戶端密鑰）
+- 所需的範圍和聲明（預期由 Gitea 提供）
+
+MinIO 的示例：
+
+![](/development/minio_oauth2.png)
+
+### Gitea 的用戶批准步驟 3
+
+例如，使用 Gitea 帳戶登錄 MinIO...
+![](/development/minio_login.png)
+
+...在成功登錄後將顯示批准彈出窗口：
+![](/development/gitea_approval.png)
+
+默認情況下，如果第三方設置範圍為 `openid`、`email`、`profile` 和 `groups`，並且用戶批准，應用程式將獲得用戶所有公共和私人資源（倉庫、問題、用戶信息等）的完全訪問權限。
+
+> **注意：** 目前，如果期望限制訪問，設置 Gitea 中的 OAuth2 應用程式的管理員必須依賴第三方發送的範圍和知情用戶的批准決定。在應用程式設置過程中，管理員無法通過範圍設置限制訪問。
+
+## 細粒度範圍
+
+從 v1.23 版本開始，Gitea 支援細粒度範圍，允許第三方請求更有限的訪問權限。這些範圍以前僅適用於[個人訪問令牌](#scopes)，使用戶能夠限制對特定 URL 路徑的訪問。
+
+範圍按高級 API 路徑分組，並進一步細化如下：
+
+- `read`：`GET` 路徑
+- `write`：`POST`、`PUT`、`PATCH` 和 `DELETE` 路徑（以及 `GET`）
+
+例如，第三方可以請求最小訪問權限，允許 Gitea 作為簡單的 OpenID Connect (OIDC) 提供者。如果第三方僅添加 `public-only` 到 'openid'，不添加其他或任何組合的範圍 `email`、`userinfo` 或 `groups`，Gitea 將作為基本的單一登錄提供者。此配置僅提供用戶可以使用正確憑證登錄的驗證，僅提供基本信息，如用戶名、電子郵件和公共組織和團隊成員資格列表。
+
+當引入任何來自個人訪問令牌的細粒度範圍時，Gitea 將不允許完全訪問（如默認情況下）。相反，它將根據對倉庫、問題、ActivityPub、管理功能、組織、用戶、包或其他功能的讀寫權限構建細粒度訪問。
+
+> **注意：** 如果第三方添加任何範圍以外的 OIDC 範圍：`openid`、`email`、`profile` 和 `groups` 或已在個人訪問令牌中找到的範圍，範圍將回退到完全訪問，如 v1.23 之前的情況。
+
+顯示給用戶的批准頁面顯示第三方請求的範圍列表。一旦批准，此決定將被記住。如果第三方在未來的請求中更改其請求的範圍，整個流程將失敗，需要重新授權。
+
+## 端點
+
+| 端點                    | URL                                 |
+| ----------------------- | ----------------------------------- |
+| OpenID Connect 發現     | `/.well-known/openid-configuration` |
+| 授權端點                | `/login/oauth/authorize`            |
+| 訪問令牌端點            | `/login/oauth/access_token`         |
+| OpenID Connect 用戶信息 | `/login/oauth/userinfo`             |
+| JSON Web 密鑰集         | `/login/oauth/keys`                 |
+
+## 支援的 OAuth2 授權
+
+目前 Gitea 只支援 [**授權碼授權**](https://tools.ietf.org/html/rfc6749#section-1.3.1) 標準，並額外支援以下擴展：
+
+- [代碼交換的證明密鑰 (PKCE)](https://tools.ietf.org/html/rfc7636)
+- [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
+
+要作為第三方應用程式使用授權碼授權，需要通過設置中的“應用程式” (`/user/settings/applications`) 部分註冊新應用程式。要測試或調試，你可以使用網頁工具 https://oauthdebugger.com/。
+
+## 範圍
+
+Gitea 支援範圍訪問令牌，允許用戶限制令牌僅在選定的 URL 路徑上操作。範圍按高級 API 路徑分組，並進一步細化如下：
+
+- `read`：`GET` 路徑
+- `write`：`POST`、`PUT`、`PATCH` 和 `DELETE` 路徑（以及 `GET`）
+
+Gitea 令牌範圍如下：
+
+| 名稱                                      | 描述                                                                              |
+| ----------------------------------------- | --------------------------------------------------------------------------------- |
+| **（無範圍）**                            | 不支援。即使是公共倉庫也需要範圍。                                                |
+| **activitypub**                           | `activitypub` API 路徑：ActivityPub 相關操作。                                    |
+| &nbsp;&nbsp;&nbsp; **read:activitypub**   | 授予 ActivityPub 操作的讀取訪問權限。                                             |
+| &nbsp;&nbsp;&nbsp; **write:activitypub**  | 授予 ActivityPub 操作的讀寫/刪除訪問權限。                                        |
+| **admin**                                 | `/admin/*` API 路徑：全站管理操作（對非管理帳戶隱藏）。                           |
+| &nbsp;&nbsp;&nbsp; **read:admin**         | 授予管理操作的讀取訪問權限，例如獲取計劃任務或註冊用戶電子郵件。                  |
+| &nbsp;&nbsp;&nbsp; **write:admin**        | 授予管理操作的讀寫/刪除訪問權限，例如運行計劃任務或更新用戶帳戶。                 |
+| **issue**                                 | `issues/*`、`labels/*`、`milestones/*` API 路徑：問題相關操作。                   |
+| &nbsp;&nbsp;&nbsp; **read:issue**         | 授予問題操作的讀取訪問權限，例如獲取問題評論、問題附件和里程碑。                  |
+| &nbsp;&nbsp;&nbsp; **write:issue**        | 授予問題操作的讀寫/刪除訪問權限，例如發布或編輯問題評論或附件，並更新里程碑。     |
+| **misc**                                  | 保留供未來使用。                                                                  |
+| &nbsp;&nbsp;&nbsp; **read:misc**          | 保留供未來使用。                                                                  |
+| &nbsp;&nbsp;&nbsp; **write:misc**         | 保留供未來使用。                                                                  |
+| **notification**                          | `notification/*` API 路徑：用戶通知操作。                                         |
+| &nbsp;&nbsp;&nbsp; **read:notification**  | 授予用戶通知的讀取訪問權限，例如用戶訂閱的通知和閱讀新通知。                      |
+| &nbsp;&nbsp;&nbsp; **write:notification** | 授予用戶通知的讀寫/刪除訪問權限，例如將通知標記為已讀。                           |
+| **organization**                          | `orgs/*` 和 `teams/*` API 路徑：組織和團隊管理操作。                              |
+| &nbsp;&nbsp;&nbsp; **read:organization**  | 授予組織和團隊狀態的讀取訪問權限，例如列出用戶可見的所有組織、團隊和團隊成員。    |
+| &nbsp;&nbsp;&nbsp; **write:organization** | 授予組織和團隊狀態的讀寫/刪除訪問權限，例如創建和更新團隊以及更新組織設置。       |
+| **package**                               | `/packages/*` API 路徑：包操作                                                    |
+| &nbsp;&nbsp;&nbsp; **read:package**       | 授予包操作的讀取訪問權限，例如閱讀和下載可用的包。                                |
+| &nbsp;&nbsp;&nbsp; **write:package**      | 授予包操作的讀寫/刪除訪問權限。目前與 `read:package` 相同。                       |
+| **repository**                            | `/repos/*` API 路徑，除了 `/repos/issues/*`：倉庫文件、拉取請求和發佈操作。       |
+| &nbsp;&nbsp;&nbsp; **read:repository**    | 授予倉庫操作的讀取訪問權限，例如獲取倉庫文件、發佈、協作者。                      |
+| &nbsp;&nbsp;&nbsp; **write:repository**   | 授予倉庫操作的讀寫/刪除訪問權限，例如獲取更新倉庫文件、創建拉取請求、更新協作者。 |
+| **user**                                  | `/user/*` 和 `/users/*` API 路徑：用戶相關操作。                                  |
+| &nbsp;&nbsp;&nbsp; **read:user**          | 授予用戶操作的讀取訪問權限，例如獲取用戶倉庫訂閱和用戶設置。                      |
+| &nbsp;&nbsp;&nbsp; **write:user**         | 授予用戶操作的讀寫/刪除訪問權限，例如更新用戶倉庫訂閱、關注的用戶和用戶設置。     |
+
+## 預配置應用程式
+
+Gitea 在啟動時默認為以下服務創建 OAuth 應用程式，因為我們認為這些應用程式是普遍有用的。
+
+| 應用程式                                                                          | 描述         | 客戶端 ID                              |
+| --------------------------------------------------------------------------------- | ------------ | -------------------------------------- |
+| [git-credential-oauth](https://github.com/hickford/git-credential-oauth)          | Git 憑證助手 | `a4792ccc-144e-407e-86c9-5e7d8d9c3269` |
+| [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager) | Git 憑證助手 | `e90ee53c-94e2-48ac-9358-a874fb9e0662` |
+| [tea](https://gitea.com/gitea/tea)                                                | tea          | `d57cb8c4-630c-4168-8324-ec79935e18d4` |
+
+為防止意外行為，它們在 UI 中顯示為鎖定，其創建可以通過 `app.ini` 中的 `DEFAULT_APPLICATIONS` 參數進行控制。
+
+## 客戶端類型
+
+Gitea 支援機密和公共客戶端類型，[如 RFC 6749 定義](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1)。
+
+對於公共客戶端，重定向 URI 為回送 IP 地址，例如 `http://127.0.0.1/` 允許任何端口。避免使用 `localhost`，[如 RFC 8252 建議](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3)。
+
+## 示例
+
+### 機密客戶端
+
+:::note
+此示例不使用 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 攻擊。
+
+   ![授權頁面](/authorize.png)
+
+   現在將要求用戶授權你的應用程式。如果他們授權，用戶將被重定向到 `REDIRECT_URL`，例如：
+
+   ```curl
+   https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
+   ```
+
+2. 使用重定向提供的 `code`，你可以請求新的應用程式和刷新令牌。訪問令牌端點接受 `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` 是為此應用程式生成的唯一密鑰。請注意，密鑰僅在你創建/註冊應用程式後可見，無法恢復。如果你丟失了密鑰，必須通過應用程式設置重新生成密鑰。
+
+   `access_token` 請求中的 `REDIRECT_URI` 必須與 `authorize` 請求中的 `REDIRECT_URI` 匹配。
+
+3. 使用 `access_token` 進行 [API 請求](development/api-usage.md#oauth2-provider) 以訪問用戶的資源。
+
+### 公共客戶端 (PKCE)
+
+PKCE（代碼交換的證明密鑰）是 OAuth 流程的擴展，允許在不需要提供客戶端密鑰的情況下進行安全的憑證交換。
+
+**注意**：請確保你已將你的 OAuth 應用程式註冊為公共客戶端。
+
+為了實現這一點，你必須為每個授權請求提供一個 `code_verifier`。`code_verifier` 必須是一個隨機字串，最小長度為 43 個字符，最大長度為 128 個字符。它可以包含字母