nprasad2077/docs
1
1 Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-11-15 06:13:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into lunny/add_project_workflow

Browse Source
This commit is contained in:
Lunny Xiao committed 2026-10-22 23:22:15 +00:00
2 parents 3b71a35b51 c00af83676
commit c902fe9253
2340 files changed
+379885 -36853
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

i18n/zh-tw/code.json
-8
View File
@@ -1,8 +0,0 @@
{
"outdated.message": {
"message": "當前中文文檔翻譯不是最新版，請訪問英文版本查看最新內容，或"
},
"outdated.help": {
"message": "幫助我們翻譯"
}
}
i18n/zh-tw/docusaurus-plugin-content-docs/current.json → i18n/zh-tw/docs/current.json
+1 -1
View File
@@ -12,7 +12,7 @@
"message": "Actions"
},
"sidebar.docs.category.packages": {
"message": "軟體包"
"message": "套件"
},
"sidebar.docs.category.Development": {
"message": "開發"
i18n/zh-tw/docusaurus-plugin-content-docs/current/administration/_category_.json → i18n/zh-tw/docs/current/administration/_category_.json
View File
File renamed without changes.
i18n/zh-tw/docs/current/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/docs/current/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/docs/current/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/data/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/docs/current/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/docs/current/administration/command-line.md
+534
View File
File diff suppressed because it is too large. Load diff
i18n/zh-tw/docs/current/administration/config-cheat-sheet.md
+1559
View File
File diff suppressed because it is too large. Load diff
i18n/zh-tw/docs/current/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/docs/current/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/docs/current/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/docs/current/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/docs/current/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/docs/current/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/docs/current/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/docs/current/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/docs/current/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/docs/current/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/docs/current/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/docs/current/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/docs/current/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/current/contributing/_category_.json → i18n/zh-tw/docs/current/contributing/_category_.json
View File
File renamed without changes.
i18n/zh-tw/docs/current/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/docs/current/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/docs/current/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/docs/current/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/current/development/_category_.json → i18n/zh-tw/docs/current/development/_category_.json
View File
File renamed without changes.
i18n/zh-tw/docs/current/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/docs/current/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/docs/current/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/docs/current/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/docs/current/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/current/help/_category_.json → i18n/zh-tw/docs/current/help/_category_.json
View File
File renamed without changes.
i18n/zh-tw/docs/current/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/docs/current/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/docs/current/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/current/installation/_category_.json → i18n/zh-tw/docs/current/installation/_category_.json
View File
File renamed without changes.
i18n/zh-tw/docusaurus-plugin-content-docs/current/installation/comparison.md → i18n/zh-tw/docs/current/installation/comparison.md
+85 -85
View File
@@ -6,99 +6,99 @@ aliases:
- /zh-tw/comparison
---
# 对比 Gitea 与其它 Git 托管工具
# 對比 Gitea 與其它 Git 託管工具
这里列出了 Gitea 与其它一些 Git 托管工具之间的异同，以便确认 Gitea 是否能够满足您的需求。
這裡列出了 Gitea 與其它一些 Git 託管工具之間的異同，以便確認 Gitea 是否能夠滿足您的需求。
请注意，此列表中的某些表项可能已经过时，因为我们并没有定期检查其它产品的功能是否有所更改。你可以前往 [Github issue](https://github.com/go-gitea/gitea/issues) 来帮助我们更新过时的内容，感谢！
請注意，此列表中的某些表項可能已經過時，因為我們並沒有定期檢查其它產品的功能是否有所更改。你可以前往 [Github issue](https://github.com/go-gitea/gitea/issues) 來幫助我們更新過時的內容，感謝！
_表格中的符号含义:_
_表格中的符號含義:_
- _✓ - 支持_
- _✓ - 支援_
- _⁄ - 部分支持_
- _⁄ - 部分支援_
- _✘ - 不支持_
- _✘ - 不支援_
- _⚙️ - 由第三方服务或插件支持_
- _⚙️ - 由第三方服務或外掛支援_
#### 主要特性
| 特性 | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE |
| -------------------------------- | --------------------------------------------------- | ---- | --------- | --------- | --------- | -------------- | ------------ |
| 开源免费 | ✓ | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ |
| 低资源开销 (RAM/CPU) | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ |
| 支持多种数据库 | ✓ | ✓ | ✘ | ⁄ | ⁄ | ✓ | ✓ |
| 支持多种操作系统 | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ |
| 升级简便 | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ |
| 可观测性 | **✘** | ✘ | ✓ | ✓ | ✓ | ✓ | ? |
| 支持第三方渲染工具 | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ? |
| 開源免費 | ✓ | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ |
| 低資源開銷 (RAM/CPU) | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ |
| 支援多種資料庫 | ✓ | ✓ | ✘ | ⁄ | ⁄ | ✓ | ✓ |
| 支援多種操作系統 | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ |
| 升級簡便 | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ |
| 可觀測性 | **✘** | ✘ | ✓ | ✓ | ✓ | ✓ | ? |
| 支援第三方渲染工具 | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ? |
| WebAuthn (2FA) | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ? |
| 扩展 API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 内置软件包/容器注册中心 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 同步提交到外部仓库 (push mirror) | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ |
| 同步外部仓库的提交 (pull mirror) | ✓ | ✘ | ✘ | ✓ | ✓ | ✘ | ? |
| 浅色和深色主题 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ? |
| 自定义主题支持 | ✓ | ✓ | ✘ | ✘ | ✘ | ✓ | ✘ |
| 支持 Markdown | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 支持 CSV | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | ? |
| Git 驱动的静态 pages | [⚙️][gitea-pages-server], [⚙️][gitea-caddy-plugin] | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| Git 驱动的集成化 wiki | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (cloud only) | ✘ |
| 擴展 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 数学公式 | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ |
| 內置 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 签名的提交 | ✓ | ✘ | ✓ | ✓ | ✓ | ? | ? |
| 拒绝未通过验证的提交 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 外部仓库迁移 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 仓库活跃度页面 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 組織里程碑 | [✘](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) | ✓ | ✘ | ✘ |
| 工單跟蹤 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (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
@@ -107,34 +107,34 @@ _表格中的符号含义:_
| 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 权限 | ✓ | ✘ | ✓ | ⁄ | ✓ | ✓ | ✓ |
| 評論 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) | ✘ |
| 下載 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 用户同步 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 支援 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 的状态 | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 支援 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/docs/current/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/docs/current/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/docs/current/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/docs/current/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-1.24/installation/on-kubernetes.md → i18n/zh-tw/docs/current/installation/on-kubernetes.md
+9 -9
View File
@@ -8,9 +8,9 @@ aliases:
# 在 Kubernetes 中安裝 Gitea
Gitea 已经提供了便于在 Kubernetes 云原生环境中安裝所需的 Helm Chart
Gitea 已經提供了便於在 Kubernetes 雲原生環境中安裝所需的 Helm Chart
默认安裝指令為：
預設安裝指令為：
```bash
helm repo add gitea https://dl.gitea.com/charts
@@ -18,21 +18,21 @@ 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 會部署單實例的 Gitea, PostgreSQL, Memcached。若您想實現自訂安裝（包括設定 Gitea 集群、NGINX Ingress、MySQL、MariaDB、持久儲存等），請前往閱讀：[Gitea Helm Chart](https://gitea.com/gitea/helm-chart/)
您也可以通過 `helm show` 命令导出 `README.md` 和配置文件 `values.yaml` 進行学习和编辑，例如：
您也可以透過 `helm show` 命令導出 `README.md` 和設定文件 `values.yaml` 進行學習和編輯，例如：
```bash
helm show values gitea/gitea > values.yaml
helm show readme gitea/gitea > README.md
# 使用自定义的配置文件 values.yaml
# 使用自定義的配置文件 values.yaml
helm install gitea -f values.yaml gitea/gitea
```
## 运行状况检查接口
## 運行狀況檢查介面
Gitea 附带了一个运行状况检查接口 `/api/healthz`，你可以像这样在 Kubernetes 中配置它：
Gitea 附帶了一個運行狀況檢查介面 `/api/healthz`，你可以像這樣在 Kubernetes 中設定它：
```yaml
livenessProbe:
@@ -46,7 +46,7 @@ livenessProbe:
failureThreshold: 10
```
成功的运行状况检查響應代码為 HTTP `200`，下面是示例：
成功的運行狀況檢查響應程式碼為 HTTP `200`，下面是範例：
```json
HTTP/1.1 200 OK
@@ -71,4 +71,4 @@ HTTP/1.1 200 OK
}
```
有关更多信息，請参考 Kubernetes 文檔 [配置存活、就绪和启动探测器](https://kubernetes.io/zh-tw/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
有關更多資訊，請參考 Kubernetes 文件 [設定存活、就緒和啟動探測器](https://kubernetes.io/zh-tw/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
i18n/zh-tw/docs/current/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/docs/current/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/docs/current/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/docs/current/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/docs/current/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/current/usage/_category_.json → i18n/zh-tw/docs/current/usage/_category_.json
View File
File renamed without changes.
Loaded 50 of 2340 files, more files were not shown because too many files have changed in this diff. Show more