mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-06 18:10:36 +00:00
Add version v28 (#564)
<!-- cloudflare-preview --> Preview: https://pr-564.docs-gitea-com.pages.dev Reviewed-on: https://gitea.com/gitea/docs/pulls/564 Reviewed-by: bircni <[email protected]> Co-authored-by: Lunny Xiao <[email protected]>
This commit is contained in:
Lunny Xiao authored and 
bircni committed
1 parent
deb2f068d4
commit
ba60edbbda
338 files changed
+114457
-47
No files matched your search
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "開發",
|
||||
"position": 40,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/development",
|
||||
"title": "開發"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
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。您可以從 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中獲取更多設定相關資訊。
|
||||
|
||||
<a id="authentication"></a>
|
||||
<a id="通過-api-認證"></a>
|
||||
## 透過 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:[email protected]/api/v1/users/yourusername/tokens
|
||||
[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
|
||||
```
|
||||
|
||||
## 使用 Sudo 方式請求 API
|
||||
|
||||
此 API 允許管理員借用其他使用者身份進行 API 請求。只需在請求中指定查詢參數 `sudo=` 或是指定 header 中的 `Sudo:` 為需要使用的使用者 username 即可。
|
||||
@@ -0,0 +1,334 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
slug: "hacking-on-gitea"
|
||||
sidebar_position: 10
|
||||
aliases:
|
||||
- /zh-tw/hacking-on-gitea
|
||||
---
|
||||
|
||||
# 玩轉 Gitea
|
||||
|
||||
## 快速入門
|
||||
|
||||
要獲得快速工作的開發環境，您可以使用 Gitpod。
|
||||
|
||||
[](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/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 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 "[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
|
||||
```
|
||||
|
||||
為了能夠建立合併請求，應將分叉儲存庫添加為 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-tw.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。
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
date: "2023-05-25T17: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: "2023-05-25T17: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,128 @@
|
||||
---
|
||||
date: "2019-04-19:44:00+01:00"
|
||||
slug: "oauth2-provider"
|
||||
sidebar_position: 41
|
||||
aliases:
|
||||
- /zh-tw/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** | 完全控制所有儲存庫 |
|
||||
| **repo:status** | 授予對所有儲存庫中提交狀態的讀/寫存取權限 |
|
||||
| **public_repo** | 僅授予對公開儲存庫的讀/寫存取權限 |
|
||||
| **admin:repo_hook** | 授予對所有儲存庫的 Hooks 存取權限，該權限已包含在 `repo` 範圍中 |
|
||||
| **write:repo_hook** | 授予對儲存庫 Hooks 的讀/寫存取權限 |
|
||||
| **read:repo_hook** | 授予對儲存庫 Hooks 的只讀存取權限 |
|
||||
| **admin:org** | 授予對組織設定的完全存取權限 |
|
||||
| **write:org** | 授予對組織設定的讀/寫存取權限 |
|
||||
| **read:org** | 授予對組織設定的只讀存取權限 |
|
||||
| **admin:public_key** | 授予公鑰管理的完全存取權限 |
|
||||
| **write:public_key** | 授予對公鑰的讀/寫存取權限 |
|
||||
| **read:public_key** | 授予對公鑰的只讀存取權限 |
|
||||
| **admin:org_hook** | 授予對組織級別 Hooks 的完全存取權限 |
|
||||
| **admin:user_hook** | 授予對使用者級別 Hooks 的完全存取權限 |
|
||||
| **notification** | 授予對通知的完全存取權限 |
|
||||
| **user** | 授予對使用者個人資料資訊的完全存取權限 |
|
||||
| **read:user** | 授予對使用者個人資料的讀取權限 |
|
||||
| **user:email** | 授予對使用者電子電子郵件地址的讀取權限 |
|
||||
| **user:follow** | 授予存取權限以關注/取消關注使用者 |
|
||||
| **delete_repo** | 授予刪除儲存庫的權限 |
|
||||
| **package** | 授予對託管包的完全存取權限 |
|
||||
| **write:package** | 授予對包的讀/寫存取權限 |
|
||||
| **read:package** | 授予對包的讀取權限 |
|
||||
| **delete:package** | 授予對包的刪除權限 |
|
||||
| **admin:gpg_key** | 授予 GPG 密鑰管理的完全存取權限 |
|
||||
| **write:gpg_key** | 授予對 GPG 密鑰的讀/寫存取權限 |
|
||||
| **read:gpg_key** | 授予對 GPG 密鑰的只讀存取權限 |
|
||||
| **admin:application** | 授予應用程式管理的完全存取權限 |
|
||||
| **write:application** | 授予應用程式管理的讀/寫存取權限 |
|
||||
| **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 攻擊。
|
||||
|
||||
|
||||
|
||||
使用者將會被詢問是否授權給您的應用程式。如果他們同意了授權，使用者將會被重定向到 `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 請求](api-usage) 以讀寫使用者的資源。
|
||||
Reference in new issue
Block a user