nprasad2077/docs
1
1 Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-11-07 10:30:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add version v28 (#564)

Browse Source 
<!-- 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 2026-09-30 06:40:44 +00:00
1 parent deb2f068d4
commit ba60edbbda
338 files changed
+114457 -47
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "運維",
"position": 30,
"link": {
"type": "generated-index",
"slug": "/administration",
"title": "運維"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/adding-legal-pages.md
+34
View File
@@ -0,0 +1,34 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: adding-legal-pages
sidebar_position: 110
aliases:
- /zh-tw/adding-legal-pages
---
# 添加法律頁面
一些法域（例如歐盟）要求在網站上添加特定的法律頁面（例如隱私政策）。按照以下步驟將它們添加到你的 Gitea 實例中。
## 獲取頁面
Gitea 源程式碼附帶了範例頁面，位於 `contrib/service/sample-page` 目錄中。將它們複製到 `custom/public/assets/` 目錄下。例如，如果要添加隱私政策：
```
wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/service/sample-page/privacy.html.sample
```
現在，你需要編輯該頁面以滿足你的需求。特別是，你必須更改電子電子郵件地址、網址以及與 "Your Gitea Instance" 相關的引用，以匹配你的情況。
請務必不要放置會暗示 Gitea 專案對你的伺服器負責的一般服務條款或隱私聲明。
## 使其可見
建立或追加到 `/path/to/custom/templates/custom/extra_links_footer.tmpl` 文件中：
```go
<a class="item" href="{{AppSubUrl}}/assets/privacy.html">隱私政策</a>
```
重啟 Gitea 以查看更改。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/authentication.md
+301
View File
@@ -0,0 +1,301 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "authentication"
sidebar_position: 10
aliases:
- /zh-tw/authentication
---
# 認證
## 輕量級目錄訪問協議（Lightweight Directory Access Protocol，LDAP）
透過 BindDN 的 LDAP 和簡單認證方式 LDAP 共享以下欄位:
- 認證名稱 **(必選)**
- 分配給新授權方法的名稱。
- 主機名 **(必選)**
- LDAP 服務的主機地址.
- 例如:`mydomain.com`
- 端口號 **(必選)**
- LDAP 服務的端口號.
- 例如: LDAP `389`/ LDAPs `636`
- 安全協議 (可選)
- 連接 LDAP 伺服器時是否使用 TLS 協議。
- 管理員過濾規則 (可選)
- 一個 LDAP 過濾器，用於指定哪些使用者應該被賦予管理員特權。如果使用者帳戶符合過濾器條件，則該使用者將被授予管理員權限。
- 範例:`(objectClass=adminAccount)`
- 適用於 Microsoft Active Directory（AD）的範例:`memberOf=CN=admin-group,OU=example,DC=example,DC=org`
- 使用者名稱屬性（可選）
- 使用者 LDAP 記錄中包含使用者名稱稱的屬性。在第一次成功登入後，將使用指定的屬性值作為新的 Gitea 帳號名稱。若留空，則使用登入表單上提供的使用者名稱。
- 當提供的登入名與多個屬性匹配時，這一選項非常有用，但是隻有一個特定屬性應該用於 Gitea 帳號名稱，請參閱"使用者過濾器"。
- 範例:uid
- 適用於 Microsoft Active Directory（AD）的範例:`sAMAccountName`
- 名字屬性（可選）
- 使用者 LDAP 記錄中包含使用者名稱字的屬性。將用於填充他們的帳號資訊。
- 範例:givenName
- 姓氏屬性（可選）
- 使用者 LDAP 記錄中包含使用者姓氏的屬性。將用於填充他們的帳號資訊。
- 範例:`sn`
- 電子郵件屬性 **(必選)**
- 使用者 LDAP 記錄中包含使用者電子電子郵件地址的屬性。將用於填充他們的帳號資訊。
- 範例:`mail`
### LDAP(via BindDN)
需要額外設定以下欄位:
- 綁定 DN (可選)
- 搜索使用者時綁定到 LDAP 伺服器的 DN。這可以留空以執行匿名搜索。
- 範例: `cn=Search,dc=mydomain,dc=com`
- 綁定密碼 (可選)
- 上述指定的 Bind DN（綁定區別名）的密碼，如果有的話。注意：該密碼在伺服器上使用 SECRET_KEY 進行加密儲存。仍然建議確保 Bind DN 具有儘可能少的權限。
- 使用者搜索基準 **(必選)**
- 這是用於搜索使用者帳戶的 LDAP 基礎路徑.
- 範例: `ou=Users,dc=mydomain,dc=com`
- 使用者過濾規則 **(必選)**
- LDAP 過濾器聲明如何查找試圖進行身份驗證的使用者記錄
`%[1]s`匹配參數將替換為登入表單中給出的登入名
- 範例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
- 範例 for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
- 如需多次替換，應使用 `%[1]s`，例如在將提供的登入名與多個屬性（如使用者標識符、電子郵件甚至電話號碼）進行匹配時。
- 範例: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))`
- 啟用使用者同步
- 這個選項啟用了一個週期性任務，用於將 Gitea 使用者與 LDAP 伺服器進行同步。預設的同步週期是每 24 小時，
但您可以在 app.ini 文件中進行更改。
有關此部分的詳細說明，請參閱[sample
app.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
的*cron.sync_external_users* 部分的註釋。前面提到的*User Search Base*和*User Filter*
設定將限制哪些使用者可以使用 Gitea 以及哪些使用者將被同步。
在初始運行任務時，將根據給定的設定建立所有與 LDAP 匹配的使用者，因此在使用大型企業 LDAP 目錄時需要小心。
### LDAP(simple auth)
需要額外設定以下欄位:
- 使用者 DN **(必選)**
- 用作使用者 DN 的模板。匹配參數 `%s` 將替換為登入表單中的登入名。
- 範例: `cn=%s,ou=Users,dc=mydomain,dc=com`
- 範例: `uid=%s,ou=Users,dc=mydomain,dc=com`
- 使用者搜索基準 (可選)
- 使用者搜索基準聲明哪些使用者帳戶將被搜索.
- 範例: `ou=Users,dc=mydomain,dc=com`
- 使用者過濾規則 **(必選)**
- LDAP 過濾器聲明何時允許使用者登入
`%[1]s`匹配參數將替換為登入表單中給出的登入名。
- 範例: `(&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))`
- 範例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
### 使用 LDAP 驗證分組成員
使用以下欄位:
- 群組搜索基礎 DN(可選)
- 組使用的 LDAP DN。
- 範例: `ou=group,dc=mydomain,dc=com`
- 組名過濾器 (可選)
- LDAP 過濾器，聲明如何在上述 DN 中查找有效組。
- 範例: `(|(cn=gitea_users)(cn=admins))`
- 組中的使用者屬性 (可選)
- 組中列出了哪個使用者的 LDAP 屬性。
- 範例: `uid`
- 使用者組屬性 (可選)
- 哪個組的 LDAP 屬性包含一個高於使用者屬性名稱的數組。
- 範例: `memberUid`
## 可插拔式認證模組(Pluggable Authentication Module,PAM)
這個過程啟用了 PAM（Pluggable Authentication Modules）認證。使用者仍然可以透過使用者管理手動添加到系統中。
PAM 提供了一種機制，通過對使用者進行 PAM 認證來自動將其添加到當前資料庫中。為了與普通的 Linux 密碼一起使用，
運行 Gitea 的使用者還必須具有對`/etc/shadow`的讀取權限，以便在使用公鑰登入時檢查帳號的有效性。
**注意**:如果使用者已將 SSH 公鑰添加到 Gitea 中，使用這些密鑰可能會繞過登入檢查系統。因此，
如果您希望禁用使用 PAM 進行身份驗證的使用者，應該在 Gitea 中手動禁用該帳號，使用內置的使用者管理功能。
1. 設定和安裝準備.
- 建議您建立一個管理使用者.
- 建議取消自動註冊.
1. 一旦資料庫已初始化完成，使用新建立的管理員帳號登入.
1. 導航至使用者設定（右上角的圖標），然後選擇
`Site Administration` -> `Authentication Sources`, 並選擇
`Add Authentication Source`.
1. 填寫欄位如下:
- 認證類型:`PAM`。
- 名稱:任何有效的值都可以，如果您願意，可以使用"System Authentication"。
- PAM 服務名稱:從/etc/pam.d/目錄下選擇適用於所需認證的正確文件[^1]。
- PAM 電子郵件域:使用者認證時要附加的電子郵件後綴。例如，如果登入系統期望一個名為 gituse 的使用者，
並且將此欄位設定為 mail.com，那麼 Gitea 在驗證一個 GIT 實例的使用者時將期望 user emai 欄位為gituser@mail.com[^2]。
**Note**: PAM 支援通過[build-time flags](installation/from-source.md)添加,
而官方提供的二進制文件通常不會預設啟用此功能。PAM 需要確保系統上有必要的 libpam 動態庫，並且編譯器可以訪問必要的 PAM 開發頭文件。
[^1]:
例如，在 Debian "Bullseye"上使用標準 Linux 登入，可以使用`common-session-noninteractive`。這個值對於其他版本的 Debian，
包括 Ubuntu 和 Mint，可能也是有效的，請查閱您所使用發行版的文件以確認。
[^2]: **PAM 的必選項** 請注意:在上面的範例中，使用者將作為`gituser`而不是`[email protected]`登入到 Gitea 的 Web 介面。
## 簡單郵件傳輸協議(Simple Mail Transfer Protocol,SMTP)
此選項允許 Gitea 以 Gitea 使用者身份登入 SMTP 主機。請設定以下欄位:
- 身份驗證名稱 **(必選)**
- 分配給新授權方法的名稱
- SMTP 驗證類型 **(必選)**
- 用於連接 SMTP 主機的驗證類型，plain 或 login
- 主機名 **(必選)**
- SMTP 服務的主機地址
- 例如:`smtp.mydomain.com`
- 端口號 **(必選)**
- SMTP 服務的端口號
- 例如: `587`
- 允許的域名
- 如果使用公共 SMTP 主機或有多個域的 SMTP 主機，限制哪些域可以登入
限制哪些域可以登入。
- 範例: `gitea.com,mydomain.com,mydomain2.com`
- 強制使用 SMTPS
- 預設情況下將使用 SMTPS 連接到端口 465.如果您希望將 smtp 用於其他端口，自行設定
- 否則，如果伺服器提供' STARTTLS '擴展名，則將使用此擴展名
- 跳過 TLS 驗證
- 禁用 TLS 驗證身份.
- 該認證源處於激活狀態
- 啟用或禁用此身份驗證源
## FreeIPA
- 要使用 FreeIPA 憑據登入 Gitea，需要為 Gitea 建立一個綁定帳戶。
建立一個綁定帳戶:
- 在 FreeIPA 伺服器上建立一個 gitea.ldif 文件，並將`dc=example,dc=com`替換為您的`dn`，然後提供一個適當安全的密碼。
```sh
dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
changetype: add
objectclass: account
objectclass: simplesecurityobject
uid: gitea
userPassword: secure password
passwordExpirationTime: 20380119031407Z
nsIdleTimeout: 0
```
- 導入 LDIF 文件（如果需要，請將 localhost 更改為 IPA 伺服器）。系統會提示您輸入 Directory Manager 的密碼。:
```sh
ldapmodify -h localhost -p 389 -x -D \
"cn=Directory Manager" -W -f gitea.ldif
```
- 為`gitea_users`添加 IPA 組:
```sh
ipa group-add --desc="Gitea Users" gitea_users
```
- **提示**:對於 IPA 憑證錯誤，運行' kinit admin '並提供域管理帳戶密碼.
- 以管理員身份登入 Gitea，點擊 Admin Panel 下的`Authentication`。然後單擊`Add New Source`並填寫詳細資訊，更改所有適當的地方。
## SPNEGO with SSPI (Kerberos/NTLM, for Windows only)
Gitea 支援通過 Windows 內置的安全支援提供程式介面（Security Support Provider Interface，SSPI）實現 SPNEGO 單點登入認證（由 RFC4559 定義的方案），用於伺服器的 Web 部分。SSPI 僅在 Windows 環境中工作，即當伺服器和客戶端都在 Windows 操作系統上運行時。
在激活 SSPI 單點登入認證（SSO）之前，您需要準備您的環境:
- 在 Active Directory 中建立一個單獨的使用者帳號，gitea.exe 進程將在該帳號下運行（例如，在 domain.local 域下建立一個名為 user 的帳號:
- 為運行 gitea.exe 的主機建立一個服務主體名稱（Service Principal Name，SPN），其類別為 HTTP:
- 以特權域使用者（例如域管理員）的身份啟動“命令提示符”或“PowerShell”。
- 運行下面的命令，將 host.domain.local 替換為 Web 應用程式將運行的伺服器的完全限定域名（FQDN），將 domain\user 替換為在前一步中建立的帳號名稱:
```sh
setspn -A HTTP/host.domain.local domain\user
```
在遵循上述步驟之前，請確保您按照以下流程進行操作:
1. 用之前建立的使用者登入（如果已經登入，請先註銷）。
2. 確保在`custom/conf/app.ini`文件的`[server]`部分中，`ROOT_URL`設定為 Web 應用程式將運行的伺服器的完全限定域名（FQDN），與之前建立服務主體名稱時使用的一致（例如，`host.domain.local`）。
3. 啟動 Web 伺服器（運行 `gitea.exe web`）。
4. 在 `Site Administration -> Authentication Sources` 中添加一個 `SPNEGO with SSPI` 認證源，以啟用 SSPI 認證。
5. 在域中的客戶端計算機上，使用任何域使用者登入（與運行`gitea.exe`的伺服器不同）。
6. 如果您使用 Chrome 或 Edge 瀏覽器，請將 Web 應用程式的 URL 添加到“本地站點”（`Internet選項 -> 安全 -> 本地站點 -> 站點`）。
7. 啟動 Chrome 或 Edge 瀏覽器，導航到 Gitea 的 FQDN URL（例如，`http://host.domain.local:3000`）。
8. 在控制面板中點擊“Sign In”按鈕，然後選擇 SSPI，將會自動使用當前登入到計算機的使用者進行登入。
9. 如果無法正常工作，請確保:
- 您不是在運行`gitea.exe`的同一臺伺服器上運行 Web 瀏覽器。應該在與伺服器不同的域加入計算機（客戶端）上運行 Web 瀏覽器。如果客戶端和伺服器都在同一臺計算機上運行，則 NTLM 將優先於 Kerberos。
- 主機上只有一個`HTTP/...`的 SPN。
- SPN 中只包含主機名，不包含端口號。
- 將 Web 應用程式的 URL 添加到"本地站點"。
- 伺服器和客戶端的時鐘差異不超過 5 分鐘（取決於組策略）。
- 在 Internet Explorer 中啟用了"整合 Windows 身份驗證"（在"高級設定"下）。
遵循這些步驟，您應該能夠成功啟用和使用 SSPI 單點登入認證（SSO）。
## 反向代理認證
Gitea 支援通過讀取反向代理傳遞的 HTTP 頭中的登入名或者 email 地址來支援反向代理來認證。預設是不啟用的，你可以用以下設定啟用。
```ini
[service]
ENABLE_REVERSE_PROXY_AUTHENTICATION = true
```
預設的登入使用者名稱的 HTTP 頭是 `X-WEBAUTH-USER`，你可以透過修改 `REVERSE_PROXY_AUTHENTICATION_USER` 來變更它。如果使用者不存在，可以自動建立使用者，當然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 來啟用它。
預設的登入使用者 Email 的 HTTP 頭是 `X-WEBAUTH-EMAIL`，你可以透過修改 `REVERSE_PROXY_AUTHENTICATION_EMAIL` 來變更它。如果使用者不存在，可以自動建立使用者，當然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 來啟用它。你也可以透過修改 `ENABLE_REVERSE_PROXY_EMAIL` 來啟用或停用這個 HTTP 頭。
如果設定了 `ENABLE_REVERSE_PROXY_FULL_NAME=true`，則使用者的全名會從 `X-WEBAUTH-FULLNAME` 讀取，這樣在自動建立使用者時將使用這個欄位作為使用者全名，你也可以透過修改 `REVERSE_PROXY_AUTHENTICATION_FULL_NAME` 來變更 HTTP 頭。
你也可以透過修改 `REVERSE_PROXY_TRUSTED_PROXIES` 來設定反向代理的 IP 地址範圍，加強安全性，預設值是 `127.0.0.0/8,::1/128`。 通過 `REVERSE_PROXY_LIMIT`， 可以設定最多信任幾級反向代理。
你可以透過以下設定為 API 啟用此認證方法：
```ini
[service]
ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true
```
:::note
當此方法用於 API 時，反向代理負責處理 CSRF 保護。
:::
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/backup-and-restore.md
+146
View File
@@ -0,0 +1,146 @@
---
date: "2018-06-06T09:33:00+08:00"
slug: "backup-and-restore"
sidebar_position: 11
aliases:
- /zh-tw/backup-and-restore
---
# 備份與恢復
Gitea 已經實現了 `dump` 命令可以用來備份所有需要的文件到一個 zip 壓縮文件。該壓縮文件可以被用來進行資料恢復。
## 備份一致性
為了確保 Gitea 實例的一致性，在備份期間必須關閉它。
Gitea 包括資料庫、文件和 Git 儲存庫，當它被使用時所有這些都會發生變化。例如，當遷移正在進行時，在資料庫中建立一個事務，而 Git 儲存庫正在被複制。如果備份發生在遷移的中間，Git 儲存庫可能是不完整的，儘管資料庫聲稱它是完整的，因為它是在之後被轉儲的。避免這種競爭條件的唯一方法是在備份期間停止 Gitea 實例。
## 備份命令 (`dump`)
先轉到 git 使用者的權限: `su git`. 再 Gitea 目錄運行 `./gitea dump`。一般會顯示類似如下的輸出：
```
2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
2016/12/27 22:32:22 Dumping database...
2016/12/27 22:32:22 Packing dump files...
2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
2016/12/27 22:32:34 Finish dumping in file gitea-dump-1482906742.zip
```
最後生成的 `gitea-dump-1482906742.zip` 文件將會包含如下內容：
- `app.ini` - 如果原先儲存在預設的 custom/ 目錄之外，則是設定文件的可選副本
- `custom/` - 所有保存在 `custom/` 目錄下的設定和自訂的文件。
- `data/` - 資料目錄（APP_DATA_PATH），如果使用文件會話，則不包括會話。該目錄包括 `attachments`、`avatars`、`lfs`、`indexers`、如果使用 SQLite 則包括 SQLite 文件。
- `repos/` - 儲存庫目錄的完整副本。
- `gitea-db.sql` - 資料庫 dump 出來的 SQL。
- `log/` - Logs 文件，如果用作遷移不是必須的。
中間備份文件將會在臨時目錄進行建立，如果您要重新指定臨時目錄，可以用 `--tempdir` 參數，或者用 `TMPDIR` 環境變量。
## 備份資料庫
`gitea dump` 建立的 SQL 轉儲使用 XORM，Gitea 管理員可能更喜歡使用本地的 MySQL 和 PostgreSQL 轉儲工具。使用 XORM 轉儲資料庫時仍然存在一些問題，可能會導致在嘗試恢復時出現問題。
```sh
# mysql
mysqldump -u$USER -p$PASS --database $DATABASE > gitea-db.sql
# postgres
pg_dump -U $USER $DATABASE > gitea-db.sql
```
### 使用 Docker （`dump`）
在使用 Docker 時，使用 `dump` 命令有一些注意事項。
必須以 `gitea/conf/app.ini` 中指定的 `RUN_USER = <OS_USERNAME>` 執行該命令；並且，為了讓備份文件夾的壓縮過程能夠順利執行，`docker exec` 命令必須在 `--tempdir` 內部執行。
範例：
```none
docker exec -u <OS_USERNAME> -it -w <--tempdir> $(docker ps -qf 'name=^<NAME_OF_DOCKER_CONTAINER>$') bash -c '/usr/local/bin/gitea dump -c </path/to/app.ini>'
```
\*注意：`--tempdir` 指的是 Gitea 使用的 Docker 環境的臨時目錄；如果您沒有指定自訂的 `--tempdir`，那麼 Gitea 將使用 `/tmp` 或 Docker 容器的 `TMPDIR` 環境變量。對於 `--tempdir`，請相應調整您的 `docker exec` 命令選項。
結果應該是一個文件，儲存在指定的 `--tempdir` 中，類似於：`gitea-dump-1482906742.zip`
## 恢復命令 (`restore`)
當前還沒有恢復命令，恢復需要人工進行。主要是把文件和資料庫進行恢復。
例如：
```sh
unzip gitea-dump-1610949662.zip
cd gitea-dump-1610949662
mv app.ini /etc/gitea/conf/app.ini
mv data/* /var/lib/gitea/data/
mv log/* /var/lib/gitea/log/
mv repos/* /var/lib/gitea/repositories/
chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
# mysql
mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE <gitea-db.sql
# sqlite3
sqlite3 $DATABASE_PATH <gitea-db.sql
# postgres
psql -U $USER -d $DATABASE < gitea-db.sql
service gitea restart
```
如果安裝方式發生了變化（例如 二進制 -> Docker），或者 Gitea 安裝到了與之前安裝不同的目錄，則需要重新生成儲存庫 Git 鉤子。
在 Gitea 運行時，並從 Gitea 二進制文件所在的目錄執行：`./gitea admin regenerate hooks`
這樣可以確保儲存庫 Git 鉤子中的應用程式和設定文件路徑與當前安裝一致。如果這些路徑沒有更新，儲存庫的 `push` 操作將失敗。
### 使用 Docker (`restore`)
在基於 Docker 的 Gitea 實例中，也沒有恢復命令的支援。恢復過程與前面描述的步驟相同，但路徑不同。
範例：
```sh
# 在容器中打開 bash 會話
docker exec --user git -it 2a83b293548e bash
# 在容器內解壓您的備份文件
unzip gitea-dump-1610949662.zip
cd gitea-dump-1610949662
# 恢復 Gitea 數據
mv data/* /data/gitea
# 恢復倉庫本身
mv repos/* /data/git/repositories/
# 調整文件權限
chown -R git:git /data
# 重新生成 Git 鉤子
/usr/local/bin/gitea -c '/data/gitea/conf/app.ini' admin regenerate hooks
```
Gitea 容器中的預設使用者是 `git`（1000:1000）。請用您的 Gitea 容器 ID 或名稱替換 `2a83b293548e`。
### 使用 Docker-rootless (`restore`)
在 Docker-rootless 容器中的恢復工作流程只是要使用的目錄不同：
```sh
# 在容器中打開 bash 會話
docker exec --user git -it 2a83b293548e bash
# 在容器內解壓您的備份文件
unzip gitea-dump-1610949662.zip
cd gitea-dump-1610949662
# 恢復 app.ini
mv data/conf/app.ini /etc/gitea/app.ini
# 恢復 Gitea 數據
mv data/* /var/lib/gitea
# 恢復倉庫本身
mv repos/* /var/lib/gitea/git/repositories
# 調整文件權限
chown -R git:git /etc/gitea/app.ini /var/lib/gitea
# 重新生成 Git 鉤子
/usr/local/bin/gitea -c '/etc/gitea/app.ini' admin regenerate hooks
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/cmd-embedded.md
+93
View File
@@ -0,0 +1,93 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "cmd-embedded"
sidebar_position: 20
aliases:
- /zh-tw/cmd-embedded
---
# 嵌入資源提取工具
Gitea 的可執行文件包含了運行所需的所有資源：模板、圖片、樣式表和翻譯文件。你可以透過在 `custom` 目錄下的相應路徑中放置替換文件來覆蓋其中的任何資源（詳見 [自訂 Gitea 設定](../administration/customizing-gitea.md)）。
要獲取嵌入資源的副本以進行編輯，可以使用 CLI 中的 `embedded` 命令，通過操作系統的 shell 執行。
**注意：** 嵌入資源提取工具包含在 Gitea 1.12 及以上版本中。
## 資源列表
要列出嵌入在 Gitea 可執行文件中的資源，請使用以下語法：
```sh
gitea embedded list [--include-vendored] [patterns...]
```
`--include-vendored` 標誌使命令包括被供應的文件，這些文件通常被排除在外；即來自外部庫的文件，這些文件是 Gitea 所需的（例如 [octicons](https://octicons.github.com/) 等）。
可以提供一系列文件搜索模式。Gitea 使用 [gobwas/glob](https://github.com/gobwas/glob) 作為其 glob 語法。以下是一些範例：
- 列出所有模板文件，無論在哪個虛擬目錄下：`**.tmpl`
- 列出所有郵件模板文件：`templates/mail/**.tmpl`
列出 `public/assets/img` 目錄下的所有文件：`public/assets/img/**`
不要忘記為模式使用引號，因為空格、`*` 和其他字符可能對命令行解釋器有特殊含義。
如果未提供模式，則列出所有文件。
### 範例：列出所有嵌入文件
列出所有路徑中包含 `openid` 的嵌入文件：
```sh
$ gitea embedded list '**openid**'
public/assets/img/auth/openid_connect.svg
public/assets/img/openid-16x16.png
templates/user/auth/finalize_openid.tmpl
templates/user/auth/signin_openid.tmpl
templates/user/auth/signup_openid_connect.tmpl
templates/user/auth/signup_openid_navbar.tmpl
templates/user/auth/signup_openid_register.tmpl
templates/user/settings/security_openid.tmpl
```
## 提取資源
要提取嵌入在 Gitea 可執行文件中的資源，請使用以下語法：
```sh
gitea [--config {file}] embedded extract [--destination {dir}|--custom] [--overwrite|--rename] [--include-vendored] {patterns...}
```
`--config` 選項用於告知 Gitea `app.ini` 設定文件的位置（如果不在預設位置）。此選項僅在使用 `--custom` 標誌時使用。
`--destination` 選項用於指定提取文件的目標目錄。預設為當前目錄。
`--custom` 標誌告知 Gitea 直接將文件提取到 `custom` 目錄中。為使其正常工作，該命令需要知道 `app.ini` 設定文件的位置（通過 `--config` 指定），並且根據設定的不同，需要從 Gitea 通常啟動的目錄運行。有關詳細資訊，請參閱 [自訂 Gitea 設定](../administration/customizing-gitea.md)。
`--overwrite` 標誌允許覆蓋目標目錄中的任何現有文件。
`--rename` 標誌告知 Gitea 將目標目錄中的任何現有文件重命名為 `filename.bak`。之前的 `.bak` 文件將被覆蓋。
至少需要提供一個文件搜索模式；有關模式的語法和範例，請參閱上述 `list` 子命令。
### 重要提示
請確保**只提取需要自訂的文件**。位於 `custom` 目錄中的文件不會受到 Gitea 的升級過程的影響。當 Gitea 升級到新版本（通過替換可執行文件）時，許多嵌入文件將發生變化。Gitea 將尊重並使用在 `custom` 目錄中找到的任何文件，即使這些文件是舊的和不相容的。
### 範例：提取郵件模板
將郵件模板提取到臨時目錄：
```sh
$ mkdir tempdir
$ gitea embedded extract --destination tempdir 'templates/mail/**.tmpl'
Extracting to tempdir:
tempdir/templates/mail/auth/activate.tmpl
tempdir/templates/mail/auth/activate_email.tmpl
tempdir/templates/mail/auth/register_notify.tmpl
tempdir/templates/mail/auth/reset_passwd.tmpl
tempdir/templates/mail/issue/assigned.tmpl
tempdir/templates/mail/issue/default.tmpl
tempdir/templates/mail/notify/collaborator.tmpl
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/command-line.md
+534
View File
@@ -0,0 +1,534 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "command-line"
sidebar_position: 1
aliases:
- /zh-tw/command-line
---
# 命令行
## 用法
`gitea [全域選項] 命令 [命令或全域選項] [參數...]`
## 全域選項
所有全域選項均可被放置在命令級別。
- `--help`，`-h`：顯示幫助文本並退出。可選。
- `--version`，`-v`：顯示版本資訊並退出。可選。 (範例：`Gitea version 1.1.0+218-g7b907ed built with: bindata, sqlite`)。
- `--custom-path path`，`-C path`：Gitea 自訂文件夾的路徑。可選。 (預設值：`AppWorkPath`/custom 或 `$GITEA_CUSTOM`)。
- `--config path`，`-c path`：Gitea 設定文件的路徑。可選。 (預設值：`custom`/conf/app.ini)。
- `--work-path path`，`-w path`：Gitea 的 `AppWorkPath`。可選。 (預設值：LOCATION_OF_GITEA_BINARY 或 `$GITEA_WORK_DIR`)
注意：預設的 custom-path、config 和 work-path 也可以在構建時更改（如果需要）。
## 命令
### web
啟動伺服器：
- 選項：
- `--port number`，`-p number`：端口號。可選。 (預設值：3000)。覆蓋設定文件中的設定。
- `--install-port number`：運行安裝頁面的端口號。可選。 (預設值：3000)。覆蓋設定文件中的設定。
- `--pid path`，`-P path`：Pid 文件的路徑。可選。
- `--quiet`，`-q`：只在控制檯上輸出 Fatal 日誌，用於在設定日誌之前發出的日誌。
- `--verbose`：在控制檯上輸出跟蹤日誌，用於在設定日誌之前發出的日誌。
- 範例：
- `gitea web`
- `gitea web --port 80`
- `gitea web --config /etc/gitea.ini --pid /some/custom/gitea.pid`
- 注意：
- Gitea 不應以 root 使用者身份運行。要綁定到低於 1024 的端口，您可以在 Linux 上使用 setcap 命令：`sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea`。每次更新 Gitea 都需要重新執行此操作。
### admin
管理員操作：
- 命令：
- `user`：
- `list`：
- 選項：
- `--admin`：僅列出管理員使用者。可選。
- 描述：列出所有現有使用者。
- 範例：
- `gitea admin user list`
- `delete`：
- 選項：
- `--email`：要刪除的使用者的電子郵件。
- `--username`：要刪除的使用者的使用者名稱。
- `--id`：要刪除的使用者的 ID。
- 必須提供 `--id`、`--username` 或 `--email` 中的一個。如果提供多個，則所有條件必須匹配。
- 範例：
- `gitea admin user delete --id 1`
- `create`：
- 選項：
- `--name value`：使用者名稱。必填。自 Gitea 1.9.0 版本起，請改用 `--username` 標誌。
- `--username value`：使用者名稱。必填。Gitea 1.9.0 新增。
- `--password value`：密碼。必填。
- `--email value`：郵箱。必填。
- `--admin`：如果提供此選項，將建立一個管理員使用者。可選。
- `--access-token`：如果提供，將為使用者建立存取權杖。可選。（預設值：false）。
- `--must-change-password`：如果提供，建立的使用者將在初始登入後需要選擇一個新密碼。可選。（預設值：true）。
- `--random-password`：如果提供，將使用隨機生成的密碼作為建立使用者的密碼。`--password` 的值將被忽略。可選。
- `--random-password-length`：如果提供，將用於設定隨機生成密碼的長度。可選。（預設值：12）
- 範例：
- `gitea admin user create --username myname --password asecurepassword --email [email protected]`
- `change-password`：
- 選項：
- `--username value`，`-u value`：使用者名稱。必填。
- `--password value`，`-p value`：新密碼。必填。
- 範例：
- `gitea admin user change-password --username myname --password asecurepassword`
- `must-change-password`：
- 參數：
- `[username...]`：需要更改密碼的使用者
- 選項：
- `--all`，`-A`：強制所有使用者更改密碼
- `--exclude username`，`-e username`：排除給定的使用者。可以多次設定。
- `--unset`：撤銷對給定使用者的強制密碼更改
- `regenerate`：
- 選項：
- `hooks`：重新生成所有儲存庫的 Git Hooks。
- `keys`：重新生成 authorized_keys 文件。
- 範例：
- `gitea admin regenerate hooks`
- `gitea admin regenerate keys`
- `auth`：
- `list`：
- 描述：列出所有存在的外部認證源。
- 範例：
- `gitea admin auth list`
- `delete`：
- 選項：
- `--id`：要刪除的源的 ID。必填。
- 範例：
- `gitea admin auth delete --id 1`
- `add-oauth`：
- 選項：
- `--name`：應用程式名稱。
- `--provider`：OAuth2 提供者。
- `--key`：客戶端 ID（Key）。
- `--secret`：客戶端密鑰。
- `--auto-discover-url`：OpenID Connect 自動發現 URL（僅在使用 OpenID Connect 作為提供程式時需要）。
- `--use-custom-urls`：在 GitLab/GitHub OAuth 端點上使用自訂 URL。
- `--custom-tenant-id`：在 OAuth 端點上使用自訂租戶 ID。
- `--custom-auth-url`：使用自訂授權 URL（GitLab/GitHub 的選項）。
- `--custom-token-url`：使用自訂令牌 URL（GitLab/GitHub 的選項）。
- `--custom-profile-url`：使用自訂設定文件 URL（GitLab/GitHub 的選項）。
- `--custom-email-url`：使用自訂電子郵件 URL（GitHub 的選項）。
- `--icon-url`：OAuth2 登入源的自訂圖標 URL。
- `--skip-local-2fa`：允許源覆蓋本地 2FA。（可選）
- `--scopes`：請求此 OAuth2 源的附加範圍。（可選）
- `--required-claim-name`：必須設定的聲明名稱，以允許使用者使用此源登入。（可選）
- `--required-claim-value`：必須設定的聲明值，以允許使用者使用此源登入。（可選）
- `--group-claim-name`：提供此源的組名的聲明名稱。（可選）
- `--admin-group`：管理員使用者的組聲明值。（可選）
- `--restricted-group`：受限使用者的組聲明值。（可選）
- `--group-team-map`：組與組織團隊之間的 JSON 映射。（可選）
- `--group-team-map-removal`：根據組自動激活團隊成員資格的刪除。（可選）
- 範例：
- `gitea admin auth add-oauth --name external-github --provider github --key OBTAIN_FROM_SOURCE --secret OBTAIN_FROM_SOURCE`
- `update-oauth`：
- 選項：
- `--id`：要更新的源的 ID。必填。
- `--name`：應用程式名稱。
- `--provider`：OAuth2 提供者。
- `--key`：客戶端 ID（Key）。
- `--secret`：客戶端密鑰。
- `--auto-discover-url`：OpenID Connect 自動發現 URL（僅在使用 OpenID Connect 作為提供程式時需要）。
- `--use-custom-urls`：在 GitLab/GitHub OAuth 端點上使用自訂 URL。
- `--custom-tenant-id`：在 OAuth 端點上使用自訂租戶 ID。
- `--custom-auth-url`：使用自訂授權 URL（GitLab/GitHub 的選項）。
- `--custom-token-url`：使用自訂令牌 URL（GitLab/GitHub 的選項）。
- `--custom-profile-url`：使用自訂設定文件 URL（GitLab/GitHub 的選項）。
- `--custom-email-url`：使用自訂電子郵件 URL（GitHub 的選項）。
- `--icon-url`：OAuth2 登入源的自訂圖標 URL。
- `--skip-local-2fa`：允許源覆蓋本地 2FA。（可選）
- `--scopes`：請求此 OAuth2 源的附加範圍。
- `--required-claim-name`：必須設定的聲明名稱，以允許使用者使用此源登入。（可選）
- `--required-claim-value`：必須設定的聲明值，以允許使用者使用此源登入。（可選）
- `--group-claim-name`：提供此源的組名的聲明名稱。（可選）
- `--admin-group`：管理員使用者的組聲明值。（可選）
- `--restricted-group`：受限使用者的組聲明值。（可選）
- 範例：
- `gitea admin auth update-oauth --id 1 --name external-github-updated`
- `add-smtp`：
- 選項：
- `--name`：應用程式名稱。必填。
- `--auth-type`：SMTP 認證類型（PLAIN/LOGIN/CRAM-MD5）。預設為 PLAIN。
- `--host`：SMTP 主機。必填。
- `--port`：SMTP 端口。必填。
- `--force-smtps`：SMTPS 始終在端口 465 上使用。設定此選項以強制在其他端口上使用 SMTPS。
- `--skip-verify`：跳過 TLS 驗證。
- `--helo-hostname`：發送 HELO 時使用的主機名。留空以發送當前主機名。
- `--disable-helo`：禁用 SMTP helo。
- `--allowed-domains`：留空以允許所有域。使用逗號（','）分隔多個域。
- `--skip-local-2fa`：跳過 2FA 登入。
- `--active`：啟用此認證源。
備註：
`--force-smtps`、`--skip-verify`、`--disable-helo`、`--skip-local-2fs` 和 `--active` 選項可以採用以下形式使用：
- `--option`、`--option=true` 以啟用選項
- `--option=false` 以禁用選項
如果未指定這些選項，則在 `update-smtp` 中不會更改值，或者在 `add-smtp` 中將使用預設的 `false` 值。
- 範例：
- `gitea admin auth add-smtp --name ldap --host smtp.mydomain.org --port 587 --skip-verify --active`
- `update-smtp`：
- 選項：
- `--id`：要更新的源的 ID。必填。
- 其他選項與 `add-smtp` 共享
- 範例：
- `gitea admin auth update-smtp --id 1 --host smtp.mydomain.org --port 587 --skip-verify=false`
- `gitea admin auth update-smtp --id 1 --active=false`
- `add-ldap`：添加新的 LDAP（通過 Bind DN）認證源
- 選項：
- `--name value`：認證名稱。必填。
- `--not-active`：停用認證源。
- `--security-protocol value`：安全協議名稱。必填。
- `--skip-tls-verify`：禁用 TLS 驗證。
- `--host value`：LDAP 伺服器的地址。必填。
- `--port value`：連接到 LDAP 伺服器時使用的端口。必填。
- `--user-search-base value`：使用者帳戶將在其中搜索的 LDAP 基礎路徑。必填。
- `--user-filter value`：聲明如何查找試圖進行身份驗證的使用者記錄的 LDAP 過濾器。必填。
- `--admin-filter value`：指定是否應授予使用者管理員特權的 LDAP 過濾器。
- `--restricted-filter value`：指定是否應將使用者設定為受限狀態的 LDAP 過濾器。
- `--username-attribute value`：使用者 LDAP 記錄中包含使用者名稱的屬性。
- `--firstname-attribute value`：使用者 LDAP 記錄中包含使用者名稱字的屬性。
- `--surname-attribute value`：使用者 LDAP 記錄中包含使用者姓氏的屬性。
- `--email-attribute value`：使用者 LDAP 記錄中包含使用者電子電子郵件地址的屬性。必填。
- `--public-ssh-key-attribute value`：使用者 LDAP 記錄中包含使用者公共 SSH 密鑰的屬性。
- `--avatar-attribute value`：使用者 LDAP 記錄中包含使用者頭像的屬性。
- `--bind-dn value`：在搜索使用者時綁定到 LDAP 伺服器的 DN。
- `--bind-password value`：綁定 DN 的密碼（如果有）。
- `--attributes-in-bind`：在綁定 DN 上下文中獲取屬性。
- `--synchronize-users`：啟用使用者同步。
- `--page-size value`：搜索頁面大小。
- 範例：
- `gitea admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))" --email-attribute mail`
- `update-ldap`：更新現有的 LDAP（通過 Bind DN）認證源
- 選項：
- `--id value`：認證源的 ID。必填。
- `--name value`：認證名稱。
- `--not-active`：停用認證源。
- `--security-protocol value`：安全協議名稱。
- `--skip-tls-verify`：禁用 TLS 驗證。
- `--host value`：LDAP 伺服器的地址。
- `--port value`：連接到 LDAP 伺服器時使用的端口。
- `--user-search-base value`：使用者帳戶將在其中搜索的 LDAP 基礎路徑。
- `--user-filter value`：聲明如何查找試圖進行身份驗證的使用者記錄的 LDAP 過濾器。
- `--admin-filter value`：指定是否應授予使用者管理員特權的 LDAP 過濾器。
- `--restricted-filter value`：指定是否應將使用者設定為受限狀態的 LDAP 過濾器。
- `--username-attribute value`：使用者 LDAP 記錄中包含使用者名稱的屬性。
- `--firstname-attribute value`：使用者 LDAP 記錄中包含使用者名稱字的屬性。
- `--surname-attribute value`：使用者 LDAP 記錄中包含使用者姓氏的屬性。
- `--email-attribute value`：使用者 LDAP 記錄中包含使用者電子電子郵件地址的屬性。
- `--public-ssh-key-attribute value`：使用者 LDAP 記錄中包含使用者公共 SSH 密鑰的屬性。
- `--avatar-attribute value`：使用者 LDAP 記錄中包含使用者頭像的屬性。
- `--bind-dn value`：在搜索使用者時綁定到 LDAP 伺服器的 DN。
- `--bind-password value`：綁定 DN 的密碼（如果有）。
- `--attributes-in-bind`：在綁定 DN 上下文中獲取屬性。
- `--synchronize-users`：啟用使用者同步。
- `--page-size value`：搜索頁面大小。
- 範例：
- `gitea admin auth update-ldap --id 1 --name "my ldap auth source"`
- `gitea admin auth update-ldap --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
- `add-ldap-simple`：添加新的 LDAP（簡單身份驗證）認證源
- 選項：
- `--name value`：認證名稱。必填。
- `--not-active`：停用認證源。
- `--security-protocol value`：安全協議名稱。必填。
- `--skip-tls-verify`：禁用 TLS 驗證。
- `--host value`：LDAP 伺服器的地址。必填。
- `--port value`：連接到 LDAP 伺服器時使用的端口。必填。
- `--user-search-base value`：使用者帳戶將在其中搜索的 LDAP 基礎路徑。
- `--user-filter value`：聲明如何查找試圖進行身份驗證的使用者記錄的 LDAP 過濾器。必填。
- `--admin-filter value`：指定是否應授予使用者管理員特權的 LDAP 過濾器。
- `--restricted-filter value`：指定是否應將使用者設定為受限狀態的 LDAP 過濾器。
- `--username-attribute value`：使用者 LDAP 記錄中包含使用者名稱的屬性。
- `--firstname-attribute value`：使用者 LDAP 記錄中包含使用者名稱字的屬性。
- `--surname-attribute value`：使用者 LDAP 記錄中包含使用者姓氏的屬性。
- `--email-attribute value`：使用者 LDAP 記錄中包含使用者電子電子郵件地址的屬性。必填。
- `--public-ssh-key-attribute value`：使用者 LDAP 記錄中包含使用者公共 SSH 密鑰的屬性。
- `--avatar-attribute value`：使用者 LDAP 記錄中包含使用者頭像的屬性。
- `--user-dn value`：使用者的 DN。必填。
- 範例：
- `gitea admin auth add-ldap-simple --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-dn "cn=%s,ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(cn=%s))" --email-attribute mail`
- `update-ldap-simple`：更新現有的 LDAP（簡單身份驗證）認證源
- 選項：
- `--id value`：認證源的 ID。必填。
- `--name value`：認證名稱。
- `--not-active`：停用認證源。
- `--security-protocol value`：安全協議名稱。
- `--skip-tls-verify`：禁用 TLS 驗證。
- `--host value`：LDAP 伺服器的地址。
- `--port value`：連接到 LDAP 伺服器時使用的端口。
- `--user-search-base value`：使用者帳戶將在其中搜索的 LDAP 基礎路徑。
- `--user-filter value`：聲明如何查找試圖進行身份驗證的使用者記錄的 LDAP 過濾器。
- `--admin-filter value`：指定是否應授予使用者管理員特權的 LDAP 過濾器。
- `--restricted-filter value`：指定是否應將使用者設定為受限狀態的 LDAP 過濾器。
- `--username-attribute value`：使用者 LDAP 記錄中包含使用者名稱的屬性。
- `--firstname-attribute value`：使用者 LDAP 記錄中包含使用者名稱字的屬性。
- `--surname-attribute value`：使用者 LDAP 記錄中包含使用者姓氏的屬性。
- `--email-attribute value`：使用者 LDAP 記錄中包含使用者電子電子郵件地址的屬性。
- `--public-ssh-key-attribute value`：使用者 LDAP 記錄中包含使用者公共 SSH 密鑰的屬性。
- `--avatar-attribute value`：使用者 LDAP 記錄中包含使用者頭像的屬性。
- `--user-dn value`：使用者的 DN。
- 範例：
- `gitea admin auth update-ldap-simple --id 1 --name "my ldap auth source"`
- `gitea admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
### cert
生成自簽名的 SSL 證書。將輸出到當前目錄下的`cert.pem`和`key.pem`文件中，並且會覆蓋任何現有文件。
- 選項：
- `--host value`：逗號分隔的主機名和 IP 地址列表，此證書適用於這些主機。支援使用通配符。必填。
- `--ecdsa-curve value`：用於生成密鑰的 ECDSA 曲線。可選。有效選項為 P224、P256、P384、P521。
- `--rsa-bits value`：要生成的 RSA 密鑰的大小。可選。如果設定了--ecdsa-curve，則忽略此選項。（預設值：3072）。
- `--start-date value`：證書的建立日期。可選。（格式：`Jan 1 15:04:05 2011`）。
- `--duration value`：證書有效期。可選。（預設值：8760h0m0s）
- `--ca`：如果提供此選項，則證書將生成自己的證書頒發機構。可選。
- 範例：
- `gitea cert --host git.example.com,example.com,www.example.com --ca`
### dump
將所有文件和資料庫導出到一個 zip 文件中。輸出文件將保存在當前目錄下，類似於`gitea-dump-1482906742.zip`。
- 選項：
- `--file name`，`-f name`：指定要建立的導出文件的名稱。可選。（預設值：gitea-dump-[timestamp].zip）。
- `--tempdir path`，`-t path`：指定臨時目錄的路徑。可選。（預設值：/tmp）。
- `--skip-repository`，`-R`：跳過儲存庫的導出。可選。
- `--skip-custom-dir`：跳過自訂目錄的導出。可選。
- `--skip-lfs-data`：跳過 LFS 資料的導出。可選。
- `--skip-attachment-data`：跳過附件資料的導出。可選。
- `--skip-package-data`：跳過包資料的導出。可選。
- `--skip-log`：跳過日誌資料的導出。可選。
- `--database`，`-d`：指定資料庫的 SQL 語法。可選。
- `--verbose`，`-V`：如果提供此選項，顯示附加詳細資訊。可選。
- `--type`：設定導出的格式。可選。（預設值：zip）
- 範例：
- `gitea dump`
- `gitea dump --verbose`
### generate
用於在設定文件中生成隨機值和令牌。對於自動部署時生成值非常有用。
- 命令:
- `secret`:
- 選項:
- `INTERNAL_TOKEN`: 用於內部 API 調用身份驗證的令牌。
- `JWT_SECRET`: 用於 LFS 和 OAUTH2 JWT 身份驗證的密鑰（LFS_JWT_SECRET 是此選項的別名，用於向後相容）。
- `SECRET_KEY`: 全域密鑰。
- 範例:
- `gitea generate secret INTERNAL_TOKEN`
- `gitea generate secret JWT_SECRET`
- `gitea generate secret SECRET_KEY`
### keys
提供一個 SSHD AuthorizedKeysCommand。需要在 sshd 設定文件中進行設定:
```ini
...
# -e 的值和 AuthorizedKeysCommandUser 應與運行 Gitea 的用戶名匹配
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /path/to/gitea keys -e git -u %u -t %t -k %k
```
該命令將返回適用於提供的密鑰的合適 authorized_keys 行。您還應在 `app.ini` 的 `[server]` 部分設定值 `SSH_CREATE_AUTHORIZED_KEYS_FILE=false`。
注意: opensshd 要求 Gitea 程式由 root 擁有，並且不可由組或其他人寫入。程式必須使用絕對路徑指定。
注意: Gitea 必須在運行此命令時處於運行狀態才能成功。
### migrate
遷移資料庫。該命令可用於在首次啟動伺服器之前運行其他命令。此命令是冪等的。
### doctor check
對 Gitea 實例進行診斷，可以修復一些可修復的問題。
預設只運行部分檢查，額外的檢查可以參考：
- `gitea doctor check --list` - 列出所有可用的檢查
- `gitea doctor check --all` - 運行所有可用的檢查
- `gitea doctor check --default` - 運行預設的檢查
- `gitea doctor check --run [check(s),]...` - 運行指定的名字的檢查
有些問題可以透過設定 `--fix` 選項進行自動修復。
額外的日誌可以透過 `--log-file=...` 進行設定。
#### doctor recreate-table
有時，在遷移時，舊的列和預設值可能會在資料庫模式中保持不變。這可能會導致警告，如下所示:
```
2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync() [W] Table user Column keep_activity_private db default is , struct default is 0
```
您可以透過以下方式讓 Gitea 重新建立這些表，並將舊資料複製到新表中，並適當設定預設值：
```
gitea doctor recreate-table user
```
您可以使用以下方式讓 Gitea 重新建立多個表：
```
gitea doctor recreate-table table1 table2 ...
```
如果您希望 Gitea 重新建立所有表，請直接調用：
```
gitea doctor recreate-table
```
強烈建議在運行這些命令之前備份您的資料庫。
### doctor convert
將現有的 MySQL 資料庫從 utf8 轉換為 utf8mb4，或者把 MSSQL 資料庫從 varchar 轉換為 nvarchar。
### manager
管理運行中的伺服器操作：
- 命令:
- `shutdown`: 優雅地關閉運行中的進程
- `restart`: 優雅地重新啟動運行中的進程（對於 Windows 伺服器尚未實現）
- `flush-queues`: 刷新運行中的進程中的隊列
- 選項:
- `--timeout value`: 刷新過程的超時時間（預設值: 1m0s）
- `--non-blocking`: 設定為 true，以在返回之前不等待刷新完成
- `logging`: 調整日誌命令
- 命令:
- `pause`: 暫停日誌記錄
- 注意:
- 如果日誌級別低於此級別，日誌級別將被臨時提升為 INFO。
- Gitea 將在一定程度上緩衝日誌，並在超過該點後丟棄日誌。
- `resume`: 恢復日誌記錄
- `release-and-reopen`: 使 Gitea 釋放和重新打開用於日誌記錄的文件和連接（相當於向 Gitea 發送 SIGUSR1 信號）。
- `remove name`: 刪除指定的日誌記錄器
- 選項:
- `--group group`, `-g group`: 從中刪除子記錄器的組（預設為`default`）
- `add`: 添加日誌記錄器
- 命令:
- `console`: 添加控制檯日誌記錄器
- 選項:
- `--group value`, `-g value`: 要添加日誌記錄器的組 - 預設為"default"
- `--name value`, `-n value`: 新日誌記錄器的名稱 - 預設為模式
- `--level value`, `-l value`: 新日誌記錄器的日誌級別
- `--stacktrace-level value`, `-L value`: 堆棧跟蹤日誌級別
- `--flags value`, `-F value`: 日誌記錄器的標誌
- `--expression value`, `-e value`: 日誌記錄器的匹配表達式
- `--prefix value`, `-p value`: 日誌記錄器的前綴
- `--color`: 在日誌中使用顏色
- `--stderr`: 將控制檯日誌輸出到 stderr - 僅適用於控制檯
- `file`: 添加文件日誌記錄器
- 選項:
- `--group value`, `-g value`: 要添加日誌記錄器的組 - 預設為"default"
- `--name value`, `-n value`: 新日誌記錄器的名稱 - 預設為模式
- `--level value`, `-l value`: 新日誌記錄器的日誌級別
- `--stacktrace-level value`, `-L value`: 堆棧跟蹤日誌級別
- `--flags value`, `-F value`: 日誌記錄器的標誌
- `--expression value`, `-e value`: 日誌記錄器的匹配表達式
- `--prefix value`, `-p value`: 日誌記錄器的前綴
- `--color`: 在日誌中使用顏色
- `--filename value`, `-f value`: 日誌記錄器的文件名
- `--rotate`, `-r`: 輪轉日誌
- `--max-size value`, `-s value`: 在輪轉之前的最大大小（以位元組為單位）
- `--daily`, `-d`: 每天輪轉日誌
- `--max-days value`, `-D value`: 保留的每日日誌的最大數量
- `--compress`, `-z`: 壓縮輪轉的日誌
- `--compression-level value`, `-Z value`: 使用的壓縮級別
- `conn`: 添加網路連接日誌記錄器
- 選項:
- `--group value`, `-g value`: 要添加日誌記錄器的組 - 預設為"default"
- `--name value`, `-n value`: 新日誌記錄器的名稱 - 預設為模式
- `--level value`, `-l value`: 新日誌記錄器的日誌級別
- `--stacktrace-level value`, `-L value`: 堆棧跟蹤日誌級別
- `--flags value`, `-F value`: 日誌記錄器的標誌
- `--expression value`, `-e value`: 日誌記錄器的匹配表達式
- `--prefix value`, `-p value`: 日誌記錄器的前綴
- `--color`: 在日誌中使用顏色
- `--reconnect-on-message`, `-R`: 對於每個消息重新連接主機
- `--reconnect`, `-r`: 連接中斷時重新連接主機
- `--protocol value`, `-P value`: 設定要使用的協議：tcp、unix 或 udp（預設為 tcp）
- `--address value`, `-a value`: 要連接到的主機地址和端口（預設為:7020）
- `smtp`: 添加 SMTP 日誌記錄器
- 選項:
- `--group value`, `-g value`: 要添加日誌記錄器的組 - 預設為"default"
- `--name value`, `-n value`: 新日誌記錄器的名稱 - 預設為模式
- `--level value`, `-l value`: 新日誌記錄器的日誌級別
- `--stacktrace-level value`, `-L value`: 堆棧跟蹤日誌級別
- `--flags value`, `-F value`: 日誌記錄器的標誌
- `--expression value`, `-e value`: 日誌記錄器的匹配表達式
- `--prefix value`, `-p value`: 日誌記錄器的前綴
- `--color`: 在日誌中使用顏色
- `--username value`, `-u value`: 郵件伺服器使用者名稱
- `--password value`, `-P value`: 郵件伺服器密碼
- `--host value`, `-H value`: 郵件伺服器主機（預設為: 127.0.0.1:25）
- `--send-to value`, `-s value`: 要發送到的電子電子郵件地址
- `--subject value`, `-S value`: 發送電子郵件的主題標題
- `processes`: 顯示 Gitea 進程和 Goroutine 資訊
- 選項:
- `--flat`: 以平面表格形式顯示進程，而不是樹形結構
- `--no-system`: 不顯示系統進程
- `--stacktraces`: 顯示與進程關聯的 Goroutine 的堆棧跟蹤
- `--json`: 輸出為 JSON 格式
- `--cancel PID`: 向具有 PID 的進程發送取消命令（僅適用於非系統進程）
### dump-repo
`dump-repo` 從 Git/GitHub/Gitea/GitLab 中轉儲儲存庫資料：
- 選項：
- `--git_service service`：Git 服務，可以是 `git`、`github`、`gitea`、`gitlab`。如果 `clone_addr` 可以被識別，則可以忽略此選項。
- `--repo_dir dir`，`-r dir`：儲存資料的儲存庫目錄路徑。
- `--clone_addr addr`：將被克隆的 URL，目前可以是 git/github/gitea/gitlab 的 http/https URL。例如：https://github.com/lunny/tango.git
- `--auth_username lunny`：訪問 `clone_addr` 的使用者名稱。
- `--auth_password <password>`：訪問 `clone_addr` 的密碼。
- `--auth_token <token>`：訪問 `clone_addr` 的個人令牌。
- `--owner_name lunny`：如果非空，資料將儲存在具有所有者名稱的目錄中。
- `--repo_name tango`：如果非空，資料將儲存在具有儲存庫名稱的目錄中。
- `--units <units>`：要遷移的專案，一個或多個專案應以逗號分隔。允許的專案有 wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments。如果為空，則表示所有專案。
### restore-repo
`restore-repo` 從磁盤目錄中還原儲存庫資料：
- 選項：
- `--repo_dir dir`，`-r dir`：還原資料的儲存庫目錄路徑。
- `--owner_name lunny`：還原目標所有者名稱。
- `--repo_name tango`：還原目標儲存庫名稱。
- `--units <units>`：要還原的專案，一個或多個專案應以逗號分隔。允許的專案有 wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments。如果為空，則表示所有專案。
### actions generate-runner-token
生成一個供 Runner 使用的新令牌，用於向伺服器註冊。
- 選項：
- `--scope {owner}[/{repo}]`，`-s {owner}[/{repo}]`：限制 Runner 的範圍，沒有範圍表示該 Runner 可用於所有儲存庫，但你也可以將其限制為特定的儲存庫或所有者。
要註冊全域 Runner：
```
gitea actions generate-runner-token
```
要註冊特定組織的 Runner，例如 `org`：
```
gitea actions generate-runner-token -s org
```
要註冊特定儲存庫的 Runner，例如 `username/test-repo`：
```
gitea actions generate-runner-token -s username/test-repo
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/config-cheat-sheet.md
+1561
View File
File diff suppressed because it is too large. Load diff
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/customizing-gitea.md
+83
View File
@@ -0,0 +1,83 @@
---
date: "2017-04-15T14:56:00+02:00"
slug: "customizing-gitea"
sidebar_position: 100
aliases:
- /zh-tw/customizing-gitea
---
# 自訂 Gitea 設定
Gitea 引用 `custom` 目錄中的自訂設定文件來覆蓋設定、模板等預設設定。
如果從二進制部署 Gitea ，則所有預設路徑都將相對於該 gitea 二進制文件；如果從發行版安裝，則可能會將這些路徑修改為 Linux 文件系統標準。Gitea
將會自動建立包括 `custom/` 在內的必要應用目錄，應用本身的設定存放在
`custom/conf/app.ini` 當中。在發行版中可能會以 `/etc/gitea/` 的形式為 `custom` 設定一個符號鏈接，查看設定詳情請移步：
- [快速備忘單](../administration/config-cheat-sheet.md)
- [完整設定清單](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
如果您在 binary 同目錄下無法找到 `custom` 文件夾，請檢查您的 `GITEA_CUSTOM`
環境變量設定， 因為它可能被設定到了其他地方（可能被一些啟動腳本設定指定了目錄）。
- [環境變量清單](../administration/environment-variables.md)
**注：** 必須完全重啟 Gitea 以使設定生效。
## 使用自訂 /robots.txt
將 [想要展示的內容](http://www.robotstxt.org/) 存放在 `custom` 目錄中的
`robots.txt` 文件來讓 Gitea 使用自訂的`/robots.txt` （預設：空 404）。
## 使用自訂的公共文件
將自訂的公共文件（比如頁面和圖片）作為 webroot 放在 `custom/public/` 中來讓 Gitea 提供這些自訂內容（符號鏈接將被追蹤）。
舉例說明：`image.png` 存放在 `custom/public/assets/`中，那麼它可以透過鏈接 http://gitea.domain.tld/assets/image.png 訪問。
## 修改預設頭像
替換以下目錄中的 png 圖片： `custom/public/assets/img/avatar\_default.png`
## 自訂 Gitea 頁面
您可以改變 Gitea `custom/templates` 的每個單頁面。您可以在 Gitea 源碼的 `templates` 目錄中找到用於覆蓋的模板文件，應用將根據
`custom/templates` 目錄下的路徑結構進行匹配和覆蓋。
包含在 `{{` 和 `}}` 中的任何語句都是 Gitea 的模板語法，如果您不完全理解這些元件，不建議您對它們進行修改。
### 添加鏈接和頁籤
如果您只是想添加額外的鏈接到頂部導航欄或額外的選項卡到儲存庫視圖，您可以將它們放在您 `custom/templates/custom/` 目錄下的 `extra_links.tmpl` 和 `extra_tabs.tmpl` 文件中。
舉例說明：假設您需要在網站放置一個靜態的“關於”頁面，您只需將該頁面放在您的
"custom/public/"目錄下（比如 `custom/public/impressum.html`）並且將它與 `custom/templates/custom/extra_links.tmpl` 鏈接起來即可。
這個鏈接應當使用一個名為“item”的 class 來匹配當前樣式，您可以使用 `{{AppSubUrl}}` 來獲取 base URL:
`<a class="item" href="{{AppSubUrl}}/assets/impressum.html">Impressum</a>`
同理，您可以將頁籤添加到 `extra_tabs.tmpl` 中，使用同樣的方式來添加頁籤。它的具體樣式需要與
`templates/repo/header.tmpl` 中已有的其他選項卡的樣式匹配
([source in GitHub](https://github.com/go-gitea/gitea/blob/main/templates/repo/header.tmpl))
### 頁面的其他新增內容
除了 `extra_links.tmpl` 和 `extra_tabs.tmpl`，您可以在您的 `custom/templates/custom/` 目錄中存放一些其他有用的模板，例如：
- `header.tmpl`，在 `<head>` 標記結束之前的模板，例如添加自訂 CSS 文件
- `body_outer_pre.tmpl`，在 `<body>` 標記開始處的模板
- `body_inner_pre.tmpl`，在頂部導航欄之前，但在主 container 內部的模板，例如添加一個 `<div class="full height">`
- `body_inner_post.tmpl`，在主 container 結束處的模板
- `body_outer_post.tmpl`，在底部 `<footer>` 元素之前.
- `footer.tmpl`，在 `<body>` 標籤結束處的模板，可以在這裡填寫一些附加的 Javascript 腳本。
## 自訂 gitignores，labels， licenses， locales 以及 readmes
將自訂文件放在 `custom/options` 下相應子的文件夾中即可
## 更改 Gitea 外觀
內置主題是“gitea-light”、“gitea-dark”和“gitea-auto”（自動適應操作系統設定）。
預設主題可以透過 `app.ini` 的 [ui](../administration/config-cheat-sheet.md) 部分中的 `DEFAULT_THEME` 進行更改。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/email-setup.md
+77
View File
@@ -0,0 +1,77 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "email-setup"
sidebar_position: 12
aliases:
- /zh-tw/email-setup
---
# Email 設定
Gitea 具有郵件功能，用於發送事務性郵件（例如註冊確認郵件）。它可以設定為使用 Sendmail（或相容的 MTA，例如 Postfix 和 msmtp）或直接使用 SMTP 伺服器。
## 使用 Sendmail
使用 `sendmail` 命令作為郵件傳輸代理（mailer）。
注意：對於在官方 Gitea Docker 鏡像中使用，請使用 SMTP 版本進行設定（請參考下一節）。
注意：對於面向互聯網的網站，請查閱您的 MTA 文件以瞭解通過 TLS 發送郵件的說明。同時設定 SPF、DMARC 和 DKIM DNS 記錄，以使發送的郵件被各個電子郵件提供商接受為合法郵件。
```ini title="app.ini"
[mailer]
ENABLED = true
FROM = [email protected]
PROTOCOL = sendmail
SENDMAIL_PATH = /usr/sbin/sendmail
SENDMAIL_ARGS = "--" ; 大多數 "sendmail" 程序都接受選項，使用 "--" 將防止電子郵件地址被解釋為選項。
```
## 使用 SMTP
直接使用 SMTP 伺服器作為中繼。如果您不想在實例上設定 MTA，但在電子郵件提供商那裡有一個帳戶，這個選項非常有用。
```ini title="app.ini"
[mailer]
ENABLED = true
FROM = [email protected]
PROTOCOL = smtps
SMTP_ADDR = mail.mydomain.com
SMTP_PORT = 587
USER = [email protected]
PASSWD = `password`
```
重啟 Gitea 以使設定更改生效。
要發送測試郵件以驗證設定，請轉到 Gitea > 站點管理 > 設定 > SMTP 郵件設定。
有關所有選項的完整列表，請查看[設定速查表](../administration/config-cheat-sheet.md)。
請注意：只有在使用 TLS 或 `HOST=localhost` 加密 SMTP 伺服器通信時才支援身份驗證。TLS 加密可以透過以下方式進行：
- 通過端口 587 的 STARTTLS（也稱為 Opportunistic TLS）。初始連接是明文的，但如果伺服器支援，則可以升級為 TLS。
- 通過預設端口 465 的 SMTPS 連接。連接到伺服器從一開始就使用 TLS。
- 使用 `PROTOCOL=smtps` 進行強制的 SMTPS 連接。（這兩種方式都被稱為 Implicit TLS）
這是由於 Go 內部庫對 STRIPTLS 攻擊的保護機制。
請注意，自 2018 年起，[RFC8314](https://tools.ietf.org/html/rfc8314#section-3) 推薦使用 Implicit TLS。
### Gmail
以下設定應該適用於 Gmail 的 SMTP 伺服器：
```ini title="app.ini"
[mailer]
ENABLED = true
HOST = smtp.gmail.com:465 ; 對於 Gitea >= 1.18.0，刪除此行
SMTP_ADDR = smtp.gmail.com
SMTP_PORT = 465
FROM = [email protected]
USER = example.user
PASSWD = `***`
PROTOCOL = smtps
```
請注意，您需要建立並使用一個 [應用密碼](https://support.google.com/accounts/answer/185833?hl=en) 並在您的 Google 帳戶上啟用 2FA。您將無法直接使用您的 Google 帳戶密碼。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/environment-variables.md
+49
View File
@@ -0,0 +1,49 @@
---
date: "2017-04-08T11:34:00+02:00"
slug: "environment-variables"
sidebar_position: 10
aliases:
- /zh-tw/environment-variables
---
# 環境變量清單
這裡是用來控制 Gitea 行為表現的的環境變量清單，您需要在執行如下 Gitea 啟動命令前設定它們來確保設定生效：
```
GITEA_CUSTOM=/home/gitea/custom ./gitea web
```
## Go 的設定
因為 Gitea 使用 Go 語言編寫，因此它使用了一些相關的 Go 的設定參數：
- `GOOS`
- `GOARCH`
- [`GOPATH`](https://go.dev/cmd/go/#hdr-GOPATH_environment_variable)
您可以在[官方文件](https://go.dev/cmd/go/#hdr-Environment_variables)中查閱這些設定參數的詳細資訊。
## Gitea 的文件目錄
- `GITEA_WORK_DIR`：工作目錄的絕對路徑
- `GITEA_CUSTOM`：預設情況下 Gitea 使用預設目錄 `GITEA_WORK_DIR`/custom，您可以使用這個參數來設定 _custom_ 目錄
- `GOGS_WORK_DIR`： 已廢棄，請使用 `GITEA_WORK_DIR` 替代
- `GOGS_CUSTOM`： 已廢棄，請使用 `GITEA_CUSTOM` 替代
## 操作系統設定
- `USER`：Gitea 運行時使用的系統使用者，它將作為一些 repository 的訪問地址的一部分
- `USERNAME`： 如果沒有設定 `USER`， Gitea 將使用 `USERNAME`
- `HOME`： 使用者的 home 目錄，在 Windows 中會使用 `USERPROFILE` 環境變量
### 僅限於 Windows 的設定
- `USERPROFILE`： 使用者的主目錄，如果未設定則會使用 `HOMEDRIVE` + `HOMEPATH`
- `HOMEDRIVE`: 用於訪問 home 目錄的主驅動器路徑（C 盤）
- `HOMEPATH`：在指定主驅動器下的 home 目錄相對路徑
## Miscellaneous
- `SKIP_MINWINSVC`：如果設定為 1，在 Windows 上不會以 service 的形式運行。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/external-renderers.md
+194
View File
@@ -0,0 +1,194 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "external-renderers"
sidebar_position: 60
aliases:
- /zh-tw/external-renderers
---
# 外部渲染器
Gitea 通過外部二進制文件支援自訂文件渲染（例如 Jupyter notebooks、asciidoc 等），只需要進行以下步驟：
- 安裝外部二進制文件
- 在您的 `app.ini` 文件中添加一些設定
- 重新啟動 Gitea 實例
此功能支援整個文件的渲染。如果您想要在 Markdown 中渲染程式碼塊，您需要使用 JavaScript 進行一些操作。請參閱 [自訂 Gitea 設定](../administration/customizing-gitea.md) 頁面上的一些範例。
## 安裝外部二進制文件
為了通過外部二進制文件進行文件渲染，必須安裝它們的關聯套件。
如果您正在使用 Docker 鏡像，則您的 `Dockerfile` 應該包含以下內容：
```docker
FROM docker.gitea.com/gitea:@dockerVersion@
[...]
COPY custom/app.ini /data/gitea/conf/app.ini
[...]
RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng libffi-dev pandoc python3-dev py3-pyzmq pipx
# 安裝其他您需要的外部渲染器的軟件包
RUN pipx install jupyter docutils --include-deps
# 在上面添加您需要安裝的任何其他 Python 軟件包
```
## `app.ini` 文件設定
在您的自訂 `app.ini` 文件中為每個外部渲染器添加一個 `[markup.XXXXX]` 部分：
```ini
[markup.asciidoc]
ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "asciidoctor -s -a showtitle --out-file=- -"
; 輸入不是標準輸入而是文件
IS_INPUT_FILE = false
[markup.jupyter]
ENABLED = true
FILE_EXTENSIONS = .ipynb
RENDER_COMMAND = "jupyter nbconvert --stdin --stdout --to html --template basic"
IS_INPUT_FILE = false
[markup.restructuredtext]
ENABLED = true
FILE_EXTENSIONS = .rst
RENDER_COMMAND = "timeout 30s pandoc +RTS -M512M -RTS -f rst"
IS_INPUT_FILE = false
```
如果您的外部標記語言依賴於在生成的 HTML 元素上的額外類和屬性，您可能需要啟用自訂的清理策略。Gitea 使用 [`bluemonday`](https://godoc.org/github.com/microcosm-cc/bluemonday) 包作為我們的 HTML 清理器。下面的範例可以用於支援從 [`pandoc`](https://pandoc.org/) 輸出的伺服器端 [KaTeX](https://katex.org/) 渲染結果。
```ini
[markup.sanitizer.TeX]
; Pandoc 渲染 TeX 段落為帶有 "math" 類的 <span> 元素，根據上下文可能還帶有 "inline" 或 "display" 類。
; - 請注意，這與我們的 Markdown 解析器中內置的數學支持不同，後者使用 <code> 元素。
ELEMENT = span
ALLOW_ATTR = class
REGEXP = ^\s*((math(\s+|$)|inline(\s+|$)|display(\s+|$)))+
[markup.markdown]
ENABLED = true
FILE_EXTENSIONS = .md,.markdown
RENDER_COMMAND = pandoc -f markdown -t html --katex
```
您必須在每個部分中定義 `ELEMENT` 和 `ALLOW_ATTR`。
要定義多個條目，請添加唯一的字母數字後綴（例如，`[markup.sanitizer.1]` 和 `[markup.sanitizer.something]`）。
要僅為特定的外部渲染器應用清理規則，它們必須使用渲染器名稱，例如 `[markup.sanitizer.asciidoc.rule-1]`、`[markup.sanitizer.<renderer>.rule-1]`。
**注意**：如果規則在渲染器 ini 部分之前定義，或者名稱與渲染器不匹配，它將應用於所有渲染器。
完成設定更改後，請重新啟動 Gitea 以使更改生效。
**注意**：在 Gitea 1.12 之前，存在一個名為 `markup.sanitiser` 的單個部分，其中的鍵被重新定義為多個規則，但是，這種設定方法存在重大問題，需要通過多個部分進行設定。
### 範例：HTML
直接渲染 HTML 文件：
```ini
[markup.html]
ENABLED = true
FILE_EXTENSIONS = .html,.htm
RENDER_COMMAND = cat
; 輸入不是標準輸入，而是文件
IS_INPUT_FILE = true
[markup.sanitizer.html.1]
ELEMENT = div
ALLOW_ATTR = class
[markup.sanitizer.html.2]
ELEMENT = a
ALLOW_ATTR = class
```
請注意：此範例中的設定將允許渲染 HTML 文件，並使用 `cat` 命令將文件內容輸出為 HTML。此外，設定中的兩個清理規則將允許 `<div>` 和 `<a>` 元素使用 `class` 屬性。
在進行設定更改後，請重新啟動 Gitea 以使更改生效。
### 範例：Office DOCX
使用 [`pandoc`](https://pandoc.org/) 顯示 Office DOCX 文件：
```ini
[markup.docx]
ENABLED = true
FILE_EXTENSIONS = .docx
RENDER_COMMAND = "pandoc --from docx --to html --self-contained --template /path/to/basic.html"
[markup.sanitizer.docx.img]
ALLOW_DATA_URI_IMAGES = true
```
在此範例中，設定將允許顯示 Office DOCX 文件，並使用 `pandoc` 命令將文件轉換為 HTML 格式。同時，清理規則中的 `ALLOW_DATA_URI_IMAGES` 設定為 `true`，允許使用 Data URI 格式的圖片。
模板文件的內容如下：
```
$body$
```
### 範例：Jupyter Notebook
使用 [`nbconvert`](https://github.com/jupyter/nbconvert) 顯示 Jupyter Notebook 文件：
```ini
[markup.jupyter]
ENABLED = true
FILE_EXTENSIONS = .ipynb
RENDER_COMMAND = "jupyter-nbconvert --stdin --stdout --to html --template basic"
[markup.sanitizer.jupyter.img]
ALLOW_DATA_URI_IMAGES = true
```
在此範例中，設定將允許顯示 Jupyter Notebook 文件，並使用 `nbconvert` 命令將文件轉換為 HTML 格式。同樣，清理規則中的 `ALLOW_DATA_URI_IMAGES` 設定為 `true`，允許使用 Data URI 格式的圖片。
在進行設定更改後，請重新啟動 Gitea 以使更改生效。
## 自訂 CSS
在 `.ini` 文件中，可以使用 `[markup.XXXXX]` 的格式指定外部渲染器，並且由外部渲染器生成的 HTML 將被包裝在一個帶有 `markup` 和 `XXXXX` 類的 `<div>` 中。`markup` 類提供了預定義的樣式（如果 `XXXXX` 是 `markdown`，則使用 `markdown` 類）。否則，您可以使用這些類來針對渲染的 HTML 內容進行定製樣式。
因此，您可以編寫一些 CSS 樣式：
```css
.markup.XXXXX html {
font-size: 100%;
overflow-y: scroll;
-webkit-text-size-adjust: 100%;
-ms-text-size-adjust: 100%;
}
.markup.XXXXX body {
color: #444;
font-family: Georgia, Palatino, "Palatino Linotype", Times, "Times New Roman",
serif;
font-size: 12px;
line-height: 1.7;
padding: 1em;
margin: auto;
max-width: 42em;
background: #fefefe;
}
.markup.XXXXX p {
color: orangered;
}
```
將您的樣式表添加到自訂目錄中，例如 `custom/public/assets/css/my-style-XXXXX.css`，並使用自訂的頭文件 `custom/templates/custom/header.tmpl` 進行導入：
```html
<link rel="stylesheet" href="{{AppSubUrl}}/assets/css/my-style-XXXXX.css" />
```
通過以上步驟，您可以將自訂的 CSS 樣式應用到特定的外部渲染器，使其具有所需的樣式效果。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/fail2ban-setup.md
+86
View File
@@ -0,0 +1,86 @@
---
date: "2022-08-01T00:00:00+00:00"
slug: "fail2ban-setup"
sidebar_position: 16
aliases:
- /zh-tw/fail2ban-setup
---
# 設定 Fail2ban
**Fail2ban 檢查客戶端登入日誌，將多次登入失敗的客戶端識別為攻擊者並在一段時間內阻止其訪問服務。如果你的實例是公開的，這一點尤其重要。請管理員仔細設定 fail2ban，錯誤的設定將導致防火牆阻止你訪問自己的伺服器。**
Gitea 會在日誌文件 `log/gitea.log` 中記錄登入失敗的 CLI、SSH 或 HTTP 客戶端 IP 地址，而你需要將 Gitea 的日誌輸出模式從預設的 `console` 更改為 `file`。這表示將日誌輸出到文件，使得 fail2ban 可以定期掃描日誌內容。
當使用者的身份驗證失敗時，日誌中會記錄此類資訊：
```log
2018/04/26 18:15:54 [I] Failed authentication attempt for user from xxx.xxx.xxx.xxx
```
```log
2020/10/15 16:08:44 [E] invalid credentials from xxx.xxx.xxx.xxx
```
## 設定規則
添加日誌過濾器規則到設定文件 `/etc/fail2ban/filter.d/gitea.conf`:
```ini
[Definition]
failregex = .*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
ignoreregex =
```
添加監獄規則到設定文件 `/etc/fail2ban/jail.d/gitea.conf`:
```ini
[gitea]
enabled = true
filter = gitea
logpath = /var/lib/gitea/log/gitea.log
maxretry = 10
findtime = 3600
bantime = 900
action = iptables-allports
```
如果你的 Gitea 實例運行在 Docker 容器中，並且直接將容器端口暴露到外部網路，
你還需要添加 `chain="FORWARD"` 到監獄規則設定文件 `/etc/fail2ban/jail.d/gitea-docker.conf`
以適應 Docker 的網路轉發規則。但如果你在容器的宿主機上使用 Nginx 反向代理連接到 Gitea 則無需這樣設定。
```ini
[gitea-docker]
enabled = true
filter = gitea
logpath = /var/lib/gitea/log/gitea.log
maxretry = 10
findtime = 3600
bantime = 900
action = iptables-allports[chain="FORWARD"]
```
最後，運行 `systemctl restart fail2ban` 即可應用更改。現在，你可以使用 `systemctl status fail2ban` 檢查 fail2ban 運行狀態。
上述規則規定客戶端在 1 小時內，如果登入失敗的次數達到 10 次，則通過 iptables 鎖定該客戶端 IP 地址 15 分鐘。
## 設定反向代理
如果你使用 Nginx 反向代理到 Gitea 實例，你還需要設定 Nginx 的 HTTP 頭部值 `X-Real-IP` 將真實的客戶端 IP 地址傳遞給 Gitea。否則 Gitea 程式會將客戶端地址錯誤解析為反向代理伺服器的地址，例如迴環地址 `127.0.0.1`。
```
proxy_set_header X-Real-IP $remote_addr;
```
額外注意，在 Gitea 的設定文件 `app.ini` 中存在下列預設值：
```
REVERSE_PROXY_LIMIT = 1
REVERSE_PROXY_TRUSTED_PROXIES = 127.0.0.0/8,::1/128
```
`REVERSE_PROXY_LIMIT` 限制反向代理伺服器的層數，設定為 `0` 表示不使用這些標頭。
`REVERSE_PROXY_TRUSTED_PROXIES` 表示受信任的反向代理伺服器網路地址，
經過該網路地址轉發來的流量會經過解析 `X-Real-IP` 頭部得到真實客戶端地址。
（參考 [configuration cheat sheet](../administration/config-cheat-sheet.md)）
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/git-lfs-support.md
+24
View File
@@ -0,0 +1,24 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "git-lfs-setup"
sidebar_position: 12
aliases:
- /zh-tw/git-lfs-setup
---
# Git LFS 設定
要使用 Gitea 內置的 LFS 支援，您需要更新 `app.ini` 文件：
```ini
[server]
; 啟用 git-lfs 支持。true 或 false，默認為 false。
LFS_START_SERVER = true
[lfs]
; 存放 LFS 文件的路徑，默認為 data/lfs。
PATH = /home/gitea/data/lfs
```
**注意**：LFS 伺服器支援需要伺服器上安裝 Git v2.1.2 以上版本。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/https-support.md
+89
View File
@@ -0,0 +1,89 @@
---
date: "2023-04-09T11:00:00+02:00"
slug: "https-setup"
sidebar_position: 12
---
# HTTPS設定
## 使用內置伺服器
在啟用HTTPS之前，確保您擁有有效的SSL/TLS證書。
建議在測試和評估情況下使用自簽名證書，請運行 `gitea cert --host [HOST]` 以生成自簽名證書
如果您在伺服器上使用阿帕奇（Apache）或Nginx，建議參考 [反向代理指南](reverse-proxies.md)。
要使用Gitea內置HTTPS支援，您必須編輯`app.ini`文件。
```ini
[server]
PROTOCOL = https
ROOT_URL = https://git.example.com:3000/
HTTP_PORT = 3000
CERT_FILE = cert.pem
KEY_FILE = key.pem
```
請注意，如果您的證書由第三方證書頒發機構簽名（即不是自簽名的），則 cert.pem 應包含證書鏈。伺服器證書必須是 cert.pem 中的第一個條目，後跟中介（如果有）。不必包含根證書，因為連接客戶端必須已經擁有根證書才能建立信任關係。要了解有關設定值的更多資訊，請查看 [設定備忘單](../administration/config-cheat-sheet.md)。
對於“CERT_FILE”或“KEY_FILE”欄位，當文件路徑是相對路徑時，文件路徑相對於“GITEA_CUSTOM”環境變量。它也可以是絕對路徑。
### 設定HTTP重定向
Gitea伺服器僅支援監聽一個端口；要重定向HTTP請求致HTTPS端口，您需要啟用HTTP重定向服務：
```ini
[server]
REDIRECT_OTHER_PORT = true
; Port the redirection service should listen on
PORT_TO_REDIRECT = 3080
```
如果您使用Docker，確保端口已設定在 `docker-compose.yml` 文件
## 使用 ACME (預設: Let's Encrypt)
[ACME](https://tools.ietf.org/html/rfc8555) 是一種證書頒發機構標準協議，允許您自動請求和續訂 SSL/TLS 證書。[Let`s Encrypt](https://letsencrypt.org/) 是使用此標準的免費公開信任的證書頒發機構伺服器。僅實施“HTTP-01”和“TLS-ALPN-01”挑戰。為了使 ACME 質詢通過並驗證您的域所有權，“80”端口（“HTTP-01”）或“443”端口（“TLS-ALPN-01”）上 gitea 域的外部流量必須由 gitea 實例提供服務。可能需要設定 [HTTP 重定向](#設定http重定向) 和端口轉發才能正確路由外部流量。否則，到端口“80”的正常流量將自動重定向到 HTTPS。**您必須同意**ACME提供商的服務條款（預設為Let's Encrypt的 [服務條款](https://letsencrypt.org/documents/LE-SA-v1.2-2017年11月15日.pdf)。
使用預設 Let's Encrypt 的最小設定如下：
```ini
[server]
PROTOCOL=https
DOMAIN=git.example.com
ENABLE_ACME=true
ACME_ACCEPTTOS=true
ACME_DIRECTORY=https
;; Email can be omitted here and provided manually at first run, after which it is cached
ACME_EMAIL=[email protected]
```
小型設定請使用 [smallstep CA](https://github.com/smallstep/certificates), 點擊 [教學](https://smallstep.com/docs/tutorials/acme-challenge) 瞭解更多資訊。
```ini
[server]
PROTOCOL=https
DOMAIN=git.example.com
ENABLE_ACME=true
ACME_ACCEPTTOS=true
ACME_URL=https://ca.example.com/acme/acme/directory
;; Can be omitted if using the system's trust is preferred
;ACME_CA_ROOT=/path/to/root_ca.crt
ACME_DIRECTORY=https
ACME_EMAIL=[email protected]
```
要了解關於設定, 請前往 [設定備忘單](../administration/config-cheat-sheet.md)獲取更多資訊
## 使用反向代理伺服器
按照 [reverse proxy guide](reverse-proxies.md) 的規則設定你的反向代理伺服器
然後，按照下面的嚮導啟用 HTTPS：
- [nginx](https://nginx.org/en/docs/http/configuring_https_servers.html)
- [apache2/httpd](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html)
- [caddy](https://caddyserver.com/docs/tls)
注意：僅在代理層啟用 HTTPS 被稱為 [TLS 終止代理](https://en.wikipedia.org/wiki/TLS_termination_proxy)。代理伺服器接受傳入的 TLS 連接，解密內容，然後將現在未加密的內容傳遞給 Gitea。只要代理和 Gitea 實例在同一臺計算機上或在私有網路中的不同計算機上（代理暴露給外部網路），這通常是可以接受的。如果您的 Gitea 實例與代理隔離在公共網路上，或者如果您想要全端到端的加密，您還可以直接在 Gitea 中 [啟用內置伺服器的 HTTPS 支援](#使用內置伺服器)，並將連接轉發到 HTTPS 上。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/logging-config.md
+263
View File
@@ -0,0 +1,263 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "logging-config"
sidebar_position: 40
aliases:
- /zh-tw/logging-configuration
---
# 日誌設定
Gitea 的日誌設定主要由以下三種類型的元件組成：
- `[log]` 部分用於一般設定
- `[log.<mode-name>]` 部分用於設定不同的日誌輸出方式，也稱為 "writer mode"，模式名稱同時也作為 "writer name"
- `[log]` 部分還可以包含遵循 `logger.<logger-name>.<CONFIG-KEY>` 模式的子日誌記錄器的設定
預設情況下，已經有一個完全功能的日誌輸出，因此不需要重新定義。
## 收集日誌以獲取幫助
要收集日誌以獲取幫助和報告問題，請參閱 [需要幫助](help/support.md)。
## `[log]` 部分
在 Gitea 中，日誌設施的設定在 `[log]` 部分及其子部分。
在頂層的 `[log]` 部分，可以放置以下設定項：
- `ROOT_PATH`：（預設值：**%(GITEA_WORK_DIR)/log**）：日誌文件的基本路徑。
- `MODE`：（預設值：**console**）：要用於預設日誌記錄器的日誌輸出列表。
- `LEVEL`：（預設值：**Info**）：要持久化的最嚴重的日誌事件，不區分大小寫。可能的值為：`Trace`、`Debug`、`Info`、`Warn`、`Error`、`Fatal`。
- `STACKTRACE_LEVEL`：（預設值：**None**）：對於此類及更嚴重的事件，將在記錄時打印堆棧跟蹤。
它還可以包含以下子日誌記錄器：
- `logger.router.MODE`：（預設值：**,**）：用於路由器日誌記錄器的日誌輸出列表。
- `logger.access.MODE`：（預設值：**_empty_**）：用於訪問日誌記錄器的日誌輸出列表。預設情況下，訪問日誌記錄器被禁用。
- `logger.xorm.MODE`：（預設值：**,**）：用於 XORM 日誌記錄器的日誌輸出列表。
將子日誌記錄器的模式設定為逗號（`,`）表示使用預設的全域 `MODE`。
## 快速範例
### 預設（空）設定
空設定等同於預設設定：
```ini
[log]
ROOT_PATH = %(GITEA_WORK_DIR)/log
MODE = console
LEVEL = Info
STACKTRACE_LEVEL = None
logger.router.MODE = ,
logger.xorm.MODE = ,
logger.access.MODE =
; 這是“控制檯”模式的配置選項（由上面的 MODE=console 使用）
[log.console]
MODE = console
FLAGS = stdflags
PREFIX =
COLORIZE = true
```
這等同於將所有日誌發送到控制檯，並將預設的 Golang 日誌也發送到控制檯日誌中。
這只是一個範例，預設情況下不需要將其寫入設定文件中。
### 禁用路由日誌並將一些訪問日誌記錄到文件中
禁用路由日誌，將訪問日誌（>=Warn）記錄到 `access.log` 中：
```ini
[log]
logger.router.MODE =
logger.access.MODE = access-file
[log.access-file]
MODE = file
LEVEL = Warn
FILE_NAME = access.log
```
### 為不同的模式設定不同的日誌級別
將預設日誌（>=Warn）記錄到 `gitea.log` 中，將錯誤日誌記錄到 `file-error.log` 中：
```ini
[log]
LEVEL = Warn
MODE = file, file-error
; 默認情況下，"file" 模式會將日誌記錄到 %(log.ROOT_PATH)/gitea.log，因此我們不需要設置它
; [log.file]
[log.file-error]
LEVEL = Error
FILE_NAME = file-error.log
```
## 日誌輸出（模式和寫入器）
Gitea 提供以下日誌寫入器：
- `console` - 輸出日誌到 `stdout`（或 `stderr`，如果已在設定中設定）
- `file` - 輸出日誌到文件
- `conn` - 輸出日誌到套接字（網路或 Unix 套接字）
### 公共設定
某些設定適用於所有日誌輸出模式：
- `MODE` 是日誌輸出寫入器的模式。它將預設為 ini 部分的模式名稱。因此，`[log.console]` 將預設為 `MODE = console`。
- `LEVEL` 是此輸出將記錄的最低日誌級別。
- `STACKTRACE_LEVEL` 是此輸出將打印堆棧跟蹤的最低日誌級別。
- `COLORIZE` 對於 `console`，預設為 `true`，否則預設為 `false`。
#### `EXPRESSION`
`EXPRESSION` 表示日誌事件必須匹配才能被輸出寫入器記錄的正則表達式。
日誌消息（去除顏色）或 `longfilename:linenumber:functionname` 必須匹配其中之一。
注意：整個消息或字符串不需要完全匹配。
請注意，此表達式將在寫入器的 goroutine 中運行，而不是在日誌事件的 goroutine 中運行。
#### `FLAGS`
`FLAGS` 表示在每條消息之前打印的前置日誌上下文資訊。
它是一個逗號分隔的字符串集。值的順序無關緊要。
預設值為 `stdflags`（= `date,time,medfile,shortfuncname,levelinitial`）。
可能的值為：
- `none` 或 `,` - 無標誌。
- `date` - 當地時區的日期：`2009/01/23`。
- `time` - 當地時區的時間：`01:23:23`。
- `microseconds` - 微秒精度：`01:23:23.123123`。假定有時間。
- `longfile` - 完整的文件名和行號：`/a/b/c/d.go:23`。
- `shortfile` - 文件名的最後一個部分和行號：`d.go:23`。
- `funcname` - 調用者的函數名：`runtime.Caller()`。
- `shortfuncname` - 函數名的最後一部分。覆蓋 `funcname`。
- `utc` - 如果設定了日期或時間，則使用 UTC 而不是本地時區。
- `levelinitial` - 提供的級別的初始字符，放在方括號內，例如 `[I]` 表示 info。
- `level` - 在方括號內的級別，例如 `[INFO]`。
- `gopid` - 上下文的 Goroutine-PID。
- `medfile` - 文件名的最後 20 個字符 - 相當於 `shortfile,longfile`。
- `stdflags` - 相當於 `date,time,medfile,shortfuncname,levelinitial`。
### Console 模式
在此模式下，日誌記錄器將將日誌消息轉發到 Gitea 進程附加的 stdout 和 stderr 流。
對於 console 模式的日誌記錄器，如果不在 Windows 上，或者 Windows 終端可以設定為 ANSI 模式，或者是 cygwin 或 Msys 管道，則 `COLORIZE` 預設為 `true`。
設定：
- `STDERR`：**false**：日誌記錄器是否應將日誌打印到 `stderr` 而不是 `stdout`。
### File 模式
在此模式下，日誌記錄器將將日誌消息保存到文件中。
設定：
- `FILE_NAME`：要將日誌事件寫入的文件，相對於 `ROOT_PATH`，預設為 `%(ROOT_PATH)/gitea.log`。異常情況：訪問日誌預設為 `%(ROOT_PATH)/access.log`。
- `MAX_SIZE_SHIFT`：**28**：單個文件的最大大小位移。28 表示 256Mb。詳細資訊見下文。
- `LOG_ROTATE` **true**：是否輪轉日誌文件。
- `DAILY_ROTATE`：**true**：是否每天旋轉日誌。
- `MAX_DAYS`：**7**：在此天數之後刪除旋轉的日誌文件。
- `COMPRESS`：**true**：預設情況下是否使用 gzip 壓縮舊的日誌文件。
- `COMPRESSION_LEVEL`：**-1**：壓縮級別。詳細資訊見下文。
`MAX_SIZE_SHIFT` 通過將給定次數左移 1 (`1 << x`) 來定義文件的最大大小。
在 v1.17.3 版本時的確切行為可以在[這裡](https://github.com/go-gitea/gitea/blob/v1.17.3/modules/setting/log.go#L185)中查看。
`COMPRESSION_LEVEL` 的有用值範圍從 1 到（包括）9，其中較高的數字表示更好的壓縮。
請注意，更好的壓縮可能會帶來更高的資源使用。
必須在前面加上 `-` 符號。
### Conn 模式
在此模式下，日誌記錄器將通過網路套接字發送日誌消息。
設定：
- `ADDR`：**:7020**：設定要連接的地址。
- `PROTOCOL`：**tcp**：設定協議，可以是 "tcp"、"unix" 或 "udp"。
- `RECONNECT`：**false**：在連接丟失時嘗試重新連接。
- `RECONNECT_ON_MSG`：**false**：為每條消息重新連接主機。
### "Router" 日誌記錄器
當 Gitea 的路由處理程式工作時，Router 日誌記錄器記錄以下消息類型：
- `started` 消息將以 TRACE 級別記錄
- `polling`/`completed` 路由將以 INFO 級別記錄。異常情況："/assets" 靜態資源請求也會以 TRACE 級別記錄。
- `slow` 路由將以 WARN 級別記錄
- `failed` 路由將以 WARN 級別記錄
### "XORM" 日誌記錄器
為了使 XORM 輸出 SQL 日誌，還應將 `[database]` 部分中的 `LOG_SQL` 設定為 `true`。
### "Access" 日誌記錄器
"Access" 日誌記錄器是自 Gitea 1.9 版本以來的新日誌記錄器。它提供了符合 NCSA Common Log 標準的日誌格式。雖然它具有高度可設定性，但在更改其模板時應謹慎。此日誌記錄器的主要好處是，Gitea 現在可以使用標準日誌格式記錄訪問日誌，因此可以使用標準工具進行分析。
您可以透過使用 `logger.access.MODE = ...` 來啟用此日誌記錄器。
如果需要，可以透過更改 `ACCESS_LOG_TEMPLATE` 的值來更改 "Access" 日誌記錄器的格式。
請注意，訪問日誌記錄器將以 `INFO` 級別記錄，將此日誌記錄器的 `LEVEL` 設定為 `WARN` 或更高級別將導致不記錄訪問日誌。
#### ACCESS_LOG_TEMPLATE
此值表示一個 Go 模板。其預設值為
```tmpl
{{.Ctx.RemoteHost}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}" "{{.Ctx.Req.UserAgent}}"`
```
模板接收以下選項：
- `Ctx` 是 `context.Context`
- `Identity` 是 `SignedUserName`，如果使用者未登入，則為 "-"
- `Start` 是請求的開始時間
- `ResponseWriter` 是 `http.ResponseWriter`
更改此模板時必須小心，因為它在標準的 panic 恢復陷阱之外運行。此模板應該儘可能簡單，因為它會為每個請求運行一次。
## 釋放和重新打開、暫停和恢復日誌記錄
如果您在 Unix 上運行，您可能希望釋放和重新打開日誌以使用 `logrotate` 或其他工具。
可以透過向運行中的進程發送 `SIGUSR1` 信號或運行 `gitea manager logging release-and-reopen` 命令來強制 Gitea 釋放並重新打開其日誌文件和連接。
或者，您可能希望暫停和恢復日誌記錄 - 可以透過使用 `gitea manager logging pause` 和 `gitea manager logging resume` 命令來實現。請注意，當日志記錄暫停時，低於 INFO 級別的日誌事件將不會儲存，並且只會儲存有限數量的事件。在暫停時，日誌記錄可能會阻塞，儘管是暫時性的，但會大大減慢 Gitea 的運行速度，因此建議僅暫停很短的時間。
### 在 Gitea 運行時添加和刪除日誌記錄
可以使用 `gitea manager logging add` 和 `remove` 子命令在 Gitea 運行時添加和刪除日誌記錄。
此功能只能調整正在運行的日誌系統，不能用於啟動未初始化的訪問或路由日誌記錄器。如果您希望啟動這些系統，建議調整 app.ini 並（優雅地）重新啟動 Gitea 服務。
這些命令的主要目的是在運行中的系統上輕鬆添加臨時日誌記錄器，以便調查問題，因為重新啟動可能會導致問題消失。
## 使用 `logrotate` 而不是內置的日誌輪轉
Gitea 包含內置的日誌輪轉功能，對於大多數部署來說應該已經足夠了。但是，如果您想使用 `logrotate` 工具：
- 在 `app.ini` 中將 `LOG_ROTATE` 設定為 `false`，禁用內置的日誌輪轉。
- 安裝 `logrotate`。
- 根據部署要求設定 `logrotate`，有關設定語法細節，請參閱 `man 8 logrotate`。
在 `postrotate/endscript` 塊中通過 `kill -USR1` 或 `kill -10` 向 `gitea` 進程本身發送 `USR1` 信號，
或者運行 `gitea manager logging release-and-reopen`（使用適當的環境設定）。
確保設定適用於由 Gitea 日誌記錄器生成的所有文件，如上述部分所述。
- 始終使用 `logrotate /etc/logrotate.conf --debug` 來測試您的設定。
- 如果您正在使用 Docker 並從容器外部運行，您可以使用
`docker exec -u $OS_USER $CONTAINER_NAME sh -c 'gitea manager logging release-and-reopen'`
或 `docker exec $CONTAINER_NAME sh -c '/bin/s6-svc -1 /etc/s6/gitea/'`，或直接向 Gitea 進程本身發送 `USR1` 信號。
下一個 `logrotate` 作業將包括您的設定，因此不需要重新啟動。
您還可以立即使用 `logrotate /etc/logrotate.conf --force` 重新加載 `logrotate`。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/mail-templates.md
+254
View File
@@ -0,0 +1,254 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "mail-templates"
sidebar_position: 45
aliases:
- /zh-tw/mail-templates
---
# 郵件模板
為了定製特定操作的電子郵件主題和內容，可以使用模板來自訂 Gitea。這些功能的模板位於 [`custom` 目錄](../administration/customizing-gitea.md) 下。
如果沒有自訂的替代方案，Gitea 將使用內部模板作為預設模板。
自訂模板在 Gitea 啟動時加載。對它們的更改在 Gitea 重新啟動之前不會被識別。
## 支援模板的郵件通知
目前，以下通知事件使用模板：
| 操作名稱 | 用途 |
| ---------- | ---------------------------------------------------------------------- |
| `new` | 建立了新的工單或合併請求。 |
| `comment` | 在現有工單或合併請求中建立了新的評論。 |
| `close` | 關閉了工單或合併請求。 |
| `reopen` | 重新打開了工單或合併請求。 |
| `review` | 在合併請求中進行審查的首要評論。 |
| `approve` | 對合併請求進行批准的首要評論。 |
| `reject` | 對合併請求提出更改請求的審查的首要評論。 |
| `code` | 關於合併請求的程式碼的單個評論。 |
| `assigned` | 使用者被分配到工單或合併請求。 |
| `default` | 未包括在上述類別中的任何操作，或者當對應類別的模板不存在時使用的模板。 |
特定消息類型的模板路徑為：
```sh
custom/templates/mail/{操作類型}/{操作名稱}.tmpl
```
其中 `{操作類型}` 是 `issue` 或 `pull`（針對合併請求），`{操作名稱}` 是上述列出的操作名稱之一。
例如，有關合併請求中的評論的電子郵件的特定模板是：
```sh
custom/templates/mail/pull/comment.tmpl
```
然而，並不需要為每個操作類型/名稱組合建立模板。
使用回退系統來選擇適當的模板。在此列表中，將使用 _第一個存在的_ 模板：
- 所需**操作類型**和**操作名稱**的特定模板。
- 操作類型為 `issue` 和所需**操作名稱**的模板。
- 所需**操作類型**和操作名稱為 `default` 的模板。
- 操作類型為` issue` 和操作名稱為 `default` 的模板。
唯一必需的模板是操作類型為 `issue` 操作名稱為 `default` 的模板，除非使用者在 `custom` 目錄中覆蓋了它。
## 模板語法
郵件模板是 UTF-8 編碼的文本文件，需要遵循以下格式之一：
```
用於主題行的文本和宏
------------
用於郵件正文的文本和宏
```
或者
```
用於郵件正文的文本和宏
```
指定 _主題_ 部分是可選的（因此也是虛線分隔符）。在使用時，_主題_ 和 _郵件正文_ 模板之間的分隔符需要至少三個虛線；分隔符行中不允許使用其他字符。
_主題_ 和 _郵件正文_ 由 [Golang 的模板引擎](https://go.dev/pkg/text/template/) 解析，並提供了為每個通知組裝的 _元資料上下文_。上下文包含以下元素：
| 名稱 | 類型 | 可用性 | 用途 |
| ------------------ | ---------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.FallbackSubject` | string | 始終可用 | 預設主題行。參見下文。 |
| `.Subject` | string | 僅在正文中可用 | 解析後的 _主題_。 |
| `.Body` | string | 始終可用 | 工單、合併請求或評論的消息，從 Markdown 解析為 HTML 並進行了清理。請勿與 _郵件正文_ 混淆。 |
| `.Link` | string | 始終可用 | 源工單、合併請求或評論的地址。 |
| `.Issue` | models.Issue | 始終可用 | 產生通知的工單（或合併請求）。要獲取特定於合併請求的資料（例如 `HasMerged`），可以使用 `.Issue.PullRequest`，但需要注意，如果工單 _不是_ 合併請求，則該欄位將為 `nil`。 |
| `.Comment` | models.Comment | 如果適用 | 如果通知是針對添加到工單或合併請求的評論，則其中包含有關評論的資訊。 |
| `.IsPull` | bool | 始終可用 | 如果郵件通知與合併請求關聯（即 `.Issue.PullRequest` 不為 `nil` ），則為 `true`。 |
| `.Repo` | string | 始終可用 | 儲存庫的名稱，包括所有者名稱（例如 `mike/stuff`） |
| `.User` | models.User | 始終可用 | 事件來源儲存庫的所有者。要獲取使用者名稱（例如 `mike`），可以使用 `.User.Name`。 |
| `.Doer` | models.User | 始終可用 | 執行觸發通知事件的操作的使用者。要獲取使用者名稱（例如 `rhonda`），可以使用 `.Doer.Name`。 |
| `.IsMention` | bool | 始終可用 | 如果此通知僅是因為在評論中提到了使用者而生成的，並且收件人未訂閱源，則為 `true`。如果收件人已訂閱工單或儲存庫，則為 `false`。 |
| `.SubjectPrefix` | string | 始終可用 | 如果通知是關於除工單或合併請求建立之外的其他內容，則為 `Re：`；否則為空字符串。 |
| `.ActionType` | string | 始終可用 | `"issue"` 或 `"pull"`。它將與實際的 _操作類型_ 對應，與選擇的模板無關。 |
| `.ActionName` | string | 始終可用 | 它將是上述操作類型之一（`new` ，`comment` 等），並與選擇的模板對應。 |
| `.ReviewComments` | []models.Comment | 始終可用 | 審查中的程式碼評論列表。評論文本將在 `.RenderedContent` 中，引用的程式碼將在 `.Patch` 中。 |
所有名稱區分大小寫。
### 模板中的主題部分
用於郵件主題的模板引擎是 Golang 的 [`text/template`](https://go.dev/pkg/text/template/)。
有關語法的詳細資訊，請參閱鏈接的文件。
主題構建的步驟如下：
- 根據通知類型和可用的模板選擇一個模板。
- 解析並解析模板（例如，將 `{{.Issue.Index}}` 轉換為工單或合併請求的編號）。
- 將所有空格字符（例如 `TAB`，`LF` 等）轉換為普通空格。
- 刪除所有前導、尾隨和多餘的空格。
- 將字符串截斷為前 256 個字母（字符）。
如果最終結果為空字符串，**或者**沒有可用的主題模板（即所選模板不包含主題部分），將使用 Gitea 的**內部預設值**。
內部預設（回退）主題相當於：
```
{{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#{{.Issue.Index}})
```
例如：`Re: [mike/stuff] New color palette (#38)`
即使存在有效的主題模板，Gitea 的預設主題也可以在模板的元資料中作為 `.FallbackSubject` 找到。
### 模板中的郵件正文部分
用於郵件正文的模板引擎是 Golang 的 [`html/template`](https://go.dev/pkg/html/template/)。
有關語法的詳細資訊，請參閱鏈接的文件。
郵件正文在郵件主題之後進行解析，因此還有一個額外的 _元資料_ 欄位，即在考慮所有情況之後實際呈現的主題。
期望的結果是 HTML（包括結構元素，如`<html>`，`<body>`等）。可以透過 `<style>` 塊、`class` 和 `style` 屬性進行樣式設定。但是，`html/template` 會進行一些 [自動轉義](https://go.dev/pkg/html/template/#hdr-Contexts)，需要考慮這一點。
不支援附件（例如圖像或外部樣式表）。但是，也可以引用其他模板，例如以集中方式提供 `<style>` 元素的內容。外部模板必須放置在 `custom/mail` 下，並相對於該目錄引用。例如，可以使用 `{{template styles/base}}` 包含 `custom/mail/styles/base.tmpl`。
郵件以 `Content-Type: multipart/alternative` 發送，因此正文以 HTML 和文本格式發送。通過剝離 HTML 標記來獲取文本版本。
## 故障排除
郵件的呈現方式直接取決於郵件應用程式的功能。許多郵件客戶端甚至不支援 HTML，因此顯示生成郵件中包含的文本版本。
如果模板無法呈現，則只有在發送郵件時纔會注意到。
如果主題模板失敗，將使用預設主題，如果從 _郵件正文_ 中成功呈現了任何內容，則將使用該內容，忽略其他內容。
如果遇到問題，請檢查 [Gitea 的日誌](../administration/logging-config.md) 以獲取錯誤消息。
## 範例
`custom/templates/mail/issue/default.tmpl`:
```html
[{{.Repo}}] @{{.Doer.Name}}
{{if eq .ActionName "new"}}
創建了
{{else if eq .ActionName "comment"}}
評論了
{{else if eq .ActionName "close"}}
關閉了
{{else if eq .ActionName "reopen"}}
重新打開了
{{else}}
更新了
{{end}}
{{if eq .ActionType "issue"}}
工單
{{else}}
合併請求
{{end}}
#{{.Issue.Index}}: {{.Issue.Title}}
------------
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>{{.Subject}}</title>
</head>
<body>
{{if .IsMention}}
<p>
您收到此郵件是因為 @{{.Doer.Name}} 提到了您。
</p>
{{end}}
<p>
<p>
<a href="{{AppUrl}}/{{.Doer.LowerName}}">@{{.Doer.Name}}</a>
{{if not (eq .Doer.FullName "")}}
({{.Doer.FullName}})
{{end}}
{{if eq .ActionName "new"}}
創建了
{{else if eq .ActionName "close"}}
關閉了
{{else if eq .ActionName "reopen"}}
重新打開了
{{else}}
更新了
{{end}}
<a href="{{.Link}}">{{.Repo}}#{{.Issue.Index}}</a>。
</p>
{{if not (eq .Body "")}}
<h3>消息內容：</h3>
<hr>
{{.Body}}
{{end}}
</p>
<hr>
<p>
<a href="{{.Link}}">在 Gitea 上查看</a>。
</p>
</body>
</html>
```
該模板將生成以下內容：
### 主題
> [mike/stuff] @rhonda 在合併請求 #38 上進行了評論：New color palette
### 郵件正文
> [@rhonda](#)（Rhonda Myers）更新了 [mike/stuff#38](#)。
>
> #### 消息內容
>
> \_**************\*\*\*\***************\_**************\*\*\*\***************
>
> Mike, I think we should tone down the blues a little.
>
> \_**************\*\*\*\***************\_**************\*\*\*\***************
>
> [在 Gitea 上查看](#)。
## 高級用法
模板系統包含一些函數，可用於進一步處理和格式化消息。以下是其中一些函數的列表：
| 函數名 | 參數 | 可用於 | 用法 |
| ---------------- | ----------- | ---------- | ------------------------------------------------ |
| `AppUrl` | - | 任何地方 | Gitea 的 URL |
| `AppName` | - | 任何地方 | 從 `app.ini` 中設定，通常為 "Gitea" |
| `AppDomain` | - | 任何地方 | Gitea 的主機名 |
| `EllipsisString` | string, int | 任何地方 | 將字符串截斷為指定長度；根據需要添加省略號 |
| `SanitizeHTML` | string | 僅正文部分 | 通過刪除其中的危險 HTML 標籤對文本進行清理 |
| `SafeHTML` | string | 僅正文部分 | 將輸入作為 HTML 處理；可用於輸出原始的 HTML 內容 |
這些都是 _函數_，而不是元資料，因此必須按以下方式使用：
```html
像這樣使用： {{SanitizeHTML "Escape<my
>text"}} 或者這樣使用： {{"Escape<my
>text" | SanitizeHTML}} 或者這樣使用： {{AppUrl}} 但不要像這樣使用：
{{.AppUrl}}</my
></my
>
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/repo-indexer.md
+50
View File
@@ -0,0 +1,50 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "repo-indexer"
sidebar_position: 45
aliases:
- /zh-tw/repo-indexer
---
# 儲存庫索引器
## 設定儲存庫索引器
通過在您的 [`app.ini`](../administration/config-cheat-sheet.md) 中啟用此功能，Gitea 可以透過儲存庫的文件進行搜索：
```ini
[indexer]
; ...
REPO_INDEXER_ENABLED = true
REPO_INDEXER_PATH = indexers/repos.bleve
MAX_FILE_SIZE = 1048576
REPO_INDEXER_INCLUDE =
REPO_INDEXER_EXCLUDE = resources/bin/**
```
請記住，索引內容可能會消耗大量系統資源，特別是在首次建立索引或全域更新索引時（例如升級 Gitea 之後）。
### 按大小選擇要索引的文件
`MAX_FILE_SIZE` 選項將使索引器跳過所有大於指定值的文件。
### 按路徑選擇要索引的文件
Gitea 使用 [`gobwas/glob` 庫](https://github.com/gobwas/glob) 中的 glob 模式匹配來選擇要包含在索引中的文件。
限制文件列表可以防止索引被派生或無關的文件（例如 lss、sym、map 等）污染，從而使搜索結果更相關。這還有助於減小索引的大小。
`REPO_INDEXER_EXCLUDE_VENDORED`（預設值為 true）將排除供應商文件不包含在索引中。
`REPO_INDEXER_INCLUDE`（預設值為空）是一個逗號分隔的 glob 模式列表，用於在索引中**包含**的文件。空列表表示“_包含所有文件_”。
`REPO_INDEXER_EXCLUDE`（預設值為空）是一個逗號分隔的 glob 模式列表，用於從索引中**排除**的文件。與該列表匹配的文件將不會被索引。`REPO_INDEXER_EXCLUDE` 優先於 `REPO_INDEXER_INCLUDE`。
模式匹配工作方式如下：
- 要匹配所有帶有 `.txt` 擴展名的文件，無論在哪個目錄中，請使用 `**.txt`。
- 要匹配僅在儲存庫的根級別中具有 `.txt` 擴展名的所有文件，請使用 `*.txt`。
- 要匹配 `resources/bin` 目錄及其子目錄中的所有文件，請使用 `resources/bin/**`。
- 要匹配位於 `resources/bin` 目錄下的所有文件，請使用 `resources/bin/*`。
- 要匹配所有名為 `Makefile` 的文件，請使用 `**Makefile`。
- 匹配目錄沒有效果；模式 `resources/bin` 不會包含/排除該目錄中的文件；`resources/bin/**` 會。
- 所有文件和模式都規範化為小寫，因此 `**Makefile`、`**makefile` 和 `**MAKEFILE` 是等效的。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/reverse-proxies.md
+454
View File
@@ -0,0 +1,454 @@
---
date: "2018-05-22T11:00:00+00:00"
slug: "reverse-proxies"
sidebar_position: 16
aliases:
- /zh-tw/reverse-proxies
---
# 反向代理
## 通用設定
1. 在您的 `app.ini` 文件中添加設定 `[server] ROOT_URL = https://git.example.com/`
2. 將 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
3. 確保反向代理不會解碼 URI。`https://git.example.com/a%2Fb`的請求應該被傳遞給 `http://gitea:3000/a%2Fb`。
4. 確保 `Host` 和 `X-Forwarded-Proto` 頭被正確的傳遞給 Gitea，使 Gitea 可以看到正在訪問的真實 URL。
5. 確保 Web 伺服器有完整的憑證（包括所有中間憑證和根憑證），以便 `git clone` 和 `git pull` 正常工作。
6. Gitea 會在 `/-/ws` 使用 WebSocket 連線，用於通知計數等即時更新。請確保反向代理使用 HTTP/1.1，並轉發 `Upgrade` 和 `Connection` 頭，參見下面的示例。否則 Gitea 會改為定期輪詢。
## 使用子路徑
通常，**不推薦**將 Gitea 放到子路徑。人們很少使用此設定，並且在極少數情況下可能會出現一些問題。
為了讓 Gitea 在子路徑工作（例如：`https://common.example.com/gitea/`），需要在上面的通用設定之外進行一些額外的設定：
1. 在 `app.ini` 文件中使用設定 `[server] ROOT_URL = https://common.example.com/gitea/`。
2. 將 `https://common.example.com/gitea/foo` 反向代理到 `http://gitea:3000/foo`。
3. 容器映像註冊表需要在根目錄級別有一個固定的子路徑 `v2`，您必須做下列設定：
- 將 `https://common.example.com/v2` 反向代理到 `http://gitea:3000/v2`。
- 確保 URI 和標頭也被正確的傳遞（見上面的通用設定）
## 使用 Nginx 作為反向代理服務
如果您想使用 Nginx 作為 Gitea 的反向代理服務，您可以參照以下 `nginx.conf` 設定中 `server` 的 `http` 部分。
確保 `client_max_body_size` 足夠大，否則在上傳大文件時會出現 "client_max_body_size" 錯誤。
```nginx
server {
...
location / {
client_max_body_size 512M;
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Connection $http_connection;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
## 使用 Nginx 作為反向代理服務並將 Gitea 路由至一個子路徑
如果您已經有一個域名並且想與 Gitea 共享該域名，您可以增加以下 `nginx.conf` 設定中 `server` 的 `http` 部分，為 Gitea 添加路由規則：
```nginx
server {
...
location ~ ^/(gitea|v2)($|/) {
client_max_body_size 512M;
# 確保 nginx 使用未轉義 URI， 按原樣保持 "%2F"。 確保 nginx 去除 "/gitea" 子路徑前綴， 按原樣傳遞 "/v2"。
rewrite ^ $request_uri;
rewrite ^/(gitea($|/))?(.*) /$3 break;
proxy_pass http://127.0.0.1:3000$uri;
proxy_http_version 1.1;
# 其他的常規 HTTP 表頭，見上面“使用 Nginx 作為反向代理服務”小節的配置
proxy_set_header Connection $http_connection;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
然後您**必須**在 Gitea 的設定文件中正確的添加類似 `[server] ROOT_URL = http://git.example.com/git/` 的設定項。
## 使用 Nginx 直接提供靜態資源
我們可以透過將資源分為靜態和動態兩種類型來調節性能。
CSS 文件、JavaScript 文件、圖片和字體是靜態內容。首頁、儲存庫視圖和工單列表是動態內容。
Nginx 可以直接提供靜態資源，並且只代理動態資源請求給 Gitea。
Nginx 為提供靜態內容進行了優化，而代理大響應可能與這一優化行為相反。
（見[https://serverfault.com/q/587386](https://serverfault.com/q/587386)）
將 Gitea 源程式碼儲存庫的一個快照下載到 `/path/to/gitea`。
在此之後，在本地儲存庫目錄運行 `make frontend` 來生成靜態資源。在這個情況下，我們只對 `public/` 目錄感興趣，您可以刪除剩下的其他目錄。
（為了生成靜態資源，您需要安裝一個[帶 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
取決於您的使用者量的大小，您可以將流量分離到兩個不同的伺服器，或者為靜態資源設定一個 cdn。
### 單伺服器節點，單域名
將 `[server] STATIC_URL_PREFIX = /_/static` 寫入您的 Gitea 設定文件，並設定 nginx：
```nginx
server {
listen 80;
server_name git.example.com;
location /_/static/assets/ {
alias /path/to/gitea/public/;
}
location / {
# 其他指令見上面「使用 Nginx 作為反向代理服務」小節
proxy_pass http://localhost:3000;
}
}
```
### 雙伺服器節點，雙域名
將 `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` 寫入您的 Gitea 設定文件，並設定 nginx：
```nginx
# 運行 Gitea 的服務器
server {
listen 80;
server_name git.example.com;
location / {
# 其他指令見上面「使用 Nginx 作為反向代理服務」小節
proxy_pass http://localhost:3000;
}
}
```
```nginx
# 提供靜態資源的服務器
server {
listen 80;
server_name cdn.example.com;
location /gitea/ {
alias /path/to/gitea/public/;
}
location / {
return 404;
}
}
```
## Nginx Proxy Manager
如果使用 Nginx Proxy Manager 作為 Gitea 的反向代理，設定與原生 Nginx 略有不同。
它會[預設給自訂 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf)，因此上面 Nginx 設定裡對應的指令不要再寫一遍。否則會因為指令重複（尤其是 `proxy_set_header Host $host`）出現 `400 bad request`。
建立 `/` 自訂 location 時，只需在其設定中加入：
```nginx
client_max_body_size 512M;
```
在代理主機上啟用 `Websockets Support`，Nginx Proxy Manager 會自行加入 WebSocket 相關指令。再額外添加 `proxy_http_version` 會導致 Nginx 拒絕啟動。
## 使用 Apache HTTPD 作為反向代理服務
如果您想使用 Apache HTTPD 作為 Gitea 的反向代理服務，您可以為您的 Apache HTTPD 作如下設定（在 Ubuntu 中，設定文件通常在 `/etc/apache2/httpd.conf` 目錄下）：
```apacheconf
<VirtualHost *:80>
...
ProxyPreserveHost On
ProxyRequests off
AllowEncodedSlashes NoDecode
ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
:::note
必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`。
`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本。更舊的版本**必須**去掉它，否則 Apache HTTPD 將無法啟動。
:::
如果希望用 Let's Encrypt 的 webroot 驗證，請在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`，避免把這些請求代理到 Gitea。
## 使用 Apache HTTPD 作為反向代理服務並將 Gitea 路由至一個子路徑
如果您已經有一個域名並且想與 Gitea 共享該域名，您可以增加以下設定為 Gitea 添加路由規則（在 Ubuntu 中，設定文件通常在 `/etc/apache2/httpd.conf` 目錄下）：
```apacheconf
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
AllowEncodedSlashes NoDecode
# 注意: 路徑和 URL 後面都不要寫路徑符號 '/'
ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
然後您**必須**在 Gitea 的設定文件中正確的添加類似 `[server] ROOT_URL = http://git.example.com/git/` 的設定項。
:::note
必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更舊的版本請去掉它。
:::
## 使用 Apache HTTPD 直接提供靜態資源
我們可以通過將資源分為靜態和動態兩種類型來調節性能。
CSS 文件、JavaScript 文件、圖片和字體是靜態內容。首頁、倉庫視圖和工單列表是動態內容。
Apache HTTPD 可以直接提供靜態資源，並且只代理動態資源請求給 Gitea。
將 Gitea 源代碼倉庫的一個快照下載到 `/path/to/gitea/`。
在此之後，在本地倉庫目錄運行 `make frontend` 來生成靜態資源。在這個情況下，我們只對 `public/` 目錄感興趣，您可以刪除剩下的其他目錄。
（為了生成靜態資源，您需要安裝一個[帶 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
取決於您的用戶量的大小，您可以將流量分離到兩個不同的服務器，或者為靜態資源設定一個 cdn。
### 單伺服器節點，單域名
將 `[server] STATIC_URL_PREFIX = /_/static` 寫入您的 Gitea 設定文件：
```apacheconf
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
ProxyPass /_/static/ !
Alias /_/static/ /path/to/gitea/public/
<Directory /path/to/gitea/public/>
Options FollowSymlinks
AllowOverride None
Require all granted
</Directory>
AllowEncodedSlashes NoDecode
# 注意: 路徑和 URL 後面都不要寫路徑符號 '/'
ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
:::note
必須啟用以下 Apache HTTPD 元件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更舊的版本請去掉它。
:::
## 使用 Caddy 作為反向代理服務
如果您想使用 Caddy 作為 Gitea 的反向代理服務，您可以在 `Caddyfile` 中添加如下設定：
```
git.example.com {
reverse_proxy localhost:3000
}
```
## 使用 Caddy 作為反向代理服務並將 Gitea 路由至一個子路徑
如果您已經有一個域名並且想與 Gitea 共享該域名，您可以在您的 `Caddyfile` 文件中增加以下設定，為 Gitea 添加路由規則：
```
git.example.com {
route /git/* {
uri strip_prefix /git
reverse_proxy localhost:3000
}
}
```
然後您**必須**在 Gitea 的設定文件中正確的添加類似 `[server] ROOT_URL = http://git.example.com/git/` 的設定項。
## 使用 IIS 作為反向代理服務
如果您想使用 IIS 作為 Gitea 的反向代理服務，你需要為 IIS 設定 URL 重寫來作為反向代理。
1. 在 IIS 中設定一個空網頁，比如命名為 `Gitea Proxy`。
2. 根據[微軟社區中為 IIS 設定 URL 重寫的指南](https://techcommunity.microsoft.com/t5/iis-support-blog/setup-iis-with-url-rewrite-as-a-reverse-proxy-for-real-world/ba-p/846222#M343)的前兩步進行設定，也就是：
- 使用 Microsoft Web Platform Installer 5.1 (WebPI) 安裝 Application Request Routing（簡稱 ARR），或者在 [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing) 下載這個外掛。
- 一但這個模組被安裝到 IIS 上，你將會在 IIS 管理控制檯看到一個叫做 URL Rewrite 的新圖標。
- 安裝 Windows 功能 `WebSocket Protocol`，否則 ARR 無法代理 Gitea 的 WebSocket 端點。
- 打開 IIS 管理控制檯，在左邊的列表中點擊 `Gitea Proxy` 網頁。在中間選中並且雙擊 URL Rewrite 的圖標來加載 URL 重寫的面板。
- 在管理控制檯的右邊選擇 `Add Rule` 操作，並且在 `Inbound and Outbound Rules` 分類中選擇 `Reverse Proxy Rule`。
- 在 Inbound Rules 中， 將 server name 設定為 Gitea 正在運行的主機以及對應端口。例如，如果你在 localhost 的 3000 端口上運行 Gitea，則設定為 `127.0.0.1:3000`。
- 啟用 SSL Offloading
- 在 Outbound Rules 中，確保設定了 `Rewrite the domain names of the links in HTTP response`，並且將 `From:` 設定為上面的 server name，將 `To:` 設定為你的外部訪問名稱，例如：`git.example.com`
- 關閉 Application Request Routing 的 `Server Proxy Settings` 中的 `Reverse rewrite host in response headers`（在 IIS 管理員中選擇伺服器節點，打開 `Application Request Routing Cache`，再開啟右側的 `Server Proxy Settings`）。若保持開啟，ARR 會把 `Location` 頭裡的主機改回內部位址，導致登入或表單提交後的重新導向把瀏覽器送到 `127.0.0.1:3000` 而不是 `git.example.com`。
- 現在，根據下面的內容為您的網頁編輯 `web.config`（將 `127.0.0.1:3000` 和 `git.example.com` 改為適當的值）
```xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.web>
<httpRuntime requestPathInvalidCharacters="" />
</system.web>
<system.webServer>
<security>
<requestFiltering>
<hiddenSegments>
<clear />
</hiddenSegments>
<denyUrlSequences>
<clear />
</denyUrlSequences>
<fileExtensions allowUnlisted="true">
<clear />
</fileExtensions>
</requestFiltering>
</security>
<rewrite>
<rules useOriginalURLEncoding="false">
<rule name="ReverseProxyInboundRule1" stopProcessing="true">
<match url="(.*)" />
<action type="Rewrite" url="http://127.0.0.1:3000{UNENCODED_URL}" />
<serverVariables>
<set name="HTTP_X_ORIGINAL_ACCEPT_ENCODING" value="HTTP_ACCEPT_ENCODING" />
<set name="HTTP_ACCEPT_ENCODING" value="" />
</serverVariables>
</rule>
</rules>
<outboundRules>
<rule name="ReverseProxyOutboundRule1" preCondition="ResponseIsHtml1">
<!-- set the pattern correctly here - if you only want to accept http or https -->
<!-- change the pattern and the action value as appropriate -->
<match filterByTags="A, Form, Img" pattern="^http(s)?://127.0.0.1:3000/(.*)" />
<action type="Rewrite" value="http{R:1}://git.example.com/{R:2}" />
</rule>
<rule name="RestoreAcceptEncoding" preCondition="NeedsRestoringAcceptEncoding">
<match serverVariable="HTTP_ACCEPT_ENCODING" pattern="^(.*)" />
<action type="Rewrite" value="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" />
</rule>
<preConditions>
<preCondition name="ResponseIsHtml1">
<add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html" />
</preCondition>
<preCondition name="NeedsRestoringAcceptEncoding">
<add input="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" pattern=".+" />
</preCondition>
</preConditions>
</outboundRules>
</rewrite>
<urlCompression doDynamicCompression="true" />
<handlers>
<clear />
<add name="StaticFile" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />
</handlers>
<!-- Map all extensions to the same MIME type, so all files can be
downloaded. -->
<staticContent>
<clear />
<mimeMap fileExtension="*" mimeType="application/octet-stream" />
</staticContent>
</system.webServer>
</configuration>
```
## 使用 HAProxy 作為反向代理服務
如果您想使用 HAProxy 作為 Gitea 的反向代理服務，您可以將下面的內容加入您的 HAProxy 設定。
在 frontend 部分加入一個 acl 來將對 gitea.example.com 的請求重定向到正確的後端。
```
frontend http-in
...
acl acl_gitea hdr(host) -i gitea.example.com
use_backend gitea if acl_gitea
...
```
添加之前定義好的 backend 部分
```
backend gitea
server localhost:3000 check
```
如果您將 http 內容重定向到 https，上面的設定文件也能夠使用。只需要記住，在 HAProxy 和 Gitea 之間的連接將由 http 完成，所以你不需要在 Gitea 的設定文件中啟用 https。
## 使用 HAProxy 作為反向代理服務並將 Gitea 路由至一個子路徑
如果您已經有一個域名並且想與 Gitea 共享該域名，您可以在您的 HAProxy 中加入如下設定，為 Gitea 添加路由規則：
```
frontend http-in
...
acl acl_gitea path_beg /gitea
use_backend gitea if acl_gitea
...
```
在這個設定下，http://example.com/gitea/ 將被重定向到您的 Gitea 實例。
接下來，對於 backend 部分：
```
backend gitea
http-request replace-path /gitea\/?(.*) \/\1
server localhost:3000 check
```
添加的 http-request 在需要的時候會自動加入反斜槓/，並且通過將 http://example.com/gitea 正確設定為根來在內部路徑中刪除 /gitea，使其能夠正常工作。
然後您**必須**在 Gitea 的設定文件中正確的添加類似 `[server] ROOT_URL = http://example.com/gitea/` 的設定項。
## 使用 Traefik 作為反向代理服務
如果您想使用 traefik 作為 Gitea 的反向代理服務，您可以在 `docker-compose.yaml` 中添加 label 部分（假設使用 docker 作為 traefik 的 provider）：
```yaml
gitea:
image: docker.io/gitea/gitea
...
labels:
- "traefik.enable=true"
- "traefik.http.routers.gitea.rule=Host(`example.com`)"
- "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
```
這份設定假設您使用 traefik 來處理 HTTPS 服務，並在其和 Gitea 之間使用 HTTP 進行通信。
## 使用 Traefik 作為反向代理服務並將 Gitea 路由至一個子路徑
如果您已經有一個域名並且想與 Gitea 共享該域名，您可以在您的 `docker-compose.yaml` 文件中增加以下設定，為 Gitea 添加路由規則（假設使用 docker 作為 traefik 的 provider）：
```yaml
gitea:
image: docker.io/gitea/gitea
...
labels:
- "traefik.enable=true"
- "traefik.http.routers.gitea.rule=Host(`example.com`) && PathPrefix(`/gitea`)"
- "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
- "traefik.http.middlewares.gitea-stripprefix.stripprefix.prefixes=/gitea"
- "traefik.http.routers.gitea.middlewares=gitea-stripprefix"
```
這份設定假設您使用 traefik 來處理 HTTPS 服務，並在其和 Gitea 之間使用 HTTP 進行通信。
然後您**必須**在 Gitea 的設定文件中正確的添加類似 `[server] ROOT_URL = http://example.com/gitea/` 的設定項。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/search-engines-indexation.md
+30
View File
@@ -0,0 +1,30 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "search-engines-indexation"
sidebar_position: 60
aliases:
- /zh-tw/search-engines-indexation
---
# 搜索引擎索引
預設情況下，您的 Gitea 安裝將被搜索引擎索引。
如果您不希望您的儲存庫對搜索引擎可見，請進一步閱讀。
## 使用 robots.txt 阻止搜索引擎索引
為了使 Gitea 為頂級安裝提供自訂的`robots.txt`（預設為空的 404），請在 [`custom`文件夾或`CustomPath`]（administration/customizing-gitea.md）中建立一個名為 `public/robots.txt` 的文件。
有關如何設定 `robots.txt` 的範例，請參考 [https://moz.com/learn/seo/robotstxt](https://moz.com/learn/seo/robotstxt)。
```txt
User-agent: *
Disallow: /
```
如果您將 Gitea 安裝在子目錄中，則需要在頂級目錄中建立或編輯 `robots.txt`。
```txt
User-agent: *
Disallow: /gitea/
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/signing.md
+137
View File
@@ -0,0 +1,137 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "signing"
sidebar_position: 50
aliases:
- /zh-tw/signing
---
# GPG 提交簽名
Gitea 將通過檢查提交是否由 Gitea 資料庫中的密鑰簽名，或者提交是否與 Git 的預設密鑰匹配，來驗證提供的樹中的 GPG 提交簽名。
密鑰不會被檢查以確定它們是否已過期或撤銷。密鑰也不會與密鑰伺服器進行檢查。
如果找不到用於驗證提交的密鑰，提交將被標記為灰色的未鎖定圖標。如果提交被標記為紅色的未鎖定圖標，則表示它使用帶有 ID 的密鑰簽名。
請注意：提交的簽署者不必是提交的作者或提交者。
此功能要求 Git >= 1.7.9，但要實現全部功能，需要 Git >= 2.0.0。
## 自動簽名
有許多地方 Gitea 會生成提交：
- 儲存庫初始化
- Wiki 更改
- 使用編輯器或 API 進行的 CRUD 操作
- 從合併請求進行合併
根據設定和伺服器信任，您可能希望 Gitea 對這些提交進行簽名。
## 安裝和生成 Gitea 的 GPG 密鑰
如何安裝簽名密鑰由伺服器管理員決定。Gitea 目前使用伺服器的 `git` 命令生成所有提交，因此將使用伺服器的 `gpg` 進行簽名（如果設定了）。管理員應該審查 GPG 的最佳實踐 - 特別是可能建議僅安裝簽名的子密鑰，而不是主簽名和認證的密鑰。
## 通用設定
Gitea 的簽名設定可以在 `app.ini` 的 `[repository.signing]` 部分找到：
```ini
...
[repository.signing]
SIGNING_KEY = default
SIGNING_NAME =
SIGNING_EMAIL =
INITIAL_COMMIT = always
CRUD_ACTIONS = pubkey, twofa, parentsigned
WIKI = never
MERGES = pubkey, twofa, basesigned, commitssigned
...
```
### `SIGNING_KEY`
首先討論的選項是 `SIGNING_KEY`。有三個主要選項：
- `none` - 這將阻止 Gitea 對任何提交進行簽名
- `default` - Gitea 將使用 `git config` 中設定的預設密鑰
- `KEYID` - Gitea 將使用具有 ID `KEYID` 的 GPG 密鑰對提交進行簽名。在這種情況下，您應該提供 `SIGNING_NAME` 和 `SIGNING_EMAIL`，以便顯示此密鑰的資訊。
`default` 選項將讀取 `git config` 中的 `commit.gpgsign` 選項 - 如果設定了該選項，它將使用 `user.signingkey`、`user.name` 和 `user.email` 的結果。
通過在 Gitea 的儲存庫中調整 Git 的 `config` 文件，可以使用 `SIGNING_KEY=default` 為每個儲存庫提供不同的簽名密鑰。然而，這顯然不是一個理想的使用者介面，因此可能會發生更改。
:::warning
**自 1.17 起**，Gitea 在自己的主目錄 `[git].HOME_PATH`（預設為 `%(APP_DATA_PATH)/home`）中運行 git，並使用自己的設定文件 `{[git].HOME_PATH}/.gitconfig`。
如果您有自己定製的 Gitea git 設定，您應該將這些設定設定在系統 git 設定文件中（例如 `/etc/gitconfig`）或者 Gitea 的內部 git 設定文件 `{[git].HOME_PATH}/.gitconfig` 中。
與 git 命令相關的主目錄文件（如 `.gnupg`）也應該放在 Gitea 的 git 主目錄 `[git].HOME_PATH` 中。
如果您希望將 `.gnupg` 目錄放在 `{[git].HOME_PATH}/` 之外的位置，請考慮設定 `$GNUPGHOME` 環境變量為您首選的位置，否則 Gitea 將會從 `{[git].HOME_PATH}/.gnupg` 查找私鑰。
:::
### `INITIAL_COMMIT`
此選項確定在建立儲存庫時，Gitea 是否應該對初始提交進行簽名。可能的取值有：
- `never`：從不簽名
- `pubkey`：僅在使用者擁有公鑰時進行簽名
- `twofa`：僅在使用者使用 2FA 登入時進行簽名
- `always`：始終簽名
除了 `never` 和 `always` 之外的選項可以組合為逗號分隔的列表。如果所有選擇的選項都為 true，則提交將被簽名。
### `WIKI`
此選項確定 Gitea 是否應該對 Wiki 的提交進行簽名。可能的取值有：
- `never`：從不簽名
- `pubkey`：僅在使用者擁有公鑰時進行簽名
- `twofa`：僅在使用者使用 2FA 登入時進行簽名
- `parentsigned`：僅在父提交已簽名時進行簽名。
- `always`：始終簽名
除了 `never` 和 `always` 之外的選項可以組合為逗號分隔的列表。如果所有選擇的選項都為 true，則提交將被簽名。
### `CRUD_ACTIONS`
此選項確定 Gitea 是否應該對 Web 編輯器或 API CRUD 操作的提交進行簽名。可能的取值有：
- `never`：從不簽名
- `pubkey`：僅在使用者擁有公鑰時進行簽名
- `twofa`：僅在使用者使用 2FA 登入時進行簽名
- `parentsigned`：僅在父提交已簽名時進行簽名。
- `always`：始終簽名
除了 `never` 和 `always` 之外的選項可以組合為逗號分隔的列表。如果所有選擇的選項都為 true，則更改將被簽名。
### `MERGES`
此選項確定 Gitea 是否應該對 PR 的合併提交進行簽名。可能的選項有：
- `never`：從不簽名
- `pubkey`：僅在使用者擁有公鑰時進行簽名
- `twofa`：僅在使用者使用 2FA 登入時進行簽名
- `basesigned`：僅在基礎儲存庫中的父提交已簽名時進行簽名。
- `headsigned`：僅在頭分支中的頭提交已簽名時進行簽名。
- `commitssigned`：僅在頭分支中的所有提交到合併點的提交都已簽名時進行簽名。
- `approved`：僅對已批准的合併到受保護分支的提交進行簽名。
- `always`：始終簽名
除了 `never` 和 `always` 之外的選項可以組合為逗號分隔的列表。如果所有選擇的選項都為 true，則合併將被簽名。
## 獲取簽名密鑰的公鑰
用於簽署 Gitea 提交的公鑰可以透過 API 獲取：
```sh
/api/v1/signing-key.gpg
```
在存在特定於儲存庫的密鑰的情況下，可以透過以下方式獲取：
```sh
/api/v1/repos/:username/:reponame/signing-key.gpg
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/contributing/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "貢獻",
"position": 35,
"link": {
"type": "generated-index",
"slug": "/contributing",
"title": "貢獻"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/contributing/guidelines-backend.md
+110
View File
@@ -0,0 +1,110 @@
---
date: "2023-05-25T23:41:00+08:00"
slug: "guidelines-backend"
sidebar_position: 20
aliases:
- /zh-tw/guidelines-backend
---
# 後端開發指南
## 背景
Gitea 使用 Golang 作為後端編程語言。它使用了許多第三方包，並且自己也編寫了一些包。
例如，Gitea 使用[Chi](https://github.com/go-chi/chi)作為基本的 Web 框架。[Xorm](https://xorm.io)是一個用於與資料庫交互的 ORM 框架。
因此，管理這些包非常重要。在開始編寫後端程式碼之前，請參考以下準則。
## 包設計準則
### 包列表
為了保持易於理解的程式碼並避免循環依賴，擁有良好的程式碼結構是很重要的。Gitea 後端分為以下幾個部分：
- `build`：幫助構建 Gitea 的腳本。
- `cmd`：包含所有 Gitea 的實際子命令，包括 web、doctor、serv、hooks、admin 等。`web`將啟動 Web 服務。`serv`和`hooks`將被 Git 或 OpenSSH 調用。其他子命令可以幫助維護 Gitea。
- `tests`：常用的測試函數
- `tests/integration`：整合測試，用於測試後端迴歸。
- `tests/e2e`：端到端測試，用於測試前端和後端的相容性和視覺迴歸。
- `models`：包含由 xorm 用於構建資料庫表的資料結構。它還包含查詢和更新資料庫的函數。應避免與其他 Gitea 程式碼的依賴關係。在某些情況下，比如日誌記錄時可以例外。
- `models/db`：基本的資料庫操作。所有其他`models/xxx`包都應依賴於此包。`GetEngine`函數只能從 models/中調用。
- `models/fixtures`：單元測試和整合測試中使用的範例資料。一個`yml`文件表示一個將在測試開始時加載到資料庫中的表。
- `models/migrations`：儲存不同版本之間的資料庫遷移。修改資料庫結構的 PR**必須**包含一個遷移步驟。
- `modules`：在 Gitea 中處理特定功能的不同模組。工作正在進行中：其中一些模組應該移到`services`中，特別是那些依賴於 models 的模組，因為它們依賴於資料庫。
- `modules/setting`：儲存從 ini 文件中讀取的所有系統設定，並在各處引用。但是在可能的情況下，應將其作為函數參數使用。
- `modules/git`：用於與`Git`命令行或 Gogit 包交互的包。
- `public`：編譯後的前端文件（JavaScript、圖像、CSS 等）
- `routers`：處理伺服器請求。由於它使用其他 Gitea 包來處理請求，因此其他包（models、modules 或 services）不能依賴於 routers。
- `routers/api`：包含`/api/v1`相關路由，用於處理 RESTful API 請求。
- `routers/install`：只能在系統處於安裝模式（INSTALL_LOCK=false）時響應。
- `routers/private`：僅由內部子命令調用，特別是`serv`和`hooks`。
- `routers/web`：處理來自 Web 瀏覽器或 Git SMART HTTP 協議的 HTTP 請求。
- `services`：用於常見路由操作或命令執行的支援函數。使用`models`和`modules`來處理請求。
- `templates`：用於生成 HTML 輸出的 Golang 模板。
### 包依賴關係
由於 Golang 不支援導入循環，我們必須仔細決定包之間的依賴關係。這些包之間有一些級別。以下是理想的包依賴關係方向。
`cmd` -> `routers` -> `services` -> `models` -> `modules`
從左到右，左側的包可以依賴於右側的包，但右側的包不能依賴於左側的包。在同一級別的子包中，可以根據該級別的規則進行依賴。
**注意事項**
為什麼我們需要在`models`之外使用資料庫事務？以及如何使用？
某些操作在資料庫記錄插入/更新/刪除失敗時應該允許回滾。
因此，服務必須能夠建立資料庫事務。以下是一些範例：
```go
// services/repository/repository.go
func CreateXXXX() error {
return db.WithTx(func(ctx context.Context) error {
// do something, if err is returned, it will rollback automatically
if err := issues.UpdateIssue(ctx, repoID); err != nil {
// ...
return err
}
// ...
return nil
})
}
```
在`services`中**不應該**直接使用`db.GetEngine(ctx)`，而是應該在`models/`下編寫一個函數。
如果該函數將在事務中使用，請將`context.Context`作為函數的第一個參數。
```go
// models/issues/issue.go
func UpdateIssue(ctx context.Context, repoID int64) error {
e := db.GetEngine(ctx)
// ...
}
```
### 包名稱
對於頂層包，請使用複數作為包名，例如`services`、`models`，對於子包，請使用單數，例如`services/user`、`models/repository`。
### 導入別名
由於有一些使用相同包名的包，例如`modules/user`、`models/user`和`services/user`，當這些包在一個 Go 文件中被導入時，很難知道我們使用的是哪個包以及它是變量名還是導入名。因此，我們始終建議使用導入別名。為了與常見的駝峰命名法的包變量區分開，建議使用**snake_case**作為導入別名的命名規則。
例如：`import user_service "code.gitea.io/gitea/services/user"`
### 重要注意事項
- 永遠不要寫成`x.Update(exemplar)`，而沒有明確的`WHERE`子句：
- 這將導致表中的所有行都被使用 exemplar 的非零值進行更新，包括 ID。
- 通常應該寫成`x.ID(id).Update(exemplar)`。
- 如果在遷移過程中使用`x.Insert(exemplar)`向表中插入記錄，而 ID 是預設的：
- 對於 MSSQL 變體，你將需要執行`` SET IDENTITY_INSERT `table` ON ``（否則遷移將失敗）
- 對於 PostgreSQL，你還需要更新 ID 序列，否則遷移將悄無聲息地通過，但後續的插入將失敗：
`` SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false) ``
### 未來的任務
目前，我們正在進行一些重構，以完成以下任務：
- 糾正不符合規則的程式碼。
- `models`中的文件太多了，所以我們正在將其中的一些移動到子包`models/xxx`中。
- 由於它們依賴於`models`，因此應將某些`modules`子包移動到`services`中。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/contributing/guidelines-frontend.md
+149
View File
@@ -0,0 +1,149 @@
---
date: "2023-05-25T16:00:00+02:00"
slug: "guidelines-frontend"
sidebar_position: 20
aliases:
- /zh-tw/guidelines-frontend
---
# 前端開發指南
## 背景
Gitea 在其前端中使用[Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html)（基於[jQuery](https://api.jquery.com)）和 [Vue3](https://vuejs.org/)。
HTML 頁面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。
源文件可以在以下目錄中找到：
- **CSS 樣式**： `web_src/css/`
- **JavaScript 文件**： `web_src/js/`
- **Vue 元件**： `web_src/js/components/`
- **Go HTML 模板**： `templates/`
## 通用準則
我們推薦使用[Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)和[Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)。
## Gitea 特定準則
1. 每個功能（Fomantic-UI/jQuery 模組）應放在單獨的文件/目錄中。
2. HTML 的 id 和 class 應使用 kebab-case，最好包含 2-3 個與功能相關的關鍵詞。
3. 在 JavaScript 中使用的 HTML 的 id 和 class 應在整個專案中是唯一的，並且應包含 2-3 個與功能相關的關鍵詞。建議在僅在 JavaScript 中使用的 class 中使用 `js-` 前綴。
4. 不應覆蓋框架提供的 class 的 CSS 樣式。始終使用具有 2-3 個與功能相關的關鍵詞的新 class 名稱來覆蓋框架樣式。Gitea 中的幫助 CSS 類在 `helpers.less` 中。
5. 後端可以透過使用`ctx.PageData["myModuleData"] = map[]{}`將複雜資料傳遞給前端，但不要將整個模型暴露給前端，以避免泄露敏感資料。
6. 簡單頁面和與 SEO 相關的頁面使用 Go HTML 模板渲染生成靜態的 Fomantic-UI HTML 輸出。複雜頁面可以使用 Vue3。
7. 明確變量類型，優先使用`elem.disabled = true`而不是`elem.setAttribute('disabled', 'anything')`，優先使用`$el.prop('checked', var === 'yes')`而不是`$el.prop('checked', var)`。
8. 使用語義化元素，優先使用`<button class="ui button">`而不是`<div class="ui button">`。
9. 避免在 CSS 中使用不必要的`!important`，如果無法避免，添加註釋解釋為什麼需要它。
10. 避免在一個事件監聽器中混合不同的事件，優先為每個事件使用獨立的事件監聽器。
11. 推薦使用自訂事件名稱前綴`ce-`。
12. 建議使用 Tailwind CSS，它可以透過 `tw-` 前綴獲得，例如 `tw-relative`. Gitea 自身的助手類 CSS 使用 `gt-` 前綴（`gt-ellipsis`），Gitea 自身的私有框架級 CSS 類使用 `g-` 前綴（`g-modal-confirm`）。
13. 儘量避免內聯腳本和樣式，建議將 JS 程式碼放入 JS 文件中並使用 CSS 類。如果內聯腳本和樣式不可避免，請解釋無法避免的原因。
### 可訪問性 / ARIA
在歷史上，Gitea 大量使用了可訪問性不友好的框架 Fomantic UI。
Gitea 使用一些補丁使 Fomantic UI 更具可訪問性（參見 `aria.md`），
但仍然存在許多問題需要大量的工作和時間來修復。
### 框架使用
不建議混合使用不同的框架，這會使程式碼難以維護。
一個 JavaScript 模組應遵循一個主要框架，並遵循該框架的最佳實踐。
推薦的實現方式：
- Vue + Vanilla JS
- Fomantic-UI（jQuery）
- htmx （部分頁面重新加載其他靜態元件）
- Vanilla JS
不推薦的實現方式：
- Vue + Fomantic-UI（jQuery）
- jQuery + Vanilla JS
- htmx + 任何其他需要大量 JavaScript 程式碼或不必要的功能，如 htmx 腳本 (`hx-on`)
為了保持介面一致，Vue 元件可以使用 Fomantic-UI 的 CSS 類。
儘管不建議混合使用不同的框架，
我們使用 htmx 進行簡單的交互。您可以在此 [PR](https://github.com/go-gitea/gitea/pull/28908) 中查看一個簡單交互的範例，其中應使用 htmx。如果您需要更高級的反應性，請不要使用 htmx，請使用其他框架（Vue/Vanilla JS）。
但如果混合使用是必要的，並且程式碼設計良好且易於維護，也可以工作。
### `async` 函數
只有當函數內部存在`await`調用或返回`Promise`時，纔將函數標記為`async`。
不建議使用`async`事件監聽器，這可能會導致問題。
原因是`await`後的程式碼在事件分發之外執行。
參考：https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
如果一個事件監聽器必須是`async`，應在任何`await`之前使用`e.preventDefault()`，
建議將其放在函數的開頭。
如果我們想在非異步上下文中調用`async`函數，
建議使用`const _promise = asyncFoo()`來告訴讀者
這是有意為之的，我們想調用異步函數並忽略 Promise。
一些 lint 規則和 IDE 也會在未處理返回的 Promise 時發出警告。
### 獲取資料
要獲取資料，請使用`modules/fetch.js`中的包裝函數`GET`、`POST`等。他們
接受內容的`data`選項，將自動設定 CSRF 令牌並返回
[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)。
### HTML 屬性和 dataset
禁止使用`dataset`，它的駝峰命名行為使得搜索屬性變得困難。
然而，仍然存在一些特殊情況，因此當前的準則是：
- 對於舊程式碼：
- 應將`$.data()`重構為`$.attr()`。
- 在極少數情況下，可以使用`$.data()`將一些非字符串資料綁定到元素上，但強烈不推薦使用。
- 對於新程式碼：
- 不應使用`node.dataset`，而應使用`node.getAttribute`。
- 不要將任何使用者資料綁定到 DOM 節點上，使用合適的設計模式描述節點和資料之間的關係。
### 顯示/隱藏元素
- 推薦在 Vue 元件中使用`v-if`和`v-show`來顯示/隱藏元素。
- Go 模板程式碼應使用 `.tw-hidden` 和 `showElem()/hideElem()/toggleElem()` 來顯示/隱藏元素，請參閱`.tw-hidden`的註釋以獲取更多詳細資訊。
### Go HTML 模板中的樣式和屬性
建議使用以下方式：
```html
<div
class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}"
{{if
.IsFoo}}data-foo{{end}}
></div>
```
而不是：
```html
<div
class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"
{{if
.IsFoo}}
data-foo{{end}}
></div>
```
以使程式碼更易讀。
### 舊程式碼
許多舊程式碼已經存在於本文撰寫之前。建議重構舊程式碼以遵循指南。
### Vue3 和 JSX
Gitea 現在正在使用 Vue3。我們決定不引入 JSX，以保持 HTML 程式碼和 JavaScript 程式碼分離。
### UI 範例
Gitea 使用一些自制的 UI 元素並自訂其他元素，以將它們更好地整合到通用 UI 方法中。當在開發模式（`RUN_MODE=dev`）下運行 Gitea 時，在 `http(s)://your-gitea-url:port/devtest` 下會提供一個包含一些標準化 UI 範例的頁面。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/contributing/guidelines-refactoring.md
+40
View File
@@ -0,0 +1,40 @@
---
date: "2023-05-25T00:00:00+00:00"
slug: "guidelines-refactoring"
sidebar_position: 20
aliases:
- /zh-tw/guidelines-refactoring
---
# 重構指南
## 背景
自 2014 年 2 月 12 日編寫了第一行程式碼以來，Gitea 已經發展成為一個龐大的專案。
因此，程式碼庫變得越來越大。程式碼庫越大，維護就越困難。
存在許多過時的機制，許多框架混合在一起，一些遺留程式碼可能會導致錯誤並阻礙新功能的開發。
為了使程式碼庫更易於維護，使 Gitea 變得更好，開發人員應牢記使用現代機制來重構舊程式碼。
本文件是關於重構程式碼庫的指南集合。
## 重構建議
- 設計更多關於未來的內容，而不僅僅解決當前問題。
- 減少模糊性，減少衝突，提高可維護性。
- 描述重構，例如：
- 為什麼需要重構。
- 如何解決舊問題。
- 重構的優點/缺點是什麼。
- 只做必要的更改，儘量保留舊邏輯。
- 引入一些中間步驟，使重構更容易審查，完整的重構計劃可以在幾個 PR 中完成。
- 如果存在分歧，應該請 TOC（技術監督委員會）參與決策。
- 添加必要的測試以確保重構的正確性。
- 非錯誤重構優先在里程碑的開始時進行，這樣可以更容易地在發佈之前發現問題。
## 審查和合併建議
- 重構的 PR 不應該長時間保持打開狀態（通常為 7 天），應儘快進行審查。
- 重構的 PR 應儘快合併，不應被其他 PR 阻塞。
- 如果 TOC 沒有異議，重構的 PR 可以在 7 天后由一名核心成員（非作者）批准後合併。
- 如果最終結果良好，容忍一些不完美/臨時的步驟。
- 如果重構是必要的，容忍一些迴歸錯誤，並儘快修復錯誤。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/contributing/localization.md
+25
View File
@@ -0,0 +1,25 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "localization"
sidebar_position: 70
aliases:
- /zh-tw/localization
---
# 本地化
Gitea 的本地化是通過我們的[Crowdin 專案](https://crowdin.com/project/gitea)進行的。
對於對**英語翻譯**的更改，可以發出 pull-request，來更改[英語語言環境](https://github.com/go-gitea/gitea/blob/main/options/locale/locale_en-US.ini)中合適的關鍵字。
有關對**非英語**翻譯的更改，請參閱上面的 Crowdin 專案。
## 支援的語言
上述 Crowdin 專案中列出的任何語言一旦翻譯了 25% 或更多都將得到支援。
翻譯被接受後，它將在下一次 Crowdin 同步後反映在主儲存庫中，這通常是在任何 PR 合併之後。
在撰寫本文時，這意味著更改後的翻譯可能要到 Gitea 的下一個版本纔會出現。
如果使用開發版本，則在同步更改內容後，它應該會在更新後立即顯示。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/development/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "開發",
"position": 40,
"link": {
"type": "generated-index",
"slug": "/development",
"title": "開發"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/development/api-usage.md
+65
View File
@@ -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 即可。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/development/hacking-on-gitea.md
+334
View File
@@ -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。
[![在 Gitpod 中打開](/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/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。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/development/integrations.md
+37
View File
@@ -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!
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/development/migrations.md
+31
View File
@@ -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)中找到這些介面。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/development/oauth2-provider.md
+128
View File
@@ -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** | 完全控制所有儲存庫 |
| &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](/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 請求](api-usage) 以讀寫使用者的資源。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/help/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "幫助",
"position": 5,
"link": {
"type": "generated-index",
"slug": "/help",
"title": "幫助"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/help/faq.md
+435
View File
@@ -0,0 +1,435 @@
---
date: "2023-05-25T16:00:00+02:00"
slug: "faq"
sidebar_position: 5
aliases:
- /zh-tw/faq
---
# 常見問題
本頁面包含一些常見問題和答案。
有關更多幫助資源，請查看所有[支援選項](help/support.md)。
## 1.x 和 1.x.x 下載之間的區別
以 1.7.x 版本為例。
**注意：**此範例也適用於 Docker 鏡像！
在我們的[下載頁面](https://dl.gitea.com/gitea/)上，您會看到一個 1.7 目錄，以及 1.7.0、1.7.1、1.7.2、1.7.3、1.7.4、1.7.5 和 1.7.6 的目錄。
1.7 目錄和 1.7.0 目錄是**不同**的。1.7 目錄是在每個合併到[`release/v1.7`](https://github.com/go-gitea/gitea/tree/release/v1.7)分支的提交上構建的。
然而，1.7.0 目錄是在建立[`v1.7.0`](https://github.com/go-gitea/gitea/releases/tag/v1.7.0)標籤時建立的構建。
這意味著 1.x 的下載會隨著提交合併到各自的分支而改變（將其視為每個版本的單獨的“main”分支）。
另一方面，1.x.x 的下載應該永遠不會改變。
## 如何從 Gogs/GitHub 等遷移到 Gitea
要從 Gogs 遷移到 Gitea：
- [Gogs 版本 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
要從 GitHub 遷移到 Gitea，您可以使用 Gitea 內置的遷移表單。
為了遷移諸如問題、拉取請求等專案，您需要至少輸入您的使用者名稱。
[Example (requires login)](https://demo.gitea.com/repo/migrate)
要從 GitLab 遷移到 Gitea，您可以使用這個非關聯的工具：
https://github.com/loganinak/MigrateGitlabToGogs
<a id="where-does-gitea-store-what-file"></a>
<a id="Gitea儲存文件的位置"></a>
## Gitea 儲存文件的位置
- _`AppWorkPath`_
- `--work-path`標誌
- 或者環境變量`GITEA_WORK_DIR`
- 或者在構建時設定的內置值
- 或者包含 Gitea 二進制文件的目錄
- `%(APP_DATA_PATH)`（資料庫、索引器等的預設路徑）
- `app.ini`中的`APP_DATA_PATH`
- 或者*`AppWorkPath`*`/data`
- _`CustomPath`_（自訂模板）
- `--custom-path`標誌
- 或者環境變量`GITEA_CUSTOM`
- 或者在構建時設定的內置值
- 或者*`AppWorkPath`*`/custom`
- HomeDir
- Unix：環境變量`HOME`
- Windows：環境變量`USERPROFILE`，或者環境變量`HOMEDRIVE`+`HOMEPATH`
- RepoRootPath
- `app.ini`中\[repository]部分的`ROOT`（如果是絕對路徑）
- 否則*`AppWorkPath`*`/ROOT`(如果`app.ini`中\[repository]部分的`ROOT`是相對路徑）
- 預設值為`%(APP_DATA_PATH)/gitea-repositories`
- INI（設定文件）
- `--config`標誌
- 或者在構建時設定的可能內置值
- 或者 _`CustomPath`_`/conf/app.ini`
- SQLite 資料庫
- app.ini 中 database 部分的 PATH
- 或者`%(APP_DATA_PATH)/gitea.db`
## 看不到克隆 URL 或克隆 URL 不正確
有幾個地方可能會導致顯示不正確。
1. 如果使用反向代理，請確保按照[反向代理指南](../administration/reverse-proxies.md)中的正確說明進行設定。
2. 確保在`app.ini`的`server`部分中正確設定了`ROOT_URL`。
如果某些克隆選項未顯示（HTTP/S 或 SSH），可以在`app.ini中`
- `DISABLE_HTTP_GIT`: 如果設為 true, 將會沒有 HTTP/HTTPS 鏈接
- `DISABLE_SSH`: 如果設為 true, 將會沒有 SSH 鏈接
- `SSH_EXPOSE_ANONYMOUS`: 如果設為 false, SSH 鏈接將會對匿名使用者隱藏
## 文件上傳失敗：413 Request Entity Too Large
當反向代理限制文件上傳大小時，會出現此錯誤。
有關使用 nginx 解決此問題，請參閱[反向代理指南](../administration/reverse-proxies.md)。
## 自訂模板無法加載或運行錯誤
Gitea 的自訂模板必須將其添加到正確的位置，否則 Gitea 將無法找到並使用自訂模板。
模板的正確路徑應該相對於`CustomPath`。
1. 要找到`CustomPath`，請在站點管理 -> 設定 中查找自訂文件根路徑。
如果找不到，請嘗試`echo $GITEA_CUSTOM`。
2. 如果仍然找不到，預設值可以被計算
3. 如果仍然找不到路徑，則可以參考[自訂 Gitea](../administration/customizing-gitea.md)頁面，將模板添加到正確的位置。
## Gitea 是否有"GitHub/GitLab Pages"功能？
Gitea 不提供內置的 Pages 伺服器。您需要一個專用的域名來提供靜態頁面，以避免 CSRF 安全風險。
對於簡單的用法，您可以使用反向代理來重寫和提供 Gitea 的原始文件 URL 中的靜態內容。
還有一些已經可用的第三方服務，比如獨立[pages server](https://codeberg.org/Codeberg/pages-server)的或[caddy plugin](https://github.com/42wim/caddy-gitea)，可以提供所需的功能。
## 活躍使用者與禁止登入使用者
在 Gitea 中，"活躍使用者"是指通過電子郵件激活其帳戶的使用者。
"禁止登入使用者"是指不允許再登入到 Gitea 的使用者。
## 設定日誌記錄
- [官方文件](../administration/logging-config.md)
## 什麼是 Swagger？
[Swagger](https://swagger.io/) 是 Gitea 用於其 API 文件的工具。
所有 Gitea 實例都有內置的 API，無法完全禁用它。
但是，您可以在 app.ini 的 api 部分將 ENABLE_SWAGGER 設定為 false，以禁用其文件顯示。
有關更多資訊，請參閱 Gitea 的[API 文件](development/api-usage.md)。
您可以在上查看最新的 API（例如）https://gitea.com/api/swagger
您還可以在上查看`swagger.json`文件的範例 https://gitea.com/swagger.v1.json
## 調整伺服器用於公共/私有使用
### 防止垃圾郵件發送者
有多種方法可以組合使用來防止垃圾郵件發送者：
1. 通過設定電子郵件域名的白名單或黑名單。
2. 通過設定一些域名或者 OpenID 白名單（見下文）。
3. 在您的`app.ini`中將`ENABLE_CAPTCHA`設定為`true`，並正確設定`RECAPTCHA_SECRET`和 `RECAPTCHA_SITEKEY`。
4. 將`DISABLE_REGISTRATION`設定為`true`，並通過 [CLI](../administration/command-line.md)、[API](development/api-usage.md) 或 Gitea 的管理介面建立新使用者。
### 僅允許/阻止特定的電子郵件域名
您可以在`app.ini`中的`[service]`下的設定`EMAIL_DOMAIN_WHITELIST` 或 `EMAIL_DOMAIN_BLOCKLIST`。
### 僅允許/阻止特定的 OpenID 提供商
您可以在`app.ini`的`[openid]`下設定`WHITELISTED_URI`或`BLACKLISTED_URIS`。
**注意**： 白名單優先，如果白名單非空，則忽略黑名單。
### 僅允許發佈問題的使用者
目前實現這一點的方法是建立/修改一個具有最大儲存庫建立限制為 0 的使用者。
### 受限制的使用者
受限制的使用者僅能訪問其組織/團隊成員和協作所在的內容的子集，而忽略組織/儲存庫等的公共標誌。
範例用例：一個公司運行一個需要登入的 Gitea 實例。大多數儲存庫是公開的（所有同事都可以訪問/瀏覽）。
在某些情況下，某個客戶或第三方需要訪問特定的儲存庫，並且只能訪問該儲存庫。通過將此類客戶帳戶設定為受限制帳戶，並使用團隊成員身份和/或協作來授予所需的任何存取權限，可以簡單地實現這一點，而無需使所有內容都變為私有。
### 啟用 Fail2ban
使用 [Fail2Ban](../administration/fail2ban-setup.md) 監視並阻止基於日誌模式的自動登入嘗試或其他惡意行為。
## SSHD vs 內建 SSH
SSHD 是大多數 Unix 系統上內建的 SSH 伺服器。
Gitea 還提供了自己的 SSH 伺服器，用於在 SSHD 不可用時使用。
## Gitea 運行緩慢
導致此問題的最常見原因是加載聯合頭像。
您可以透過在`app.ini`中將`ENABLE_FEDERATED_AVATAR`設定為`false`來關閉此功能。
還有一個可能需要更改的選項是在`app.ini`中將`DISABLE_GRAVATAR`設定為`true`。
## 無法建立儲存庫/文件
請確保 Gitea 具有足夠的權限來寫入其主目錄和資料目錄。
參見AppDataPath 和 RepoRootPath
**適用於 Arch 使用者的注意事項：**在撰寫本文時，Arch 套件的 systemd 文件包含了以下行：
`ReadWritePaths=/etc/gitea/app.ini`
這將使得 Gitea 無法寫入其他路徑。
## 翻譯不正確/如何添加更多翻譯
我們當前的翻譯是在我們的[Crowdin 專案](https://crowdin.com/project/gitea)上眾包進行的
無論您想要更改翻譯還是添加新的翻譯，都需要在 Crowdin 整合中進行，因為所有翻譯都會被 CI 覆蓋。
## 推送鉤子/ Webhook / Actions 未運行
如果您可以推送但無法在主頁儀表板上看到推送活動，或者推送不觸發 Webhook 和 Actions，可能是 git 鉤子不工作而導致的。
這可能是由於以下原因：
1. Git 鉤子不同步：在站點管理面板上運行“重新同步所有儲存庫的 pre-receive、update 和 post-receive 鉤子”
2. Git 儲存庫（和鉤子）儲存在一些不支援腳本執行的文件系統上（例如由 NAS 掛載），請確保文件系統支援`chmod a+x any-script`
3. 如果您使用的是 Docker，請確保 Docker Server（而不是客戶端）的版本 >= 20.10.6
## SSH 問題
如果無法通過`ssh`訪問儲存庫，但`https`正常工作，請考慮以下情況。
首先，請確保您可以透過 SSH 訪問 Gitea。
`ssh [email protected]`
如果連接成功，您應該會收到以下錯誤消息：
```
Hi there, You've successfully authenticated, but Gitea does not provide shell access.
If this is unexpected, please log in with password and setup Gitea under another user.
```
如果您收到以上消息但仍然連接成功，這意味著您的 SSH 密鑰**沒有**由 Gitea 管理。這意味著鉤子不會運行，在其他一些潛在問題中也包括在內。
如果您無法連接，可能是因為您的 SSH 密鑰在本地設定不正確。
這是針對 SSH 而不是 Gitea 的問題，因此在此不涉及。
### SSH 常見錯誤
```
Permission denied (publickey).
fatal: Could not read from remote repository.
```
此錯誤表示伺服器拒絕登入嘗試，
請檢查以下事項：
- 在客戶端：
- 確保公鑰和私鑰已添加到正確的 Gitea 使用者。
- 確保遠程 URL 中沒有任何問題。特別是，請確保 ∂
Git 使用者（@ 之前的部分）的名稱拼寫正確。
- 確保客戶端機器上的公鑰和私鑰正確無誤。
- 在伺服器上：
- 確保儲存庫存在並且命名正確。
- 檢查系統使用者主目錄中的 `.ssh` 目錄的權限。
- 驗證正確的公鑰是否已添加到 `.ssh/authorized_keys` 中。
嘗試在 Gitea 管理面板上運行
`Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)`。
- 查看 Gitea 日誌。
- 查看 /var/log/auth（或類似的文件）。
- 檢查儲存庫的權限。
以下是一個範例，其中缺少公共 SSH 密鑰，
認證成功，但是其他設定導致 SSH 無法訪問正確的
儲存庫。
```
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
```
在這種情況下，請檢查以下設定：
- 在伺服器上：
- 確保`git`系統使用者設定了可用的 shell
- 使用`getent passwd git | cut -d: -f7`進行驗證
- 可以使用`usermod`或`chsh`進行修改。
- 確保`.ssh/authorized_keys`中的`gitea serv`命令使用
正確的設定文件。
## 遷移帶有標籤的儲存庫後缺失發佈版本
要遷移帶有所有標籤的儲存庫，您需要執行兩個操作：
- 推送標籤到儲存庫：
```
git push --tags
```
- 在 Gitea 中重新同步所有儲存庫的標籤：
```
gitea admin repo-sync-releases
```
## LFS 問題
針對涉及 LFS 資料上傳的問題
```
batch response: Authentication required: Authorization error: <GITEA_LFS_URL>/info/lfs/objects/batch
Check that you have proper access to the repository
error: failed to push some refs to '<GIT_REPO_URL>'
```
檢查`app.ini`文件中的`LFS_HTTP_AUTH_EXPIRY`值。
預設情況下，LFS 令牌在 20 分鐘後過期。如果您的連接速度較慢或文件較大（或兩者都是），可能無法在時間限制內完成上傳。
您可以將此值設定為`60m`或`120m`。
## 如何在啟動 Gitea 之前建立使用者
Gitea 提供了一個子命令`gitea migrate`來初始化資料庫，然後您可以使用[管理 CLI 命令](../administration/command-line.md#admin)像正常情況下添加使用者。
## 如何啟用密碼重置
沒有密碼重置的設定。當設定了[郵件服務](../administration/email-setup.md)時，密碼重置將自動啟用；否則將被禁用。
## 如何更改使用者的密碼
- 作為管理員，您可以更改任何使用者的密碼（並可選擇強制其在下次登入時更改密碼）...
- 轉到您的`站點管理 -> 用戶賬戶`頁面並編輯使用者。
- 使用[管理 CLI 命令](../administration/command-line.md#admin)。
請注意，大多數命令還需要一個[全域標誌](../administration/command-line.md#全域選項)來指向正確的設定。
- 作為**使用者**，您可以更改密碼...
- 在您的帳號的`設定 -> 帳號`頁面（此方法**需要**您知道當前密碼）。
- 使用`忘記密碼`鏈接。
如果`忘記密碼/賬戶恢復`頁面被禁用，請聯繫管理員設定[郵件服務](../administration/email-setup.md)。
## 為什麼我的 Markdown 顯示錯誤
在 Gitea 版本 `1.11` 中，我們轉換為使用[goldmark](https://github.com/yuin/goldmark)進行 Markdown 渲染，它符合[CommonMark](https://commonmark.org/)標準。
如果您在版本`1.11`之前的 Markdown 正常工作，但在升級後無法正常工作，請仔細閱讀 CommonMark 規範，看看問題是由錯誤還是非相容的語法引起的。
如果是後者，通常規範中會列出一種符合標準的替代方法。
## 使用 MySQL 進行升級時出現的錯誤
如果在使用 MySQL 升級 Gitea 時收到以下錯誤：
> `ORM engine initialization failed: migrate: do migrate: Error: 1118: Row size too large...`
請運行 `gitea doctor convert` 或對資料庫中的每個表運行 `ALTER TABLE table_name ROW_FORMAT=dynamic;`。
潛在問題是預設行格式分配給每個表的索引空間
太小。Gitea 要求其表的`ROWFORMAT`為`DYNAMIC`。
如果收到包含`Error 1071: Specified key was too long; max key length is 1000 bytes...`
的錯誤行，則表示您正在嘗試在使用 ISAM 引擎的表上運行 Gitea。儘管在先前版本的 Gitea 中可能是湊巧能夠工作的，但它從未得到官方支援，
您必須使用 InnoDB。您應該對資料庫中的每個表運行`ALTER TABLE table_name ENGINE=InnoDB;`。
## 為什麼 Emoji 只顯示佔位符或單色圖像
Gitea 需要系統或瀏覽器安裝其中一個受支援的 Emoji 字體，例如 Apple Color Emoji、Segoe UI Emoji、Segoe UI Symbol、Noto Color Emoji 和 Twemoji Mozilla。通常，操作系統應該已經提供了其中一個字體，但特別是在 Linux 上，可能需要手動安裝它們。
## SystemD 和 Docker 上的標準輸出日誌
SystemD 上的標準輸出預設會寫入日誌記錄中。您可以嘗試使用 `journalctl`、`journalctl -u gitea` 或 `journalctl <path-to-gitea-binary>`來查看。
類似地，Docker 上的標準輸出可以使用`docker logs <container>`來查看。
要收集日誌以進行幫助和問題報告，請參閱[支援選項](help/support.md)。
## 初始日誌記錄
在 Gitea 讀取設定文件並設定其日誌記錄之前，它會將一些內容記錄到標準輸出，以幫助調試日誌記錄無法工作的情況。
您可以透過設定`--quiet`或`-q`選項來停止此日誌記錄。請注意，這只會在 Gitea 設定自己的日誌記錄之前停止日誌記錄。
如果您報告了錯誤或問題，必須提供這些資訊以恢復初始日誌記錄。
只有在完全設定了所有內容之後，您才應該設定此選項。
## 在資料庫啟動期間出現有關結構預設值的警告
有時，在遷移過程中，舊列和預設值可能在資料庫架構中保持不變。
這可能會導致警告，例如：
```
2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync() [W] Table user Column keep_activity_private db default is , struct default is 0
```
可以安全地忽略這些警告，但您可以透過讓 Gitea 重新建立這些表來停止這些警告，使用以下命令：
```
gitea doctor recreate-table user
```
這將導致 Gitea 重新建立使用者表並將舊資料複製到新表中，
並正確設定預設值。
您可以使用以下命令要求 Gitea 重新建立多個表：
```
gitea doctor recreate-table table1 table2 ...
```
如果您希望 Gitea 重新建立所有表，請使用以下命令：
```
gitea doctor recreate-table
```
在運行這些命令之前，強烈建議您備份資料庫。
## 為什麼查看文件時製表符/縮進顯示錯誤
如果您正在使用 Cloudflare，請在儀表板中關閉自動縮小選項。
`Speed` -> `Optimization` -> 在 `Auto-Minify` 設定中取消選中 `HTML`。
## 如何從磁盤採用儲存庫
- 將您的（裸）儲存庫添加到正確的位置，即您的設定所在的地方（`repository.ROOT`），確保它們位於正確的佈局`<REPO_ROOT>/[user]/[repo].git`。
- **注意：**目錄名必須為小寫。
- 您還可以在`<ROOT_URL>/admin/config`中檢查儲存庫根路徑。
- 確保存在要採用儲存庫的使用者/組織。
- 作為管理員，轉到`<ROOT_URL>/admin/repos/unadopted`並搜索。
- 使用者也可以透過設定[`ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES`](../administration/config-cheat-sheet.md) 獲得類似的權限。
- 如果上述步驟都正確執行，您應該能夠選擇要採用的儲存庫。
- 如果沒有找到儲存庫，請啟用[調試日誌記錄](../administration/config-cheat-sheet.md)以檢查是否有特定錯誤。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/help/support.md
+69
View File
@@ -0,0 +1,69 @@
---
date: "2017-01-20T15:00:00+08:00"
slug: "support"
sidebar_position: 20
aliases:
- /zh-tw/seek-help
---
# 支援選項
- [付費商業支援](https://about.gitea.com/)
- [Discord](https://discord.gg/Gitea)
- [論壇](https://forum.gitea.com/)
- [Matrix](https://matrix.to/#/#gitea-space:matrix.org)
- 注意：大多數 Matrix 頻道都與 Discord 中的對應頻道橋接，可能在橋接過程中會出現一定程度的不穩定性。
- 中文支援
- [Discourse 中文分類](https://forum.gitea.com/c/5-category/5)
- QQ 群 328432459
# Bug 報告
如果您發現了 Bug，請在 GitHub 上 [建立一個問題](https://github.com/go-gitea/gitea/issues)。
**注意：** 在請求支援時，可能需要準備以下資訊，以便幫助者獲得所需的所有資訊：
1. 您的 `app.ini`（將任何敏感資料進行必要的清除）。
2. 您看到的任何錯誤消息。
3. Gitea 日誌以及與情況相關的所有其他日誌。
- 收集 `trace` / `debug` 級別的日誌更有用（參見下一節）。
- 在使用 systemd 時，使用 `journalctl --lines 1000 --unit gitea` 收集日誌。
- 在使用 Docker 時，使用 `docker logs --tail 1000 <gitea-container>` 收集日誌。
4. 可重現的步驟，以便他人能夠更快速、更容易地重現和理解問題。
- [demo.gitea.com](https://demo.gitea.com) 可用於重現問題。
5. 如果遇到慢速/掛起/死鎖等問題，請在出現問題時報告堆棧跟蹤。
轉到 "Site Admin" -> "Monitoring" -> "Stacktrace" -> "Download diagnosis report"。
# 高級 Bug 報告提示
## 更多日誌的設定選項
預設情況下，日誌以 `info` 級別輸出到控制檯。
如果您需要設定日誌級別和/或從文件中收集日誌，
您只需將以下設定複製到您的 `app.ini` 中（刪除所有其他 `[log]` 部分），
然後您將在 Gitea 的日誌目錄中找到 `*.log` 文件（預設為 `%(GITEA_WORK_DIR)/log`）。
```ini
; 要顯示所有 SQL 日誌，您還可以在 [database] 部分中設置 LOG_SQL=true
[log]
LEVEL=debug
MODE=console,file
```
## 使用命令行收集堆棧跟蹤
Gitea 可以使用 Golang 的 pprof 處理程式和工具鏈來收集堆棧跟蹤和其他運行時資訊。
如果 Web UI 停止工作，您可以嘗試通過命令行收集堆棧跟蹤：
1. 設定 app.ini：
```
[server]
ENABLE_PPROF = true
```
2. 重新啟動 Gitea
3. 嘗試觸發 bug，當請求卡住一段時間，使用或瀏覽器訪問：獲取堆棧跟蹤。
`curl http://127.0.0.1:6060/debug/pprof/goroutine?debug=1`
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/index.md
+73
View File
@@ -0,0 +1,73 @@
---
date: "2016-11-08T16:00:00+02:00"
slug: /
sidebar_position: 10
---
# 關於 Gitea
Gitea 是一個輕量級的 DevOps 平台軟體。從開發計劃到產品成型的整個軟體生命週期，他都能夠高效而輕鬆地幫助團隊和開發者。包括 Git 託管、程式碼審查、團隊協作、套件註冊和 CI/CD。它與 GitHub、Bitbucket 和 GitLab 等比較類似。
Gitea 最初是從 [Gogs](http://gogs.io) 分支而來，幾乎所有程式碼都已更改。對於我們 Fork 的原因可以看
[這裡](https://blog.gitea.com/welcome-to-gitea/)。
## 目標
Gitea 的首要目標是建立一個極易安裝，運行非常快速，安裝和使用體驗良好的自建 Git 服務。
採用 Go 作為後端語言，只需生成一個可執行程式即可。
支援 Linux, macOS 和 Windows 等多平台，
支援主流的 x86，amd64、
ARM 和 PowerPC 等架構。
## 功能特性
- 程式碼託管：Gitea 支援建立和管理儲存庫、瀏覽提交歷史和程式碼檔案、審查和合併程式碼提交、管理協作者、管理分支等。它還支援許多常見的 Git 特性，例如標籤、Cherry-pick、hook、整合協作工具等。
- 輕量級和快速：Gitea 的設計目標之一就是輕量級和快速響應。它不像一些大型的程式碼託管平台那樣臃腫，因此在性能方面表現出色，適用於資源有限的伺服器環境。由於其輕量級設計，Gitea 在資源消耗方面相對較低，可以在資源有限的環境下運行良好。
- 易於部署和維護：輕鬆地部署在各種伺服器上，不需要複雜的設定和依賴。這使得個人開發者或小團隊可以方便地設定和管理自己的 Git 服務。
- 安全性：Gitea 注重安全性，提供了使用者權限管理、存取控制清單等功能，可以確保程式碼和資料的安全性。
- 程式碼評審：程式碼評審同時支援 Pull Request workflow 和 AGit workflow。評審人可以在線瀏覽程式碼，並提交評審意見或問題。提交者可以接收到評審意見，並在線回復或修改程式碼。程式碼評審可以幫助使用者和企業提高程式碼質量。
- CI/CD：Gitea Actions 支援 CI/CD 功能，該功能相容 GitHub Actions，使用者可以採用熟悉的 YAML 格式編寫 workflows，也可以重用大量的已有的 Actions 外掛。Actions 外掛支援從任意的 Git 網站中下載。
- 專案管理：Gitea 透過看板和工單來跟蹤一個專案的需求，功能和 bug。工單支援分支，標籤、里程碑、指派、時間跟蹤、到期時間、依賴關係等功能。
- 製品庫：Gitea 支援超過 20 種不同種類的公有或私有套件管理，包括：Cargo, Chef, Composer, Conan, Conda, Container, Helm, Maven, npm, NuGet, Pub, PyPI, RubyGems, Vagrant 等
- 開源社區支援：Gitea 是一個基於 MIT 許可證的開源專案，Gitea 擁有一個活躍的開源社區，能夠持續地進行開發和改進，同時也積極接受社區貢獻，保持了平台的更新和創新。
- 多語言支援：Gitea 提供多種語言介面，適應全球範圍內的使用者，促進了國際化和本地化。
更多功能特性：詳見：https://docs.gitea.com/installation/comparison#general-features
## 系統要求
- 樹莓派 Pi3 功能強大，足以運行 Gitea 來處理小型工作負載。
- 對於小型團隊/專案而言，2 個 CPU 內核和 1GB 內存通常就足夠了。
- 在 UNIX 系統上，Gitea 應使用專用的非 root 系統帳號運行。
- 注意：Gitea 管理 `~/.ssh/authorized_keys` 文件。以普通使用者身份運行 Gitea 可能會破壞該使用者的登入能力。
- [Git](https://git-scm.com/) 需要 2.0.0 或更高版本。
- [Git Large File Storage](https://git-lfs.github.com/) 如果啟用，且 Git 版本大於等於 2.1.2，則該選項可用
- 如果 Git 版本大於等於 2.18，將自動啟用 Git 提交歷史圖形化展示功能
## 瀏覽器支援
- 最後 2 個版本的 Chrome、Firefox、Safari 和 Edge
- Firefox ESR
## 技術棧
- Web 框架：[Chi](http://github.com/go-chi/chi)
- ORM：[XORM](https://xorm.io)
- UI 框架：
- [jQuery](https://jquery.com)
- [Fomantic UI](https://fomantic-ui.com)
- [Vue3](https://vuejs.org)
- 更多元件參見 package.json
- 編輯器：
- [CodeMirror](https://codemirror.net)
- [EasyMDE](https://github.com/Ionaru/easy-markdown-editor)
- [Monaco Editor](https://microsoft.github.io/monaco-editor)
- 資料庫驅動：
- [github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)
- [github.com/lib/pq](https://github.com/lib/pq)
- [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
- [github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb)
## 整合支援
請前往 [Awesome Gitea](https://gitea.com/gitea/awesome-gitea/) 獲得更多的第三方整合支援
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "安裝",
"position": 10,
"link": {
"type": "generated-index",
"slug": "/installation",
"title": "安裝"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/comparison.md
+140
View File
@@ -0,0 +1,140 @@
---
date: "2019-02-14T11:51:04+08:00"
slug: "comparison"
sidebar_position: 5
aliases:
- /zh-tw/comparison
---
# 對比 Gitea 與其它 Git 託管工具
這裡列出了 Gitea 與其它一些 Git 託管工具之間的異同，以便確認 Gitea 是否能夠滿足您的需求。
請注意，此列表中的某些表項可能已經過時，因為我們並沒有定期檢查其它產品的功能是否有所更改。你可以前往 [Github issue](https://github.com/go-gitea/gitea/issues) 來幫助我們更新過時的內容，感謝！
_表格中的符號含義:_
- _✓ - 支援_
- _⁄ - 部分支援_
- _✘ - 不支援_
- _⚙️ - 由第三方服務或外掛支援_
#### 主要特性
| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
| -------------------------------- | --------------------------------------------------- | ---- | --------- | --------- | --------- | -------------- | ------------ |
| 開源免費 | ✓ | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ |
| 低資源開銷 (RAM/CPU) | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ |
| 支援多種資料庫 | ✓ | ✓ | ✘ | ⁄ | ⁄ | ✓ | ✓ |
| 支援多種操作系統 | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ |
| 升級簡便 | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ |
| 可觀測性 | **✘** | ✘ | ✓ | ✓ | ✓ | ✓ | ? |
| 支援第三方渲染工具 | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ? |
| WebAuthn (2FA) | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ? |
| 擴展 API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 內置套件/容器註冊中心 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 同步提交到外部儲存庫 (push mirror) | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ |
| 同步外部儲存庫的提交 (pull mirror) | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ? |
| 淺色和深色主題 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ? |
| 自訂主題支援 | ✓ | ✓ | ✘ | ✘ | ✘ | ✓ | ✘ |
| 支援 Markdown | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 支援 CSV | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | ? |
| Git 驅動的靜態 pages | [⚙️][gitea-pages-server], [⚙️][gitea-caddy-plugin] | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Git 驅動的整合化 wiki | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (cloud only) | ✘ |
| 部署令牌 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 儲存庫寫權限令牌 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| RSS Feeds | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ | ✘ |
| 內置 CI/CD | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 子組織：組織內的組織 | [✘](https://github.com/go-gitea/gitea/issues/1872) | ✘ | ✘ | ✓ | ✓ | ✘ | ✓ |
| 多實例交互 | [/](https://github.com/go-gitea/gitea/issues/18240) | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ |
| Markdown 繪圖 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Markdown 數學公式 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
#### 程式碼管理
| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
| -------------------- | --------------------------------------------------- | ---- | --------- | --------- | --------- | --------- | ------------ |
| 儲存庫主題描述 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 儲存庫內程式碼搜索 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 全域程式碼搜索 | ✓ | ✘ | ✓ | ✘ | ✓ | ✓ | ✓ |
| Git LFS 2.0 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 組織里程碑 | [✘](https://github.com/go-gitea/gitea/issues/14622) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 細粒度使用者角色 | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 提交人的身份驗證 | ⁄ | ✘ | ? | ✓ | ✓ | ✓ | ✘ |
| GPG 簽名的提交 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| SSH 簽名的提交 | ✓ | ✘ | ✓ | ✓ | ✓ | ? | ? |
| 拒絕未通過驗證的提交 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 外部儲存庫遷移 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 儲存庫活躍度頁面 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 分支管理 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 建立新分支 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 在線程式碼編輯 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 提交的統計圖表 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 模板儲存庫 | ✓ | ✘ | ✓ | ✘ | ✓ | ✓ | ✘ |
| Git Blame | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 可視化鏡像變化 | ✓ | ✘ | ✓ | ? | ? | ? | ? |
#### 工單管理
| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
| ------------------- | -------------------------------------------------- | --------------------------------------------- | --------- | ----------------------------------------------------------------------- | --------- | -------------- | ------------ |
| 工單跟蹤 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (cloud only) | ✘ |
| 工單模板 | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 標籤 | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 時間跟蹤 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 支援多個負責人 | ✓ | ✘ | ✓ | ✘ | ✓ | ✘ | ✘ |
| 關聯的工單 | ✘ | ✘ | ⁄ | [✓](https://docs.gitlab.com/ce/user/project/issues/related_issues.html) | ✓ | ✘ | ✘ |
| 私密工單 | [✘](https://github.com/go-gitea/gitea/issues/3217) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 評論反饋 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 鎖定討論 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 工單批處理 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 工單看板 | [✓](https://github.com/go-gitea/gitea/pull/8346) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 從工單建立分支 | ✘ | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 從評論建立工單 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 工單搜索 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 工單全域搜索 | [✘](https://github.com/go-gitea/gitea/issues/2434) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 工單依賴關係 | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | ✘ |
| 通過 Email 建立工單 | [✘](https://github.com/go-gitea/gitea/issues/6226) | [✘](https://github.com/gogs/gogs/issues/2602) | ✘ | ✓ | ✓ | ✓ | ✘ |
| 服務檯 | [✘](https://github.com/go-gitea/gitea/issues/6219) | ✘ | ✘ | [✓](https://gitlab.com/groups/gitlab-org/-/epics/3103) | ✓ | ✘ | ✘ |
#### Pull/Merge requests
| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
| ------------------------------------ | -------------------------------------------------- | ---- | --------- | --------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------ | ------------ |
| Pull/Merge requests | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Squash merging | ✓ | ✘ | ✓ | [✓](https://docs.gitlab.com/ce/user/project/merge_requests/squash_and_merge.html) | ✓ | ✓ | ✓ |
| Rebase merging | ✓ | ✓ | ✓ | ✘ | ⁄ | ✘ | ✓ |
| 評論 Pull/Merge request 中的某行程式碼 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 指定 Pull/Merge request 的審覈人 | ✓ | ✘ | ⁄ | ✓ | ✓ | ✓ | ✓ |
| 解決 Merge 衝突 | [✘](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 限制某些使用者的 push 和 merge 權限 | ✓ | ✘ | ✓ | ⁄ | ✓ | ✓ | ✓ |
| 回退某些 commits 或 merge request | [✓](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| Pull/Merge requests 模板 | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 查看 Cherry-picking 的更改 | [✓](https://github.com/go-gitea/gitea/issues/5158) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ |
| 下載 Patch | ✓ | ✘ | ✓ | ✓ | ✓ | [/](https://jira.atlassian.com/plugins/servlet/mobile#issue/BCLOUD-8323) | ✘ |
| Merge queues | ✘ | ✘ | ✓ | ✘ | ✓ | ✘ | ✘ |
#### 第三方整合
| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
| -------------------------- | -------------------------------------------------- | --------------------------------------------- | --------- | --------- | --------- | --------- | ------------ |
| 支援 Webhook | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 自訂 Git 鉤子 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 整合 AD / LDAP | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 支援多個 LDAP / AD 服務 | ✓ | ✓ | ✘ | ✘ | ✓ | ✓ | ✓ |
| LDAP 使用者同步 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| SAML 2.0 service provider | [✘](https://github.com/go-gitea/gitea/issues/5512) | [✘](https://github.com/gogs/gogs/issues/1221) | ✓ | ✓ | ✓ | ✓ | ✘ |
| 支援 OpenId 連接 | ✓ | ✘ | ✓ | ✓ | ✓ | ? | ✘ |
| 整合 OAuth 2.0（外部授權） | ✓ | ✘ | ⁄ | ✓ | ✓ | ? | ✓ |
| 作為 OAuth 2.0 provider | [✓](https://github.com/go-gitea/gitea/pull/5378) | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 二次驗證 (2FA) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 整合 Mattermost/Slack | ✓ | ✓ | ⁄ | ✓ | ✓ | ⁄ | ✓ |
| 整合 Discord | ✓ | ✓ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 整合 Microsoft Teams | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✘ |
| 顯示外部 CI/CD 的狀態 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
[gitea-caddy-plugin]: https://github.com/42wim/caddy-gitea
[gitea-pages-server]: https://codeberg.org/Codeberg/pages-server
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/database-preparation.md
+300
View File
@@ -0,0 +1,300 @@
---
date: "2020-01-16"
slug: "database-prep"
sidebar_position: 10
aliases:
- /zh-tw/database-prep
---
# 資料庫準備
在使用 Gitea 前，您需要準備一個資料庫。Gitea 支援 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（內置） 和 MSSQL（>= 2012 SP4）這幾種資料庫。本頁將指導您準備資料庫。由於 PostgreSQL 和 MySQL 在生產環境中被廣泛使用，因此本文件將僅涵蓋這兩種資料庫。如果您計劃使用 SQLite，則可以忽略本章內容。
如果您使用不受支援的資料庫版本，請通過 [聯繫我們](/help/support) 以獲取有關我們的擴展支援的資訊。我們可以為舊資料庫提供測試和支援，並將這些修復整合到 Gitea 程式碼庫中。
資料庫實例可以與 Gitea 實例在相同機器上（本地資料庫），也可以與 Gitea 實例在不同機器上（遠程資料庫）。
注意：以下所有步驟要求您的選擇的資料庫引擎已安裝在您的系統上。對於遠程資料庫設定，請在資料庫實例上安裝伺服器應用程式，在 Gitea 伺服器上安裝客戶端程式。客戶端程式用於測試 Gitea 伺服器與資料庫之間的連接，而 Gitea 本身使用 Go 提供的資料庫驅動程式完成相同的任務。此外，請確保伺服器和客戶端使用相同的引擎版本，以使某些引擎功能正常工作。出於安全原因，請使用安全密碼保護 `root`（MySQL）或 `postgres`（PostgreSQL）資料庫超級使用者。以下步驟假設您在資料庫和 Gitea 伺服器上都使用 Linux。
## MySQL/MariaDB
1. 對於遠程資料庫設定，您需要讓 MySQL 監聽您的 IP 地址。編輯資料庫實例上的 `/etc/mysql/my.cnf` 文件中的 `bind-address` 選項為：
```ini
bind-address = 203.0.113.3
```
2. 在資料庫實例上，使用 `root` 使用者登入到資料庫控制檯：
```
mysql -u root -p
```
按提示輸入密碼。
3. 建立一個將被 Gitea 使用的資料庫使用者，並使用密碼進行身份驗證。以下範例中使用了 `'gitea'` 作為密碼。請為您的實例使用一個安全密碼。
對於本地資料庫：
```sql
SET old_passwords=0;
CREATE USER 'gitea' IDENTIFIED BY 'gitea';
```
對於遠程資料庫：
```sql
SET old_passwords=0;
CREATE USER 'gitea'@'192.0.2.10' IDENTIFIED BY 'gitea';
```
其中 `192.0.2.10` 是您的 Gitea 實例的 IP 地址。
根據需要替換上述使用者名稱和密碼。
4. 使用 UTF-8 字符集和大小寫敏感的排序規則建立資料庫。
`utf8mb4_bin` 是 MySQL/MariaDB 的通用排序規則。
Gitea 啟動後會嘗試把資料庫修改為更合適的字符集 (`utf8mb4_0900_as_cs` 或者 `uca1400_as_cs`) 並在可能的情況下更改資料庫。
如果你想指定自己的字符集規則，可以在 `app.ini` 中設定 `[database].CHARSET_COLLATION`。
```sql
CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_bin';
```
根據需要替換資料庫名稱。
5. 將資料庫上的所有權限授予上述建立的資料庫使用者。
對於本地資料庫：
```sql
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea';
FLUSH PRIVILEGES;
```
對於遠程資料庫：
```sql
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'192.0.2.10';
FLUSH PRIVILEGES;
```
6. 通過 `exit` 退出資料庫控制檯。
7. 在您的 Gitea 伺服器上，測試與資料庫的連接：
```
mysql -u gitea -h 203.0.113.3 -p giteadb
```
其中 `gitea` 是資料庫使用者名稱，`giteadb` 是資料庫名稱，`203.0.113.3` 是資料庫實例的 IP 地址。對於本地資料庫，省略 `-h` 選項。
到此您應該能夠連接到資料庫了。
## PostgreSQL
1. 對於遠程資料庫設定，通過編輯資料庫實例上的 postgresql.conf 文件中的 `listen_addresses` 將 `PostgreSQL` 設定為監聽您的 IP 地址：
```ini
listen_addresses = 'localhost, 203.0.113.3'
```
2. PostgreSQL 預設使用 `md5` 質詢-響應加密方案進行密碼身份驗證。現在這個方案不再被認為是安全的。改用 SCRAM-SHA-256 方案，通過編輯資料庫伺服器上的` postgresql.conf` 設定文件：
```ini
password_encryption = scram-sha-256
```
重啟 PostgreSQL 以應用該設定。
3. 在資料庫伺服器上，以超級使用者身份登入到資料庫控制檯：
```
su -c "psql" - postgres
```
4. 建立具有登入權限和密碼的資料庫使用者（在 PostgreSQL 術語中稱為角色）。請使用安全的、強密碼，而不是下面的 `'gitea'`：
```sql
CREATE ROLE gitea WITH LOGIN PASSWORD 'gitea';
```
根據需要替換使用者名稱和密碼。
5. 使用 UTF-8 字符集建立資料庫，並由之前建立的資料庫使用者擁有。可以根據預期內容使用任何 `libc` 排序規則，使用 `LC_COLLATE` 和 `LC_CTYPE` 參數指定：
```sql
CREATE DATABASE giteadb WITH OWNER gitea TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';
```
根據需要替換資料庫名稱。
6. 通過將以下身份驗證規則添加到 `pg_hba.conf`，允許資料庫使用者訪問上面建立的資料庫。
對於本地資料庫：
```ini
local giteadb gitea scram-sha-256
```
對於遠程資料庫：
```ini
host giteadb gitea 192.0.2.10/32 scram-sha-256
```
根據您自己的資料庫名稱、使用者和 Gitea 實例的 IP 地址進行替換。
注意：`pg_hba.conf` 上的規則按順序評估，也就是第一個匹配的規則將用於身份驗證。您的 PostgreSQL 安裝可能附帶了適用於所有使用者和資料庫的通用身份驗證規則。如果是這種情況，您可能需要將此處提供的規則放置在此類通用規則之上。
重啟 PostgreSQL 以應用新的身份驗證規則。
7. 在您的 Gitea 伺服器上，測試與資料庫的連接。
對於本地資料庫：
```
psql -U gitea -d giteadb
```
對於遠程資料庫：
```
psql "postgres://[email protected]/giteadb"
```
其中 `gitea` 是資料庫使用者，`giteadb` 是資料庫名稱，`203.0.113.3` 是您的資料庫實例的 IP 地址。
您應該會被提示輸入資料庫使用者的密碼，並連接到資料庫。
## 使用 TLS 進行資料庫連接
如果 Gitea 和您的資料庫實例之間的通信是通過私有網路進行的，或者如果 Gitea 和資料庫運行在同一臺伺服器上，那麼可以省略本節，因為 Gitea 和資料庫實例之間的安全性不會受到嚴重威脅。但是，如果資料庫實例位於公共網路上，請使用 TLS 對資料庫連接進行加密，以防止第三方攔截流量資料。
### 先決條件
- 您需要兩個有效的 TLS 證書，一個用於資料庫實例（資料庫伺服器），一個用於 Gitea 實例（資料庫客戶端）。兩個證書都必須由受信任的 CA 簽名。
- 資料庫證書必須在 `X509v3 Extended Key Usage` 擴展屬性中包含 `TLS Web Server Authentication`，而客戶端證書則需要在相應的屬性中包含 `TLS Web Client Authentication`。
- 在資料庫伺服器證書中，`Subject Alternative Name` 或 `Common Name` 條目之一必須是資料庫實例的完全限定域名（FQDN）（例如 `db.example.com`）。在資料庫客戶端證書中，上述提到的條目之一必須包含 Gitea 將用於連接的資料庫使用者名稱。
- 您需要將 Gitea 和資料庫伺服器的域名映射到它們各自的 IP 地址。可以為它們設定 DNS 記錄，也可以在每個系統上的 `/etc/hosts`（Windows 中的 `%WINDIR%\System32\drivers\etc\hosts`）中添加本地映射。這樣可以透過域名而不是 IP 地址進行資料庫連接。有關詳細資訊，請參閱您系統的文件。
### PostgreSQL TLS
Gitea 使用的 PostgreSQL 驅動程式支援雙向 TLS。在雙向 TLS 中，資料庫客戶端和伺服器通過將各自的證書發送給對方進行驗證來相互認證。換句話說，伺服器驗證客戶端證書，客戶端驗證伺服器證書。
1. 在資料庫實例所在的伺服器上，放置以下憑據：
- `/path/to/postgresql.crt`: 資料庫實例證書
- `/path/to/postgresql.key`: 資料庫實例私鑰
- `/path/to/root.crt`: 用於驗證客戶端證書的 CA 證書鏈
2. 在 `postgresql.conf` 中添加以下選項：
```ini
ssl = on
ssl_ca_file = '/path/to/root.crt'
ssl_cert_file = '/path/to/postgresql.crt'
ssl_key_file = '/path/to/postgresql.key'
ssl_min_protocol_version = 'TLSv1.2'
```
3. 根據 PostgreSQL 的要求，調整憑據的所有權和權限：
```
chown postgres:postgres /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
chmod 0600 /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
```
4. 編輯 `pg_hba.conf` 規則，僅允許 Gitea 資料庫使用者通過 SSL 連接，並要求客戶端證書驗證。
對於 PostgreSQL 12：
```ini
hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=verify-full
```
對於 PostgreSQL 11 及更早版本：
```ini
hostssl giteadb gitea 192.0.2.10/32 scram-sha-256 clientcert=1
```
根據需要替換資料庫名稱、使用者和 Gitea 實例的 IP 地址。
5. 重新啟動 PostgreSQL 以應用上述設定。
6. 在運行 Gitea 實例的伺服器上，將以下憑據放置在運行 Gitea 的使用者的主目錄下（例如 `git`）：
- `~/.postgresql/postgresql.crt`: 資料庫客戶端證書
- `~/.postgresql/postgresql.key`: 資料庫客戶端私鑰
- `~/.postgresql/root.crt`: 用於驗證伺服器證書的 CA 證書鏈
注意：上述文件名在 PostgreSQL 中是硬編碼的，無法更改。
7. 根據需要調整憑據、所有權和權限：
```
chown git:git ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
chown 0600 ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
```
8. 測試與資料庫的連接：
```
psql "postgres://[email protected]/giteadb?sslmode=verify-full"
```
您將被提示輸入資料庫使用者的密碼，然後連接到資料庫。
### MySQL/MariaDB TLS
雖然 Gitea 使用的 MySQL 驅動程式也支援雙向 TLS，但目前 Gitea 僅支援單向 TLS。有關詳細資訊，請參見工單＃10828。
在單向 TLS 中，資料庫客戶端在連接握手期間驗證伺服器發送的證書，而伺服器則假定連接的客戶端是合法的，因為不進行客戶端證書驗證。
1. 在資料庫實例上放置以下憑據：
- `/path/to/mysql.crt`: 資料庫實例證書
- `/path/to/mysql.key`: 資料庫實例密鑰
- `/path/to/ca.crt`: CA 證書鏈。在單向 TLS 中不使用此文件，但用於驗證雙向 TLS 中的客戶端證書。
2. 將以下選項添加到 `my.cnf`：
```ini
[mysqld]
ssl-ca = /path/to/ca.crt
ssl-cert = /path/to/mysql.crt
ssl-key = /path/to/mysql.key
tls-version = TLSv1.2,TLSv1.3
```
3. 調整憑據的所有權和權限：
```
chown mysql:mysql /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
chmod 0600 /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
```
4. 重新啟動 MySQL 以應用設定。
5. Gitea 的資料庫使用者可能已經建立過，但只會對運行 Gitea 的伺服器的 IP 地址進行身份驗證。要對其域名進行身份驗證，請重新建立使用者，並設定其需要通過 TLS 連接到資料庫：
```sql
DROP USER 'gitea'@'192.0.2.10';
CREATE USER 'gitea'@'example.gitea' IDENTIFIED BY 'gitea' REQUIRE SSL;
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'example.gitea';
FLUSH PRIVILEGES;
```
根據需要替換資料庫使用者名稱、密碼和 Gitea 實例域名。
6. 確保用於驗證資料庫伺服器證書的 CA 證書鏈位於資料庫和 Gitea 伺服器的系統證書儲存中。請參考系統文件中有關將 CA 證書添加到證書儲存的說明。
7. 在運行 Gitea 的伺服器上，測試與資料庫的連接：
```
mysql -u gitea -h example.db -p --ssl
```
至此應該成功連接到資料庫了。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/from-binary.md
+205
View File
@@ -0,0 +1,205 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-from-binary"
sidebar_position: 15
aliases:
- /zh-tw/install-from-binary
---
# 使用二進制文件安裝
所有打包的二進制程式均包含 SQLite，MySQL 和 PostgreSQL 的資料庫連接支援，同時網站的靜態資源均已嵌入到可執行程式中，這一點和曾經的 Gogs 有所不同。
## 下載
你可以從 [下載頁面](https://dl.gitea.com/gitea/) 選擇對應平台的二進制文件。
### 選擇架構
- **對於 Linux**，`linux-amd64` 適用於 64-bit 的 Intel/AMD 平台。更多架構包含 `arm64` (Raspberry PI 4)，`386` (32-bit)，`arm-5` 以及 `arm-6`。
- **對於 Windows**，`windows-4.0-amd64` 適用於 64-bit 的 Intel/AMD 平台，`386` 適用於 32-bit 的 Intel/AMD 平台。（提示：`gogit-windows` 版本內建了 gogit 可能緩解在舊的 Windows 平台上 Go 程式調用 git 子程式時面臨的 [性能問題](https://github.com/go-gitea/gitea/pull/15482)）
- **對於 macOS**，`darwin-arm64` 適用於 Apple Silicon 架構，`darwin-amd64` 適用於 Intel 架構.
- **對於 FreeBSD**，`freebsd12-amd64` 適用於 64-bit 的 Intel/AMD 平台。
### 使用 wget 下載
使用以下命令下載適用於 64-bit Linux 平台的二進制文件。
```sh
wget -O gitea https://dl.gitea.com/gitea/@version@/gitea-@version@-linux-amd64
chmod +x gitea
```
## 驗證 GPG 簽名
Gitea 對打包的二進制文件使用 [GPG 密鑰](https://keys.openpgp.org/search?q=teabot%40gitea.io) 簽名以防止篡改。
請根據對應文件名 `.asc` 中包含的校驗碼檢驗文件的一致性。
```sh
gpg --keyserver hkps://keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
gpg --verify gitea-@[email protected] gitea-@version@-linux-amd64
```
校驗正確時的資訊為 `Good signature from "Teabot <[email protected]>"`。
校驗錯誤時的資訊為 `This key is not certified with a trusted signature!`。
## 伺服器設定
**提示：** `GITEA_WORK_DIR` 表示 Gitea 工作的路徑。以下路徑可以透過 [環境變量](../administration/environment-variables.md) 初始化。
### 準備環境
檢查是否安裝 Git。要求 Git 版本 >= 2.0。
```sh
git --version
```
建立使用者（推薦使用名稱 `git`）
```sh
# On Ubuntu/Debian:
adduser \
--system \
--shell /bin/bash \
--gecos 'Git Version Control' \
--group \
--disabled-password \
--home /home/git \
git
# On Fedora/RHEL/CentOS:
groupadd --system git
adduser \
--system \
--shell /bin/bash \
--comment 'Git Version Control' \
--gid git \
--home-dir /home/git \
--create-home \
git
```
### 建立工作路徑
```sh
mkdir -p /var/lib/gitea/{custom,data,log}
chown -R git:git /var/lib/gitea/
chmod -R 750 /var/lib/gitea/
mkdir /etc/gitea
chown root:git /etc/gitea
chmod 770 /etc/gitea
```
> **注意：** 為了讓 Web 安裝程式可以寫入設定文件，我們臨時為 `/etc/gitea` 路徑授予了組外使用者 `git` 寫入權限。建議在安裝結束後將設定文件的權限設定為只讀。
>
> ```sh
> chmod 750 /etc/gitea
> chmod 640 /etc/gitea/app.ini
> ```
如果您不希望通過 Web 安裝程式建立設定文件，可以將設定文件設定為僅供 Gitea 使用者只讀（owner/group `root:git`, mode `0640`）並手工建立設定文件：
- 設定 `INSTALL_LOCK=true` 關閉安裝介面
- 手動設定資料庫連接參數
- 使用 `gitea generate secret` 建立 `SECRET_KEY` 和 `INTERNAL_TOKEN`
- 提供所有必要的密鑰
詳情參考 [命令行文件](../administration/command-line.md) 中有關 `gitea generate secret` 的內容。
### 設定 Gitea 工作路徑
**提示：** 如果使用 Systemd 管理 Gitea 的 Linux 服務，你可以採用 `WorkingDirectory` 參數來設定工作路徑。 否則，使用環境變量 `GITEA_WORK_DIR` 來明確指出程式工作和資料存放路徑。
```sh
export GITEA_WORK_DIR=/var/lib/gitea/
```
### 複製二進制文件到全域位置
```sh
cp gitea /usr/local/bin/gitea
```
### 添加 bash/zsh 自動補全（從 1.19 版本開始）
可以在 [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete) 找到啟用 bash 自動補全的腳本。可以將其複製到 `/usr/share/bash-completion/completions/gitea`，或在 `.bashrc` 中引用。
同樣地，zsh 自動補全的腳本可以在 [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete) 找到。您可以將其複製到 `/usr/share/zsh/_gitea`，或在您的 `.zshrc` 中引用。
具體情況可能會有所不同，這些腳本可能需要進一步的改進。
## 運行 Gitea
完成以上步驟後，可以透過兩種方式運行 Gitea：
### 1. 建立服務自動啟動 Gitea（推薦）
學習建立 [Linux 服務](installation/run-as-service-in-ubuntu.md)
### 2. 通過命令行終端運行
```sh
GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini
```
## 升級到最新版本
您可以透過停止程式，替換 `/usr/local/bin/gitea` 並重啟來更新到新版本。直接替換可執行程式時不要更改或使用新的文件名稱，以避免資料出錯。
建議您在更新之前進行[備份](../administration/backup-and-restore.md)。
如果您按照上述描述執行了安裝步驟，二進制文件的通用名稱應為 gitea。請勿更改此名稱，即不要包含版本號。
### 1. 使用 systemd 重新啟動 Gitea（推薦）
我們建議使用 systemd 作為服務管理器，使用 `systemctl restart gitea` 安全地重啟程式。
### 2. 非 systemd 重啟方法
使用 SIGHUP 信號關閉程式：查詢到 Gitea 程式的 PID，使用 `kill -1 $GITEA_PID`，或者 `killall -1 gitea`。
更優雅的停止指令可能包括 `kill $GITEA_PID` 或者 `killall gitea`。
**提示：** 我們不建議使用 SIGKILL 信號（`-9`），這會強制停止 Gitea 程式，但不會正確關閉隊列、索引器等任務。
請參閱下面的疑難解答說明，以在 Gitea 版本更新後修復損壞的儲存庫。
## 排查故障
### 舊版 glibc
舊版 Linux 發行版（例如 Debian 7 和 CentOS 6）可能無法加載 Gitea 二進制文件，通常會產生類似於 `./gitea: /lib/x86_64-linux-gnu/libc.so.6:
version 'GLIBC\_2.14' not found (required by ./gitea)` 的錯誤。這是由於 dl.gitea.com 提供的二進制文件中整合了 SQLite 支援。在這種情況下，通常可以選擇[從源程式碼安裝](installation/from-source.md)，而不包括 SQLite 支援。
### 在另一個端口上運行 Gitea
對於出現類似於 `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:3000:
bind: address already in use` 的錯誤，需要將 Gitea 啟動在另一個空閒端口上。您可以使用 `./gitea web -p $PORT` 來實現。可能已經有另一個 Gitea 實例在運行。
### 在 Raspbian 上運行 Gitea
從 v1.8 版本開始，arm7 版本的 Gitea 存在問題，無法在樹莓派和類似設備上運行。
建議切換到 arm6 版本，該版本經過測試並已被證明可以在樹莓派和類似設備上運行。
### 更新到新版本的 Gitea 後出現的 Git 錯誤
如果在更新過程中，二進制文件的名稱已更改為新版本的 Gitea，則現有儲存庫中的 Git 鉤子將不再起作用。在這種情況下，當推送到儲存庫時，會顯示 Git 錯誤。
```
remote: ./hooks/pre-receive.d/gitea: line 2: [...]: No such file or directory
```
錯誤資訊中的 `[...]` 部分將包含您先前 Gitea 二進制文件的路徑。
要解決此問題，請轉到管理選項，並運行任務 `Resynchronize pre-receive, update and post-receive hooks of all repositories`，以將所有鉤子更新為包含新的二進制文件路徑。請注意，這將覆蓋所有 Git 鉤子，包括自訂的鉤子。
如果您沒有使用 Gitea 內置的 SSH 伺服器，您還需要通過在管理選項中運行任務 `Update the '.ssh/authorized_keys' file with Gitea SSH keys.` 來重新編寫授權密鑰文件。
> 更多經驗總結，請參考英文版 [Troubleshooting](https://docs.gitea.com/installation/install-from-binary#troubleshooting)
如果從本頁中沒有找到你需要的內容，請前往 [幫助頁面](help/support.md)
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/from-package.md
+104
View File
@@ -0,0 +1,104 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-from-package"
sidebar_position: 20
aliases:
- /zh-tw/install-from-package
---
# 套件管理器安裝
## 官方套件管理器
### macOS
macOS 平台下當前我們僅支援通過 `brew` 來安裝。如果你沒有安裝 [Homebrew](http://brew.sh/)，你也可以查看 [從二進制安裝](installation/from-binary.md)。在你安裝了 `brew` 之後， 你可以執行以下命令：
```
brew install gitea
```
## 非官方套件管理器
### Alpine Linux
Gitea 已經包含在 Alpine Linux 的[社區儲存庫](https://pkgs.alpinelinux.org/packages?name=gitea&branch=edge)中，版本與 Gitea 官方保持同步。
```sh
apk add gitea
```
### Arch Linux
Gitea 已經在滾動發佈發行版的官方[社區儲存庫](https://www.archlinux.org/packages/community/x86_64/gitea/)中，版本與 Gitea 官方保持同步。
```sh
pacman -S gitea
```
### Arch Linux ARM
官方支援 [aarch64](https://archlinuxarm.org/packages/aarch64/gitea)， [armv7h](https://archlinuxarm.org/packages/armv7h/gitea) 和 [armv6h](https://archlinuxarm.org/packages/armv6h/gitea) 架構。
```sh
pacman -S gitea
```
### Gentoo Linux
滾動發佈的發行版在其官方社區軟件儲存庫中提供了 [Gitea](https://packages.gentoo.org/packages/www-apps/gitea)，並且會隨著新的 Gitea 發佈提供套件更新。
```sh
emerge gitea -va
```
### Canonical Snap
目前 Gitea 已在 Snap Store 中發佈，名稱為 [gitea](https://snapcraft.io/gitea)。
```sh
snap install gitea
```
### SUSE/openSUSE
OpenSUSE 構建服務為 [openSUSE 和 SLE](https://software.opensuse.org/download/package?package=gitea&project=devel%3Atools%3Ascm)
提供包，你可以在開發軟件設定管理儲存庫中找到它們。
### Windows
目前你可以透過 [Chocolatey](https://chocolatey.org/) 來安裝 [Gitea](https://chocolatey.org/packages/gitea)。
```sh
choco install gitea
```
你也可以 [從二進制安裝](installation/from-binary.md) 。
### FreeBSD
可以使用 Gitea 的 FreeBSD port `www/gitea`。 請安裝預構建的二進制包：
```
pkg install gitea
```
對於最新版本，或使用自訂選項構建 port，請
[從 port 安裝](https://www.freebsd.org/doc/handbook/ports-using.html)：
```
su -
cd /usr/ports/www/gitea
make install clean
```
該 port 使用標準的 FreeBSD 文件系統佈局：設定文件在 `/usr/local/etc/gitea` 目錄中，
模板、選項、外掛和主題在 `/usr/local/share/gitea` 目錄中，啟動腳本在 `/usr/local/etc/rc.d/gitea` 目錄中。
要使 Gitea 作為服務運行，請運行 `sysrc gitea_enable=YES` 並使用 `service gitea start` 命令啟動它。
### 其它
如果這裡沒有找到你喜歡的套件管理器，可以使用 Gitea 第三方套件。這裡有一個完整的列表： [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/branch/master/README.md#user-content-packages)。
如果你知道其他 Gitea 第三方套件，請發送 PR 來添加它。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/from-source.md
+218
View File
@@ -0,0 +1,218 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-from-source"
sidebar_position: 30
aliases:
- /zh-tw/install-from-source
---
# 使用源程式碼安裝
你需要 [安裝 Go](https://golang.google.cn/doc/install) 並正確設定 Go 環境。特別的，建議設定`$GOPATH`環境變量，並將 Go 的二進制目錄或目錄`${GOPATH//://bin:}/bin`添加到`$PATH`中。請參閱 Go 百科上關於 [GOPATH](https://github.com/golang/go/wiki/GOPATH) 的詞條。
接下來，[安裝 Node.js 和 npm](https://nodejs.org/zh-tw/download/)， 這是構建 JavaScript 和 CSS 文件所需的。最低支援的 Node.js 版本是 @minNodeVersion@，建議使用最新的 LTS 版本。
**注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不過，建議獲取與我們的持續整合（continuous integration, CI）相同的版本，請參閱在 [Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md) 中給出的建議。
## 下載
首先，我們需要獲取源碼。由於引入了 Go 模組，最簡單的方法是直接使用 Git，因為我們不再需要在 GOPATH 內構建 Gitea。
```bash
git clone https://github.com/go-gitea/gitea
```
（之前的版本中建議使用 `go get`，但現在不再需要。）
你可以選擇編譯和安裝的版本，當前有多個選擇。`main` 分支代表當前的開發版本。如果你想編譯 `main` 版本，你可以直接跳到 [構建](#構建) 部分。
如果你想編譯帶有標籤的發行版本，可以使用以下命令簽出：
```bash
git branch -a
git checkout @sourceBranch@
```
要驗證一個拉取請求（Pull Request, PR），要先啟用新的分支（其中 `xyz` 是 PR 的 ID；例如，對於 [#2663](https://github.com/go-gitea/gitea/pull/2663)，ID 是 `2663 `）：
```bash
git fetch origin pull/xyz/head:pr-xyz
```
要以指定發行版本（如 @sourceVersion@ ）的源程式碼來構建 Gitea，可執行以下命令列出可用的版本並選擇某個版本簽出。
使用以下命令列出可用的版本：
```bash
git tag -l
git checkout @sourceVersion@ # or git checkout pr-xyz
```
## 構建
要從源程式碼進行構建，系統必須預先安裝以下程式：
- `go` @minGoVersion@ 或更高版本，請參閱 [這裡](https://go.dev/dl/)
- `node` @minNodeVersion@ 或更高版本，並且安裝 `npm`, 請參閱 [這裡](https://nodejs.org/zh-tw/download/)
- `make`, 請參閱 [這裡](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
為了儘可能簡化編譯過程，提供了各種 [make 任務](https://github.com/go-gitea/gitea/blob/main/Makefile)。
根據你的構建需求，以下 tags 可以使用：
- `bindata`: 構建一個單一的整體二進制文件，包含所有資源。適用於構建生產環境版本。
- `sqlite sqlite_unlock_notify`: 啟用對 [SQLite3](https://sqlite.org/) 資料庫的支援。僅建議在少數人使用時使用這個模式。
- `pam`: 啟用對 PAM（ Linux 可插拔認證模組）的支援。可用於對本地使用者進行身份驗證或擴展身份驗證到 PAM 可用的方法。
- `gogit`：（實驗性功能）使用 go-git 變體的 Git 命令。
將所有資源（JS/CSS/模板等）打包到二進制文件中。在生產環境部署時，使用`bindata`構建標籤是必需的。在開發/測試 Gitea 或能夠明確分離資源時，可以不用`bindata`。
要包含所有資源，請使用 `bindata` 標籤：
```bash
TAGS="bindata" make build
```
在我們的持續整合系統的預設發行版中，構建標籤為：`TAGS="bindata sqlite sqlite_unlock_notify"`。因此，從源碼構建的最簡單、推薦方式是：
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build
```
`build`目標分為兩個子目標：
- `make backend` 需要 [Go @minGoVersion@](https://golang.google.cn/doc/install) 或更高版本。
- `make frontend` 需要 [Node.js @minNodeVersion@](https://nodejs.org/zh-tw/download/) 或更高版本。
如果存在預構建的前端文件，可以僅構建後端：
```bash
TAGS="bindata" make backend
```
## 測試
按照上述步驟完成後，工作目錄中將會有一個`gitea`二進制文件。可以從該目錄進行測試，或將其移動到帶有測試資料的目錄中。當手動從命令行啟動 Gitea 時，可以透過按下`Ctrl + C`來停止程式。
```bash
./gitea web
```
## 更改預設路徑
Gitea 將從`CustomPath`中查找許多資訊。預設的，這會在運行 Gitea 時當前工作目錄下的`custom/`目錄中（譯者案：即`$PATH_TO_YOUR_GITEA$/custom/`）。它還將在`$(CustomPath)/conf/app.ini`中查找其設定文件`CustomConf`，並將當前工作目錄用作一些可設定值的相對基本路徑`AppWorkPath`。最後，靜態文件將從預設為 `AppWorkPath`的`StaticRootPath`提供。
儘管在開發時這些值很有用，但可能與下游使用者的偏好衝突。
一種選擇是使用腳本文件來隱藏`gitea`二進制文件，並在運行 Gitea 之前建立適當的環境。然而，在構建時，可以使用`make`的`LDFLAGS`環境變量來更改這些預設值。適當的設定如下：
- 要設定`CustomPath`，請使用`LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""`
- 對於`CustomConf`，應該使用`-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"`
- 對於`AppWorkPath`，應該使用`-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"`
- 對於`StaticRootPath`，應該使用`-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"`
- 要更改預設的 PID 文件位置，請使用`-X \"code.gitea.io/gitea/cmd.PIDFile=/run/gitea.pid\"`
將這些字符串與其前導的`-X`添加到`LDFLAGS`變量中，並像上面那樣使用適當的`TAGS`運行`make build`。
運行`gitea help`將允許您查看設定的`gitea`設定。
## 交叉編譯
`go`編譯器工具鏈支援將程式碼交叉編譯到不同的目標架構上。請參考[`GOOS`和`GOARCH`環境變量](https://go.dev/doc/install/source#environment) 以獲取支援的目標列表。如果您想為性能較弱的系統（如樹莓派）構建 Gitea，交叉編譯非常有用。
要使用構建標籤（`TAGS`）進行交叉編譯 Gitea，您還需要一個 C 交叉編譯器，該編譯器的目標架構與`GOOS`和`GOARCH`變量選擇的架構相同。例如，要為 Linux ARM64（`GOOS=linux`和`GOARCH=arm64`）進行交叉編譯，您需要`aarch64-unknown-linux-gnu-gcc`交叉編譯器。這是因為 Gitea 構建標籤使用了`cgo`的外部函數介面（FFI）。
在沒有任何標籤的情況下，交叉編譯的 Gitea 為 Linux ARM64 版本：
```
GOOS=linux GOARCH=arm64 make build
```
要交叉編譯 Linux ARM64 下的 Gitea，這是推薦的構建標籤：
```
CC=aarch64-unknown-linux-gnu-gcc GOOS=linux GOARCH=arm64 TAGS="bindata sqlite sqlite_unlock_notify" make build
```
根據您的目標架構，適當替換`CC`、`GOOS`和`GOARCH`。
有時您需要構建一個靜態編譯的鏡像。為此，您需要添加以下內容：
```
LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo $TAGS" make build
```
這可以與上述的`CC`、`GOOS`和`GOARCH`結合使用。
### 添加 bash/zsh 自動補全（從 1.19 版本起）
在[`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete)中可以找到一個啟用 bash 自動補全的腳本。您可以根據需要進行修改，並在您的 `.bashrc` 中使用 `source` 命令加載該腳本，或者將其複製到 `/usr/share/bash-completion/completions/gitea`。
類似地，可以在[`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete)中找到一個用於 zsh 自動補全的腳本。您可以將其複製到 `/usr/share/zsh/_gitea`，或者在您的 `.zshrc` 中使用 `source` 命令加載該腳本。
可能需要你根據具體情況進一步改進這些腳本。
## 在 Linux 上使用 Zig 進行編譯或交叉編譯
請按照 [Zig 的入門指南](https://ziglang.org/learn/getting-started/#installing-zig) 安裝 Zig。
- 編譯 (Linux ➝ Linux)
```sh
CC="zig cc -target x86_64-linux-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
CGO_LDFLAGS="-linkmode=external -v"
GOOS=linux \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
- 交叉編譯 (Linux ➝ Windows)
```sh
CC="zig cc -target x86_64-windows-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
GOOS=windows \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
## 在 Windows 上使用 Zig 進行編譯或交叉編譯
使用`GIT BASH`編譯。
- 編譯 (Windows ➝ Windows)
```sh
CC="zig cc -target x86_64-windows-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
GOOS=windows \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
- 交叉編譯 (Windows ➝ Linux)
```sh
CC="zig cc -target x86_64-linux-gnu" \
CGO_ENABLED=1 \
CGO_CFLAGS="-O2 -g -pthread" \
CGO_LDFLAGS="-linkmode=external -v"
GOOS=linux \
GOARCH=amd64 \
TAGS="bindata sqlite sqlite_unlock_notify" \
make build
```
## Source Map
預設情況下，gitea 會為前端文件生成精簡的 Source Map 以節省空間。 這可以透過“ENABLE_SOURCEMAP”環境變量進行控制：
- `ENABLE_SOURCEMAP=true` 生成所有 Source Map，這是開發版本的預設設定
- `ENABLE_SOURCEMAP=reduced` 生成有限的 Source Map，這是生產版本的預設設定
- `ENABLE_SOURCEMAP=false` 不生成 Source Map
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/on-cloud-provider.md
+42
View File
@@ -0,0 +1,42 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-on-cloud-provider"
sidebar_position: 90
aliases:
- /zh-tw/install-on-cloud-provider
---
# 在雲伺服器上安裝 Gitea
## Cloudron
Gitea 可以在 [Cloudron](https://cloudron.io) 上進行一鍵安裝。
Cloudron 使得在您的伺服器上運行 Gitea，並保持其更新和安全變得簡單。
[![Install](/cloudron.svg)](https://cloudron.io/button.html?app=io.gitea.cloudronapp)
Gitea 套件的維護地址在[這裡](https://git.cloudron.io/cloudron/gitea-app).
這裡有一個[demo 實例](https://my.demo.cloudron.io) (使用者名稱: cloudron 密碼: cloudron) 您可以在其中嘗試運行 Gitea。
## Linode
[Linode](https://www.linode.com/) 將 Gitea 作為其市場中的一個應用程式.
要將 Gitea 部署到 Linode, 請參考 [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/).
## alwaysdata
[alwaysdata](https://www.alwaysdata.com/) 將 Gitea 作為其市場中的一個 droplet.
要將 Gitea 部署到 alwaysdata, 請參考 [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/).
## Exoscale
[Exoscale](https://www.exoscale.com/) 在其市場中提供由 [Glasskube](https://glasskube.eu/) 管理的 Gitea。
Exoscale 是一家歐洲的雲服務提供商。
該套件通過開源的 [Glasskube Kubernetes Operator](https://github.com/glasskube/operator) 進行維護和更新。
要在 Exoscale 上部署 Gitea，請參考 [Exoscale Marketplace](https://www.exoscale.com/marketplace/listing/glasskube-gitea/)。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/on-kubernetes.md
+74
View File
@@ -0,0 +1,74 @@
---
date: "2020-03-19T19:27:00+02:00"
slug: "install-on-kubernetes"
sidebar_position: 80
aliases:
- /zh-tw/install-on-kubernetes
---
# 在 Kubernetes 中安裝 Gitea
Gitea 已經提供了便於在 Kubernetes 雲原生環境中安裝所需的 Helm Chart
預設安裝指令為：
```bash
helm repo add gitea https://dl.gitea.com/charts
helm repo update
helm install gitea gitea/gitea
```
如果採用預設安裝指令，Helm 會部署單實例的 Gitea, PostgreSQL, Memcached。若您想實現自訂安裝（包括設定 Gitea 集群、NGINX Ingress、MySQL、MariaDB、持久儲存等），請前往閱讀：[Gitea Helm Chart](https://gitea.com/gitea/helm-chart/)
您也可以透過 `helm show` 命令導出 `README.md` 和設定文件 `values.yaml` 進行學習和編輯，例如：
```bash
helm show values gitea/gitea > values.yaml
helm show readme gitea/gitea > README.md
# 使用自定義的配置文件 values.yaml
helm install gitea -f values.yaml gitea/gitea
```
## 運行狀況檢查介面
Gitea 附帶了一個運行狀況檢查介面 `/api/healthz`，你可以像這樣在 Kubernetes 中設定它：
```yaml
livenessProbe:
httpGet:
path: /api/healthz
port: http
initialDelaySeconds: 200
timeoutSeconds: 5
periodSeconds: 10
successThreshold: 1
failureThreshold: 10
```
成功的運行狀況檢查響應程式碼為 HTTP `200`，下面是範例：
```json
HTTP/1.1 200 OK
{
"status": "pass",
"description": "Gitea: Git with a cup of tea",
"checks": {
"cache:ping": [
{
"status": "pass",
"time": "2022-02-19T09:16:08Z"
}
],
"database:ping": [
{
"status": "pass",
"time": "2022-02-19T09:16:08Z"
}
]
}
}
```
有關更多資訊，請參考 Kubernetes 文件 [設定存活、就緒和啟動探測器](https://kubernetes.io/zh-tw/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/run-as-service-in-ubuntu.md
+63
View File
@@ -0,0 +1,63 @@
---
date: "2017-07-21T12:00:00+02:00"
slug: "linux-service"
sidebar_position: 40
aliases:
- /zh-tw/linux-service
---
# 在 Linux 中以 service 方式運行
## 在 Ubuntu 16.04 LTS 中以 service 方式運行
### systemd 方式
在 terminal 中執行以下命令：
```
sudo vim /etc/systemd/system/gitea.service
```
接著拷貝範例程式碼 [gitea.service](https://github.com/go-gitea/gitea/blob/main/contrib/service/systemd/gitea.service) 並取消對任何需要運行在主機上的服務部分的註釋，譬如 MySQL。
修改 user，home 目錄以及其他必須的初始化參數，如果使用自訂端口，則需修改 PORT 參數，反之如果使用預設端口則需刪除 -p 標記。
激活 gitea 並將它作為系統自啟動服務：
```
sudo systemctl enable gitea
sudo systemctl start gitea
```
### 使用 supervisor
在 terminal 中執行以下命令安裝 supervisor：
```
sudo apt install supervisor
```
為 supervisor 設定日誌路徑：
```
# assuming gitea is installed in /home/git/gitea/
mkdir /home/git/gitea/log/supervisor
```
在文件編輯器中打開 supervisor 的設定文件：
```
sudo vim /etc/supervisor/supervisord.conf
```
增加如下範例設定
[supervisord config](https://github.com/go-gitea/gitea/blob/main/contrib/service/supervisor/gitea)。
將 user(git) 和 home(/home/git) 設定為與上文部署中匹配的值。如果使用自訂端口，則需修改 PORT 參數，反之如果使用預設端口則需刪除 -p 標記。
最後激活 supervisor 並將它作為系統自啟動服務：
```
sudo systemctl enable supervisor
sudo systemctl start supervisor
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/upgrade-from-gitea.md
+86
View File
@@ -0,0 +1,86 @@
---
date: "2021-09-02T16:00:00+08:00"
slug: "upgrade-from-gitea"
sidebar_position: 100
---
# 從舊版 Gitea 升級
在升級之前，您需要做如下的準備工作。
## 為重大變更檢查更新日誌
為了讓 Gitea 變得更好，進行重大變更是不可避免的，尤其是一些里程碑更新的發佈。
在更新前，請 [在 Gitea 部落格上閱讀更新日誌](https://blog.gitea.com/)
並檢查重大變更是否會影響你的 Gitea 實例。
## 在控制面板中檢查過期的設定項
一些設定項可能會在後續版本中過期，你需要在控制面板中檢查他們。如果不解決過期的設定項，
Gitea也許會在升級後無法重啟。你可以訪問 https://docs.gitea.com 獲得要升級的版本
對應的文件來修改你的設定文件。
## 降級前的備份
Gitea 會保留首二位版本號相同的版本的相容性 (`a.b.x` -> `a.b.y`)，
這些版本擁有相同的資料庫結構，可以自由升級或降級。
其他情況 (`a.b.?` -> `a.c.?`)下，
新版 Gitea 可能將會將資料庫升級到與舊版資料庫不同的結構。
舉個例子:
| 當前 | 目標 | 結果 |
| --- | --- | --- |
| 1.4.0 | 1.4.1 | ✅ |
| 1.4.1 | 1.4.0 | ⚠️ 不建議，後果自負！儘管資料庫結構可能不會變更，讓它可以正常工作。我們強烈建議降級前進行完全的備份。 |
| 1.4.x | 1.5.y | ✅ 資料庫會被自動升級。你可以直接從 1.4.x 升級到最新的 1.5.y。 |
| 1.5.y | 1.4.x | ❌ 資料庫已被升級且無法用於舊版本Gitea，使用備份來進行降級。 |
**因為你不能基於升級後的資料庫運行舊版 Gitea，所以你應該在資料庫升級前完成資料備份。**
如果你在生產環境下使用 Gitea，你應該在升級前做好備份，哪怕只是小版本的補丁更新。
備份步驟:
* 停止 Gitea 實例
* 備份資料庫
* 備份 Gitea 設定文件
* 備份 Gitea 在 `APP_DATA_PATH` 中的資料文件
* 備份 Gitea 的外部儲存 (例如: S3/MinIO 或被使用的其他儲存)
如果你在使用雲服務或擁有快照功能的文件系統，
最好對 Gitea 的資料盤及相關資料儲存進行一次快照。
在所有上述步驟準備妥當之後，要升級 Gitea，只需要下載新版，停止運行舊版，進行資料備份，然後運行新版就好。
每次 Gitea 實例啟動時，它都會檢查是否要進行資料庫遷移。
如果需要進行資料庫遷移，Gitea 會花一些時間完成升級然後繼續服務。
## 從 Docker 升級
* `docker pull` 拉取 Gitea 的最新發布版。
* 停止運行中的實例，備份資料。
* 使用 `docker` 或 `docker-compose` 啟動較新的 Gitea Docker 容器.
## 從包升級
* 停止運行中的實例，備份資料。
* 使用你的套件管理器更新 Gitea 到最新版本。
* 啟動 Gitea 實例。
## 從二進制升級
* 下載最新的 Gitea 二進制文件到臨時文件夾中。
* 停止運行中的實例，備份資料。
* 將舊的 Gitea 二進制文件覆蓋成新的。
* 啟動 Gitea 實例。
在 Linux 系統上自動執行以上步驟的腳本可在 [Gitea 的 source tree 中找到 `contrib/upgrade.sh` 來獲取](https://github.com/go-gitea/gitea/blob/main/contrib/upgrade.sh).
## 小心你的自訂模板
Gitea 的模板結構與變量可能會隨著各個版本的發佈發生變化，如果你使用了自訂模板，
你得注意你的模板與你使用的 Gitea 版本的相容性。
如果自訂模板與 Gitea 版本不相容，你可能會遇到：
`50x` 伺服器錯誤，頁面元素丟失或故障，莫名其妙的頁面佈局，等等…
移除或更新不相容的模板，Gitea Web 纔可以正常工作。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/windows-service.md
+69
View File
@@ -0,0 +1,69 @@
---
date: "2016-12-21T15:00:00-02:00"
slug: "windows-service"
sidebar_position: 50
aliases:
- /zh-tw/windows-service
---
# 註冊為 Windows 服務
## 準備工作
在 C:\gitea\custom\conf\app.ini 中進行了以下更改：
```ini title="app.ini"
RUN_USER = COMPUTERNAME$
```
將 Gitea 設定為以本地系統使用者運行。
COMPUTERNAME 是從命令行中運行 `echo %COMPUTERNAME%` 後得到的響應。如果響應是 `USER-PC`，那麼 `RUN_USER = USER-PC$`。
### 使用絕對路徑
如果您使用 SQLite3，請將 `PATH` 更改為包含完整路徑：
```ini title="app.ini"
[database]
PATH = c:/gitea/data/gitea.db
```
## 註冊為 Windows 服務
要註冊為 Windows 服務，首先以 Administrator 身份運行 `cmd`，然後執行以下命令：
```
sc.exe create gitea start= auto binPath= "\"C:\gitea\gitea.exe\" web --config \"C:\gitea\custom\conf\app.ini\""
```
別忘了將 `C:\gitea` 替換成你的 Gitea 安裝目錄。
之後在控制面板打開 "Windows Services"，搜索 "gitea"，右鍵選擇 "Run"。在瀏覽器打開 `http://localhost:3000` 就可以訪問了。（如果你修改了端口，請前往對應的端口，3000 是預設端口）。
### 服務啟動類型
據觀察，在啟動期間加載的系統上，Gitea 服務可能無法啟動，並在 Windows 事件日誌中記錄超時。
在這種情況下，將啟動類型更改為`Automatic-Delayed`。這可以在服務建立期間完成，或者通過運行設定命令來完成。
```
sc.exe config gitea start= delayed-auto
```
### 添加啟動依賴項
要將啟動依賴項添加到 Gitea Windows 服務（例如 Mysql、Mariadb），作為管理員，然後運行以下命令：
```
sc.exe config gitea depend= mariadb
```
這將確保在 Windows 計算機重新啟動時，將延遲自動啟動 Gitea，直到資料庫準備就緒，從而減少啟動失敗的情況。
## 從 Windows 服務中刪除
以 Administrator 身份運行 `cmd`，然後執行以下命令：
```
sc.exe delete gitea
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/with-docker-rootless.md
+325
View File
@@ -0,0 +1,325 @@
---
date: "2020-02-09T20:00:00+02:00"
slug: "install-with-docker-rootless"
sidebar_position: 60
aliases:
- /zh-tw/install-with-docker-rootless
---
# 使用 Docker 安裝 (rootless)
Gitea 在其 Docker Hub 組織中提供自動更新的 Docker 鏡像。您可以始終使用最新的穩定標籤，或使用其他處理 Docker 鏡像更新的服務。
rootless 鏡像使用 Gitea 內部 SSH 功能來提供 Git 協議，但不支援 OpenSSH。
本參考設定指南將使用者引導通過基於 `docker-compose` 的設定。但是，`docker-compose` 的安裝超出了本文件的範圍。要安裝`docker-compose` 本身， 請按照官方的 [安裝說明](https://docs.docker.com/compose/install/)進行操作。
## 基礎設定
最簡單的設定只需建立一個卷和一個網路，並將 `docker.gitea.com/gitea:latest-rootless` 鏡像作為服務啟動。由於沒有可用的資料庫，可以使用 SQLite3 來初始化一個。
建立一個名為 `data` 和 `config`:
```sh
mkdir -p gitea/{data,config}
cd gitea
touch docker-compose.yml
```
然後將以下內容粘貼到名為 `docker-compose.yml` 的文件中：
```yaml
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
請注意，卷應由在設定文件中指定的 UID/GID 的使用者/組所有。預設情況下，Docker 中的 Gitea 將使用 uid:1000 gid:1000。如果需要，您可以使用以下命令設定這些文件夾的所有權：
```sh
sudo chown 1000:1000 config/ data/
```
> 如果未為卷設定正確的權限，容器可能無法啟動。
對於穩定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的開發版本，則可以使用 `:main-nightly-rootless` 標籤。如果您想運行發佈分支的最新提交，可以使用 `:1.x-nightly-rootless` 標籤，其中 x 是 Gitea 的次要版本號（例如:`1.27-nightly-rootless`）。
## 自訂端口
要將整合的 SSH 和 Web 伺服器綁定到不同的端口，請調整端口部分。通常只需更改主機端口並保持容器內的端口不變。
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- - "3000:3000"
- - "2222:2222"
+ - "80:3000"
+ - "22:2222"
```
## MySQL 資料庫
要將 Gitea 與 MySQL 資料庫結合使用，請對上面建立的 `docker-compose.yml` 文件進行以下更改。
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
+ environment:
+ - GITEA__database__DB_TYPE=mysql
+ - GITEA__database__HOST=db:3306
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/mysql:8
+ restart: always
+ environment:
+ - MYSQL_ROOT_PASSWORD=gitea
+ - MYSQL_USER=gitea
+ - MYSQL_PASSWORD=gitea
+ - MYSQL_DATABASE=gitea
+ volumes:
+ - ./mysql:/var/lib/mysql
```
## PostgreSQL 資料庫
要將 Gitea 與 PostgreSQL 資料庫結合使用，請對上面建立的 `docker-compose.yml` 文件進行以下更改。
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
environment:
+ - GITEA__database__DB_TYPE=postgres
+ - GITEA__database__HOST=db:5432
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/postgres:14
+ restart: always
+ environment:
+ - POSTGRES_USER=gitea
+ - POSTGRES_PASSWORD=gitea
+ - POSTGRES_DB=gitea
+ volumes:
+ - ./postgres:/var/lib/postgresql/data
```
## 命名卷 (Named Volumes)
要使用命名卷 (Named Volumes) 而不是主機卷 (Host Volumes)，請在 `docker-compose.yml` 設定中定義和使用命名卷。這樣的更改將自動建立所需的卷。您不需要擔心權限問題，Docker 會自動處理。
```diff
version: "2"
+volumes:
+ gitea-data:
+ driver: local
+ gitea-config:
+ driver: local
+
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
volumes:
- - ./data:/var/lib/gitea
+ - gitea-data:/var/lib/gitea
- - ./config:/etc/gitea
+ - gitea-config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
MySQL 或 PostgreSQL 容器需要單獨建立。
## 自訂使用者
你可以選擇使用自訂使用者 (遵循 --user 標誌定義 https://docs.docker.com/engine/reference/run/#user)。
例如，要克隆主機使用者 `git` 的定義，請使用命令 `id -u git` 並將其添加到 `docker-compose.yml` 文件中：
請確使用者對保掛載的文件夾具有寫權限。
```diff
version: "2"
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@-rootless
restart: always
+ user: 1001
volumes:
- ./data:/var/lib/gitea
- ./config:/etc/gitea
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:2222"
```
## 啟動
要啟動基於 `docker-compose` 的這個設定，請執行 `docker-compose up -d`，以在後臺啟動 Gitea。使用 `docker-compose ps` 命令可以查看 Gitea 是否正確啟動。可以使用 `docker-compose logs` 命令查看日誌。
要關閉設定，請執行 `docker-compose down` 命令。這將停止和終止容器，但卷仍將存在。
注意：如果在 HTTP 上使用的是非 3000 端口，請將 app.ini 更改為匹配 `LOCAL_ROOT_URL = http://localhost:3000/`。
## 安裝
在通過 `docker-compose` 啟動 Docker 設定後，可以使用喜愛的瀏覽器訪問 Gitea，完成安裝過程。訪問 `http://<服務器-IP>:3000` 並按照安裝嚮導進行操作。如果資料庫是使用上述文件中的 `docker-compose` 設定啟動的，請注意必須使用 `db` 作為資料庫主機名。
## 自訂
自訂文件的位置位於 `/var/lib/gitea/custom` 目錄中，可以在這裡找到有關自訂的文件說明。如果使用主機卷（host volumes），很容易訪問這些文件；如果使用命名卷（named volumes），則可以透過另一個容器或直接訪問 `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea` 來進行訪問。在安裝後，設定文件將保存在 `/etc/gitea/app.ini` 中。
## 升級
:::warning
:exclamation::exclamation: **確保您已將資料卷遷移到 Docker 容器之外的其他位置** :exclamation::exclamation:
:::
要將安裝升級到最新版本，請按照以下步驟操作：
```bash
# 如果在 docker-compose.yml 中指定了版本，請編輯該文件以更新版本
# 拉取新的鏡像
docker-compose pull
# 啟動一個新的容器，自動移除舊的容器
docker-compose up -d
```
## 從標準鏡像升級
- 備份您的設定
- 將卷掛載點從 `/data` 更改為 `/var/lib/gitea`
- 如果使用了自訂的 `app.ini`，請將其移動到新的掛載到 `/etc/gitea` 的卷中
- 將卷中的文件夾（gitea）重命名為 custom
- 如果需要，編輯 `app.ini`
- 設定 `START_SSH_SERVER = true`
- 使用鏡像 ` docker.gitea.com/gitea:@dockerVersion@-rootless`
## 使用環境變量管理部署
除了上述的環境變量外，`app.ini` 中的任何設定都可以透過形式為 `GITEA__SECTION_NAME__KEY_NAME` 的環境變量進行設定或覆蓋。這些設定在每次 Docker 容器啟動時都會生效。完整資訊請參考[這裡](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini).
這些環境變量可以在 `docker-compose.yml` 中傳遞給 Docker 容器。以下範例將啟用 SMTP 郵件伺服器，如果主機上設定了所需的環境變量 GITEA**mailer**FROM、GITEA**mailer**HOST、GITEA**mailer**PASSWD，或者在與 `docker-compose.yml` 相同目錄中的 `.env` 文件中設定了這些環境變量：
```bash
...
services:
server:
environment:
- GITEA__mailer__ENABLED=true
- GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
- GITEA__mailer__PROTOCOL=smtp
- GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
- GITEA__mailer__IS_TLS_ENABLED=true
- GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
- GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
```
要設定所需的 TOKEN 和 SECRET 值，可以使用 Gitea 的內置[生成使用函數](../administration/command-line.md#generate).
# SSH 容器透傳
由於 SSH 在容器內運行，如果需要 SSH 支援，需要將 SSH 從主機透傳到容器。一種選擇是在容器內運行 SSH，並使用非標準端口（或將主機端口移動到非標準端口）。另一種可能更直接的選擇是將主機上的 SSH 命令轉發到容器。下面解釋了這種設定。
本指南假設您已在主機上建立了一個名為 `git` 的使用者，並具有運行 `docker exec` 的權限，並且 Gitea 容器的名稱為 `gitea`。您需要修改該使用者的 shell，以將命令轉發到容器內的 `sh` 可執行文件，使用 `docker exec`。
首先，在主機上建立文件 `/usr/local/bin/gitea-shell`，並填入以下內容：
```bash
#!/bin/sh
/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
```
注意上述 docker 命令中的 `gitea` 是容器的名稱。如果您的容器名稱不同，請記得更改。
還應確保正確設定了 shell 包裝器的權限：
```bash
sudo chmod +x /usr/local/bin/gitea-shell
```
一旦包裝器就位，您可以將其設定為 `git` 使用者的 shell：
```bash
sudo usermod -s /usr/local/bin/gitea-shell git
```
現在，所有的 SSH 命令都會被轉發到容器，您需要在主機上設定 SSH 認證。這可以透過利用 [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) 來匹配 Gitea 接受的密鑰。在主機的 `/etc/ssh/sshd_config` 文件中添加以下程式碼塊：
```bash
Match User git
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
```
（從 1.16.0 開始，您將不需要設定 `-c /etc/gitea/app.ini` 選項。）
剩下的就是重新啟動 SSH 伺服器：
```bash
sudo systemctl restart sshd
```
**注意**
這實際上並沒有使用 Docker 的 SSH，而是僅僅使用了圍繞它的命令。
從理論上講，您可以不運行內部的 SSH 伺服器。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/installation/with-docker.md
+374
View File
@@ -0,0 +1,374 @@
---
date: "2016-12-01T16:00:00+02:00"
slug: "install-with-docker"
sidebar_position: 70
aliases:
- /zh-tw/install-with-docker
---
# 使用 Docker 安裝
Gitea 在其 Docker Hub 組織內提供自動更新的 Docker 鏡像。可以始終使用最新的穩定標籤或使用其他服務來更新 Docker 鏡像。
該參考設定指導使用者完成基於 `docker-compose` 的設定，但是 `docker-compose` 的安裝不在本文件的範圍之內。要安裝 `docker-compose` 本身，請遵循官方[安裝說明](https://docs.docker.com/compose/install/)。
## 基本
最簡單的設定只是建立一個卷和一個網路，然後將 `docker.gitea.com/gitea:latest` 鏡像作為服務啟動。由於沒有可用的資料庫，因此可以使用 SQLite3 初始化資料庫。建立一個類似 `gitea` 的目錄，並將以下內容粘貼到名為 `docker-compose.yml` 的文件中。請注意，該卷應由設定文件中指定的 UID/GID 的使用者/組擁有。如果您不授予卷正確的權限，則容器可能無法啟動。另請注意，標籤 `:latest` 安裝的是最新的穩定版本。對於穩定的發行版，您也可以使用 `:1` 或指定某個發行版，例如 `@dockerVersion@`。如果您想使用最新的開發版本，則可以使用 `:main-nightly` 標籤；如果您想運行發佈分支的最新提交，可以使用 `:1.x-nightly` 標籤，其中 x 是 Gitea 的次要版本號（例如:`1.27-nightly`）。
```yaml
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
```
## 端口
要將整合的 openSSH 守護進程和 Web 伺服器綁定到其他端口，請調整端口部分。通常，只需更改主機端口，容器內的端口保持原樣即可。
```diff
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- - "3000:3000"
- - "222:22"
+ - "8080:3000"
+ - "2221:22"
```
## 資料庫
### MySQL 資料庫
要將 Gitea 與 MySQL 資料庫結合使用，請將這些更改應用於上面建立的 `docker-compose.yml` 文件。
```diff
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
+ - GITEA__database__DB_TYPE=mysql
+ - GITEA__database__HOST=db:3306
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/mysql:8
+ restart: always
+ environment:
+ - MYSQL_ROOT_PASSWORD=gitea
+ - MYSQL_USER=gitea
+ - MYSQL_PASSWORD=gitea
+ - MYSQL_DATABASE=gitea
+ networks:
+ - gitea
+ volumes:
+ - ./mysql:/var/lib/mysql
```
### PostgreSQL 資料庫
要將 Gitea 與 PostgreSQL 資料庫結合使用，請將這些更改應用於上面建立的 `docker-compose.yml` 文件。
```diff
version: "3"
networks:
gitea:
external: false
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
+ - GITEA__database__DB_TYPE=postgres
+ - GITEA__database__HOST=db:5432
+ - GITEA__database__NAME=gitea
+ - GITEA__database__USER=gitea
+ - GITEA__database__PASSWD=gitea
restart: always
networks:
- gitea
volumes:
- ./gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
+ depends_on:
+ - db
+
+ db:
+ image: docker.io/library/postgres:14
+ restart: always
+ environment:
+ - POSTGRES_USER=gitea
+ - POSTGRES_PASSWORD=gitea
+ - POSTGRES_DB=gitea
+ networks:
+ - gitea
+ volumes:
+ - ./postgres:/var/lib/postgresql/data
```
## 命名卷
要使用命名卷而不是主機卷，請在 `docker-compose.yml` 設定中定義並使用命名卷。此更改將自動建立所需的卷。您無需擔心命名卷的權限；Docker 將自動處理該問題。
```diff
version: "3"
networks:
gitea:
external: false
+volumes:
+ gitea:
+ driver: local
+
services:
server:
image: docker.gitea.com/gitea:@dockerVersion@
container_name: gitea
restart: always
networks:
- gitea
volumes:
- - ./gitea:/data
+ - gitea:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "222:22"
```
MySQL 或 PostgreSQL 容器將需要分別建立。
## 啟動
要基於 `docker-compose` 啟動此設定，請執行 `docker-compose up -d`，以在後臺啟動 Gitea。使用 `docker-compose ps` 將顯示 Gitea 是否正確啟動。可以使用 `docker-compose logs` 查看日誌。
要關閉設定，請執行 `docker-compose down`。這將停止並殺死容器。這些卷將仍然存在。
注意：如果在 http 上使用非 3000 端口，請更改 app.ini 以匹配 `LOCAL_ROOT_URL = http://localhost:3000/`。
## 安裝
通過 `docker-compose` 啟動 Docker 安裝後，應該可以使用喜歡的瀏覽器訪問 Gitea，以完成安裝。訪問 http://server-ip:3000 並遵循安裝嚮導。如果資料庫是通過上述 `docker-compose` 設定啟動的，請注意，必須將 `db` 用作資料庫主機名。
## 環境變量
您可以透過環境變量設定 Gitea 的一些設定：
（預設值以**粗體**顯示）
- `APP_NAME`：**“Gitea: Git with a cup of tea”**：應用程式名稱，在頁面標題中使用。
- `RUN_MODE`：**prod**：應用程式運行模式，會影響性能和調試。"dev"，"prod"或"test"。
- `DOMAIN`：**localhost**：此伺服器的域名，用於 Gitea UI 中顯示的 http 克隆 URL。
- `SSH_DOMAIN`：**localhost**：該伺服器的域名，用於 Gitea UI 中顯示的 ssh 克隆 URL。如果啟用了安裝頁面，則 SSH 域伺服器將採用以下形式的 DOMAIN 值（保存時將覆蓋此設定）。
- `SSH_PORT`：**22**：克隆 URL 中顯示的 SSH 端口。
- `SSH_LISTEN_PORT`：**%(SSH_PORT)s**：內置 SSH 伺服器的端口。
- `DISABLE_SSH`：**false**：如果不可用，請禁用 SSH 功能。如果要禁用 SSH 功能，則在安裝 Gitea 時應將 SSH 端口設定為 `0`。
- `HTTP_PORT`：**3000**：HTTP 監聽端口。
- `ROOT_URL`：**""**：覆蓋自動生成的公共 URL。如果內部 URL 和外部 URL 不匹配（例如在 Docker 中），這很有用。
- `LFS_START_SERVER`：**false**：啟用 git-lfs 支援。
- `DB_TYPE`：**sqlite3**：正在使用的資料庫類型[mysql，postgres，mssql，sqlite3]。
- `DB_HOST`：**localhost:3306**：資料庫主機地址和端口。
- `DB_NAME`：**gitea**：資料庫名稱。
- `DB_USER`：**root**：資料庫使用者名稱。
- `DB_PASSWD`：**"_empty_"** ：資料庫使用者密碼。如果您在密碼中使用特殊字符，請使用“您的密碼”進行引用。
- `INSTALL_LOCK`：**false**：禁止訪問安裝頁面。
- `SECRET_KEY`：**""** ：全域密鑰。這應該更改。如果它具有一個值並且 `INSTALL_LOCK` 為空，則 `INSTALL_LOCK` 將自動設定為 `true`。
- `DISABLE_REGISTRATION`：**false**：禁用註冊，之後只有管理員才能為使用者建立帳戶。
- `REQUIRE_SIGNIN_VIEW`：**false**：啟用此選項可強制使用者登入以查看任何頁面。
- `USER_UID`：**1000**：在容器內運行 Gitea 的使用者的 UID（Unix 使用者 ID）。如果使用主機卷，則將其與 `/data` 卷的所有者的 UID 匹配（對於命名卷，則不需要這樣做）。
- `USER_GID`：**1000**：在容器內運行 Gitea 的使用者的 GID（Unix 組 ID）。如果使用主機卷，則將其與 `/data` 卷的所有者的 GID 匹配（對於命名卷，則不需要這樣做）。
## 自訂
[此處](../administration/customizing-gitea.md)描述的定製文件應放在 `/data/gitea` 目錄中。如果使用主機卷，則訪問這些文件非常容易；對於命名卷，可以透過另一個容器或通過直接訪問 `/var/lib/docker/volumes/gitea_gitea/_data` 來完成。安裝後，設定文件將保存在 `/data/gitea/conf/app.ini` 中。
## 升級
:::warning
:exclamation::exclamation: **確保已將資料捲到 Docker 容器外部的某個位置** :exclamation::exclamation:
:::
要將安裝升級到最新版本：
```bash
# Edit `docker-compose.yml` to update the version, if you have one specified
# Pull new images
docker-compose pull
# Start a new container, automatically removes old one
docker-compose up -d
```
## 使用環境變量管理部署
除了上面的環境變量之外，`app.ini` 中的任何設定都可以使用以下形式的環境變量進行設定或覆蓋：`GITEA__SECTION_NAME__KEY_NAME`。 每次 docker 容器啟動時都會應用這些設定。 完整資訊在[這裡](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini)。
```bash
...
services:
server:
environment:
- GITEA__mailer__ENABLED=true
- GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
- GITEA__mailer__PROTOCOL=smtps
- GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
- GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
- GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
```
Gitea 將為每次新安裝自動生成新的 `SECRET_KEY` 並將它們寫入 `app.ini`。 如果您想手動設定 `SECRET_KEY`，您可以使用以下 docker 命令來使用 Gitea 內置的[方法](../administration/command-line.md#generate)生成 `SECRET_KEY`。 安裝後請妥善保管您的 `SECRET_KEY`，如若丟失則無法解密已加密的資料。
以下命令將向 `stdout` 輸出一個新的 `SECRET_KEY` 和 `INTERNAL_TOKEN`，然後您可以將其放入環境變量中。
```bash
docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret SECRET_KEY
docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKEN
```
```yaml
---
services:
server:
environment:
- GITEA__security__SECRET_KEY=[value returned by generate secret SECRET_KEY]
- GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
```
## SSH 容器直通
由於 SSH 在容器內運行，因此，如果需要 SSH 支援，則需要將 SSH 從主機傳遞到容器。一種選擇是在非標準端口上運行容器 SSH（或將主機端口移至非標準端口）。另一個可能更直接的選擇是將 SSH 連接從主機轉發到容器。下面將說明此設定。
本指南假定您已經在名為 `git` 的主機上建立了一個使用者，該使用者與容器值 `USER_UID`/`USER_GID` 共享相同的 `UID`/`GID`。這些值可以在 `docker-compose.yml` 中設定為環境變量：
```bash
environment:
- USER_UID=1000
- USER_GID=1000
```
接下來將主機的 `/home/git/.ssh` 裝入容器。否則，SSH 身份驗證將無法在容器內運行。
```bash
volumes:
- /home/git/.ssh/:/data/git/.ssh
```
現在，需要在主機上建立 SSH 密鑰對。該密鑰對將用於向主機驗證主機上的 `git` 使用者。
```bash
sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
```
在下一步中，需要在主機上建立一個名為 `/usr/local/bin/gitea` 的文件（具有可執行權限）。該文件將發出從主機到容器的 SSH 轉發。將以下內容添加到 `/usr/local/bin/gitea`：
```bash
ssh -p 2222 -o StrictHostKeyChecking=no [email protected] "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
```
為了使轉發正常工作，需要將容器（22）的 SSH 端口映射到 `docker-compose.yml` 中的主機端口 2222。由於此端口不需要暴露給外界，因此可以將其映射到主機的 `localhost`：
```bash
ports:
# [...]
- "127.0.0.1:2222:22"
```
另外，主機上的 `/home/git/.ssh/authorized_keys` 需要修改。它需要以與 Gitea 容器內的 `authorized_keys` 相同的方式進行操作。因此，將您在上面建立的密鑰（“Gitea 主機密鑰”）的公共密鑰添加到 `/home/git/.ssh/authorized_keys`。這可以透過 `echo "$(cat /home/git/.ssh/id_rsa.pub)" >> /home/git/.ssh/authorized_keys` 完成。重要提示：來自 `git` 使用者的公鑰需要“按原樣”添加，而通過 Gitea 網路介面添加的所有其他公鑰將以 `command="/app [...]` 作為前綴。
該文件應該看起來像：
```bash
# SSH pubkey from git user
ssh-rsa <Gitea Host Key>
# other keys from users
command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
```
這是詳細的說明，當發出 SSH 請求時會發生什麼：
1. 使用 `git` 使用者向主機發出 SSH 請求，例如 `git clone git@domain:user/repo.git`。
2. 在 `/home/git/.ssh/authorized_keys` 中，該命令執行 `/usr/local/bin/gitea` 腳本。
3. `/usr/local/bin/gitea` 將 SSH 請求轉發到端口 2222，該端口已映射到容器的 SSH 端口（22）。
4. 由於 `/home/git/.ssh/authorized_keys` 中存在 `git` 使用者的公鑰，因此身份驗證主機 → 容器成功，並且 SSH 請求轉發到在 docker 容器中運行的 Gitea。
如果在 Gitea Web 介面中添加了新的 SSH 密鑰，它將以與現有密鑰相同的方式附加到 `.ssh/authorized_keys` 中。
**注意**
SSH 容器直通僅在以下情況下有效
- 在容器中使用 `opensshd`
- 如果未將 `AuthorizedKeysCommand` 與 `SSH_CREATE_AUTHORIZED_KEYS_FILE = false` 結合使用以禁用授權文件密鑰生成
- `LOCAL_ROOT_URL` 不變
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "使用指南",
"position": 35,
"link": {
"type": "generated-index",
"slug": "/usage",
"title": "使用指南"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/access-control/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "Access Control",
"position": 100,
"link": {
"type": "generated-index",
"slug": "/usage/access-control",
"description": "Permissions, security, and access control features"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/access-control/permissions.md
+77
View File
@@ -0,0 +1,77 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "permissions"
sidebar_position: 14
aliases:
- /zh-tw/permissions
---
# 權限
Gitea 支援對儲存庫進行權限管理，這樣您就可以為不同的人員提供不同的存取權限。首先，我們需要了解 `單元（Unit）`。
## 單元（Unit）
在 Gitea 中，我們將儲存庫的子模組稱為 `單元（Unit）`。現在我們有以下幾個單元。
| 名稱 | 描述 | 權限 |
| -------------- | ---------------------------------- | --------- |
| 程式碼 | 訪問源程式碼、文件、提交和分支。 | 讀取 寫入 |
| 工單 | 組織缺陷報告、任務和里程碑。 | 讀取 寫入 |
| 合併請求 | 啟用合併請求和程式碼審覈。 | 讀取 寫入 |
| 發佈 | 跟蹤專案版本和下載。 | 讀取 寫入 |
| 百科 | 與協作者編寫和共享文件。 | 讀取 寫入 |
| 外部百科 | 鏈接到外部維基。 | 讀取 |
| 外部工單跟蹤器 | 鏈接到外部工單跟蹤器。 | 讀取 |
| 專案 | 模板儲存庫的 URL。 | 讀取 寫入 |
| 包 | 鏈接到儲存庫 | 讀取 寫入 |
| Actions | 審查 Actions 日誌或重啟/取消工作流 | 讀取 寫入 |
| 設定 | 管理儲存庫。 | 管理員 |
通過不同的權限，使用者可以在這些單元上執行不同的操作。
| 名稱 | 讀取 | 寫入 | 管理員 |
| -------------- | -------------------------------- | ------------------------------ | -------- |
| 程式碼 | 查看程式碼樹、文件、提交、分支等。 | 推送程式碼。 | - |
| 工單 | 查看工單並建立新工單。 | 添加標籤、分配、關閉工單。 | - |
| 合併請求 | 查看合併請求並建立新合併請求。 | 添加標籤、分配、關閉合併請求。 | - |
| 發佈 | 查看發佈和下載文件。 | 建立/編輯發佈。 | - |
| 百科 | 查看百科頁面。克隆百科儲存庫。 | 建立/編輯百科頁面，推送更改。 | - |
| 外部百科 | 鏈接到外部百科。 | - | - |
| 外部工單跟蹤器 | 鏈接到外部工單跟蹤器。 | - | - |
| 專案 | 查看面板。 | 在面板之間移動工單。 | - |
| 包 | 查看包 | 上傳/刪除包 | - |
| Actions | 查看 Actions 日誌 | 同意 / 取消 / 重啟 | - |
| 設定 | - | - | 管理儲存庫 |
個人儲存庫和組織儲存庫之間的權限存在一些差異。
## 個人儲存庫
對於個人儲存庫，建立者是儲存庫的唯一所有者，對於該儲存庫的任何更改或刪除沒有限制。
儲存庫所有者可以添加協作者來幫助維護儲存庫。協作者可以擁有 `讀取（Read）`、`寫入（Write）` 和 `管理員（Admin）` 權限。
訪問私有儲存庫的體驗與訪問匿名公共儲存庫類似。您可以訪問儲存庫中的所有可用內容，包括克隆程式碼、建立工單、回覆工單評論、提交拉取請求等。如果你有 "寫"權限，只要分支保護規則允許，你就可以向儲存庫的特定分支推送程式碼。此外，你還可以修改百科頁面。有了 "管理"權限，你就可以修改儲存庫的設定。
但如果你不是該儲存庫的所有者，就不能刪除或轉移該儲存庫。
## 組織儲存庫
對於個人儲存庫，所有者是建立它的使用者。而對於組織儲存庫，所有者是該組織中的所有者團隊成員。對該組織儲存庫的所有權限都取決於團隊權限設定。
### 所有者團隊
建立組織時將自動建立所有者團隊，建立者將成為所有者團隊的第一名成員。所有者團隊不可刪除，且至少有一名成員。
### 管理員團隊
建立團隊時，有兩種類型的團隊。一種是管理員團隊，另一種是普通團隊。可以建立一個管理員團隊來管理某些版本庫，其成員可以對這些版本庫做任何事情。只有所有者或管理員團隊的成員才能建立新團隊。
### 普通團隊
組織中的普通團隊具有可以根據`單元(Unit)`進行權限設定。它可以有成員和儲存庫範圍。
- 一個團隊可以訪問所屬組織的所有儲存庫或特殊儲存庫。
- 也可以設定該團隊是否有建立新儲存庫的權限。
可以透過建立 "普通團隊"，並通過權限控制對其行為進行限制。一名成員可以加入多個團隊。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/access-control/protected-tags.md
+46
View File
@@ -0,0 +1,46 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "protected-tags"
sidebar_position: 45
aliases:
- /zh-tw/protected-tags
---
# 受保護的標籤
受保護的標籤允許控制誰有權限建立或更新 Git 標籤。每個規則可以匹配單個標籤名稱，或者使用適當的模式來同時控制多個標籤。
## 設定受保護的標籤
要保護一個標籤，你需要按照以下步驟進行操作：
1. 進入儲存庫的**設定** > **標籤**頁面。
2. 輸入一個用於匹配名稱的模式。你可以使用單個名稱、[glob 模式](https://pkg.go.dev/github.com/gobwas/glob#Compile) 或正則表達式。
3. 選擇允許的使用者和/或團隊。如果將這些欄位留空，則不允許任何人建立或修改此標籤。
4. 選擇**保存**以保存設定。
## 模式受保護的標籤
該模式使用 [glob](https://pkg.go.dev/github.com/gobwas/glob#Compile) 或正則表達式來匹配標籤名稱。對於正則表達式，你需要將模式括在斜槓中。
範例：
| 類型 | 模式受保護的標籤 | 可能匹配的標籤 |
| ----- | ------------------------ | --------------------------------------- |
| Glob | `v*` | `v`，`v-1`，`version2` |
| Glob | `v[0-9]` | `v0`，`v1` 到 `v9` |
| Glob | `*-release` | `2.1-release`，`final-release` |
| Glob | `gitea` | 僅限 `gitea` |
| Glob | `*gitea*` | `gitea`，`2.1-gitea`，`1_gitea-release` |
| Glob | `{v,rel}-*` | `v-`，`v-1`，`v-final`，`rel-`，`rel-x` |
| Glob | `*` | 匹配所有可能的標籤名稱 |
| Regex | `/\Av/` | `v`，`v-1`，`version2` |
| Regex | `/\Av[0-9]\z/` | `v0`，`v1` 到 `v9` |
| Regex | `/\Av\d+\.\d+\.\d+\z/` | `v1.0.17`，`v2.1.0` |
| Regex | `/\Av\d+(\.\d+){0,2}\z/` | `v1`，`v2.1`，`v1.2.34` |
| Regex | `/-release\z/` | `2.1-release`，`final-release` |
| Regex | `/gitea/` | `gitea`，`2.1-gitea`，`1_gitea-release` |
| Regex | `/\Agitea\z/` | 僅限 `gitea` |
| Regex | `/^gitea$/` | 僅限 `gitea` |
| Regex | `/\A(v\|rel)-/` | `v-`，`v-1`，`v-final`，`rel-`，`rel-x` |
| Regex | `/.+/` | 匹配所有可能的標籤名稱 |
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/actions/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "Actions",
"position": 30,
"link": {
"type": "generated-index",
"slug": "/usage/actions",
"description": "Automating workflows with Actions"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/actions/comparison.md
+102
View File
@@ -0,0 +1,102 @@
---
date: "2023-05-24T15:00:00+08:00"
slug: "comparison"
sidebar_position: 15
---
# 與GitHub Actions的對比
Gitea Actions 旨在與 GitHub Actions 相容，差異如下。
## 額外功能
<a id="absolute-action-urls"></a>
### Action URL絕對路徑
`uses:` 接受指向任意 Git 主機的絕對 URL，例如 `uses: https://gitea.com/actions/checkout@v4`。
<a id="action-prefixes"></a>
### Action 前綴
`uses:` 接受以下前綴：
- `self:` 參照您自己的 Gitea 實例，例如 `uses: self:owner/repo@v1` 或 `uses: self:owner/repo/.gitea/workflows/build.yml@v1`
- `builtin:` 執行 Gitea Runner 內建的 Action，無需下載，Job 映像檔中也不需要 Node，例如 `uses: builtin:checkout`
`builtin:checkout` 支援 `actions/checkout` 的 `repository`、`ref`、`token`、`path` 和 `fetch-depth` 輸入，預設值相同，其他輸入會使步驟失敗。
<a id="workflow-relative-actions"></a>
### 相對於工作流的 Actions
`$/` 參照工作流（或外層複合 Action）所在的儲存庫與提交，例如 `uses: $/.gitea/actions/build`。
與 `./` 不同，它不需要事先簽出程式碼。
### 使用Go編寫Actions
請參閱[建立 Go Actions](https://blog.gitea.com/creating-go-actions/)。
### 支援非標準的調度語法 @yearly, @monthly, @weekly, @daily, @hourly
`schedule` 也接受 `@yearly`、`@monthly`、`@weekly`、`@daily` 和 `@hourly`，[GitHub 則不支援](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule)。
## 不支援的工作流語法
### `jobs.<job_id>.environment`
[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) 會被忽略。
### 複雜的`runs-on`
[`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) 支援：
- 靜態字串：`runs-on: self-hosted`
- 標籤陣列：`runs-on: [linux, self-hosted]`
- 字串表達式：`runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
- 包含表達式的陣列：`runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
## 缺失的功能
### 套件儲存庫授權
`GITEA_TOKEN` 無法發佈到其所屬儲存庫的套件註冊表，例如無法推送 OCI 鏡像。
請改用個人存取權杖，參見[這個工單](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692)。
### 問題匹配器
[問題匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)會被忽略。
### 為錯誤建立註釋
[錯誤註釋](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)會被忽略。
### 表達式
[表達式](https://docs.github.com/en/actions/learn-github-actions/expressions)支援 GitHub 的標準函式與上下文。
## 缺失的UI功能
### 預處理和後處理步驟
預處理和後處理步驟在 Job 日誌中沒有各自獨立的區塊。
### 服務步驟
服務步驟在 Job 日誌中沒有各自獨立的區塊。
## 不一樣的行為
### `permissions`和`jobs.<job_id>.permissions`
`permissions` 和 `jobs.<job_id>.permissions` 控制 `GITEA_TOKEN` 的權限，其權限受儲存庫與所有者設定的限制，對於來自 fork 的拉取請求和跨儲存庫存取還會進一步受限。
不支援 `statuses`、`checks`、`deployments`、`id-token`、`security-events` 和 `pages` 等 GitHub 專屬範圍，而 Gitea 另外提供 `code`、`releases`、`wiki` 和 `projects`。
請參閱 [Actions Job 令牌權限](token-permissions.md)。
### 下載Actions
未指定主機的 Actions，例如 `uses: actions/checkout@v4`，會從 `https://github.com` 下載，若 `[actions].DEFAULT_ACTIONS_URL` 為 `self`，則從您自己的實例下載。
請參閱[設定速查表](../../administration/config-cheat-sheet.md#actions-actions)。
其他來源請參閱 [Action URL絕對路徑](#absolute-action-urls)、[Action 前綴](#action-prefixes)和[相對於工作流的 Actions](#workflow-relative-actions)。
### 上下文可用性
不檢查[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)，因此 `env` 等上下文可以在更多地方使用。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/actions/design.md
+99
View File
@@ -0,0 +1,99 @@
---
date: "2023-05-24T15:00:00+08:00"
slug: "design"
sidebar_position: 40
---
# Gitea Actions設計
Gitea Actions由多個元件組成。本文件將對它們進行逐個描述。
## Gitea Runner
Gitea Runner部分基於[nektos/act](https://github.com/nektos/act)的硬分支。
與其他CI Runner一樣，我們將其設計為Gitea的外部部分，這意味著它應該在與Gitea不同的伺服器上運行。
為了確保Runner連接到正確的Gitea實例，我們需要使用令牌註冊它。
此外，Runner通過聲明自己的標籤向Gitea報告它可以運行的Job類型。
之前，我們提到工作流文件中的 `runs-on: ubuntu-latest` 表示該Job將在具有`ubuntu-latest`標籤的Runner上運行。
但是，Runner如何知道要運行 `ubuntu-latest`？答案在於將標籤映射到環境。
這就是為什麼Runner的每個標籤都指定了一個環境，比如`my_custom_label:docker://centos:7`。
這意味著Runner可以接受需要在`my_custom_label`上運行的Job，並通過使用`centos:7`鏡像的Docker容器來運行它。
然而，Docker不是唯一的選擇。
Runner 也支援直接在主機上運行Job。
這是通過像`linux_arm:host`這樣的標籤實現的。
這個標籤表示Runner可以接受需要在`linux_arm`上運行的Job，並直接在主機上運行它們。
標籤的設計遵循格式`label[:schema[:args]]`。
如果省略了schema，則預設為`host`。
因此，
- `my_custom_label:docker://node:18`：使用`node:18 Docker`鏡像運行帶有`my_custom_label`標籤的Job。
- `my_custom_label:host`：在主機上直接運行帶有`my_custom_label`標籤的Job。
- `my_custom_label`：等同於`my_custom_label:host`。
## 通信協議
由於 runner 是Gitea的獨立部分，我們需要一種協議讓Runner與Gitea實例進行通信。
然而，我們不認為讓Gitea監聽一個新端口是個好主意。
相反，我們希望重用HTTP端口，這意味著我們需要一個與HTTP相容的協議。
因此，我們選擇使用基於HTTP的gRPC。
協議定義於[actions-proto-def](https://gitea.com/gitea/actions-proto-def)，其Go程式碼位於[actionslib](https://gitea.com/gitea/actionslib)。
有關 gRPC 的更多資訊，請前往[其官方網站](https://grpc.io/)。
## 網路架構
讓我們來看一下整體的網路架構。
這將幫助您解決一些問題，並解釋為什麼使用迴環地址註冊Runner是個不好的主意。
![network](/images/usage/actions/network.png)
圖片中標記了四個網路連接，並且箭頭的方向表示建立連接的方向。
### 連接 1， runner到Gitea實例
Runner 必須能夠連接到Gitea以接收任務併發送執行結果回來。
### 連接 2，Job容器到Gitea實例
即使Job容器位於同一臺機器上，它們的網路命名空間與Runner不同。
舉個例子，如果工作流中包含 `actions/checkout@v4`，Job容器需要連接到Gitea來獲取程式碼。
獲取程式碼並不總是運行某些Job所必需的，但在大多數情況下是必需的。
如果您使用迴環地址註冊Runner，當Runner與Gitea在同一臺機器上時，Runner可以連接到Gitea。
然而，如果Job容器嘗試從本地主機獲取程式碼，它將失敗，因為Gitea不在同一個容器中。
### 連接 3，runner到互聯網
當您使用諸如 `actions/checkout@v4` 的一些Actions時，runner 下載的是腳本，而不是Job容器。
預設情況下，它從[github.com](https://github.com/)下載，因此需要訪問互聯網。
若將`DEFAULT_ACTIONS_URL`設定為`self`，或使用`uses: self:owner/repo@ref`，則改從您的Gitea實例下載。
它還預設從Docker Hub下載一些Docker鏡像，這也需要互聯網訪問。
然而，互聯網訪問並不是絕對必需的。
您可以設定您的Gitea實例從您的內部網路設施中獲取 Actions 或鏡像。
實際上，您的Gitea實例可以同時充當 Actions 市場和鏡像註冊表。
您可以將GitHub上的Actions儲存庫鏡像到您的Gitea實例，並將其用作普通Actions。
而 [Gitea 容器註冊表](usage/packages/container.md) 可用作Docker鏡像註冊表。
### 連接 4，Job容器到互聯網
當使用諸如`actions/setup-go@v5`的Actions時，可能需要從互聯網下載資源，以設定Job容器中的Go語言環境。
因此，成功完成這些Actions需要訪問互聯網。
然而，這也是可選的。
您可以使用自訂的Actions來避免依賴互聯網訪問，或者可以使用已安裝所有依賴項的打包的Docker鏡像來運行Job。
## 總結
使用Gitea Actions只需要確保Runner能夠連接到Gitea實例。
互聯網訪問是可選的，但如果沒有互聯網訪問，將需要額外的工作。
換句話說：當Runner能夠自行查詢互聯網時，它的工作效果最好，但您不需要將其暴露給互聯網（無論是單向還是雙向）。
如果您在使用Gitea Actions時遇到任何網路問題，希望上面的圖片能夠幫助您進行故障排除。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/actions/faq.md
+120
View File
@@ -0,0 +1,120 @@
---
date: "2023-05-24T15:00:00+08:00"
slug: "faq"
sidebar_position: 100
---
# Gitea Actions常見問題解答
本頁面包含一些關於Gitea Actions的常見問題和答案。
## 是否可以在我的實例中預設禁用新儲存庫的Actions？
是的，當您為實例啟用Actions時，您可以選擇預設啟用actions單元以適用於所有新儲存庫。
```ini
[repository]
; 去掉 repo.actions 將不會為新倉庫自動啟用actions
DEFAULT_REPO_UNITS = ...,repo.actions
```
## 在工作流文件中應該使用`${{ github.xyz }}`還是`${{ gitea.xyz }}`？
您可以使用`github.xyz`，Gitea將正常工作。
如前所述，Gitea Actions的設計是與GitHub Actions相容的。
然而，我們建議在工作流文件中使用`gitea.xyz`，以防止在工作流文件中出現不同類型的密鑰（因為您在Gitea上使用此工作流，而不是GitHub）。
不過，這完全是可選的，因為目前這兩個選項的效果是相同的。
## 使用`actions/checkout@v4`等Actions時，Job容器會從何處下載腳本？
預設從 `https://github.com` 下載，若 `[actions].DEFAULT_ACTIONS_URL` 為 `self`，則從您自己的實例下載，參見[設定速查表](../../administration/config-cheat-sheet.md#actions-actions)。
若要使用其他來源的 Action，請指定其主機：
- `uses: https://gitea.com/owner/repo@ref`
- `uses: http://your_gitea_instance.com/owner/repo@ref`
- `uses: self:owner/repo@ref`，用於您自己的 Gitea 實例
## 如何限制Runner的權限？
Runner 只會連接到您的 Gitea 實例。
對於每個 Job，Runner 會取得一個僅限於該 Job 所屬儲存庫的 `GITEA_TOKEN`，參見 [Actions Job 令牌權限](token-permissions.md)。
若要讓 Job 存取更多私有儲存庫或外部系統，請向其傳遞[密鑰](usage/actions/secrets.md)。
## 如何避免被黑客攻擊？
有兩種可能的攻擊類型：未知的Runner竊取您的儲存庫中的程式碼或密鑰，或惡意腳本控制您的Runner。
避免前者意味著不允許您不認識的人為您的儲存庫、組織或實例註冊Runner。
後者要複雜一些。
如果您為公司使用私有的Gitea實例，您可能不需要擔心安全問題，因為您信任您的同事，並且可以追究他們的責任。
對於公共實例，情況略有不同。
以下是我們在 [gitea.com](http://gitea.com/)上的做法：
- 我們僅為 "gitea" 組織註冊Runner，因此我們的Runner不會執行來自其他儲存庫的Job。
- 我們的Runner始終在隔離容器中運行Job。雖然可以直接在主機上進行這樣的操作，但出於安全考慮，我們選擇不這樣做。
- 對於 fork 的拉取請求，需要獲得批准才能運行Actions。參見[#22803](https://github.com/go-gitea/gitea/pull/22803)。
- 如果有人在[gitea.com](http://gitea.com/)為其儲存庫或組織註冊自己的Runner，我們不會反對，只是不會在我們的組織中使用它。然而，他們應該注意確保該Runner不被他們不認識的其他使用者使用。
## runner支援哪些操作系統？
官方發佈了 Linux、macOS 和 Windows 的二進制檔案。
理論上，Go 和 Docker 支援的其他系統也能運作。
## 為什麼選擇GitHub Actions？為什麼不選擇與GitLab CI/CD相容的工具？
[@lunny](https://gitea.com/lunny)在實現Actions的[問題](https://github.com/go-gitea/gitea/issues/13539)中已經解釋過這個問題。
此外，Actions不僅是一個CI/CD 系統，還是一個自動化工具。
在開源世界中，已經有許多[市場上的Actions](https://github.com/marketplace?type=actions)實現了。
能夠重用它們是令人興奮的。
## 如果它在多個標籤上運行，例如 `runs-on: [label_a, label_b]`，會發生什麼？
Job 會在具有所有這些標籤的 Runner 上運行，與 [GitHub](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) 相同。
Runner 會使用它所具有的第一個標籤對應的環境。
## 代理標籤和自訂標籤對於Runner有什麼區別？
Gitea 已不再有自訂標籤。
Runner 每次啟動時都會宣告其標籤，標籤來自 `runner.labels` 設定或註冊時指定的標籤，因此請在那裡修改並重新啟動 Runner。
## Gitea Actions runner會有更多的實現嗎？
雖然我們希望提供更多的選擇，但由於我們有限的人力資源， runner將是唯一受支援的官方Runner。
然而，無論您如何決定，Gitea 和 runner都是完全開源的，所以任何人都可以建立一個新的/更好的實現。
我們支援您的選擇，無論您如何決定。
如果您選擇分支 runner 來建立自己的版本，請在您認為您的更改對其他人也有幫助的情況下貢獻這些更改。
## Gitea 支援哪些工作流觸發事件？
表格中列出的所有事件都是支援的，並且與 GitHub 相容。
對於僅 GitHub 支援的事件，請參閱 GitHub 的[文件](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows)。
| 觸發事件 | 活動類型 |
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------|
| create | 不適用 |
| delete | 不適用 |
| fork | 不適用 |
| gollum | 不適用 |
| push | 不適用 |
| issues | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
| issue_comment | `created`, `edited`, `deleted` |
| pull_request | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled` |
| pull_request_review | `submitted`, `edited` |
| pull_request_review_comment | `created`, `edited` |
| release | `published`, `edited` |
| registry_package | `published` |
> 對於 `pull_request` 事件，在 [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) 中 `ref` 是 `refs/pull/:prNumber/merge`，它指向這個拉取請求合併提交的一個預覽。但是 Gitea 沒有這種 reference。
> 因此，Gitea Actions 中 `ref` 是 `refs/pull/:prNumber/head`，它指向這個拉取請求的頭分支而不是合併提交的預覽。
## 如何共享私有儲存庫中的 Actions 和可重複使用的工作流？
前往儲存庫的**設定** > **Actions** > **General** 頁面，添加協作所有者。
協作所有者的私有儲存庫可以存取目前儲存庫中的 Actions 和工作流。
若要在同一使用者或組織內共享，請改為在該使用者或組織的**設定** > **Actions** > **General** > **Cross-Repository Access** 中添加這些私有儲存庫。
參見[跨儲存庫存取](token-permissions.md#cross-repository-access)。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/actions/overview.md
+42
View File
@@ -0,0 +1,42 @@
---
date: "2023-05-24T15:00:00+08:00"
slug: "overview"
sidebar_position: 1
---
# Overview
從Gitea **1.19**版本開始，Gitea Actions成為了內置的CI/CD解決方案。
## 名稱
Gitea Actions與[GitHub Actions](https://github.com/features/actions)相似且相容，它的名稱也受到了它的啟發。
為了避免混淆，在這裡我們明確了拼寫方式：
- "Gitea Actions"（兩個單詞都大寫且帶有"s"）是Gitea功能的名稱。
- "GitHub Actions"是GitHub功能的名稱。
- "Actions"根據上下文的不同可以指代以上任意一個。在本文件中指代的是"Gitea Actions"。
- "action"或"actions"指代一些要使用的腳本/外掛，比如"actions/checkout@v4"或"actions/cache@v3"。
## Runner
和其他CI/CD解決方案一樣，Gitea不會自己運行Job，而是將Job委託給Runner。
Gitea Actions的Runner被稱為[Gitea Runner](https://gitea.com/gitea/runner)，它是一個獨立的程式，也是用Go語言編寫的。
它的重要部分來自[nektos/act](http://github.com/nektos/act)的一個硬分支。
由於Runner是獨立部署的，可能存在潛在的安全問題。
為了避免這些問題，請遵循兩個簡單的規則：
- 不要為你的儲存庫、組織或實例使用你不信任的Runner。
- 不要為你不信任的儲存庫、組織或實例提供Runner。
對於內部使用的Gitea實例，比如企業或個人使用的實例，這兩個規則不是問題，它們自然而然就是如此。
然而，對於公共的Gitea實例，比如[gitea.com](https://gitea.com)，在添加或使用Runner時應當牢記這兩個規則。
## 狀態
Gitea Actions仍然在開發中，因此可能存在一些錯誤和缺失的功能。
並且在穩定版本（v1.20或更高版本）之前可能會進行一些重大的更改。
如果情況發生變化，我們將在此處進行更新。
因此，請在其他地方找到過時文章時參考此處的內容。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/actions/quickstart.md
+131
View File
@@ -0,0 +1,131 @@
---
date: "2023-05-24T15:00:00+08:00"
slug: "quickstart"
sidebar_position: 10
---
# 快速入門
本頁面將指導您使用Gitea Actions的過程。
## 設定Gitea
首先，您需要一個Gitea實例。
您可以按照[文件](installation/from-package.md) 來設定一個新實例或升級現有實例。
無論您如何安裝或運行Gitea，只要版本號是1.19.0或更高即可。
從1.21.0開始，預設情況下，Actions是啟用的。如果您正在使用1.21.0之前的版本，您需要將以下內容添加到設定文件中以啟用它：
```ini
[actions]
ENABLED=true
```
如果您想了解更多資訊或在設定過程中遇到任何問題，請參考[設定速查表](../../administration/config-cheat-sheet.md#actions-actions)。
### 設定Runner
Gitea Actions需要[runner](https://gitea.com/gitea/runner) 來運行Job。
為了避免消耗過多資源並影響Gitea實例，建議您在與Gitea實例分開的機器上啟動Runner。
您可以使用[預構建的二進制文件](http://dl.gitea.com/gitea-runner)或[容器鏡像](https://hub.docker.com/r/gitea/runner/tags)來設定Runner。
在進一步操作之前，建議您先使用預構建的二進制文件以命令行方式運行它，以確保它與您的環境相容，尤其是如果您在本地主機上運行Runner。
如果出現問題，這樣調試起來會更容易。
該Runner可以在隔離的Docker容器中運行Job，因此您需要確保已安裝Docker並且Docker守護進程正在運行。
雖然這不是嚴格必需的，因為Runner也可以直接在主機上運行Job，這取決於您的設定方式。
然而，建議使用Docker運行Job，因為它更安全且更易於管理。
在運行Runner之前，您需要使用以下命令將其註冊到Gitea實例中：
```bash
./runner register --no-interactive --instance <instance> --token <token>
```
需要兩個必需的參數：`instance` 和 `token`。
`instance`是您的Gitea實例的地址，如`http://192.168.8.8:3000`或`https://gitea.com`。
Runner和Job容器（由Runner啟動以執行Job）將連接到此地址。
這意味著它可能與用於Web訪問的`ROOT_URL`不同。
使用迴環地址（例如 `127.0.0.1` 或 `localhost`）是一個不好的選擇。
如果不確定使用哪個地址，通常選擇局域網地址即可。
`token` 用於身份驗證和標識，例如 `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`。
它只能使用一次，並且不能用於註冊多個Runner。
您可以從以下位置獲取不同級別的`token`,從而建立出相應級別的`runner`
- 實例級別：管理員設定頁面，例如 `<your_gitea.com>/admin/actions/runners`。
- 組織級別：組織設定頁面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
- 儲存庫級別：儲存庫設定頁面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。
![register runner](/images/usage/actions/register-runner.png)
註冊後，當前目錄中將出現一個名為 `.runner` 的新文件，該文件儲存了註冊資訊。
請不要手動編輯該文件。
如果該文件丟失或損壞，只需刪除它然後重新註冊即可。
最後，是時候啟動Runner了：
```bash
./runner daemon
```
您可以在管理頁面上看到新的Runner：
![view runner](/images/usage/actions/view-runner.png)
您可以透過訪問[runner](runner) 獲取更多資訊。
### 使用Actions
即使對於啟用了Gitea實例的Actions，儲存庫仍預設禁用Actions。
要啟用它，請轉到儲存庫的設定頁面，例如`your_gitea.com/<owner>/repo/settings`，然後啟用`Enable Repository Actions`。
![enable actions](/images/usage/actions/enable-actions.png)
接下來的步驟可能相當複雜。
您需要學習Actions的[工作流語法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)，並編寫您想要的工作流文件。
不過，我們可以從一個簡單的演示開始：
```yaml
name: Gitea Actions Demo
run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀
on: [push]
jobs:
Explore-Gitea-Actions:
runs-on: ubuntu-latest
steps:
- run: echo "🎉 The job was automatically triggered by a ${{ gitea.event_name }} event."
- run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!"
- run: echo "🔎 The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}."
- name: Check out repository code
uses: actions/checkout@v4
- run: echo "💡 The ${{ gitea.repository }} repository has been cloned to the runner."
- run: echo "🖥️ The workflow is now ready to test your code on the runner."
- name: List files in the repository
run: |
ls ${{ gitea.workspace }}
- run: echo "🍏 This job's status is ${{ job.status }}."
```
您可以將上述範例上傳為一個以`.yaml`擴展名的文件，放在儲存庫的`.gitea/workflows/`目錄中，例如`.gitea/workflows/demo.yaml`。
您可能會注意到，這與[GitHub Actions的快速入門](https://docs.github.com/en/actions/quickstart)非常相似。
這是因為Gitea Actions在儘可能相容GitHub Actions的基礎上進行設計。
請注意，演示文件中包含一些表情符號。
請確保您的資料庫支援它們，特別是在使用MySQL時。
如果字符集不是`utf8mb4`，將出現錯誤，例如`Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`。
有關更多資訊，請參閱[資料庫準備工作](../../installation/database-preparation.md#mysqlmariadb)。
或者，您可以從演示文件中刪除所有表情符號，然後再嘗試一次。
`on: [push]` 這一行表示當您向該儲存庫推送提交時，工作流將被觸發。
然而，當您上傳 YAML 文件時，它也會推送一個提交，所以您應該在"Actions"標籤中看到一個新的任務。
![view job](/images/usage/actions/view-job.png)
做得好！您已成功開始使用Actions。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/actions/runner.md
+57
View File
@@ -0,0 +1,57 @@
---
date: "2023-05-24T15:00:00+08:00"
slug: "runner"
sidebar_position: 20
aliases:
- /zh-tw/act-runner
---
# Gitea Runner
本頁面將介紹[Gitea Runner](https://gitea.com/gitea/runner)，這是Gitea Actions的Runner。
:::tip
詳細的安裝、設定和使用說明，請參閱 [Gitea Runner 文件](/runner/)。
:::
## 獲取註冊令牌
### Runner級別
您可以在不同級別上註冊Runner，它可以是：
- 實例級別：Runner將為實例中的所有儲存庫運行Job。
- 組織級別：Runner將為組織中的所有儲存庫運行Job。
- 儲存庫級別：Runner將為其所屬的儲存庫運行Job。
請注意，即使儲存庫具有自己的儲存庫級別Runner，它仍然可以使用實例級別或組織級別Runner。未來的版本可能提供更多對此進行更好控制的選項。
Runner級別決定了從哪裡獲取註冊令牌。
- 實例級別：管理員設定頁面，例如 `<your_gitea.com>/admin/actions/runners`。
- 組織級別：組織設定頁面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
- 儲存庫級別：儲存庫設定頁面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。
如果您無法看到設定頁面，請確保您具有正確的權限並且已啟用 Actions。
註冊令牌的格式是一個隨機字符串 `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`。
註冊令牌也可以透過 Gitea 的 [命令列](../../administration/command-line.md#actions-generate-runner-token) 獲得:
```
gitea --config /etc/gitea/app.ini actions generate-runner-token
```
使用者也可以使用 `GITEA_RUNNER_REGISTRATION_TOKEN` 或 `GITEA_RUNNER_REGISTRATION_TOKEN_FILE` 環境變量以在 Gitea 啟動時設定全域的註冊令牌，例如：
```
openssl rand -hex 24 > /some-dir/runner-token
export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
./gitea --config ...
```
來自環境變量的令牌在通過 Web 介面或 API 重置(重新建立新令牌)前將一直有效。
令牌可用於註冊多個 Runner，直到使用 Web 介面中的令牌重置鏈接將其撤銷並替換為新令牌。
獲取註冊令牌後，請參閱 [Gitea Runner 文件](/runner/) 了解如何安裝、設定和運行您的 Runner。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/actions/scoped-workflows.md
+119
View File
@@ -0,0 +1,119 @@
---
date: "2026-06-26T00:00:00+00:00"
slug: "scoped-workflows"
sidebar_position: 60
---
# 作用域工作流程
作用域工作流程（Scoped Workflows）讓你把 Actions 工作流程集中維護在一個**來源（source）**儲存庫中，並讓它們自動在許多其他儲存庫上執行，而無需把工作流程檔案複製到每個儲存庫裡。
提交到來源儲存庫作用域工作流程目錄下的工作流程檔案，會在該來源所適用的每個儲存庫（稱為**消費方（consuming）**儲存庫）上執行。每次執行都在**消費方儲存庫自身的環境**中進行：使用它的 runner、Secret、`GITEA_TOKEN` 和分支，而工作流程**內容則讀取自來源儲存庫**。這適用於在組織或實例範圍內強制推行共用 CI：程式碼檢查、安全掃描、合規或政策檢查等。
## 層級
來源儲存庫可以在兩個層級註冊：
- **擁有者層級（Owner level）**：由組織或使用者註冊。該來源的工作流程會在該組織或使用者擁有的每個儲存庫上執行。
- **實例層級（Instance level）**：由網站管理員註冊。該來源的工作流程會在實例上的**每一個**儲存庫上執行。
同一個儲存庫可以同時在兩個層級註冊；對於每個符合的事件，它仍只會被評估一次。
:::note
實例層級的來源適用於實例上的**每一個**儲存庫，且被設為必要（required）的來源無法被選擇退出（opt out）。偵測會在每個儲存庫的每次事件上執行。請審慎註冊。
:::
## 設定
作用域工作流程存放在一個與一般工作流程分開的目錄中，由 `app.ini` 中 `[actions]` 區段的 `SCOPED_WORKFLOW_DIRS` 控制：
```ini
[actions]
SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
```
- 預設值為 `.gitea/scoped_workflows`。
- 可以列出多個目錄（以逗號分隔）。
- **不得與** `WORKFLOW_DIRS`（一般工作流程目錄，預設為 `.gitea/workflows` 和 `.github/workflows`）**重疊**。
- 留空表示沒有任何目錄存放作用域工作流程，因此不會找到也不會執行任何作用域工作流程。設定頁面仍會顯示、來源仍可註冊，但不會有任何作用域工作流程執行。
把作用域工作流程放在它們自己的目錄中，表示來源儲存庫**自身**的 Actions 不受影響：只有 `SCOPED_WORKFLOW_DIRS` 下的檔案才會被當作作用域工作流程。
## 從一個儲存庫提供作用域工作流程
1. 在準備作為來源的儲存庫中，把工作流程檔案提交到其**預設分支**上的作用域工作流程目錄下，例如 `.gitea/scoped_workflows/lint.yaml`：
```yaml
name: Lint
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: echo "lint the consuming repository here"
```
2. 將該儲存庫註冊為來源：
- **組織**：*組織設定 -> Actions -> 作用域工作流程*
- **使用者**：*使用者設定 -> Actions -> 作用域工作流程*
- **實例（管理員）**：*網站管理 -> Actions -> 作用域工作流程*
搜尋並新增該儲存庫。此後，它的作用域工作流程便會適用於該層級下的消費方儲存庫。
來源儲存庫也在它自己的作用域內，因此它會像其他消費方一樣在自身上執行這些工作流程。
## 作用域工作流程如何執行
- 該執行屬於**消費方**儲存庫，使用它的 runner、Secret、`GITEA_TOKEN` 和 ref。它在那裡的行為與一般執行一致，包括重新執行、日誌和提交狀態。
- 工作流程**內容讀取自來源**儲存庫，並釘選在事件發生時來源預設分支的 commit 上。
- 偵測使用消費方儲存庫的事件，因此工作流程的 `on:` 觸發器（例如 `push` 和 `pull_request`）必須與該事件相符。
## 選擇退出（Opting out）
消費方儲存庫可以在其 **Actions** 頁面（該工作流程會顯示在其來源之下）停用一個它不想要的作用域工作流程。已被標記為**必要（required）**（見下文）的工作流程，消費方儲存庫永遠無法將其停用，也無法選擇退出。
## 必要工作流程與合併門檻
在作用域工作流程設定頁面上，你可以把個別工作流程標記為**必要（required）**，並為每個工作流程給定一個或多個**狀態檢查模式（status-check patterns）**（每行一個 glob）。一個必要的作用域工作流程：
- 無法被消費方儲存庫停用。
- 會對合併請求（PR）形成合併門檻：消費方的 PR 只有在一個符合**每一個**模式的提交狀態都**通過**後才能合併（必須存在且通過，must-present-and-pass）。一個從不產生任何狀態的必要檢查會**阻擋**合併，而不是被靜默略過，因此在消費方停用 Actions 也無法繞過它。
作用域執行產生的狀態檢查 context 形如：
```
<來源儲存庫全名>: <工作流程顯示名稱> / <job> (<event>)
```
設定頁面會為每個工作流程預覽這些 “Expected status checks（預期狀態檢查）”，並標記出與你的模式相符的專案，便於你確認模式是否正確。一種常見模式是對 job 和 event 使用萬用字元，例如 `my-org/ci-repo: Lint / *`。
強制範圍：
- 必要檢查會在任何設有**分支保護規則**的目標分支上強制生效，即使該規則自身的狀態檢查處於關閉狀態。
- **沒有**保護規則的目標分支不受門檻約束。
:::warning
只有執行在會產生提交狀態的事件（`push`、`pull_request`、`pull_request_target`、`release`）上的工作流程才能被設為必要。僅執行在 `workflow_dispatch`、`schedule` 或 `workflow_call` 等事件上的工作流程不會產生任何狀態，因此把它設為必要會**永久**阻擋每一個消費方 PR 的合併。設定頁面在這種情況下會向你發出警告。
:::
## 可重複使用的工作流程（`uses:`）
作用域工作流程可以呼叫可重複使用的工作流程：
- **本機**參照（`uses: ./...` 或 `uses: $/...`）會相對於**來源**儲存庫解析：即呼叫方工作流程內容的來源儲存庫，而非消費方儲存庫。
- **跨儲存庫**參照（`uses: owner/repo/...@ref` 或 `uses: self:owner/repo/...@ref`）會以**消費方儲存庫的**讀取權限來解析。如果它指向一個私有儲存庫，請確保每個消費方儲存庫都能讀取它，否則工作流程會在那裡失敗。
可重複使用的工作流程可以放在來源儲存庫的 `SCOPED_WORKFLOW_DIRS`（或 `WORKFLOW_DIRS`）之下。
## 安全性注意事項
來源儲存庫的工作流程內容會在它所適用的每個儲存庫中執行，其步驟指令碼及其輸出會寫入該儲存庫的 Actions 日誌，任何能檢視消費方儲存庫 Actions 的人都能讀取這些日誌。
- 因此，將一個**私有**儲存庫註冊為來源，會透過這些日誌洩漏其工作流程邏輯。只應註冊那些其工作流程內容可以與每個消費方儲存庫共用的儲存庫。
## 限制
- 目前不支援將 `on: schedule` 和 `on: workflow_run` 作為作用域工作流程觸發器。
- 作用域工作流程內容讀取自來源的預設分支；來源的其他分支不會被使用。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/actions/secrets.md
+28
View File
@@ -0,0 +1,28 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "secrets"
sidebar_position: 50
---
# 密鑰管理
密鑰管理允許您在使用者、組織或儲存庫中儲存敏感資訊。
密鑰管理在 Gitea 1.19+ 版本中可用。
## 設定密鑰名稱
以下規則適用於密鑰名稱：
- 密鑰名稱只能包含字母數字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下劃線 (`_`)。不允許使用空格。
- 密鑰名稱不能以 `GITHUB_` 和 `GITEA_` 前綴開頭。
- 密鑰名稱不能以數字開頭。
- 密鑰名稱不區分大小寫。
- 密鑰名稱在建立它們的級別上必須是唯一的。
例如，對於在儲存庫級別建立的密鑰，它在該儲存庫中必須具有唯一的名稱；對於在組織級別建立的密鑰，它在該級別上必須具有唯一的名稱。
如果在多個級別上存在具有相同名稱的密鑰，則最低級別的密鑰優先生效。例如，如果組織級別的密鑰與儲存庫級別的密鑰具有相同的名稱，則儲存庫級別的密鑰將優先生效。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/actions/token-permissions.md
+126
View File
@@ -0,0 +1,126 @@
---
date: "2026-03-19T00:00:00+01:00"
slug: "token-permissions"
sidebar_position: 30
---
# Actions Job 令牌權限（`GITEA_TOKEN`）
每個 Actions Job 都會取得一個內建令牌（`GITEA_TOKEN`），可用於存取 Gitea（透過 HTTP(S) 使用 Git、API 請求等）。
本頁說明 Gitea 如何決定該令牌可以執行哪些操作。
在工作流中，可以透過 `${{ secrets.GITEA_TOKEN }}` 使用它。這些設定和 `permissions:` 只影響 `GITEA_TOKEN`（不影響個人存取權杖等其他密鑰）。API 呼叫請參閱 [API 認證](../../development/api-usage.md#authentication)。
<a id="where-permissions-come-from"></a>
## 權限的來源
Gitea 依以下順序決定 Job 令牌權限：
1. Job 層級的 `permissions:`（`jobs.<job_id>.permissions`）
2. 工作流層級的 `permissions:`（頂層）
3. 設定中的預設權限（所有者或儲存庫）
接著，結果會再受到所設定的最大令牌權限**限縮**（見下文）。
<a id="supported-workflow-syntax"></a>
## 支援的工作流語法
Gitea 支援與 GitHub Actions 相容的 `permissions:` 關鍵字。
<a id="scalar-values"></a>
### 純量值
```yaml
permissions: read-all # or: write-all
```
<a id="scoped-mapping"></a>
### 依範圍對應
```yaml
permissions:
contents: read
issues: write
pull-requests: none
```
每個範圍的有效存取模式值為 `read`、`write` 和 `none`。
<a id="supported-scopes"></a>
### 支援的範圍
- `contents`（適用於 `code` 和 `releases`）
- `code`
- `releases`
- `issues`
- `pull-requests`
- `actions`
- `wiki`
- `projects`
- `packages`（若目標功能支援）
如果同時指定 `contents` 和更細的範圍（例如 `code` 或 `releases`），該單元以更細的範圍為準。
<a id="compatibility-notes"></a>
### 相容性說明
Gitea 支援 GitHub Actions 權限範圍的一個子集。
Gitea Actions 目前不支援 `statuses`、`checks`、`deployments`、`id-token`、`security-events` 和 `pages` 等 GitHub 專屬範圍。
Gitea 另外提供一些儲存庫單元範圍，它們在 GitHub Actions 中並不是獨立的範圍：
- `code`
- `releases`
- `wiki`
- `projects`
<a id="default-permission-mode"></a>
## 預設權限模式
如果工作流和 Job 都沒有定義 `permissions:`，Gitea 會使用所設定的預設模式：
- **Permissive**（寬鬆）：對 Job 所屬儲存庫的大多數單元具有讀取和寫入權限（向下相容的預設值）。
- **受限**（Restricted）：對 Job 所屬儲存庫的 `code`、`releases` 和 `packages` 具有唯讀權限，預設無法存取其他單元。
<a id="maximum-token-permissions-clamping"></a>
## 最大令牌權限（限縮）
您可以為每個儲存庫單元設定最大權限。
Job 的實際權限計算方式如下：
`effective = min(requested, maximum)`
也就是說，工作流可以降低 Job 的權限，但不能超過您所設定的最大值。
如果未設定最大值，所有範圍的最大值預設為 `write`。
<a id="where-to-configure"></a>
## 設定位置
您可以在以下位置設定預設值和最大值：
- **使用者 / 組織**：`Settings` → `Actions` → `General`
- **儲存庫**：`Settings` → `Actions` → `General`
- 對於組織內的儲存庫，儲存庫可以沿用所有者層級的設定，或透過 **Override owner-level configuration** 選擇退出。
注意：只有在啟用**儲存庫 Actions** 後，才會顯示儲存庫層級的令牌權限設定。
<a id="fork-pull-requests"></a>
## 來自 fork 的拉取請求
基於安全考量，由來自 fork 的拉取請求觸發的工作流，對儲存庫內容一律只有唯讀權限，不受工作流 `permissions:` 或設定影響。
<a id="cross-repository-access"></a>
## 跨儲存庫存取
預設情況下，`GITEA_TOKEN` 只能存取：
- Job 所屬的儲存庫（依計算出的權限）
- 公開儲存庫（唯讀）
預設會拒絕存取其他私有儲存庫。
使用者或組織可以在**設定** > **Actions** > **General** > **Cross-Repository Access** 中，允許唯讀存取選定的私有儲存庫。
私有儲存庫也可以在**設定** > **Actions** > **General** 中允許選定的協作所有者。
這樣，這些所有者的私有儲存庫就能為了 Actions 用途讀取目前的私有儲存庫，例如私有 Actions 和可重複使用的工作流。
由來自 fork 的拉取請求觸發的工作流，永遠無法取得對私有儲存庫的跨儲存庫存取權，即使這些儲存庫已列入清單也一樣。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/actions/variables.md
+30
View File
@@ -0,0 +1,30 @@
---
date: "2024-04-10T22:21:00+08:00"
slug: "actions-variables"
sidebar_position: 25
---
# 變量
您可以建立使用者、組織和儲存庫級別的變量。變量的級別取決於建立它的位置。當建立變量時，變量的名稱會被
轉換為大寫，在yaml文件中引用時需要使用大寫。
## 命名規則
以下規則適用於變量名：
- 變量名稱只能包含字母數字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下劃線 (`_`)。不允許使用空格。
- 變量名稱不能以 `GITHUB_` 和 `GITEA_` 前綴開頭。
- 變量名稱不能以數字開頭。
- 變量名稱不區分大小寫。
- 變量名稱在建立它們的級別上必須是唯一的。
- 變量名稱不能為 `CI`。
## 使用
建立設定變量後，它們將自動填充到 `vars` 上下文中。您可以在工作流中使用類似 `${{ vars.VARIABLE_NAME }}` 這樣的表達式來使用它們。
## 優先級
如果同名變量存在於多個級別，則級別最低的變量優先。
儲存庫級別的變量總是比組織或者使用者級別的變量優先被選中。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/agit-support.md
+45
View File
@@ -0,0 +1,45 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "agit"
sidebar_position: 12
aliases:
- /zh-tw/agit-setup
---
# AGit
在 Gitea `1.13` 版本中，添加了對 [AGit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支援。AGit 允許使用者在沒有儲存庫寫入權限的情況下直接建立拉取請求，也不需要分叉儲存庫。這有助於減少重複儲存庫的數量，降低不必要的磁盤使用量。
:::note
伺服器端需要 Git 版本 2.29 或更高版本才能正常運行。
:::
## 使用 AGit 建立 PR
AGit 允許在推送程式碼到遠程儲存庫時建立 PR（合併請求）。
通過在推送時使用特定的 refspec（git 中已知的位置標識符），可以實現這一功能。
下面的範例說明了這一點：
```shell
git push origin HEAD:refs/for/main
```
該命令的結構如下：
- `HEAD`：目標分支
- `refs/<for|draft|for-review>/<branch>`：目標 PR 類型
- `for`：建立一個以 `<branch>` 為目標分支的普通 PR
- `draft`/`for-review`：目前被靜默忽略
- `<branch>/<session>`：要打開 PR 的目標分支
- `-o <topic|title|description>`：PR 的選項
- `title`：PR 的標題
- `topic`：PR 應該打開的分支名稱
- `description`：PR 的描述
- `force-push=true`: 是否強制更新目標分支
- 注意: 如果不傳值，只用 `-o force-push` 也同樣可以正常工作。
下面是另一個高級範例，用於建立一個以 `topic`、`title` 和 `description` 為參數的新 PR，目標分支是 `main`：
```shell
git push origin HEAD:refs/for/main -o topic="Topic of my PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/issues-prs/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "Issues & Pull Requests",
"position": 20,
"link": {
"type": "generated-index",
"slug": "/usage/issues-prs",
"description": "Issues and Pull Requests workflow, templates, and collaboration features"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/issues-prs/issue-pull-request-templates.md
+283
View File
@@ -0,0 +1,283 @@
---
date: "2022-09-07T16:00:00+08:00"
slug: "issue-pull-request-templates"
sidebar_position: 15
toc: true
aliases:
- /zh-tw/issue-pull-request-templates
---
# 從模板建立工單與合併請求
開發者可以利用問題模板建立工單與合併請求，其目的在於規範參與者的語言表達。
## 模板介紹
Gitea 支援兩種格式的模板：Markdown 和 YAML。
### Markdown 模板
在 Gitea 中存在兩種用途的 Markdown 模板：
- `ISSUE_TEMPLATE/bug-report.md` 用於規範工單的 Markdown 文本描述
- `PULL_REQUEST_TEMPLATE.md` 用於規範合併請求的 Markdown 文本描述
對於以上 Markdown 模板，我們推薦您將它們放置到專案目錄 `.gitea` 進行收納。
### YAML 模板
用 YAML 語法編寫的模板相比 Markdown 可以實現更豐富的功能，利用表單實現諸如：問卷調查、字符校驗。在 Gitea 中的 YAML 同樣支援兩種用途：
- `ISSUE_TEMPLATE/bug-report.yaml` 用於建立問卷調查形式的工單
- `PULL_REQUEST_TEMPLATE.yaml` 用於建立表單形式的合併請求
對於以上 YAML 模板，我們同樣推薦您將它們放置到專案目錄 `.gitea` 進行收納。
##### 表單支援通過 URL 查詢參數傳值
當新建工單頁面 URL 以 `?title=Issue+Title&body=Issue+Text` 為查詢參數，表單將使用其中的參數（key-value）填充表單內容。
### Gitea 支援的模板文件路徑
工單模板文件名:
- `ISSUE_TEMPLATE.md`
- `ISSUE_TEMPLATE.yaml`
- `ISSUE_TEMPLATE.yml`
- `issue_template.md`
- `issue_template.yaml`
- `issue_template.yml`
- `.gitea/ISSUE_TEMPLATE.md`
- `.gitea/ISSUE_TEMPLATE.yaml`
- `.gitea/ISSUE_TEMPLATE.yml`
- `.gitea/issue_template.md`
- `.gitea/issue_template.yaml`
- `.gitea/issue_template.yml`
- `.github/ISSUE_TEMPLATE.md`
- `.github/ISSUE_TEMPLATE.yaml`
- `.github/ISSUE_TEMPLATE.yml`
- `.github/issue_template.md`
- `.github/issue_template.yaml`
- `.github/issue_template.yml`
合併請求模板:
- `PULL_REQUEST_TEMPLATE.md`
- `PULL_REQUEST_TEMPLATE.yaml`
- `PULL_REQUEST_TEMPLATE.yml`
- `pull_request_template.md`
- `pull_request_template.yaml`
- `pull_request_template.yml`
- `.gitea/PULL_REQUEST_TEMPLATE.md`
- `.gitea/PULL_REQUEST_TEMPLATE.yaml`
- `.gitea/PULL_REQUEST_TEMPLATE.yml`
- `.gitea/pull_request_template.md`
- `.gitea/pull_request_template.yaml`
- `.gitea/pull_request_template.yml`
- `.github/PULL_REQUEST_TEMPLATE.md`
- `.github/PULL_REQUEST_TEMPLATE.yaml`
- `.github/PULL_REQUEST_TEMPLATE.yml`
- `.github/pull_request_template.md`
- `.github/pull_request_template.yaml`
- `.github/pull_request_template.yml`
#### 工單模板目錄
由於工單存在多種類型，Gitea 支援將工單模板統一收納到 `ISSUE_TEMPLATE` 目錄。以下是 Gitea 支援的工單模板目錄:
- `ISSUE_TEMPLATE`
- `issue_template`
- `.gitea/ISSUE_TEMPLATE`
- `.gitea/issue_template`
- `.github/ISSUE_TEMPLATE`
- `.github/issue_template`
- `.gitlab/ISSUE_TEMPLATE`
- `.gitlab/issue_template`
目錄支援混合存放 Markdown (`.md`) 或 YAML (`.yaml`/`.yml`) 格式的工單模板。另外，合併請求模板不支援目錄存放。
## Markdown 模板語法
```md
---
name: "Template Name"
about: "This template is for testing!"
title: "[TEST] "
ref: "main"
labels:
- bug
- "help needed"
---
This is the template!
```
上面的範例表示使用者從列表中選擇一個工單模板時，列表會展示模板名稱 `Template Name` 和模板描述 `This template is for testing!`。 同時，標題會預先填充為 `[TEST]`，而正文將預先填充 `This is the template!`。該 Issue 會被指派給 `user1`。 最後，Issue 還會被分配兩個標籤，`bug` 和 `help needed`，並且將問題指向 `main` 分支。
## YAML 模板語法
YAML 模板格式如下，相比 Markdown 模板提供了更多實用性的功能。
```yaml
name: 表單名稱
about: 表單描述
title: 默認標題
body: 主體內容
type: 定義表單元素類型
id: 定義表單標號
attributes: 擴展的屬性
validations: 內容校驗
```
下例 YAML 設定文件完整定義了一個用於提交 bug 的問卷調查。
```yaml
name: Bug Report
about: File a bug report
title: "[Bug]: "
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report!
- type: input
id: contact
attributes:
label: Contact Details
description: How can we get in touch with you if we need more info?
placeholder: ex. [email protected]
validations:
required: false
- type: textarea
id: what-happened
attributes:
label: What happened?
description: Also tell us, what did you expect to happen?
placeholder: Tell us what you see!
value: "A bug happened!"
validations:
required: true
- type: dropdown
id: version
attributes:
label: Version
description: What version of our software are you running?
options:
- 1.0.2 (Default)
- 1.0.3 (Edge)
validations:
required: true
- type: dropdown
id: browsers
attributes:
label: What browsers are you seeing the problem on?
multiple: true
options:
- Firefox
- Chrome
- Safari
- Microsoft Edge
- type: textarea
id: logs
attributes:
label: Relevant log output
description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
render: shell
- type: checkboxes
id: terms
attributes:
label: Code of Conduct
description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
options:
- label: I agree to follow this project's Code of Conduct
required: true
```
### Markdown 段落
您可以在 YAML 模板中使用 `markdown` 元素為開發者提供額外的上下文支撐，這部分內容會作為建立工單的提示但不會作為工單內容提交。
`attributes` 子項提供了以下擴展能力：
| 鍵 | 描述 | 必選 | 類型 | 預設值 | 有效值 |
| ------- | ------------------------------ | ---- | ------ | ------ | ------ |
| `value` | 渲染的文本。支援 Markdown 格式 | 必選 | 字符串 | - | - |
### Textarea 多行文本輸入框
您可以使用 `textarea` 元素在表單中添加多行文本輸入框。 除了輸入文本，開發者還可以在 `textarea` 區域附加文件。
`attributes` 子項提供了以下擴展能力：
| 鍵 | 描述 | 必選 | 類型 | 預設值 | 有效值 |
| ------------- | ----------------------------------------------------------------------------------------------------- | ---- | ------ | -------- | ------------------ |
| `label` | 預期使用者輸入的簡短描述，也以表單形式顯示。 | 必選 | 字符串 | - | - |
| `description` | 提供上下文或指導的文本區域的描述，以表單形式顯示。 | 可選 | 字符串 | 空字符串 | - |
| `placeholder` | 半透明的佔位符，在文本區域空白時呈現 | 可選 | 字符串 | 空字符串 | - |
| `value` | 在文本區域中預填充的文本。 | 可選 | 字符串 | - | - |
| `render` | 如果提供了值，提交的文本將格式化為程式碼塊。 提供此鍵時，文本區域將不會擴展到文件附件或 Markdown 編輯。 | 可選 | 字符串 | - | Gitea 支援的語言。 |
`validations` 子項提供以下文本校驗參數：
| 鍵 | 描述 | 必選 | 類型 | 預設值 | 有效值 |
| ---------- | ---------------------------- | ---- | ------ | ------ | ------ |
| `required` | 防止在元素完成之前提交表單。 | 可選 | 布爾型 | false | - |
### Input 單行輸入框
您可以使用 `input` 元素添加單行文本欄位到表單。
`attributes` 子項提供了以下擴展能力：
| 鍵 | 描述 | 必選 | 類型 | 預設值 | 有效值 |
| ------------- | ---------------------------------------------- | ---- | ------ | -------- | ------ |
| `label` | 預期使用者輸入的簡短描述，也以表單形式顯示。 | 必選 | 字符串 | - | - |
| `description` | 提供上下文或指導的欄位的描述，以表單形式顯示。 | 可選 | 字符串 | 空字符串 | - |
| `placeholder` | 半透明的佔位符，在欄位空白時呈現。 | 可選 | 字符串 | 空字符串 | - |
| `value` | 欄位中預填的文本。 | 可選 | 字符串 | - | - |
`validations` 子項提供以下文本校驗參數：
| 鍵 | 描述 | 必選 | 類型 | 預設值 | 有效值 |
| ----------- | -------------------------------- | ---- | ------ | ------ | -------------------------------------------------------------- |
| `required` | 防止在未填內容時提交表單。 | 可選 | 布爾型 | false | - |
| `is_number` | 防止在未填數字時提交表單。 | 可選 | 布爾型 | false | - |
| `regex` | 直到滿足了與正則表達式匹配的值。 | 可選 | 字符串 | - | [正則表達式](https://en.wikipedia.org/wiki/Regular_expression) |
### Dropdown 下拉菜單
您可以使用 `dropdown` 元素在表單中添加下拉菜單。
`attributes` 子項提供了以下擴展能力：
| 鍵 | 描述 | 必選 | 類型 | 預設值 | 有效值 |
| ------------- | --------------------------------------------------------- | ---- | ---------- | -------- | ------ |
| `label` | 預期使用者輸入的簡短描述，以表單形式顯示。 | 必選 | 字符串 | - | - |
| `description` | 提供上下文或指導的下拉列表的描述，以表單形式顯示。 | 可選 | 字符串 | 空字符串 | - |
| `multiple` | 確定使用者是否可以選擇多個選項。 | 可選 | 布爾型 | false | - |
| `options` | 使用者可以選擇的選項列表。 不能為空，所有選擇必須是不同的。 | 必選 | 字符串數組 | - | - |
`validations` 子項提供以下文本校驗參數：
| 鍵 | 描述 | 必選 | 類型 | 預設值 | 有效值 |
| ---------- | ---------------------------- | ---- | ------ | ------ | ------ |
| `required` | 防止在元素完成之前提交表單。 | 可選 | 布爾型 | false | - |
### Checkboxes 複選框
您可以使用 `checkboxes` 元素添加一組複選框到表單。
`attributes` 子項提供了以下擴展能力：
| 鍵 | 描述 | 必選 | 類型 | 預設值 | 有效值 |
| ------------- | ----------------------------------------------------- | ---- | ------ | -------- | ------ |
| `label` | 預期使用者輸入的簡短描述，以表單形式顯示。 | 必選 | 字符串 | - | - |
| `description` | 複選框集的描述，以表單形式顯示。 支援 Markdown 格式。 | 可選 | 字符串 | 空字符串 | - |
| `options` | 使用者可以選擇的複選框列表。 有關語法，請參閱下文。 | 必選 | 數組 | - | - |
對於 `options`，您可以設定以下參數：
| 鍵 | 描述 | 必選 | 類型 | 預設值 | 有效值 |
| ---------- | --------------------------------------------------------------------------------- | ---- | ------ | ------ | ------ |
| `label` | 選項的標識符，顯示在表單中。 支援 Markdown 用於粗體或斜體文本格式化和超文本鏈接。 | 必選 | 字符串 | - | - |
| `required` | 防止在元素完成之前提交表單。 | 可選 | 布爾型 | false | - |
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/issues-prs/labels.md
+33
View File
@@ -0,0 +1,33 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "labels"
sidebar_position: 13
aliases:
- /zh-tw/labels
---
# 標籤
您可以使用標籤對工單和合併請求進行分類，並提高對它們的概覽。
## 建立標籤
對於儲存庫，可以在 `工單（Issues）` 中點擊 `標籤（Labels）` 來建立標籤。
對於組織，您可以定義組織級別的標籤，這些標籤與所有組織儲存庫共享，包括已存在的儲存庫和新建立的儲存庫。可以在組織的 `設定（Settings）` 中建立組織級別的標籤。
標籤具有必填的名稱和顏色，可選的描述，以及必須是獨佔的或非獨佔的（見下面的“作用域標籤”）。
當您建立一個儲存庫時，可以透過使用 `工單標籤（Issue Labels）` 選項來選擇標籤集。該選項列出了一些在您的實例上 [全域設定的可用標籤集](../../administration/customizing-gitea.md)。在建立儲存庫時，這些標籤也將被建立。
## 作用域標籤
作用域標籤用於確保將至多一個具有相同作用域的標籤分配給工單或合併請求。例如，如果標籤 `kind/bug` 和 `kind/enhancement` 的獨佔選項被設定，那麼工單隻能被分類為 bug 或 enhancement 中的一個。
作用域標籤的名稱必須包含 `/`（不能在名稱的任一端）。標籤的作用域是基於最後一個 `/` 決定的，因此例如標籤 `scope/subscope/item` 的作用域是 `scope/subscope`。
## 按標籤篩選
工單和合併請求列表可以按標籤進行篩選。選擇多個標籤將顯示具有所有選定標籤的工單和合併請求。
按住 alt 鍵並點擊標籤，可以將具有所選標籤的工單和合併請求從列表中排除。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/issues-prs/linked-references.md
+143
View File
@@ -0,0 +1,143 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "automatically-linked-references"
sidebar_position: 15
aliases:
- /zh-tw/automatically-linked-references
---
# 自動鏈接引用
當發佈工單、合併請求或評論時，文本描述會被解析以查找引用。這些引用將顯示為工單視圖中的鏈接，並且在某些情況下會觸發特定的“操作”。
類似地，當列出提交消息時，它們也會被解析，並且當它們被推送到主分支時可以觸發“操作”。
為了防止意外建立引用，對於引用的識別有一定的規則。例如，它們不應該包含在程式碼文本內部。它們還應該在周圍的文本中合理清晰（例如，使用空格）。
## 使用者、團隊和組織提及
當找到形式為 `@username` 的文本，並且 `username` 與現有使用者的名稱匹配時，將建立一個“提及”引用。這將通過將文本更改為指向該使用者個人資料的鏈接來顯示，並根據被提及的使用者是否具有訪問內容所需的權限來可能建立通知。
範例：
> [@John](#)，你能看一下這個嗎？
對於團隊和組織也是有效的：
> [@Documenters](#)，我們需要為此進行規劃。
> [@CoolCompanyInc](#)，這個問題關係到我們所有人！
團隊將在適當時收到郵件通知，但整個組織不會收到通知。
提交消息不會產生使用者通知。
## 提交
可以使用提交的 SHA1 哈希或至少七個字符的一部分來引用提交。它們將顯示為指向相應提交的鏈接。
範例：
> 這個錯誤是在 [e59ff077](#) 中引入的
## 工單和合併請求
可以使用簡單的符號 `#1234` 來建立對另一個工單或合併請求的引用，其中 _1234_ 是同一儲存庫中一個工單或合併請求的編號。這些引用將顯示為指向被引用內容的鏈接。
建立此類型引用的效果是，在被引用的文件中建立一個“通知”，前提是引用的建立者對其具有讀取權限。
範例：
> 這似乎與 [#1234](#) 相關
還可以使用形式 `owner/repository#1234` 來引用其他儲存庫中的工單和合併請求：
> 這似乎與 [mike/compiler#1234](#) 相關
或者也可以使用 `!1234` 符號。雖然在 Gitea 中合併請求是工單的一種形式，但 `#1234` 形式總是鏈接到工單；如果鏈接的條目恰好是一個合併請求，Gitea 會適當地進行重定向。而使用 `!1234` 符號，則會建立一個合併請求鏈接，根據需要會被重定向到工單。然而，如果使用外部跟蹤器，這個區別可能很重要，因為工單和合併請求的鏈接是不能互換的。
## 可操作的引用在合併請求和提交消息中
有時，一個提交或合併請求可能會修復或重新出現在某個特定工單中。Gitea 支援在引用之前加上特定的“關鍵字”來關閉和重新打開被引用的工單。常見的關鍵字包括“closes”、“fixes”、“reopens”等。這個列表可以由站點管理員進行 [自訂](../../administration/config-cheat-sheet)。
範例：
> 這個合併請求 _closes_ [#1234](#)
如果可操作的引用被接受，這將在被引用的工單上建立一個通知，宣佈當引用的合併請求被合併時該工單將被關閉。
為了接受可操作的引用，必須滿足以下至少一項條件之一：
- 評論者在建立引用時具有關閉或重新打開工單的權限。
- 引用位於提交消息中。
- 引用作為合併請求描述的一部分發布。
在最後一種情況下，只有當合併合併請求的人具有相應權限時，工單纔會被關閉或重新打開。
此外，只有合併請求和提交消息可以建立一個操作，只有工單可以透過這種方式被關閉或重新打開。
預設的關鍵字如下：
- **關閉工單**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved
- **重新打開工單**: reopen, reopens, reopened
## 合併請求和提交消息中的時間跟蹤
當提交或合併合併請求導致自動關閉工單時，還可以透過提交消息添加解決此工單所花費的時間。
要指定解決工單所花費的時間，需要在工單編號後面以 `@<number><time-unit>` 的格式指定時間。在一個提交消息中，可以指定多個已解決的工單，併為每個工單指定花費的時間。
支援的時間單位（`<time-unit>`）：
- `m` - 分鐘
- `h` - 小時
- `d` - 天（相當於 8 小時）
- `w` - 周（相當於 5 天）
- `mo` - 月（相當於 4 周）
用於指定時間的數字（`<number>`）也可以是小數，例如 `@1.5h` 表示一小時半。多個時間單位可以結合使用，例如 `@1h10m` 表示 1 小時 10 分鐘。
提交消息範例：
> Fixed #123 spent @1h, refs #102, fixes #124 @1.5h
這將導致工單 #123 增加 1 小時，工單 #124 增加 1 小時半。
## 外部跟蹤器
Gitea 支援使用外部工單跟蹤器，並可以在合併請求中建立對外部託管的工單的引用。但是，如果外部跟蹤器使用數字來標識工單，那麼它們將與 Gitea 中託管的合併請求無法區分。為了解決這個問題，Gitea 允許使用 `!` 標記來標識合併請求。例如：
> 這是工單 [#1234](#)，並鏈接到外部跟蹤器。
> 這是合併請求 [!1234](#)，並鏈接到 Gitea 中的合併請求。
在工單和合併請求中，`!` 和 `#` 可以互換使用，除非需要進行區分。如果儲存庫使用外部跟蹤器，預設情況下，合併提交消息將使用 `!` 作為引用。
## 工單和合併請求引用摘要
下表說明了工單和合併請求的不同類型的交叉引用。在範例中，`User1/Repo1` 指的是使用引用的儲存庫，而 `UserZ/RepoZ` 表示另一個儲存庫。
| 在 User1/Repo1 中的引用 | Repo1 的工單是外部的 | RepoZ 的工單是外部的 | 渲染效果 |
| ----------------------- | :------------------: | :------------------: | --------------------------------------------- |
| `#1234` | 否 | - | 鏈接到 `User1/Repo1` 中的工單/合併請求 1234 |
| `!1234` | 否 | - | 鏈接到 `User1/Repo1` 中的工單/合併請求 1234 |
| `#1234` | 是 | - | 鏈接到 `User1/Repo1` 的 _外部工單_ 1234 |
| `!1234` | 是 | - | 鏈接到 `User1/Repo1` 的 _PR_ 1234 |
| `User1/Repo1#1234` | 否 | - | 鏈接到 `User1/Repo1` 中的工單/合併請求 1234 |
| `User1/Repo1!1234` | 否 | - | 鏈接到 `User1/Repo1` 中的工單/合併請求 1234 |
| `User1/Repo1#1234` | 是 | - | 鏈接到 `User1/Repo1` 的 _外部工單_ 1234 |
| `User1/Repo1!1234` | 是 | - | 鏈接到 `User1/Repo1` 的 _PR_ 1234 |
| `UserZ/RepoZ#1234` | - | 否 | 鏈接到 `UserZ/RepoZ` 中的工單/合併請求 1234 |
| `UserZ/RepoZ!1234` | - | 否 | 鏈接到 `UserZ/RepoZ` 中的工單/合併請求 1234 |
| `UserZ/RepoZ#1234` | - | 是 | 鏈接到 `UserZ/RepoZ` 的 _外部工單_ 1234 |
| `UserZ/RepoZ!1234` | - | 是 | 鏈接到 `UserZ/RepoZ` 的 _PR_ 1234 |
| **字母數字工單編號:** | - | - | - |
| `AAA-1234` | 是 | - | 鏈接到 `User1/Repo1` 的 _外部工單_ `AAA-1234` |
| `!1234` | 是 | - | 鏈接到 `User1/Repo1` 的 _PR_ 1234 |
| `User1/Repo1!1234` | 是 | - | 鏈接到 `User1/Repo1` 的 _PR_ 1234 |
| _不支援_ | - | 是 | 鏈接到 `UserZ/RepoZ` 的 _外部工單_ `AAA-1234` |
| `UserZ/RepoZ!1234` | - | 是 | 鏈接到 `UserZ/RepoZ` 中的 _PR_ 1234 |
_最後一部分適用於使用字母數字格式的外部工單跟蹤器的儲存庫。_
_**-**: 不適用_
注意：不完全支援具有不同類型工單（外部 vs. 內部）的儲存庫之間的自動引用，可能會導致無效鏈接。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/issues-prs/merge-message-templates.md
+47
View File
@@ -0,0 +1,47 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "merge-message-templates"
sidebar_position: 15
aliases:
- /zh-tw/merge-message-templates
---
# 合併消息模板
## 文件名
PR 預設合併消息模板可能的文件名：
- `.gitea/default_merge_message/MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/SQUASH_TEMPLATE.md`
- `.gitea/default_merge_message/MANUALLY-MERGED_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-UPDATE-ONLY_TEMPLATE.md`
## 變量
您可以在這些模板中使用以下以 `${}` 包圍的變量，這些變量遵循 [os.Expand](https://pkg.go.dev/os#Expand) 語法：
- BaseRepoOwnerName：此合併請求的基礎儲存庫所有者名稱
- BaseRepoName：此合併請求的基礎儲存庫名稱
- BaseBranch：此合併請求的基礎儲存庫目標分支名稱
- HeadRepoOwnerName：此合併請求的源儲存庫所有者名稱
- HeadRepoName：此合併請求的源儲存庫名稱
- HeadBranch：此合併請求的源儲存庫分支名稱
- PullRequestTitle：合併請求的標題
- PullRequestDescription：合併請求的描述
- PullRequestPosterName：合併請求的提交者名稱
- PullRequestIndex：合併請求的索引號
- PullRequestReference：合併請求的引用字符與索引號。例如，#1、!2
- ClosingIssues：返回一個包含將由此合併請求關閉的所有工單的字符串。例如 `close #1, close #2`
- ReviewedOn: 該提交所屬的合併請求。例如： `Reviewed-on: https://gitea.com/foo/bar/pulls/1`
- ReviewedBy: 誰同意的此合併請求。例如： `Reviewed-by: Jane Doe <[email protected]>`
## 變基（Rebase）
在沒有合併提交的情況下進行變基時，`REBASE_TEMPLATE.md` 修改最後一次提交的消息。此模板還提供以下附加變量：
- CommitTitle：提交的標題
- CommitBody：提交的正文文本
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/issues-prs/pull-request.md
+60
View File
@@ -0,0 +1,60 @@
---
date: "2018-06-01T19:00:00+02:00"
slug: "pull-request"
sidebar_position: 13
aliases:
- /zh-tw/pull-request
---
# 合併請求
合併請求(PR)是一種提出對儲存庫進行更改的方式。
它是一種將一個分支合併到另一個分支的請求，附帶有對所做更改的描述。
合併請求通常用作貢獻者對儲存庫貢獻程式碼的方式，儲存庫的維護者可以透過對合併請求進行審查來決定是否接受這些更改。
## 建立合併請求
要建立合併請求，您需要遵循以下步驟：
1. **Fork 儲存庫** - 如果您沒有直接對儲存庫進行更改的權限，您需要將儲存庫 fork 到您自己的帳號中。
這將建立一個您可以對其進行更改的儲存庫副本。
2. **建立分支（可選）** - 在 fork 的儲存庫中建立一個新分支，該分支包含您要提出的更改。
給分支取一個描述性的名稱，以指示更改的內容。
3. **進行更改** - 進行您想要的更改，提交併將其推送到 fork 的儲存庫中。
4. **建立合併請求** - 轉到原始儲存庫並轉到“合併請求”選項卡。單擊“新建合併請求”按鈕，並將您的新分支選擇為源分支。
為您的合併請求輸入描述性標題和描述，然後單擊“建立合併請求”。
## 評審合併請求
建立合併請求後，將觸發評審流程。儲存庫的維護者將收到合併請求的通知，並可以審查所做的更改。
他們可以留下評論、請求更改或批准更改。
如果維護者請求更改，您需要在分支中進行這些更改，並將更改推送到 fork 的儲存庫中。
合併請求將自動使用新更改進行更新。
如果維護者批准更改，他們可以將合併請求合併到儲存庫中。
## 關閉合併請求
如果您不接受該合併請求，您可以關閉它。
要關閉合併請求，請轉到打開的合併請求並單擊“關閉合併請求”按鈕。這將關閉合併請求並且不會將其合併。
## 使用“Work In Progress”標記
在合併請求中使用“Work In Progress”標記可以防止合併請求被意外合併。
要將合併請求標記為“Work In Progress”，您必須在其標題中添加前綴`WIP:`或`[WIP]`（不區分大小寫）。
標記前綴可以在您的`app.ini`文件中進行設定：
```
[repository.pull-request]
WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP]
```
列表的第一個值將用於 helpers 程式。
## 合併請求模板
有關合併請求模板的更多資訊請您移步 : [工單與合併請求模板](issue-pull-request-templates)
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "Packages",
"position": 40,
"link": {
"type": "generated-index",
"slug": "/usage/packages",
"description": "Managing packages and package registries"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/alpine.md
+121
View File
@@ -0,0 +1,121 @@
---
date: "2023-03-25T00:00:00+00:00"
slug: "alpine"
sidebar_position: 4
---
# Alpine 套件註冊表
在您的使用者或組織中發佈 [Alpine](https://pkgs.alpinelinux.org/) 套件。
## 要求
要使用 Alpine 註冊表，您需要使用像 curl 這樣的 HTTP 客戶端來上傳包，並使用像 apk 這樣的套件管理器來消費包。
以下範例使用 `apk`。
## 設定套件註冊表
要註冊 Alpine 註冊表，請將 URL 添加到已知的 apk 源列表中 (`/etc/apk/repositories`):
```
https://gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
```
| 佔位符 | 描述 |
| ------------ | -------------- |
| `owner` | 套件所有者 |
| `branch` | 要使用的分支名 |
| `repository` | 要使用的儲存庫名 |
如果註冊表是私有的，請在 URL 中提供憑據。您可以使用密碼或[個人存取權杖](development/api-usage.md#透過-api-認證):
```
https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
```
Alpine 註冊表文件使用 RSA 密鑰進行簽名，apk 必須知道該密鑰。下載公鑰並將其儲存在 `/etc/apk/keys/` 目錄中：
```shell
curl -JO https://gitea.example.com/api/packages/{owner}/alpine/key
```
之後，更新本地套件索引：
```shell
apk update
```
## 發佈套件
要發佈一個 Alpine 包（`*.apk`），請執行帶有包內容的 HTTP `PUT` 操作，將其放在請求體中。
```
PUT https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}
```
| 參數 | 描述 |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `owner` | 包的所有者。 |
| `branch` | 分支可以與操作系統的發行版本匹配，例如：v3.17。 |
| `repository` | 儲存庫可以用於[分組包](https://wiki.alpinelinux.org/wiki/Repositories) 或者只是 `main` 或類似的名稱。 |
使用 HTTP 基本身份驗證的範例請求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.apk \
https://gitea.example.com/api/packages/testuser/alpine/v3.17/main
```
如果您使用的是雙重身份驗證或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)代替密碼。
您不能將具有相同名稱的文件兩次發佈到一個包中。您必須首先刪除現有的包文件。
伺服器將以以下的 HTTP 狀態碼響應：
| HTTP 狀態碼 | 含義 |
| ----------------- | ------------------------------------------ |
| `201 Created` | 套件已發佈。 |
| `400 Bad Request` | 套件的名稱、版本、分支、儲存庫或架構無效。 |
| `409 Conflict` | 具有相同參數組合的包文件已存在於套件中。 |
## 刪除套件
要刪除 Alpine 包，執行 HTTP 的 DELETE 操作。如果沒有文件，這將同時刪除包版本。
```
DELETE https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}/{architecture}/{filename}
```
| 參數 | 描述 |
| -------------- | -------------- |
| `owner` | 套件的所有者 |
| `branch` | 要使用的分支名 |
| `repository` | 要使用的儲存庫名 |
| `architecture` | 套件的架構 |
| `filename` | 要刪除的文件名 |
使用 HTTP 基本身份驗證的範例請求：
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/alpine/v3.17/main/test-package-1.0.0.apk
```
伺服器將以以下的 HTTP 狀態碼響應：
| HTTP 狀態碼 | 含義 |
| ---------------- | ------------------ |
| `204 No Content` | 成功 |
| `404 Not Found` | 未找到套件或文件 |
## 安裝套件
要從 Alpine 註冊表安裝套件，請執行以下命令：
```shell
# use latest version
apk add {package_name}
# use specific version
apk add {package_name}={package_version}
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/cargo.md
+98
View File
@@ -0,0 +1,98 @@
---
date: "2022-11-20T00:00:00+00:00"
slug: "cargo"
sidebar_position: 5
---
# Cargo 套件註冊表
為您的使用者或組織發佈 [Cargo](https://doc.rust-lang.org/stable/cargo/) 套件。
## 要求
若要使用 Cargo 套件註冊表, 您需要安裝 [Rust 和 Cargo](https://www.rust-lang.org/tools/install).
Cargo 將可用套件的資訊儲存在一個儲存在 git 儲存庫中的套件索引中。
這個儲存庫是與註冊表交互所必需的。
下面的部分將介紹如何建立它。
## 索引儲存庫
Cargo 將可用套件的資訊儲存在一個儲存在 git 儲存庫中的套件索引中。
在 Gitea 中，這個儲存庫有一個特殊的名稱叫做 `_cargo-index`。
在上傳套件之後，它的元資料會自動寫入索引中。
不應手動修改這個註冊表的內容。
使用者或組織套件設定頁面允許建立這個索引儲存庫以及設定文件。
如果需要，此操作將重寫設定文件。
例如，如果 Gitea 實例的域名已更改，這將非常有用。
如果儲存在 Gitea 中的套件與索引註冊表中的資訊不同步，設定頁面允許重建這個索引註冊表。
這個操作將遍歷註冊表中的所有套件，並將它們的資訊寫入索引中。
如果有很多套件，這個過程可能需要一些時間。
## 設定套件註冊表
要註冊這個套件註冊表，必須更新 Cargo 的設定。
將以下文本添加到位於當前使用者主目錄中的設定文件中（例如 `~/.cargo/config.toml`）：
```
[registry]
default = "gitea"
[registries.gitea]
index = "sparse+https://gitea.example.com/api/packages/{owner}/cargo/" # Sparse index
# index = "https://gitea.example.com/{owner}/_cargo-index.git" # Git
[net]
git-fetch-with-cli = true
```
| 參數 | 描述 |
| ------- | ---------------- |
| `owner` | 套件的所有者。 |
如果這個註冊表是私有的或者您想要發佈新的套件，您必須設定您的憑據。
將憑據部分添加到位於當前使用者主目錄中的憑據文件中（例如 `~/.cargo/credentials.toml`）：
```
[registries.gitea]
token = "Bearer {token}"
```
| 參數 | 描述 |
| ------- | ------------------------------------------------------------------------------------- |
| `token` | 您的[個人存取權杖](development/api-usage.md#透過-api-認證) |
## 發佈套件
在專案中運行以下命令來發布套件：
```shell
cargo publish
```
如果已經存在同名和版本的套件，您將無法發佈新的套件。您必須先刪除現有的套件。
## 安裝套件
要從套件註冊表安裝套件，請執行以下命令：
```shell
cargo add {package_name}
```
| 參數 | 描述 |
| -------------- | ------------ |
| `package_name` | 套件名稱。 |
## 支援的命令
```
cargo publish
cargo add
cargo install
cargo yank
cargo unyank
cargo search
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/chef.md
+84
View File
@@ -0,0 +1,84 @@
---
date: "2023-01-20T00:00:00+00:00"
slug: "chef"
sidebar_position: 5
---
# Chef 套件註冊表
為您的使用者或組織發佈 [Chef](https://chef.io/) cookbooks。
## 要求
要使用 Chef 套件註冊表，您需要使用 [`knife`](https://docs.chef.io/workstation/knife/).
## 認證
Chef 套件註冊表不使用使用者名稱和密碼進行身份驗證，而是使用私鑰和公鑰對請求進行簽名。
請前往套件所有者設定頁面以建立必要的密鑰對。
只有公鑰儲存在Gitea中。如果您丟失了私鑰的存取權限，您必須重新生成密鑰對。
[設定 `knife`](https://docs.chef.io/workstation/knife_setup/)，使用下載的私鑰，並將 Gitea 使用者名稱設定為 `client_name`。
## 設定套件註冊表
要將 [`knife` 設定](https://docs.chef.io/workstation/knife_setup/)為使用 Gitea 套件註冊表，請將 URL 添加到 `~/.chef/config.rb` 文件中。
```
knife[:supermarket_site] = 'https://gitea.example.com/api/packages/{owner}/chef'
```
| 參數 | 描述 |
| ------- | -------------- |
| `owner` | 套件的所有者 |
## 發佈套件
若要發佈 Chef 套件，請執行以下命令：
```shell
knife supermarket share {package_name}
```
| 參數 | 描述 |
| -------------- | ---------- |
| `package_name` | 套件名稱 |
如果已經存在同名和版本的套件，則無法發佈新的套件。您必須先刪除現有的套件。
## 安裝套件
要從套件註冊表中安裝套件，請執行以下命令：
```shell
knife supermarket install {package_name}
```
您可以指定套件的版本，這是可選的：
```shell
knife supermarket install {package_name} {package_version}
```
| 參數 | 描述 |
| ----------------- | ---------- |
| `package_name` | 套件名稱 |
| `package_version` | 套件版本 |
## 刪除套件
如果您想要從註冊表中刪除套件，請執行以下命令：
```shell
knife supermarket unshare {package_name}
```
可選地，您可以指定套件的版本：
```shell
knife supermarket unshare {package_name}/versions/{package_version}
```
| 參數 | 描述 |
| ----------------- | ---------- |
| `package_name` | 套件名稱 |
| `package_version` | 套件版本 |
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/composer.md
+110
View File
@@ -0,0 +1,110 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "composer"
sidebar_position: 10
---
# Composer 套件註冊表
為您的使用者或組織發佈 [Composer](https://getcomposer.org/) 套件。
## 要求
要使用 Composer 套件註冊表，您可以使用 [Composer](https://getcomposer.org/download/) 消費，並使用類似 `curl` 的 HTTP 上傳客戶端發佈套件。
## 發佈套件
要發佈 Composer 套件，請執行 HTTP `PUT` 操作，將套件內容放入請求體中。
套件內容必須是包含 `composer.json` 文件的壓縮 PHP 專案。
如果已經存在同名和版本的套件，則無法發佈新的套件。您必須先刪除現有的套件。
```
PUT https://gitea.example.com/api/packages/{owner}/composer
```
| 參數 | 描述 |
| ------- | -------------- |
| `owner` | 套件的所有者 |
如果 `composer.json` 文件不包含 `version` 屬性，您必須將其作為查詢參數提供：
```
PUT https://gitea.example.com/api/packages/{owner}/composer?version={x.y.z}
```
使用 HTTP 基本身份驗證的範例請求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/project.zip \
https://gitea.example.com/api/packages/testuser/composer
```
或者將套件版本指定為查詢參數：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/project.zip \
https://gitea.example.com/api/packages/testuser/composer?version=1.0.3
```
如果您使用 2FA 或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)替代密碼。
伺服器將以以下 HTTP 狀態碼響應。
| HTTP 狀態碼 | 含義 |
| ----------------- | ----------------------------------------------------------- |
| `201 Created` | 套件已發佈 |
| `400 Bad Request` | 套件名稱和/或版本無效，或具有相同名稱和版本的套件已存在 |
## 設定套件註冊表
要註冊套件註冊表，您需要將其添加到 Composer 的 `config.json` 文件中（通常可以在 `<user-home-dir>/.composer/config.json` 中找到）：
```json
{
"repositories": [{
"type": "composer",
"url": "https://gitea.example.com/api/packages/{owner}/composer"
}
]
}
```
要使用憑據訪問套件註冊表，您必須在 `auth.json` 文件中指定它們，如下所示：
```json
{
"http-basic": {
"gitea.example.com": {
"username": "{username}",
"password": "{password}"
}
}
}
```
| 參數 | 描述 |
| ---------- | --------------------------- |
| `owner` | 套件的所有者 |
| `username` | 您的 Gitea 使用者名稱 |
| `password` | 您的Gitea密碼或個人存取權杖 |
## 安裝套件
要從套件註冊表中安裝套件，請執行以下命令：
```shell
composer require {package_name}
```
您可以指定套件的版本，這是可選的：
```shell
composer require {package_name}:{package_version}
```
| 參數 | 描述 |
| ----------------- | ---------- |
| `package_name` | 套件名稱 |
| `package_version` | 套件版本 |
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/conan.md
+89
View File
@@ -0,0 +1,89 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "conan"
sidebar_position: 20
---
# Conan 套件註冊表
為您的使用者或組織發佈 [Conan](https://conan.io/) 套件。
## 要求
要使用 [conan](https://conan.io/downloads.html) 套件註冊表，您需要使用 conan 命令行工具來消費和發佈套件。
## 設定套件註冊表
要註冊套件註冊表，您需要設定一個新的 Conan remote：
```shell
conan remote add {remote} https://gitea.example.com/api/packages/{owner}/conan
conan user --remote {remote} --password {password} {username}
```
| 參數 | 描述 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `remote` | 遠程名稱。 |
| `username` | 您的 Gitea 使用者名稱。 |
| `password` | 您的 Gitea 密碼。如果您使用 2FA 或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)替代密碼。 |
| `owner` | 套件的所有者。 |
例如:
```shell
conan remote add gitea https://gitea.example.com/api/packages/testuser/conan
conan user --remote gitea --password password123 testuser
```
## 發佈套件
通過運行以下命令發佈 Conan 套件：
```shell
conan upload --remote={remote} {recipe}
```
| 參數 | 描述 |
| -------- | --------------- |
| `remote` | 遠程名稱 |
| `recipe` | 要上傳的 recipe |
For example:
```shell
conan upload --remote=gitea ConanPackage/1.2@gitea/final
```
Gitea Conan 套件註冊表支援完整的[版本修訂](https://docs.conan.io/en/latest/versioning/revisions.html)。
## 安裝套件
要從套件註冊表中安裝Conan套件，請執行以下命令：
```shell
conan install --remote={remote} {recipe}
```
| 參數 | 描述 |
| -------- | --------------- |
| `remote` | 遠程名稱 |
| `recipe` | 要下載的 recipe |
例如：
```shell
conan install --remote=gitea ConanPackage/1.2@gitea/final
```
## 支援的命令
```
conan install
conan get
conan info
conan search
conan upload
conan user
conan download
conan remove
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/conda.md
+73
View File
@@ -0,0 +1,73 @@
---
date: "2022-12-28T00:00:00+00:00"
slug: "conda"
sidebar_position: 25
---
# Conda 套件註冊表
為您的使用者或組織發佈 [Conda](https://docs.conda.io/en/latest/) 套件。
## 要求
要使用 Conda 套件註冊表，您需要使用 [conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) 命令行工具。
## 設定套件註冊表
要註冊套件註冊表並提供憑據，請編輯您的 `.condarc` 文件：
```yaml
channel_alias: https://gitea.example.com/api/packages/{owner}/conda
channels:
- https://gitea.example.com/api/packages/{owner}/conda
default_channels:
- https://gitea.example.com/api/packages/{owner}/conda
```
| 佔位符 | 描述 |
| ------- | -------------- |
| `owner` | 套件的所有者 |
有關各個設定的解釋，請參閱[官方文件](https://conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html)。
如果需要提供憑據，可以將它們作為通道 URL 的一部分嵌入（`https://user:[email protected]/...`）。
## 發佈套件
要發佈一個套件，請執行一個HTTP `PUT`操作，請求正文中包含套件內容。
```
PUT https://gitea.example.com/api/packages/{owner}/conda/{channel}/{filename}
```
| 佔位符 | 描述 |
| ---------- | --------------------------------------------------------------------------------------------------- |
| `owner` | 套件的所有者 |
| `channel` | 套件的[通道](https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html)（可選） |
| `filename` | 文件名 |
使用HTTP基本身份驗證的範例請求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/package-1.0.conda \
https://gitea.example.com/api/packages/testuser/conda/package-1.0.conda
```
如果已經存在同名和版本的套件，則無法發佈套件。您必須先刪除現有的套件。
## 安裝套件
要從套件註冊表中安裝套件，請執行以下命令之一：
```shell
conda install {package_name}
conda install {package_name}={package_version}
conda install -c {channel} {package_name}
```
| 參數 | 描述 |
| ----------------- | -------------------- |
| `package_name` | 套件的名稱 |
| `package_version` | 套件的版本 |
| `channel` | 套件的通道（可選） |
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/container.md
+81
View File
@@ -0,0 +1,81 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "container"
sidebar_position: 30
---
# 容器註冊表
為您的使用者或組織發佈符合 [Open Container Initiative(OCI)](https://opencontainers.org/) 規範的鏡像。
該容器註冊表遵循 OCI 規範，並支援所有相容的鏡像類型，如 [Docker](https://www.docker.com/) 和 [Helm Charts](https://helm.sh/)。
## 目錄
要使用容器註冊表，您可以使用適用於特定鏡像類型的工具。
以下範例使用 `docker` 客戶端。
## 登入容器註冊表
要推送鏡像或者如果鏡像位於私有註冊表中，您需要進行身份驗證：
```shell
docker login gitea.example.com
```
如果您使用的是 2FA 或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)替代密碼進行身份驗證。
## 鏡像命名約定
鏡像必須遵循以下命名約定：
`{registry}/{owner}/{image}`
例如，以下是所有者為 `testuser` 的有效鏡像名稱範例：
`gitea.example.com/testuser/myimage`
`gitea.example.com/testuser/my-image`
`gitea.example.com/testuser/my/image`
**注意:** 該註冊表僅支援大小寫不敏感的標籤名稱。因此，`image:tag` 和 `image:Tag` 將被視為相同的鏡像和標籤。
## 推送鏡像
透過執行以下命令來推送鏡像：
```shell
docker push gitea.example.com/{owner}/{image}:{tag}
```
| 參數 | 描述 |
| ------- | ------------ |
| `owner` | 鏡像的所有者 |
| `image` | 鏡像的名稱 |
| `tag` | 鏡像的標籤 |
例如：
```shell
docker push gitea.example.com/testuser/myimage:latest
```
## 拉取鏡像
透過執行以下命令來拉取鏡像：
```shell
docker pull gitea.example.com/{owner}/{image}:{tag}
```
| Parameter | Description |
| --------- | ------------ |
| `owner` | 鏡像的所有者 |
| `image` | 鏡像的名稱 |
| `tag` | 鏡像的標籤 |
例如：
```shell
docker pull gitea.example.com/testuser/myimage:latest
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/cran.md
+81
View File
@@ -0,0 +1,81 @@
---
date: "2023-01-01T00:00:00+00:00"
slug: "cran"
sidebar_position: 35
---
# CRAN 套件註冊表
將 [R](https://www.r-project.org/) 套件發佈到您的使用者或組織的類似 [CRAN](https://cran.r-project.org/) 的註冊表。
## 要求
要使用CRAN套件註冊表，您需要安裝 [R](https://cran.r-project.org/)。
## 設定套件註冊表
要註冊套件註冊表，您需要將其添加到 `Rprofile.site` 文件中，可以是系統級別、使用者級別 `~/.Rprofile` 或專案級別：
```
options("repos" = c(getOption("repos"), c(gitea="https://gitea.example.com/api/packages/{owner}/cran")))
```
| 參數 | 描述 |
| ------- | -------------- |
| `owner` | 套件的所有者 |
如果需要提供憑據，可以將它們嵌入到URL(`https://user:[email protected]/...`)中。
## 發佈套件
要發佈 R 套件，請執行帶有套件內容的 HTTP `PUT` 操作。
源程式碼套件：
```
PUT https://gitea.example.com/api/packages/{owner}/cran/src
```
| 參數 | 描述 |
| ------- | -------------- |
| `owner` | 套件的所有者 |
二進制套件：
```
PUT https://gitea.example.com/api/packages/{owner}/cran/bin?platform={platform}&rversion={rversion}
```
| 參數 | 描述 |
| ---------- | -------------- |
| `owner` | 套件的所有者 |
| `platform` | 平台的名稱 |
| `rversion` | 二進制的R版本 |
例如：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/package.zip \
https://gitea.example.com/api/packages/testuser/cran/bin?platform=windows&rversion=4.2
```
如果同名和版本的套件已存在，則無法發佈套件。您必須首先刪除現有的套件。
## 安裝套件
要從套件註冊表中安裝R套件，請執行以下命令：
```shell
install.packages("{package_name}")
```
| 參數 | 描述 |
| -------------- | ----------------- |
| `package_name` | The package name. |
例如：
```shell
install.packages("testpackage")
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/debian.md
+121
View File
@@ -0,0 +1,121 @@
---
date: "2023-01-07T00:00:00+00:00"
slug: "debian"
---
# Debian 套件註冊表
為您的使用者或組織發佈 [Debian](https://www.debian.org/distrib/packages) 套件。
## 要求
要使用 Debian 註冊表，您需要使用類似於 `curl` 的 HTTP 客戶端進行上傳，並使用類似於 `apt` 的套件管理器消費套件。
以下範例使用 `apt`。
## 設定套件註冊表
要註冊 Debian 註冊表，請將 URL 添加到已知 `apt` 源列表中：
```shell
echo "deb [signed-by=/etc/apt/keyrings/gitea-{owner}.asc] https://gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list
```
| 佔位符 | 描述 |
| -------------- | -------------- |
| `owner` | 套件的所有者 |
| `distribution` | 要使用的發行版 |
| `component` | 要使用的元件 |
如果註冊表是私有的，請在 URL 中提供憑據。您可以使用密碼或[個人存取權杖](development/api-usage.md#透過-api-認證)：
```shell
echo "deb [signed-by=/etc/apt/keyrings/gitea-{owner}.asc] https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list
```
Debian 註冊表文件使用 PGP 密鑰進行簽名，`apt` 必須知道該密鑰：
```shell
sudo curl https://gitea.example.com/api/packages/{owner}/debian/repository.key -o /etc/apt/keyrings/gitea-{owner}.asc
```
然後更新本地套件索引：
```shell
apt update
```
## 發佈套件
要發佈一個 Debian 套件（`*.deb`），執行 HTTP `PUT` 操作，並將套件內容放入請求主體中。
```
PUT https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/upload
```
| 參數 | 描述 |
| -------------- | ----------------------------------------------------- |
| `owner` | 套件的所有者 |
| `distribution` | 發行版，可能與操作系統的發行版名稱匹配，例如 `bionic` |
| `component` | 元件，可用於分組套件，或僅為 `main` 或類似的元件。 |
使用 HTTP 基本身份驗證的範例請求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.deb \
https://gitea.example.com/api/packages/testuser/debian/pool/bionic/main/upload
```
如果您使用 2FA 或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)替代密碼。
您無法向套件中多次發佈具有相同名稱的文件。您必須首先刪除現有的套件版本。
伺服器將使用以下 HTTP 狀態程式碼進行響應。
| HTTP 狀態碼 | 意義 |
| ----------------- | ---------------------------------------- |
| `201 Created` | 套件已發佈 |
| `400 Bad Request` | 套件名稱、版本、發行版、元件或架構無效 |
| `409 Conflict` | 具有相同參數組合的套件文件已經存在 |
## 刪除套件
要刪除 Debian 套件，請執行 HTTP `DELETE` 操作。如果沒有文件留下，這將同時刪除套件版本。
```
DELETE https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/{package_name}/{package_version}/{architecture}
```
| 參數 | 描述 |
| ----------------- | -------------- |
| `owner` | 套件的所有者 |
| `package_name` | 套件名稱 |
| `package_version` | 套件版本 |
| `distribution` | 套件發行版 |
| `component` | 套件元件 |
| `architecture` | 套件架構 |
使用 HTTP 基本身份驗證的範例請求：
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/debian/pools/bionic/main/test-package/1.0.0/amd64
```
伺服器將使用以下 HTTP 狀態程式碼進行響應。
| HTTP 狀態碼 | 含義 |
| ---------------- | ------------------ |
| `204 No Content` | 成功 |
| `404 Not Found` | 找不到套件或文件 |
## 安裝套件
要從 Debian 註冊表安裝套件，請執行以下命令:
```shell
# use latest version
apt install {package_name}
# use specific version
apt install {package_name}={package_version}
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/generic.md
+135
View File
@@ -0,0 +1,135 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "generic"
sidebar_position: 500
---
# 通用套件註冊表
發佈通用文件，如發佈二進制文件或其他輸出，供您的使用者或組織使用。
## 身份驗證套件註冊表
要身份驗證套件註冊表，您需要提供[自訂 HTTP 頭或使用 HTTP 基本身份驗證](development/api-usage.md#透過-api-認證)。
## 發佈套件
要發佈通用套件，請執行 HTTP `PUT` 操作，並將套件內容放入請求主體中。
您無法向套件中多次發佈具有相同名稱的文件。您必須首先刪除現有的套件版本。
```
PUT https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
```
| 參數 | 描述 |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `owner` | 套件的所有者。 |
| `package_name` | 套件名稱。它只能包含小寫字母 (`a-z`)、大寫字母 (`A-Z`)、數字 (`0-9`)、點號 (`.`)、連字符 (`-`)、加號 (`+`) 或下劃線 (`_`) |
| `package_version` | 套件版本，一個非空字符串，不包含前導或尾隨空格 |
| `file_name` | 文件名。它只能包含小寫字母 (`a-z`)、大寫字母 (`A-Z`)、數字 (`0-9`)、點號 (`.`)、連字符 (`-`)、加號 (`+`) 或下劃線 (`_`) |
使用 HTTP 基本身份驗證的範例請求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.bin \
https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
```
如果您使用 2FA 或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)替代密碼。
伺服器將使用以下 HTTP 狀態程式碼進行響應。
| HTTP 狀態碼 | 意義 |
| ----------------- | ---------------------------------- |
| `201 Created` | 套件已發佈 |
| `400 Bad Request` | 套件名稱和/或版本和/或文件名無效 |
| `409 Conflict` | 具有相同名稱的文件已存在於套件中 |
## 下載套件
要下載通用套件，請執行 HTTP `GET` 操作。
```
GET https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
```
| 參數 | 描述 |
| ----------------- | -------------- |
| `owner` | 套件的所有者 |
| `package_name` | 套件名稱 |
| `package_version` | 套件版本 |
| `file_name` | 文件名 |
文件內容將在響應主體中返回。響應的內容類型為 `application/octet-stream`。
伺服器將使用以下 HTTP 狀態程式碼進行響應。
```shell
curl --user your_username:your_token_or_password \
https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
```
伺服器會以以下 HTTP 狀態碼進行響應：
| HTTP 狀態碼 | 含義 |
| --------------- | -------------------- |
| `200 OK` | 成功 |
| `404 Not Found` | 找不到套件或者文件 |
## 刪除套件
要刪除通用套件，請執行 HTTP DELETE 操作。這將同時刪除該版本的所有文件。
```
DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}
```
| 參數 | 描述 |
| ----------------- | -------------- |
| `owner` | 套件的所有者 |
| `package_name` | 套件名稱 |
| `package_version` | 套件版本 |
伺服器將使用以下 HTTP 狀態程式碼進行響應。
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0
```
The server responds with the following HTTP Status codes.
| HTTP 狀態碼 | 意義 |
| ---------------- | ------------ |
| `204 No Content` | 成功 |
| `404 Not Found` | 找不到套件 |
## 刪除套件文件
要刪除通用套件的文件，請執行 HTTP `DELETE` 操作。如果沒有文件留下，這將同時刪除套件版本。
```
DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{filename}
```
| 參數 | 描述 |
| ----------------- | -------------- |
| `owner` | 套件的所有者 |
| `package_name` | 套件名稱 |
| `package_version` | 套件版本 |
| `filename` | 文件名 |
使用 HTTP 基本身份驗證的範例請求：
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
```
伺服器將使用以下 HTTP 狀態程式碼進行響應：
| HTTP 狀態碼 | 含義 |
| ---------------- | ------------------ |
| `204 No Content` | 成功 |
| `404 Not Found` | 找不到套件或文件 |
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/go.md
+64
View File
@@ -0,0 +1,64 @@
---
date: "2023-05-10T00:00:00+00:00"
slug: "go"
sidebar_position: 45
---
# Go 套件註冊表
為您的使用者或組織發佈 Go 套件。
## 發佈套件
要發佈 Go 套件，請執行 HTTP `PUT` 操作，並將套件內容放入請求主體中。
如果已經存在相同名稱和版本的套件，您無法發佈套件。您必須首先刪除現有的套件。
該套件必須遵循[文件中的結構](https://go.dev/ref/mod#zip-files)。
```
PUT https://gitea.example.com/api/packages/{owner}/go/upload
```
| 參數 | 描述 |
| ------- | -------------- |
| `owner` | 套件的所有者 |
要身份驗證到套件註冊表，您需要提供[自訂 HTTP 頭或使用 HTTP 基本身份驗證](development/api-usage.md#透過-api-認證)：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.zip \
https://gitea.example.com/api/packages/testuser/go/upload
```
如果您使用的是 2FA 或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)替代密碼進行身份驗證。
伺服器將使用以下 HTTP 狀態程式碼進行響應。
| HTTP 狀態碼 | 含義 |
| ----------------- | -------------------------- |
| `201 Created` | 套件已發佈 |
| `400 Bad Request` | 套件無效 |
| `409 Conflict` | 具有相同名稱的套件已存在 |
## 安裝套件
要安裝Go套件，請指示Go使用套件註冊表作為代理：
```shell
# 使用最新版本
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}
# 或者
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@latest
# 使用特定版本
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@{package_version}
```
| 參數 | 描述 |
| ----------------- | -------------- |
| `owner` | 套件的所有者 |
| `package_name` | 套件名稱 |
| `package_version` | 套件版本 |
如果套件的所有者是私有的，則需要[提供憑據](https://go.dev/ref/mod#private-module-proxy-auth)。
有關 `GOPROXY` 環境變量的更多資訊以及如何防止資料泄漏的資訊，請[參閱文件](https://go.dev/ref/mod#private-modules)。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/helm.md
+55
View File
@@ -0,0 +1,55 @@
---
date: "2022-04-14T00:00:00+00:00"
slug: "helm"
sidebar_position: 50
---
# Helm Chart 註冊表
為您的使用者或組織發佈 [Helm](https://helm.sh/) charts。
## 要求
要使用 Helm Chart 註冊表，可以使用諸如 `curl` 或 [`helm cm-push`](https://github.com/chartmuseum/helm-push/) 外掛之類的簡單HTTP客戶端。
## 發佈套件
通過運行以下命令來發布套件：
```shell
curl --user {username}:{password} -X POST --upload-file ./{chart_file}.tgz https://gitea.example.com/api/packages/{owner}/helm/api/charts
```
或者使用 `helm cm-push` 外掛：
```shell
helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm
helm cm-push ./{chart_file}.tgz {repo}
```
| 參數 | 描述 |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `username` | 您的Gitea使用者名稱 |
| `password` | 您的Gitea密碼。如果您使用的是2FA或OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)替代密碼進行身份驗證。 |
| `repo` | 儲存庫名稱 |
| `chart_file` | Helm Chart 歸檔文件 |
| `owner` | 套件的所有者 |
## 安裝套件
要從註冊表中安裝Helm Chart，請執行以下命令：
```shell
helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm
helm repo update
helm install {name} {repo}/{chart}
```
| 參數 | 描述 |
| ---------- | --------------------------- |
| `username` | 您的Gitea使用者名稱 |
| `password` | 您的Gitea密碼或個人存取權杖 |
| `repo` | 儲存庫的名稱 |
| `owner` | 套件的所有者 |
| `name` | 本地名稱 |
| `chart` | Helm Chart的名稱 |
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/maven.md
+154
View File
@@ -0,0 +1,154 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "maven"
sidebar_position: 60
---
# Maven 套件註冊表
為您的使用者或組織發佈 [Maven](https://maven.apache.org) 套件。
## 要求
要使用 Maven 套件註冊表，您可以使用 [Maven](https://maven.apache.org/install.html) 或 [Gradle](https://gradle.org/install/)。
以下範例使用 `Maven` 和 `Gradle Groovy`。
## 設定套件註冊表
要註冊套件註冊表，首先需要將存取權杖添加到 [`settings.xml`](https://maven.apache.org/settings.html) 文件中：
```xml
<settings>
<servers>
<server>
<id>gitea</id>
<configuration>
<httpHeaders>
<property>
<name>Authorization</name>
<value>token {access_token}</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
```
然後在專案的 `pom.xml` 文件中添加以下部分：
```xml
<repositories>
<repository>
<id>gitea</id>
<url>https://gitea.example.com/api/packages/{owner}/maven</url>
</repository>
</repositories>
<distributionManagement>
<repository>
<id>gitea</id>
<url>https://gitea.example.com/api/packages/{owner}/maven</url>
</repository>
<snapshotRepository>
<id>gitea</id>
<url>https://gitea.example.com/api/packages/{owner}/maven</url>
</snapshotRepository>
</distributionManagement>
```
| 參數 | 描述 |
| -------------- | ------------------------------------------------------------------------------------- |
| `access_token` | 您的[個人存取權杖](development/api-usage.md#透過-api-認證) |
| `owner` | 套件的所有者 |
### Gradle variant
如果您計劃在專案中添加來自 Gitea 實例的一些套件，請將其添加到 repositories 部分中：
```groovy
repositories {
// other repositories
maven { url "https://gitea.example.com/api/packages/{owner}/maven" }
}
```
在 Groovy gradle 中，您可以在發佈部分中包含以下腳本：
```groovy
publishing {
// 其他發佈設置
repositories {
maven {
name = "Gitea"
url = uri("https://gitea.example.com/api/packages/{owner}/maven")
credentials(HttpHeaderCredentials) {
name = "Authorization"
value = "token {access_token}"
}
authentication {
header(HttpHeaderAuthentication)
}
}
}
}
```
## 發佈套件
要發佈套件，只需運行以下命令：
```shell
mvn deploy
```
或者，如果您使用的是 Gradle，請使用 `gradle` 命令和 `publishAllPublicationsToGiteaRepository` 任務：
```groovy
./gradlew publishAllPublicationsToGiteaRepository
```
如果您想要將預構建的套件發佈到註冊表中，可以使用 [`mvn deploy:deploy-file`](https://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html) 命令：
```shell
mvn deploy:deploy-file -Durl=https://gitea.example.com/api/packages/{owner}/maven -DrepositoryId=gitea -Dfile=/path/to/package.jar
```
| 參數 | 描述 |
| ------- | -------------- |
| `owner` | 套件的所有者 |
如果存在相同名稱和版本的套件，您無法發佈該套件。您必須先刪除現有的套件。
## 安裝套件
要從套件註冊表中安裝 Maven 套件，請在專案的 `pom.xml` 文件中添加新的依賴項：
```xml
<dependency>
<groupId>com.test.package</groupId>
<artifactId>test_project</artifactId>
<version>1.0.0</version>
</dependency>
```
在 `Gradle Groovy` 中類似的操作如下：
```groovy
implementation "com.test.package:test_project:1.0.0"
```
然後運行：
```shell
mvn install
```
## 支援的命令
```
mvn install
mvn deploy
mvn dependency:get:
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/npm.md
+132
View File
@@ -0,0 +1,132 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "npm"
sidebar_position: 70
---
# NPM Package Registry
為您的使用者或組織發佈 [npm](https://www.npmjs.com/) 包。
## 要求
要使用 npm 包註冊表，您需要安裝 [Node.js](https://nodejs.org/en/download/) 以及與之配套的套件管理器，例如 [Yarn](https://classic.yarnpkg.com/en/docs/install) 或 [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/) 本身。
該註冊表支援[作用域](https://docs.npmjs.com/misc/scope/)和非作用域套件。
以下範例使用具有作用域 `@test` 的 `npm` 工具。
## 設定套件註冊表
要註冊套件註冊表，您需要設定一個新的套件源。
```shell
npm config set {scope}:registry=https://gitea.example.com/api/packages/{owner}/npm/
npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{token}"
```
| 參數 | 描述 |
| ------- | --------------------------------------------------------------------------------------- |
| `scope` | 套件的作用域 |
| `owner` | 套件的所有者 |
| `token` | 您的[個人存取權杖](development/api-usage.md#透過-api-認證)。 |
例如：
```shell
npm config set @test:registry=https://gitea.example.com/api/packages/testuser/npm/
npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token"
```
或者，不使用作用域：
```shell
npm config set registry https://gitea.example.com/api/packages/testuser/npm/
npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token"
```
## 發佈套件
在專案中運行以下命令發佈套件：
```shell
npm publish
```
如果已經存在相同名稱和版本的套件，您無法發佈該套件。您必須先刪除現有的套件。
## 刪除套件
通過運行以下命令刪除套件：
```shell
npm unpublish {package_name}[@{package_version}]
```
| 參數 | 描述 |
| ----------------- | ---------- |
| `package_name` | 套件名稱 |
| `package_version` | 套件版本 |
例如
```shell
npm unpublish @test/test_package
npm unpublish @test/test_package@1.0.0
```
## 安裝套件
要從套件註冊表中安裝套件，請執行以下命令：
```shell
npm install {package_name}
```
| 參數 | 描述 |
| -------------- | ---------- |
| `package_name` | 套件名稱 |
例如：
```shell
npm install @test/test_package
```
## 給套件打標籤
該註冊表支援[版本標籤](https://docs.npmjs.com/adding-dist-tags-to-packages/)，可以透過 `npm dist-tag` 管理：
```shell
npm dist-tag add {package_name}@{version} {tag}
```
| 參數 | 描述 |
| -------------- | ---------- |
| `package_name` | 套件名稱 |
| `version` | 套件版本 |
| `tag` | 套件標籤 |
例如：
```shell
npm dist-tag add test_package@1.0.2 release
```
標籤名稱不能是有效的版本。所有可解析為版本的標籤名稱都將被拒絕。
## 搜索套件
該註冊表支援[搜索](https://docs.npmjs.com/cli/v7/commands/npm-search/)，但不支援像 `author:gitea` 這樣的特殊搜索限定符。
## 支援的命令
```
npm install
npm ci
npm publish
npm unpublish
npm dist-tag
npm view
npm search
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/nuget.md
+105
View File
@@ -0,0 +1,105 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "nuget"
sidebar_position: 80
---
# NuGet 套件註冊表
發佈適用於您的使用者或組織的 [NuGet](https://www.nuget.org/) 套件。套件註冊表支援 V2 和 V3 API 協議，並且您還可以使用 [NuGet 符號套件](https://docs.microsoft.com/zh-tw/nuget/create-packages/symbol-packages-snupkg)。
## 要求
要使用 NuGet 套件註冊表，您可以使用命令行介面工具，以及各種整合開發環境（IDE）中的 NuGet 功能，如 Visual Studio。有關 NuGet 客戶端的更多資訊，請參[閱官方文件](https://docs.microsoft.com/zh-tw/nuget/install-nuget-client-tools)。
以下範例使用 `dotnet nuget` 工具。
## 設定套件註冊表
要註冊套件註冊表，您需要設定一個新的 NuGet 源：
```shell
dotnet nuget add source --name {source_name} --username {username} --password {password} https://gitea.example.com/api/packages/{owner}/nuget/index.json
```
| 參數 | 描述 |
| ------------- | ---------------------------------------------------------------------------------------------------------------- |
| `source_name` | 所需源名稱 |
| `username` | 您的 Gitea 使用者名稱 |
| `password` | 您的 Gitea 密碼。如果您使用 2FA 或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)代替密碼。 |
| `owner` | 套件的所有者 |
例如：
```shell
dotnet nuget add source --name gitea --username testuser --password password123 https://gitea.example.com/api/packages/testuser/nuget/index.json
```
您可以在不提供憑據的情況下添加源，並在發佈套件時使用--api-key 參數。在這種情況下，您需要提供[個人存取權杖](development/api-usage.md#透過-api-認證)。
## 發佈套件
通過運行以下命令發佈套件：
```shell
dotnet nuget push --source {source_name} {package_file}
```
| 參數 | 描述 |
| -------------- | ---------------------------- |
| `source_name` | 所需源名稱 |
| `package_file` | 套件 `.nupkg` 文件的路徑。 |
例如：
```shell
dotnet nuget push --source gitea test_package.1.0.0.nupkg
```
如果已經存在相同名稱和版本的套件，您無法發佈該套件。您必須先刪除現有的套件。
### 符號套件
NuGet 套件註冊表支援構建用於符號伺服器的符號套件。客戶端可以請求嵌入在符號套件（`.snupkg`）中的 PDB 文件。
為此，請將 NuGet 套件註冊表註冊為符號源：
```
https://gitea.example.com/api/packages/{owner}/nuget/symbols
```
| 參數 | 描述 |
| ------- | -------------------- |
| `owner` | 套件註冊表的所有者 |
例如：
```
https://gitea.example.com/api/packages/testuser/nuget/symbols
```
## 安裝套件
要從套件註冊表安裝 NuGet 套件，請執行以下命令：
```shell
dotnet add package --source {source_name} --version {package_version} {package_name}
```
| 參數 | 描述 |
| ----------------- | ------------ |
| `source_name` | 所需源名稱 |
| `package_name` | 套件名稱 |
| `package_version` | 套件版本。 |
例如：
```shell
dotnet add package --source gitea --version 1.0.0 test_package
```
## 支援的命令
```
dotnet add
dotnet nuget push
dotnet nuget delete
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/overview.md
+96
View File
@@ -0,0 +1,96 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "overview"
sidebar_position: 1
---
# 套件註冊表
從Gitea **1.17**版本開始，套件註冊表可以用作常見套件管理器的公共或私有註冊表。
## 支援的套件管理器
目前支援以下套件管理器：
| Name | Language | Package client |
| ------------------------------------------------------------------- | ---------- | ------------------------- |
| [Alpine](usage/packages/alpine.md) | - | `apk` |
| [Cargo](usage/packages/cargo.md) | Rust | `cargo` |
| [Chef](usage/packages/chef.md) | - | `knife` |
| [Composer](usage/packages/composer.md) | PHP | `composer` |
| [Conan](usage/packages/conan.md) | C++ | `conan` |
| [Conda](usage/packages/conda.md) | - | `conda` |
| [Container](usage/packages/container.md) | - | 任何符合OCI規範的客戶端 |
| [CRAN](usage/packages/cran.md) | R | - |
| [Debian](usage/packages/debian.md) | - | `apt` |
| [Generic](usage/packages/generic.md) | - | 任何HTTP客戶端 |
| [Go](usage/packages/go.md) | Go | `go` |
| [Helm](usage/packages/helm.md) | - | 任何HTTP客戶端, `cm-push` |
| [Maven](usage/packages/maven.md) | Java | `mvn`, `gradle` |
| [npm](usage/packages/npm.md) | JavaScript | `npm`, `yarn`, `pnpm` |
| [NuGet](usage/packages/nuget.md) | .NET | `nuget` |
| [Pub](usage/packages/pub.md) | Dart | `dart`, `flutter` |
| [PyPI](usage/packages/pypi.md) | Python | `pip`, `twine` |
| [RPM](usage/packages/rpm.md) | - | `yum`, `dnf`, `zypper` |
| [RubyGems](usage/packages/rubygems.md) | Ruby | `gem`, `Bundler` |
| [Swift](usage/packages/rubygems.md) | Swift | `swift` |
| [Vagrant](usage/packages/vagrant.md) | - | `vagrant` |
**以下段落僅適用於未全域禁用套件的情況！**
## 儲存庫 x 套件
套件始終屬於所有者（使用者或組織），而不是儲存庫。
要將（已上傳的）套件鏈接到儲存庫，請打開該套件的設定頁面，並選擇要將此套件鏈接到的儲存庫。
將鏈接到整個套件，而不僅是單個版本。
鏈接套件將導致在儲存庫的套件列表中顯示該套件，並在套件頁面上顯示到儲存庫的鏈接（以及到儲存庫工單的鏈接）。
## 訪問限制
| 套件所有者類型 | 使用者 | 組織 |
| ---------------- | ---------------------------------------- | ------------------------------------------ |
| **讀取** 訪問 | 公開，如果使用者也是公開的；否則僅限此使用者 | 公開，如果組織是公開的，否則僅限組織成員 |
| **寫入** 訪問 | 僅套件所有者 | 具有組織中的管理員或寫入存取權限的組織成員 |
注意：這些訪問限制可能會[變化](https://github.com/go-gitea/gitea/issues/19270)，將通過專門的組織團隊權限添加更細粒度的控制。
## 建立或上傳套件
根據套件類型，使用相應的套件管理器。請查看特定套件管理器的子頁面以獲取說明。
## 查看套件
您可以在儲存庫頁面上查看儲存庫的套件。
1. 轉到儲存庫主頁。
2. 在導航欄中選擇**套件**
要查看有關套件的更多詳細資訊，請選擇套件的名稱。
## 下載套件
要從儲存庫下載套件：
1. 在導航欄中選擇**套件**
2. 選擇套件的名稱以查看詳細資訊。
3. 在 **Assets** 部分，選擇要下載的套件文件的名稱。
## 刪除套件
在將套件發佈到套件註冊表後，您無法編輯套件。相反，您必須刪除並重新建立它。
要從儲存庫中刪除套件：
1. 在導航欄中選擇**套件**
2. 選擇套件的名稱以查看詳細資訊。
3. 單擊**刪除套件**以永久刪除套件。
## 禁用套件註冊表
包註冊表已自動啟用。要在單個儲存庫中禁用它：
1. 在導航欄中選擇**設定**。
2. 禁用**啟用儲存庫套件註冊表**.
禁用套件註冊表不會刪除先前發佈的套件。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/pub.md
+71
View File
@@ -0,0 +1,71 @@
---
date: "2022-07-31T00:00:00+00:00"
slug: "pub"
sidebar_position: 90
---
# Pub 套件註冊表
為您的使用者或組織發佈 [Pub](https://dart.dev/guides/packages) 套件。
## 要求
要使用Pub套件註冊表，您需要使用 [dart](https://dart.dev/tools/dart-tool) 和/或 [flutter](https://docs.flutter.dev/reference/flutter-cli). 工具。
以下範例使用 `dart`。
## 設定套件註冊表
要註冊套件註冊表並提供憑據，請執行以下操作：
```shell
dart pub token add https://gitea.example.com/api/packages/{owner}/pub
```
| 佔位符 | 描述 |
| ------- | -------------- |
| `owner` | 套件的所有者 |
您需要提供您的[個人存取權杖](development/api-usage.md#透過-api-認證)。
## 發佈套件
要發佈套件，請編輯 `pubspec.yaml` 文件，並添加以下行：
```yaml
publish_to: https://gitea.example.com/api/packages/{owner}/pub
```
| 佔位符 | 描述 |
| ------- | -------------- |
| `owner` | 套件的所有者 |
現在，您可以透過運行以下命令來發布套件：
```shell
dart pub publish
```
如果已存在具有相同名稱和版本的套件，則無法發佈套件。您必須先刪除現有的套件。
## 安裝套件
要從套件註冊表安裝Pub套件，請執行以下命令：
```shell
dart pub add {package_name} --hosted-url=https://gitea.example.com/api/packages/{owner}/pub/
```
| 參數 | 描述 |
| -------------- | -------------- |
| `owner` | 套件的所有者 |
| `package_name` | 套件名稱 |
例如：
```shell
# use latest version
dart pub add mypackage --hosted-url=https://gitea.example.com/api/packages/testuser/pub/
# specify version
dart pub add mypackage:1.0.8 --hosted-url=https://gitea.example.com/api/packages/testuser/pub/
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/pypi.md
+75
View File
@@ -0,0 +1,75 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "pypi"
sidebar_position: 100
---
# PyPI 套件註冊表
為您的使用者或組織發佈 [PyPI](https://pypi.org/) 套件。
## 要求
要使用 PyPI 套件註冊表，您需要使用 [pip](https://pypi.org/project/pip/) 工具來消費和使用 [twine](https://pypi.org/project/twine/) 工具來發布套件。
## 設定套件註冊表
要註冊套件註冊表，您需要編輯本地的 `~/.pypirc` 文件。添加以下內容：
```ini
[distutils]
index-servers = gitea
[gitea]
repository = https://gitea.example.com/api/packages/{owner}/pypi
username = {username}
password = {password}
```
| 佔位符 | 描述 |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `owner` | 套件的所有者 |
| `username` | 您的 Gitea 使用者名稱 |
| `password` | 您的 Gitea 密碼。如果您使用 2FA 或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)替代密碼 |
## 發佈套件
通過運行以下命令來發布套件：
```shell
python3 -m twine upload --repository gitea /path/to/files/*
```
套件文件的擴展名為 `.tar.gz` 和 `.whl`。
如果已存在具有相同名稱和版本的套件，則無法發佈套件。您必須先刪除現有的套件。
## 安裝套件
要從套件註冊表安裝 PyPI 套件，請執行以下命令：
```shell
pip install --index-url https://{username}:{password}@gitea.example.com/api/packages/{owner}/pypi/simple --no-deps {package_name}
```
| 參數 | 描述 |
| -------------- | ----------------------------- |
| `username` | 您的 Gitea 使用者名稱 |
| `password` | 您的 Gitea 密碼或個人存取權杖 |
| `owner` | 套件的所有者 |
| `package_name` | 套件名稱 |
例如：
```shell
pip install --index-url https://testuser:password123@gitea.example.com/api/packages/testuser/pypi/simple --no-deps test_package
```
您可以使用 `--extra-index-url` 替代 `--index-url`，但這樣會使您容易受到依賴混淆攻擊，因為 `pip` 會先檢查官方 PyPi 儲存庫中的套件，然後再檢查指定的自訂儲存庫。請閱讀 `pip` 文件以獲取更多資訊。
## 支援的命令
```
pip install
twine upload
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/rpm.md
+108
View File
@@ -0,0 +1,108 @@
---
date: "2023-03-08T00:00:00+00:00"
slug: "packages/rpm"
sidebar_position: 105
---
# RPM 套件註冊表
為您的使用者或組織發佈 [RPM](https://rpm.org/) 套件。
## 要求
要使用RPM註冊表，您需要使用像 `yum`, `dnf` 或 `zypper` 這樣的套件管理器來消費套件。
以下範例使用 `dnf`。
## 設定套件註冊表
要註冊RPM註冊表，請將 URL 添加到已知 `apt` 源列表中：
```shell
dnf config-manager --add-repo https://gitea.example.com/api/packages/{owner}/rpm/{group}.repo
```
| 佔位符 | 描述 |
| ------- |--------------------------------------|
| `owner` | 套件的所有者 |
| `group` | 任何名稱,例如 `centos/7`、`el-7`、`fc38` |
如果註冊表是私有的，請在URL中提供憑據。您可以使用密碼或[個人存取權杖](development/api-usage.md#透過-api-認證)：
```shell
dnf config-manager --add-repo https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/rpm/{group}.repo
```
您還必須將憑據添加到 `/etc/yum.repos.d` 中的 `rpm.repo` 文件中的URL中。
## 發佈套件
要發佈RPM套件（`*.rpm`），請執行帶有套件內容的 HTTP `PUT` 操作。
```
PUT https://gitea.example.com/api/packages/{owner}/rpm/{group}/upload
```
| 參數 | 描述 |
| ------- |--------------|
| `owner` | 套件的所有者 |
| `group` | 套件自訂分組名稱 |
使用HTTP基本身份驗證的範例請求：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.rpm \
https://gitea.example.com/api/packages/testuser/rpm/centos/el7/version/upload
```
如果您使用 2FA 或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)替代密碼。您無法將具有相同名稱的文件兩次發佈到套件中。您必須先刪除現有的套件版本。
伺服器將以以下HTTP狀態碼響應。
| HTTP 狀態碼 | 含義 |
| ----------------- | ------------------------------------------------ |
| `201 Created` | 套件已發佈 |
| `400 Bad Request` | 套件無效 |
| `409 Conflict` | 具有相同參數組合的套件文件已經存在於該套件中 |
## 刪除套件
要刪除 RPM 套件，請執行 HTTP `DELETE` 操作。如果沒有文件剩餘，這也將刪除套件版本。
```
DELETE https://gitea.example.com/api/packages/{owner}/rpm/{group}/package/{package_name}/{package_version}/{architecture}
```
| 參數 | 描述 |
| ----------------- | -------------- |
| `owner` | 套件的所有者 |
| `group` | 套件自訂分組 |
| `package_name` | 套件名稱 |
| `package_version` | 套件版本 |
| `architecture` | 套件架構 |
使用HTTP基本身份驗證的範例請求：
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/rpm/centos/el7/package/test-package/1.0.0/x86_64
```
伺服器將以以下HTTP狀態碼響應：
| HTTP 狀態碼 | 含義 |
| ---------------- | ------------------ |
| `204 No Content` | 成功 |
| `404 Not Found` | 未找到套件或文件 |
## 安裝套件
要從RPM註冊表安裝套件，請執行以下命令：
```shell
# use latest version
dnf install {package_name}
# use specific version
dnf install {package_name}-{package_version}.{architecture}
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/rubygems.md
+115
View File
@@ -0,0 +1,115 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "rubygems"
sidebar_position: 110
---
# RubyGems 套件註冊表
為您的使用者或組織發佈 [RubyGems](https://guides.rubygems.org/) 套件。
## 要求
要使用RubyGems套件註冊表，您需要使用 [gem](https://guides.rubygems.org/command-reference/) 命令行工具來消費和發佈套件。
## 設定套件註冊表
要註冊套件註冊表，請編輯 `~/.gem/credentials` 文件並添加：
```ini
---
https://gitea.example.com/api/packages/{owner}/rubygems: Bearer {token}
```
| 參數 | 描述 |
| ------- | ------------------------------------------------------------------------------------- |
| `owner` | 套件的所有者 |
| `token` | 您的[個人存取權杖](development/api-usage.md#透過-api-認證) |
例如：
```
---
https://gitea.example.com/api/packages/testuser/rubygems: Bearer 3bd626f84b01cd26b873931eace1e430a5773cc4
```
## 發佈套件
通過運行以下命令來發布套件：
```shell
gem push --host {host} {package_file}
```
| 參數 | 描述 |
| -------------- | ------------------------ |
| `host` | 套件註冊表的URL |
| `package_file` | 套件 `.gem` 文件的路徑 |
例如：
```shell
gem push --host https://gitea.example.com/api/packages/testuser/rubygems test_package-1.0.0.gem
```
如果已經存在相同名稱和版本的套件，您將無法發佈套件。您必須先刪除現有的套件。
## 安裝套件
要從套件註冊表安裝套件，您可以使用 [Bundler](https://bundler.io) 或 `gem`。
### Bundler
在您的 `Gemfile` 中添加一個新的 `source` 塊：
```
source "https://gitea.example.com/api/packages/{owner}/rubygems" do
gem "{package_name}"
end
```
| 參數 | 描述 |
| -------------- | -------------- |
| `owner` | 套件的所有者 |
| `package_name` | 套件名稱 |
例如：
```
source "https://gitea.example.com/api/packages/testuser/rubygems" do
gem "test_package"
end
```
之後運行以下命令：
```shell
bundle install
```
### gem
執行以下命令：
```shell
gem install --host https://gitea.example.com/api/packages/{owner}/rubygems {package_name}
```
| 參數 | 描述 |
| -------------- | -------------- |
| `owner` | 套件的所有者 |
| `package_name` | 套件名稱 |
例如：
```shell
gem install --host https://gitea.example.com/api/packages/testuser/rubygems test_package
```
## 支援的命令
```
gem install
bundle install
gem push
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/storage.md
+72
View File
@@ -0,0 +1,72 @@
---
date: "2022-11-01T00:00:00+00:00"
slug: "storage"
sidebar_position: 5
---
# 儲存
本文件描述了套件註冊表的儲存方式以及如何管理儲存。
## 去重
套件註冊表具有內置的去重功能，可以對上傳的 Blob 進行去重處理。
如果上傳了兩個相同的文件，只會在文件系統上保存一個 Blob。
這樣可以確保不會浪費空間用於重複的文件。
如果上傳了兩個具有相同文件的套件，這兩個套件將顯示相同的大小，但在文件系統上，它們只需要一半的大小。
每當刪除一個套件時，只會刪除對底層 Blob 的引用。
此時，Blob 不會被刪除，因此它們仍然佔用文件系統上的空間。
當上傳新的套件時，現有的 Blob 可能會再次被引用。
這些無引用的 Blob 會在一個清理任務中被刪除。
設定 `OLDER_THAN` 可以設定無引用的 Blob 在被刪除之前保留的時間。
## 清理規則
套件註冊表可能會隨著時間的推移而變得很大，如果不進行清理的話。
建議刪除不必要的套件並設定清理規則以自動管理套件註冊表的使用情況。
每個套件所有者（使用者或組織）都可以管理應用於其套件的清理規則。
| 設定 | 描述 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 啟用 | 打開或關閉清理規則。 |
| 類型 | 每個規則管理特定的套件類型。 |
| 將模式應用於完整的套件名稱 | 如果啟用，則應用以下模式到完整的套件名稱（`package/version`），否則只使用版本號（`version`）。 |
| 保留最近的版本數 | 對於每個套件要始終保留的版本數量。 |
| 保留與以下模式匹配的版本 | 確定要保留哪些版本的正則表達式模式。空模式表示不保留任何版本，而 `.+` 表示保留所有版本。即使未設定，容器註冊表也始終保留 `latest` 版本。 |
| 刪除早於多少天的版本 | 僅刪除早於所選天數的版本。 |
| 刪除與以下模式匹配的版本 | 確定要刪除哪些版本的正則表達式模式。空模式或 `.+` 表示如果沒有其他設定指定，則刪除所有套件。 |
每個清理規則都可以顯示受影響的套件的預覽。
這可以用來檢查清理規則是否正確設定。
### 正則表達式範例
正則表達式模式會自動使用 `\A` 和 `\z` 錨點進行包圍。
不要在正則表達式模式中包含任何 `\A`、`\z`、`^` 或 `$` 標記，因為它們不是必要的。
模式是不區分大小寫的，與 Gitea 中的套件註冊表的行為相匹配。
| Pattern | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `.*` | 匹配任何可能的版本。 |
| `v.+` | 匹配以 `v` 開頭的版本。 |
| `release` | 僅匹配版本號為 `release`。 |
| `release.*` | 匹配以 `release` 命名或以 `release` 開頭的版本。 |
| `.+-temp-.+` | 匹配包含 `-temp-` 的版本。 |
| `v.+\|release` | 匹配以 `v` 開頭的版本或版本號為 `release`。 |
| `package/v.+\|other/release` | 匹配以 `v` 開頭的 package 的版本或 `other` 的版本號為 `release`。需要啟用*將模式應用於完整的套件名稱*設定。 |
### 清理規則的工作原理
清理規則是清理任務的一部分，定期運行。
清理規則：
1. 收集所有屬於所有者註冊表的特定套件類型的套件。
2. 對於每個套件，收集所有版本。
3. 根據 *保留最近的版本數* 的值，從列表中排除版本。
4. 根據 *保留與以下模式匹配的版本* 的值，從列表中排除任何版本。
5. 根據 *刪除早於多少天的版本* 的值，從列表中排除比這個值更近的版本。
6. 根據 *刪除與以下模式匹配的版本* 的值，從列表中排除任何不匹配的版本。
7. 刪除剩餘的版本。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/swift.md
+81
View File
@@ -0,0 +1,81 @@
---
date: "2023-01-10T00:00:00+00:00"
slug: "swift"
sidebar_position: 115
---
# Swift 套件註冊表
為您的使用者或組織發佈 [Swift](https://www.swift.org/) 套件。
## 要求
要使用 Swift 套件註冊表，您需要使用 [swift](https://www.swift.org/getting-started/) 消費套件，並使用 HTTP 客戶端（如 `curl`）發佈套件。
## 設定套件註冊表
要註冊套件註冊表並提供憑據，請執行以下命令：
```shell
swift package-registry set https://gitea.example.com/api/packages/{owner}/swift -login {username} -password {password}
```
| 佔位符 | 描述 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `owner` | 套件的所有者。 |
| `username` | 您的 Gitea 使用者名稱。 |
| `password` | 您的 Gitea 密碼。如果您使用兩步驗證或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)代替密碼。 |
登入是可選的，只有在套件註冊表是私有的情況下才需要。
## 發佈套件
首先，您需要打包套件的內容：
```shell
swift package archive-source
```
要發佈套件，請執行一個帶有套件內容的 HTTP `PUT` 請求，將內容放在請求正文中。
```shell --user your_username:your_password_or_token \
curl -X PUT --user {username}:{password} \
-H "Accept: application/vnd.swift.registry.v1+json" \
-F source-archive=@/path/to/package.zip \
-F metadata={metadata} \
https://gitea.example.com/api/packages/{owner}/swift/{scope}/{name}/{version}
```
| 佔位符 | 描述 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `username` | 您的 Gitea 使用者名稱。 |
| `password` | 您的 Gitea 密碼。如果您使用兩步驗證或 OAuth，請使用[個人存取權杖](development/api-usage.md#透過-api-認證)代替密碼。 |
| `owner` | 套件的所有者。 |
| `scope` | 套件的作用域。 |
| `name` | 套件的名稱。 |
| `version` | 套件的版本。 |
| `metadata` | （可選）套件的元資料。以 JSON 編碼的子集，格式參考 https://schema.org/SoftwareSourceCode |
如果已經存在相同名稱和版本的套件，則無法發佈套件。您必須首先刪除現有的套件。
## 安裝套件
要從套件註冊表安裝 Swift 套件，請將其添加到 `Package.swift` 文件的依賴項列表中：
```
dependencies: [
.package(id: "{scope}.{name}", from:"{version}")
]
```
| 參數 | 描述 |
| --------- | -------------- |
| `scope` | 套件的作用域 |
| `name` | 套件的名稱 |
| `version` | 套件的版本 |
之後，執行以下命令來安裝它：
```shell
swift package resolve
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/packages/vagrant.md
+66
View File
@@ -0,0 +1,66 @@
---
date: "2022-08-23T00:00:00+00:00"
slug: "vagrant"
sidebar_position: 120
---
# Vagrant 套件註冊表
為您的使用者或組織發佈 [Vagrant](https://www.vagrantup.com/) 套件。
## 要求
要使用 Vagrant 套件註冊表，您需要安裝 [Vagrant](https://www.vagrantup.com/downloads) 並使用類似於 `curl` 的工具進行 HTTP 請求。
## 發佈套件
透過執行 HTTP PUT 請求將 Vagrant box 發佈到註冊表：
```
PUT https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}/{package_version}/{provider}.box
```
| 參數 | 描述 |
| ----------------- | ------------------------------------------------------------------ |
| `owner` | 套件的所有者 |
| `package_name` | 套件的名稱 |
| `package_version` | 套件的版本，相容 semver 格式 |
| `provider` | [支援的提供程式名稱](https://www.vagrantup.com/docs/providers)之一 |
上傳 Hyper-V box 的範例：
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/your/vagrant.box \
https://gitea.example.com/api/packages/testuser/vagrant/test_system/1.0.0/hyperv.box
```
如果已經存在相同名稱、版本和提供程式的套件，則無法發佈套件。您必須首先刪除現有的套件。
## 安裝套件
要從套件註冊表安裝套件，請執行以下命令：
```shell
vagrant box add "https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}"
```
| 參數 | 描述 |
| -------------- | --------------- |
| `owner` | 套件的所有者. |
| `package_name` | 套件的名稱 |
例如：
```shell
vagrant box add "https://gitea.example.com/api/packages/testuser/vagrant/test_system"
```
這將安裝套件的最新版本。要添加特定版本，請使用` --box-version` 參數。
如果註冊表是私有的，您可以將您的[個人存取權杖](development/api-usage.md#透過-api-認證)傳遞給 `VAGRANT_CLOUD_TOKEN` 環境變量。
## 支援的命令
```
vagrant box add
```
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/profile-readme.md
+15
View File
@@ -0,0 +1,15 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "profile-readme"
sidebar_position: 12
---
# 個人資料 README
要在您的 Gitea 個人資料頁面顯示一個 Markdown 文件，只需建立一個名為 `.profile` 的儲存庫，並編輯其中的 `README.md` 文件。Gitea 將自動獲取該文件並在您的儲存庫上方顯示。
注意：您可以將此儲存庫設為私有。這樣可以隱藏您的源文件，使其對公眾不可見，並允許您將某些文件設為私有。但是，README.md 文件將是您個人資料上唯一存在的文件。如果您希望完全私有化 .profile 儲存庫，則需刪除或重命名 README.md 文件。
使用者範例 `.profile/README.md`:
![個人資料自述文件截圖](/images/usage/profile-readme.png)
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/repository/_category_.json
+9
View File
@@ -0,0 +1,9 @@
{
"label": "Repository",
"position": 10,
"link": {
"type": "generated-index",
"slug": "/usage/repository",
"description": "Repository management, Git operations, and content features"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/repository/clone-filter.md
+18
View File
@@ -0,0 +1,18 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "clone-filters"
sidebar_position: 25
aliases:
- /zh-tw/clone-filters
---
# 克隆過濾器 (部分克隆)
Git 引入了 `--filter` 選項用於 `git clone` 命令，該選項可以過濾掉大文件和對象（如 blob），從而建立一個儲存庫的部分克隆。克隆過濾器對於大型儲存庫和/或按流量計費的連接特別有用，因為完全克隆（不使用 `--filter`）可能會很昂貴（需要下載所有歷史資料）。
這需要 Git 2.22 或更高版本，無論是在 Gitea 伺服器上還是在客戶端上都需要如此。為了使克隆過濾器正常工作，請確保客戶端上的 Git 版本至少與伺服器上的版本相同（或更高）。以管理員身份登入到 Gitea，然後轉到管理後臺 -> 應用設定，查看伺服器的 Git 版本。
預設情況下，克隆過濾器是啟用的，除非在 `[git]` 下將 `DISABLE_PARTIAL_CLONE` 設定為 `true`。
請參閱 [GitHub 部落格文章：瞭解部分克隆](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) 以獲取克隆過濾器的常見用法（無 Blob 和無樹的克隆），以及 [GitLab 部分克隆文件](https://docs.gitlab.com/ee/topics/git/partial_clone.html) 以獲取更高級的用法（例如按文件大小過濾和取消過濾以將部分克隆轉換為完全克隆）。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/repository/incoming-email.md
+38
View File
@@ -0,0 +1,38 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "incoming-email"
sidebar_position: 13
aliases:
- /zh-tw/incoming-email
---
# 郵件接收
Gitea 支援通過接收郵件執行多種操作。本頁面描述瞭如何進行設定。
## 要求
處理接收的電子郵件需要啟用 IMAP 功能的電子郵件帳戶。
推薦的策略是使用 [電子郵件子地址](https://en.wikipedia.org/wiki/Email_address#Sub-addressing)，但也可以使用 catch-all 郵箱。
接收電子電子郵件地址中包含一個使用者/操作特定的令牌，告訴 Gitea 應執行哪個操作。
此令牌應該出現在 `To` 和 `Delivered-To` 頭欄位中。
Gitea 會嘗試檢測自動回覆並跳過它們，電子郵件伺服器也應該設定以減少接收到的干擾（垃圾郵件、通訊訂閱等）。
## 設定
要激活處理接收的電子郵件消息功能，您需要在設定文件中設定 `email.incoming` 部分。
`REPLY_TO_ADDRESS` 包含電子郵件客戶端將要回復的地址。
該地址需要包含 `%{token}` 佔位符，該佔位符將被替換為描述使用者/操作的令牌。
此佔位符在地址中只能出現一次，並且必須位於地址的使用者部分（`@` 之前）。
使用電子郵件子地址的範例可能如下：`incoming+%{token}@example.com`
如果使用 catch-all 郵箱，則佔位符可以出現在地址的使用者部分的任何位置：`incoming+%{token}@example.com`、`incoming_%{token}@example.com`、`%{token}@example.com`
## 安全性
在選擇用於接收傳入電子郵件的域時要小心。
建議在子域名上接收傳入電子郵件，例如 `incoming.example.com`，以防止與運行在 `example.com` 上的其他服務可能存在的安全問題。
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/repository/profile-readme.md
+15
View File
@@ -0,0 +1,15 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "profile-readme"
sidebar_position: 12
---
# 個人資料 README
要在您的 Gitea 個人資料頁面顯示一個 Markdown 文件，只需建立一個名為 `.profile` 的儲存庫，並編輯其中的 `README.md` 文件。Gitea 將自動獲取該文件並在您的儲存庫上方顯示。
注意：您可以將此儲存庫設為私有。這樣可以隱藏您的源文件，使其對公眾不可見，並允許您將某些文件設為私有。但是，README.md 文件將是您個人資料上唯一存在的文件。如果您希望完全私有化 .profile 儲存庫，則需刪除或重命名 README.md 文件。
使用者範例 `.profile/README.md`:
![個人資料自述文件截圖](/images/usage/profile-readme.png)
i18n/zh-tw/docusaurus-plugin-content-docs/version-28/usage/repository/push.md
+61
View File
@@ -0,0 +1,61 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "push"
sidebar_position: 15
aliases:
- /zh-tw/push-to-create
- /zh-tw/push-options
---
# 推送
在將提交推送到 Gitea 伺服器時，還有一些額外的功能。
## 通過推送打開 PR
當您第一次將提交推送到非預設分支時，您將收到一個鏈接，您可以單擊該鏈接訪問分支與主分支的比較頁面。
從那裡，您可以輕鬆建立一個拉取請求，即使您想要將其目標指向另一個分支。
![Gitea 推送提示](/gitea-push-hint.png)
## 推送選項
在 Gitea `1.13` 版本中，添加了對一些 [推送選項](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) 的支援。
### 支援的選項
- `repo.private` (true|false) - 更改儲存庫的可見性。
這在與 push-to-create 結合使用時特別有用。
- `repo.template` (true|false) - 更改儲存庫是否為模板。
將儲存庫的可見性更改為公開的範例：
```shell
git push -o repo.private=false -u origin main
```
## 推送建立
推送建立是一項功能，允許您將提交推送到在 Gitea 中尚不存在的儲存庫。這對於自動化和允許使用者建立儲存庫而無需通過 Web 介面非常有用。此功能預設處於禁用狀態。
### 啟用推送建立
在 `app.ini` 文件中，將 `ENABLE_PUSH_CREATE_USER` 設定為 `true`，如果您希望允許使用者在自己的使用者帳戶和所屬的組織中建立儲存庫，將 `ENABLE_PUSH_CREATE_ORG` 設定為 `true`。重新啟動 Gitea 以使更改生效。您可以在 [設定速查表](../../administration/config-cheat-sheet.md#儲存庫-repository) 中瞭解有關這兩個選項的更多資訊。
### 使用推送建立
假設您在當前目錄中有一個 git 儲存庫，您可以透過運行以下命令將提交推送到在 Gitea 中尚不存在的儲存庫：
```shell
# 添加要推送到的遠程倉庫
git remote add origin git@{domain}:{username}/{尚不存在的倉庫名稱}.git
# 推送到遠程倉庫
git push -u origin main
```
這假設您使用的是 SSH 遠程，但您也可以使用 HTTPS 遠程。
推送建立將預設使用 `app.ini` 中定義的可見性 `DEFAULT_PUSH_CREATE_PRIVATE`。
Loaded 100 of 338 files, more files were not shown because too many files have changed in this diff. Show more