gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-07-23 13:07:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update zh tw languages and fix some broken links

Browse Source
This commit is contained in:
Lunny Xiao
2026-07-01 14:47:51 -07:00
parent 9558006c39
commit a084bdb556
842 changed files with 31137 additions and 31065 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.23/development/api-usage.md
View File

@@ -8,10 +8,12 @@ aliases:
# API 使用
## 啟用/配置 API 訪問
## 啟用/設定 API 存取
預設情況下，`ENABLE_SWAGGER` 是啟用的，`MAX_RESPONSE_ITEMS` 設定為 50。更多資訊請參閱 [配置速查表](../administration/config-cheat-sheet.md)。
預設情況下，`ENABLE_SWAGGER` 是啟用的，`MAX_RESPONSE_ITEMS` 設定為 50。更多資訊請參閱 [設定速查表](../administration/config-cheat-sheet.md)。
<a id="authentication"></a>
<a id="通過-api-認證"></a>
## 認證
Gitea 支援以下 API 認證方法：
@@ -21,11 +23,11 @@ Gitea 支援以下 API 認證方法：
- 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 金鑰令牌類型。你可以透過查看程式碼更好地理解這一點——截至撰寫本文時，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` 發送 `POST` 請求來生成新令牌。
請注意，`/users/:name/tokens` 是一個特殊端點，需要使用 `BasicAuth` 和密碼進行認證，如下所示：
@@ -34,24 +36,25 @@ $ curl -H "Content-Type: application/json" -d '{"name":"test"}' -u username:pass
{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
```
`sha1`（令牌）只會返回一次，並且不會以明文形式存儲。當使用 `GET` 請求列出令牌時，它不會顯示；例如：
`sha1`（令牌）只會返回一次，並且不會以明文形式儲存。當使用 `GET` 請求列出令牌時，它不會顯示；例如：
```sh
$ curl --url https://yourusername:password@gitea.your.host/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 請求的示例：
要在啟用雙因素認證的情況下使用基本認證 API，你需要發送一個包含一次性密碼（6 位數旋轉令牌）的額外標頭。標頭範例如 `X-Gitea-OTP: 123456`，其中 `123456` 是你從身份驗證器中獲取的程式碼。以下是 curl 請求的範例：
```sh
$ curl -H "X-Gitea-OTP: 123456" --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
```
你也可以通過 Gitea 安裝的網頁界面創建 API 金鑰令牌：`Settings | Applications | Generate New Token`。
你也可以透過 Gitea 安裝的網頁介面建立 API 金鑰令牌：`Settings | Applications | Generate New Token`。
<a id="oauth2-provider"></a>
## OAuth2 提供者
從 Gitea 的 [OAuth2 提供者](development/oauth2-provider.md) 獲取的訪問令牌可以通過以下方法接受：
從 Gitea 的 [OAuth2 提供者](development/oauth2-provider.md) 獲取的存取權杖可以透過以下方法接受：
- HTTP 標頭中的 `Authorization bearer ...` 標頭
- URL 查詢字串中的 `token=...` 參數
@@ -78,7 +81,7 @@ curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
## 分頁
API 支援分頁。`page` 和 `limit` 參數用於指定頁碼和每頁的項目數量。如果有多頁，則返回 `Link` 標頭，其中包含下一頁、上一頁和最後一頁的鏈接。還返回 `x-total-count` 以指示項目總數。
API 支援分頁。`page` 和 `limit` 參數用於指定頁碼和每頁的專案數量。如果有多頁，則返回 `Link` 標頭，其中包含下一頁、上一頁和最後一頁的鏈接。還返回 `x-total-count` 以指示專案總數。
```sh
curl -v "http://localhost/api/v1/repos/search?limit=1"
@@ -100,7 +103,7 @@ OpenAPI 文件位於：
## Sudo
API 允許管理員用戶以其他用戶的身份 sudo API 請求。只需添加 `sudo=` 參數或 `Sudo:` 請求標頭，並附上要 sudo 的用戶名。
API 允許管理員使用者以其他使用者的身份 sudo API 請求。只需添加 `sudo=` 參數或 `Sudo:` 請求標頭，並附上要 sudo 的使用者名稱。
## SDKs

96
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.23/development/hacking-on-gitea.md
View File

@@ -16,27 +16,27 @@ aliases:
## 安裝 Go
你應該[安裝 Go](https://go.dev/doc/install) 並正確設置你的 Go 環境。
你應該[安裝 Go](https://go.dev/doc/install) 並正確設定你的 Go 環境。
接下來，[安裝 Node.js 和 npm](https://nodejs.org/en/download/)，這是構建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建議使用最新的 LTS 版本。
接下來，[安裝 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@。
需要 Go 版本 @minGoVersion@ 或更高版本。Gitea 使用 `gofmt` 來格式化源程式碼。然而，`gofmt` 的結果可能因 Go 的版本而異。因此，建議安裝我們持續整合運行的 Go 版本。截至最後更新，Go 版本應為 @goVersion@。
:::
要 lint 模板文件，請確保安裝 [Python](https://www.python.org/) 和 [Poetry](https://python-poetry.org/)。
## 安裝 Make
Gitea 大量使用 Make 來自動化任務並改進開發。這個指南涵蓋了如何安裝 Make。
Gitea 大量使用 Make 來自動化任務並改進開發。這個指南涵蓋瞭如何安裝 Make。
### 在 Linux 上
使用包管理器安裝。
使用套件管理器安裝。
在 Ubuntu/Debian 上：
@@ -65,22 +65,22 @@ sudo yum install make
- [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`。
如果你嘗試使用 Windows 命令提示符構建，你可能會遇到問題。建議使用上述提示（Git bash 或 MinGW），但如果你只有命令提示符（或可能是 PowerShell），你可以使用 [set](https://docs.microsoft.com/zh-tw/windows-server/administration/windows-commands/set_1) 命令設定環境變量，例如 `set TAGS=bindata`。
:::
## 下載和克隆 Gitea 源代碼
## 下載和克隆 Gitea 源程式碼
推薦的方法是使用 `git clone` 獲取源代碼。
推薦的方法是使用 `git clone` 獲取源程式碼。
```bash
git clone https://github.com/go-gitea/gitea
```
（由於 go 模塊的出現，不再需要從 `$GOPATH` 內構建 go 項目，因此不再推薦使用 `go get` 方法。）
（由於 go 模組的出現，不再需要從 `$GOPATH` 內構建 go 專案，因此不再推薦使用 `go get` 方法。）
## Fork Gitea
如上所述下載主要的 Gitea 源代碼。然後，在 GitHub 上 fork [Gitea repository](https://github.com/go-gitea/gitea)，並將 git 遠程 origin 切換到你的 fork 或添加你的 fork 作為另一個遠程：
如上所述下載主要的 Gitea 源程式碼。然後，在 GitHub 上 fork [Gitea repository](https://github.com/go-gitea/gitea)，並將 git 遠程 origin 切換到你的 fork 或添加你的 fork 作為另一個遠程：
```bash
# 將原始 Gitea origin 重命名為 upstream
@@ -97,13 +97,13 @@ git remote add "$FORK_NAME" "git@github.com:$GITHUB_USERNAME/gitea.git"
git fetch --all --prune
```
為了能夠創建 pull request，fork 的倉庫應該被添加為 Gitea 源代碼的遠程。否則，無法推送更改。
為了能夠建立 pull request，fork 的儲存庫應該被添加為 Gitea 源程式碼的遠程。否則，無法推送更改。
## 構建 Gitea（基礎）
查看我們的[從源代碼構建](installation/from-source.md)的[說明](installation/from-source.md)。
查看我們的[從源程式碼構建](installation/from-source.md)的[說明](installation/from-source.md)。
從源代碼構建的最簡單推薦方法是：
從源程式碼構建的最簡單推薦方法是：
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build
@@ -111,7 +111,7 @@ 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) 了解我們的持續集成如何工作。
查看 `make help` 以獲取所有可用的 `make` 目標。還可以查看 [`.drone.yml`](https://github.com/go-gitea/gitea/blob/main/.drone.yml) 瞭解我們的持續整合如何工作。
## 持續構建
@@ -128,19 +128,19 @@ make watch-frontend
make watch-backend
```
在 macOS 上，監視所有後端源文件可能會達到默認的打開文件限制，可以通過 `ulimit -n 12288` 為當前 shell 或在你的 shell 啟動文件中為所有未來的 shell 增加此限制。
在 macOS 上，監視所有後端源文件可能會達到預設的打開文件限制，可以透過 `ulimit -n 12288` 為當前 shell 或在你的 shell 啟動文件中為所有未來的 shell 增加此限制。
### 格式化、代碼分析和拼寫檢查
### 格式化、程式碼分析和拼寫檢查
我們的持續集成將拒絕未通過代碼 linter（包括格式檢查、代碼分析和拼寫檢查）的 PR。
我們的持續整合將拒絕未通過程式碼 linter（包括格式檢查、程式碼分析和拼寫檢查）的 PR。
你應該格式化你的代碼：
你應該格式化你的程式碼：
```bash
make fmt
```
並 lint 源代碼：
並 lint 源程式碼：
```bash
# lint 前端和後端代碼
@@ -149,7 +149,7 @@ make lint
make lint-backend
```
**注意**：`gofmt` 的結果取決於當前的 Go 版本。你應該運行與持續集成服務器上相同版本的 Go，如上所述。
**注意**：`gofmt` 的結果取決於當前的 Go 版本。你應該運行與持續整合伺服器上相同版本的 Go，如上所述。
### 處理 JS 和 CSS
@@ -167,7 +167,7 @@ make build && ./gitea
make lint-frontend
```
### 配置本地 ElasticSearch 實例
### 設定本地 ElasticSearch 實例
使用 docker 啟動本地 ElasticSearch 實例：
@@ -177,7 +177,7 @@ 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`：
設定 `app.ini`：
```ini
[indexer]
@@ -190,21 +190,21 @@ REPO_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
### 構建和添加 SVG
SVG 圖標使用 `make svg` 目標構建，將圖標源編譯到輸出目錄 `public/assets/img/svg` 中。自定義圖標可以添加到 `web_src/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` 標籤將僅更新用戶指定的標誌文件。
同樣的過程也可以用來從 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 路由時，你**必須**使用 [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 的下游使用者。一般來說，添加是可以接受的，但刪除或對 API 的根本性更改將被拒絕。
一旦你創建或更改了一個 API 端點，請使用以下命令重新生成 Swagger 文檔：
一旦你建立或更改了一個 API 端點，請使用以下命令重新生成 Swagger 文件：
```bash
make generate-swagger
@@ -216,19 +216,19 @@ make generate-swagger
make swagger-validate
```
你應該提交更改的 swagger JSON 文件。持續集成服務器將使用以下命令檢查是否已完成此操作：
你應該提交更改的 swagger JSON 文件。持續整合伺服器將使用以下命令檢查是否已完成此操作：
```bash
make swagger-check
```
:::note
請注意，你應該使用 Swagger 2.0 文檔，而不是 OpenAPI 3 文檔。
請注意，你應該使用 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)。
在建立新設定選項時，僅將它們添加到 `modules/setting` 文件中是不夠的。你應該將資訊添加到 `custom/conf/app.ini` 和 `docs/content/doc/administer/config-cheat-sheet.zh-tw.md` 中的[設定速查表](../administration/config-cheat-sheet.md)。
### 更改標誌
@@ -238,11 +238,11 @@ make swagger-check
make generate-images
```
這將創建必要的 Gitea favicon 和其他圖標。
這將建立必要的 Gitea favicon 和其他圖標。
### 數據庫遷移
### 資料庫遷移
如果你對 `models/` 目錄中的任何數據庫持久化結構進行了重大更改，你將需要進行新的遷移。這些可以在 `models/migrations/` 中找到。你可以使用以下命令確保你的遷移適用於主要數據庫類型：
如果你對 `models/` 目錄中的任何資料庫持久化結構進行了重大更改，你將需要進行新的遷移。這些可以在 `models/migrations/` 中找到。你可以使用以下命令確保你的遷移適用於主要資料庫類型：
```bash
make test-sqlite-migration # 使用 SQLite 進行測試，並根據需要切換到適當的數據庫
@@ -250,37 +250,37 @@ make test-sqlite-migration # 使用 SQLite 進行測試，並根據需要切換
## 測試
Gitea 運行兩種類型的測試：單元測試和集成測試。
Gitea 運行兩種類型的測試：單元測試和整合測試。
### 單元測試
單元測試由 `*_test.go` 覆蓋在 `go test` 系統中。你可以設置環境變量 `GITEA_UNIT_TESTS_LOG_SQL=1` 以在詳細模式下運行測試時顯示所有 SQL 語句（即設置 `GOTESTFLAGS=-v`）。
單元測試由 `*_test.go` 覆蓋在 `go test` 系統中。你可以設定環境變量 `GITEA_UNIT_TESTS_LOG_SQL=1` 以在詳細模式下運行測試時顯示所有 SQL 語句（即設定 `GOTESTFLAGS=-v`）。
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make test # 運行單元測試
```
### 集成測試
### 整合測試
單元測試無法完全測試 Gitea。因此，我們編寫了集成測試；然而，這些測試依賴於數據庫。
單元測試無法完全測試 Gitea。因此，我們編寫了整合測試；然而，這些測試依賴於資料庫。
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
```
將在 SQLite 環境中運行集成測試。集成測試需要安裝 `git lfs`。其他數據庫測試可用，但可能需要調整本地環境。
將在 SQLite 環境中運行整合測試。整合測試需要安裝 `git lfs`。其他資料庫測試可用，但可能需要調整本地環境。
查看 [`tests/integration/README.md`](https://github.com/go-gitea/gitea/blob/main/tests/integration/README.md) 以獲取更多信息以及如何運行單個測試。
查看 [`tests/integration/README.md`](https://github.com/go-gitea/gitea/blob/main/tests/integration/README.md) 以獲取更多資訊以及如何運行單個測試。
### PR 測試
我們的持續集成將測試代碼是否通過其單元測試，並且所有支持的數據庫將在 Docker 環境中通過集成測試。還將測試從 Gitea 的幾個最近版本的遷移。
我們的持續整合將測試程式碼是否通過其單元測試，並且所有支援的資料庫將在 Docker 環境中通過整合測試。還將測試從 Gitea 的幾個最近版本的遷移。
請提交你的 PR，並根據需要添加額外的測試和集成測試。
請提交你的 PR，並根據需要添加額外的測試和整合測試。
## 網站文檔
## 網站文件
網站文檔位於 `docs/` 中。如果你更改了這些文檔，可以使用以下命令測試你的更改以確保它們通過持續集成：
網站文件位於 `docs/` 中。如果你更改了這些文件，可以使用以下命令測試你的更改以確保它們通過持續整合：
```bash
make lint-md
@@ -288,21 +288,21 @@ 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) 以獲取更多信息。
在 `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 在開發環境中加載動態資源（例如：模板）。
`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`。
要在 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) 文檔。
任何 PR 需要兩個 Gitea 維護者的批准，並且需要通過持續整合。查看我們的 [`CONTRIBUTING.md`](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md) 文件。
如果你需要更多幫助，請加入 [Discord](https://discord.gg/gitea) #Develop 聊天。

4
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.23/development/integrations.md
View File

@@ -8,11 +8,11 @@ aliases:
# 整合
Gitea 有一個很棒的第三方整合社群，以及在各種其他項目中的一流支援。
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) 倉庫中找到它們！
如果你在尋找 [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) 儲存庫中找到它們！
## 預填新文件名稱和內容

8
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.23/development/migrations.md
View File

@@ -8,7 +8,7 @@ aliases:
# 遷移介面
完整的遷移在 Gitea 1.9.0 中引入。它定義了兩個介面來支持從其他 Git 主機平台遷移倉庫數據到 Gitea，或者在未來，將 Gitea 數據遷移到其他 Git 主機平台。
完整的遷移在 Gitea 1.9.0 中引入。它定義了兩個介面來支援從其他 Git 主機平台遷移儲存庫資料到 Gitea，或者在未來，將 Gitea 資料遷移到其他 Git 主機平台。
目前，已實現從 GitHub、GitLab 和其他 Gitea 實例的遷移。
@@ -18,14 +18,14 @@ aliases:
要從新的 Git 主機平台遷移，有兩個步驟需要更新。
- 你應該實現一個 `Downloader`，它將用於獲取倉庫信息。
- 你應該實現一個 `DownloaderFactory`，它將用於檢測 URL 是否匹配並創建上述 `Downloader`。
- 你應該實現一個 `Downloader`，它將用於獲取儲存庫資訊。
- 你應該實現一個 `DownloaderFactory`，它將用於檢測 URL 是否匹配並建立上述 `Downloader`。
- 你需要在 `init()` 中通過 `RegisterDownloaderFactory` 註冊 `DownloaderFactory`。
你可以在 [downloader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/downloader.go) 中找到這些介面。
## 上傳器介面
目前，只實現了一個 `GiteaLocalUploader`，因此我們僅通過此 `Uploader` 將下載的數據保存到本地 Gitea 實例。其他上傳器目前不支持。
目前，只實現了一個 `GiteaLocalUploader`，因此我們僅透過此 `Uploader` 將下載的資料保存到本地 Gitea 實例。其他上傳器目前不支援。
你可以在 [uploader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/uploader.go) 中找到這些介面。

107
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.23/development/oauth2-provider.md
View File

@@ -8,15 +8,15 @@ aliases:
# OAuth2 提供者
Gitea 支援作為 OAuth2 提供者，允許第三方應用程式在用戶同意的情況下訪問其資源。
Gitea 支援作為 OAuth2 提供者，允許第三方應用程式在使用者同意的情況下訪問其資源。
當作為 OAuth2 提供者時，Gitea 會針對相關的 OAuth2 應用程式驗證每個授權請求。此應用程式可以由個別用戶、組織管理員或 Gitea 實例管理員設置。
當作為 OAuth2 提供者時，Gitea 會針對相關的 OAuth2 應用程式驗證每個授權請求。此應用程式可以由個別使用者、組織管理員或 Gitea 實例管理員設定。
無論是誰配置的應用程式，第一次授權嘗試都會在用戶的網頁瀏覽器中打開一個新頁面，提示他們授權應用程式。
無論是誰設定的應用程式，第一次授權嘗試都會在使用者的網頁瀏覽器中打開一個新頁面，提示他們授權應用程式。
## 配置
## 設定
Gitea 中的 OAuth2 應用程式需要以下兩步配置：
Gitea 中的 OAuth2 應用程式需要以下兩步設定：
### Gitea 步驟 1
@@ -40,38 +40,39 @@ Gitea 中的 OAuth2 應用程式需要以下兩步配置：
- 憑證（客戶端 ID 和客戶端密鑰）
- 所需的範圍和聲明（預期由 Gitea 提供）
MinIO 的示例：
MinIO 的範例：
![](/development/minio_oauth2.png)
### Gitea 的用戶批准步驟 3
### Gitea 的使用者批准步驟 3
例如，使用 Gitea 帳戶登錄 MinIO...
例如，使用 Gitea 帳戶登入 MinIO...
![](/development/minio_login.png)
...在成功登錄後將顯示批准彈出窗口：
...在成功登入後將顯示批准彈出窗口：
![](/development/gitea_approval.png)
默認情況下，如果第三方設置範圍為 `openid`、`email`、`profile` 和 `groups`，並且用戶批准，應用程式將獲得用戶所有公共和私人資源（倉庫、問題、用戶信息等）的完全訪問權限。
預設情況下，如果第三方設定範圍為 `openid`、`email`、`profile` 和 `groups`，並且使用者批准，應用程式將獲得使用者所有公共和私人資源（儲存庫、問題、使用者資訊等）的完全存取權限。
> **注意：** 目前，如果期望限制訪問，設置 Gitea 中的 OAuth2 應用程式的管理員必須依賴第三方發送的範圍和知情用戶的批准決定。在應用程式設置過程中，管理員無法通過範圍設置限制訪問。
> **注意：** 目前，如果期望限制訪問，設定 Gitea 中的 OAuth2 應用程式的管理員必須依賴第三方發送的範圍和知情使用者的批准決定。在應用程式設定過程中，管理員無法通過範圍設定限制訪問。
<a id="scopes"></a>
## 細粒度範圍
從 v1.23 版本開始，Gitea 支援細粒度範圍，允許第三方請求更有限的訪問權限。這些範圍以前僅適用於[個人訪問令牌](#scopes)，使用戶能夠限制對特定 URL 路徑的訪問。
從 v1.23 版本開始，Gitea 支援細粒度範圍，允許第三方請求更有限的存取權限。這些範圍以前僅適用於[個人存取權杖](api-usage)，使使用者能夠限制對特定 URL 路徑的訪問。
範圍按高級 API 路徑分組，並進一步細化如下：
- `read`：`GET` 路徑
- `write`：`POST`、`PUT`、`PATCH` 和 `DELETE` 路徑（以及 `GET`）
例如，第三方可以請求最小訪問權限，允許 Gitea 作為簡單的 OpenID Connect (OIDC) 提供者。如果第三方僅添加 `public-only` 到 'openid'，不添加其他或任何組合的範圍 `email`、`userinfo` 或 `groups`，Gitea 將作為基本的單一登錄提供者。此配置僅提供用戶可以使用正確憑證登錄的驗證，僅提供基本信息，如用戶名、電子郵件和公共組織和團隊成員資格列表。
例如，第三方可以請求最小存取權限，允許 Gitea 作為簡單的 OpenID Connect (OIDC) 提供者。如果第三方僅添加 `public-only` 到 'openid'，不添加其他或任何組合的範圍 `email`、`userinfo` 或 `groups`，Gitea 將作為基本的單一登入提供者。此設定僅提供使用者可以使用正確憑證登入的驗證，僅提供基本資訊，如使用者名稱、電子郵件和公共組織和團隊成員資格列表。
當引入任何來自個人訪問令牌的細粒度範圍時，Gitea 將不允許完全訪問（如默認情況下）。相反，它將根據對倉庫、問題、ActivityPub、管理功能、組織、用戶、包或其他功能的讀寫權限構建細粒度訪問。
當引入任何來自個人存取權杖的細粒度範圍時，Gitea 將不允許完全訪問（如預設情況下）。相反，它將根據對儲存庫、問題、ActivityPub、管理功能、組織、使用者、包或其他功能的讀寫權限構建細粒度訪問。
> **注意：** 如果第三方添加任何範圍以外的 OIDC 範圍：`openid`、`email`、`profile` 和 `groups` 或已在個人訪問令牌中找到的範圍，範圍將回退到完全訪問，如 v1.23 之前的情況。
> **注意：** 如果第三方添加任何範圍以外的 OIDC 範圍：`openid`、`email`、`profile` 和 `groups` 或已在個人存取權杖中找到的範圍，範圍將回退到完全訪問，如 v1.23 之前的情況。
顯示給用戶的批准頁面顯示第三方請求的範圍列表。一旦批准，此決定將被記住。如果第三方在未來的請求中更改其請求的範圍，整個流程將失敗，需要重新授權。
顯示給使用者的批准頁面顯示第三方請求的範圍列表。一旦批准，此決定將被記住。如果第三方在未來的請求中更改其請求的範圍，整個流程將失敗，需要重新授權。
## 端點
@@ -79,22 +80,22 @@ MinIO 的示例：
| ----------------------- | ----------------------------------- |
| OpenID Connect 發現 | `/.well-known/openid-configuration` |
| 授權端點 | `/login/oauth/authorize` |
| 訪問令牌端點 | `/login/oauth/access_token` |
| OpenID Connect 用戶信息 | `/login/oauth/userinfo` |
| 存取權杖端點 | `/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)
- [程式碼交換的證明密鑰 (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/。
要作為第三方應用程式使用授權碼授權，需要通過設定中的“應用程式” (`/user/settings/applications`) 部分註冊新應用程式。要測試或調試，你可以使用網頁工具 https://oauthdebugger.com/。
## 範圍
Gitea 支援範圍訪問令牌，允許用戶限制令牌僅在選定的 URL 路徑上操作。範圍按高級 API 路徑分組，並進一步細化如下：
Gitea 支援範圍存取權杖，允許使用者限制令牌僅在選定的 URL 路徑上操作。範圍按高級 API 路徑分組，並進一步細化如下：
- `read`：`GET` 路徑
- `write`：`POST`、`PUT`、`PATCH` 和 `DELETE` 路徑（以及 `GET`）
@@ -103,38 +104,38 @@ Gitea 令牌範圍如下：
| 名稱 | 描述 |
| ----------------------------------------- | --------------------------------------------------------------------------------- |
| **（無範圍）** | 不支援。即使是公共倉庫也需要範圍。 |
| **（無範圍）** | 不支援。即使是公共儲存庫也需要範圍。 |
| **activitypub** | `activitypub` API 路徑：ActivityPub 相關操作。 |
| &nbsp;&nbsp;&nbsp; **read:activitypub** | 授予 ActivityPub 操作的讀取訪問權限。 |
| &nbsp;&nbsp;&nbsp; **write:activitypub** | 授予 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** | 授予管理操作的讀寫/刪除訪問權限，例如運行計劃任務或更新用戶帳戶。 |
| &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** | 授予問題操作的讀寫/刪除訪問權限，例如發布或編輯問題評論或附件，並更新里程碑。 |
| &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** | 授予用戶通知的讀寫/刪除訪問權限，例如將通知標記為已讀。 |
| **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** | 授予組織和團隊狀態的讀寫/刪除訪問權限，例如創建和更新團隊以及更新組織設置。 |
| &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** | 授予用戶操作的讀寫/刪除訪問權限，例如更新用戶倉庫訂閱、關注的用戶和用戶設置。 |
| &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 應用程式，因為我們認為這些應用程式是普遍有用的。
Gitea 在啟動時預設為以下服務建立 OAuth 應用程式，因為我們認為這些應用程式是普遍有用的。
| 應用程式 | 描述 | 客戶端 ID |
| --------------------------------------------------------------------------------- | ------------ | -------------------------------------- |
@@ -142,7 +143,7 @@ Gitea 在啟動時默認為以下服務創建 OAuth 應用程式，因為我們
| [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` 參數進行控制。
為防止意外行為，它們在 UI 中顯示為鎖定，其建立可以透過 `app.ini` 中的 `DEFAULT_APPLICATIONS` 參數進行控制。
## 客戶端類型
@@ -150,31 +151,31 @@ Gitea 支援機密和公共客戶端類型，[如 RFC 6749 定義](https://datat
對於公共客戶端，重定向 URI 為回送 IP 地址，例如 `http://127.0.0.1/` 允許任何端口。避免使用 `localhost`，[如 RFC 8252 建議](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3)。
## 示例
## 範例
### 機密客戶端
:::note
此示例不使用 PKCE。
此範例不使用 PKCE。
:::
1. 將用戶重定向到授權端點以獲取他們對訪問資源的同意：
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 攻擊。
可以透過在設定中註冊應用程式獲取 `CLIENT_ID`。`STATE` 是一個隨機字串，將在使用者授權後發送回你的應用程式。`state` 參數是可選的，但應該用於防止 CSRF 攻擊。
![授權頁面](/authorize.png)
現在將要求用戶授權你的應用程式。如果他們授權，用戶將被重定向到 `REDIRECT_URL`，例如：
現在將要求使用者授權你的應用程式。如果他們授權，使用者將被重定向到 `REDIRECT_URL`，例如：
```curl
https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
```
2. 使用重定向提供的 `code`，你可以請求新的應用程式和刷新令牌。訪問令牌端點接受 `application/json` 和 `application/x-www-form-urlencoded` 主體的 POST 請求，例如：
2. 使用重定向提供的 `code`，你可以請求新的應用程式和刷新令牌。存取權杖端點接受 `application/json` 和 `application/x-www-form-urlencoded` 主體的 POST 請求，例如：
```curl
POST https://[YOUR-GITEA-URL]/login/oauth/access_token
@@ -201,15 +202,15 @@ Gitea 支援機密和公共客戶端類型，[如 RFC 6749 定義](https://datat
}
```
`CLIENT_SECRET` 是為此應用程式生成的唯一密鑰。請注意，密鑰僅在你創建/註冊應用程式後可見，無法恢復。如果你丟失了密鑰，必須通過應用程式設置重新生成密鑰。
`CLIENT_SECRET` 是為此應用程式生成的唯一密鑰。請注意，密鑰僅在你建立/註冊應用程式後可見，無法恢復。如果你丟失了密鑰，必須通過應用程式設定重新生成密鑰。
`access_token` 請求中的 `REDIRECT_URI` 必須與 `authorize` 請求中的 `REDIRECT_URI` 匹配。
3. 使用 `access_token` 進行 [API 請求](development/api-usage.md#oauth2-provider) 以訪問用戶的資源。
3. 使用 `access_token` 進行 [API 請求](api-usage) 以訪問使用者的資源。
### 公共客戶端 (PKCE)
PKCE（代碼交換的證明密鑰）是 OAuth 流程的擴展，允許在不需要提供客戶端密鑰的情況下進行安全的憑證交換。
PKCE（程式碼交換的證明密鑰）是 OAuth 流程的擴展，允許在不需要提供客戶端密鑰的情況下進行安全的憑證交換。
**注意**：請確保你已將你的 OAuth 應用程式註冊為公共客戶端。