> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gitea 同步

> [!NOTE]
>
> 此功能由 [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) 開發，於 v6.3.2 以早期預覽版推出，並將在 v6.4.0 正式發布，因此其設定與行為仍可能變更。如果您遇到任何問題，歡迎提供回饋。

Gitea 同步的運作方式與 [GitHub 同步](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/github-synchronisation.md) 及 [GitLab 同步](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/gitlab-synchronisation.md) 相同：使用者連結自己的 Gitea 帳號，將專案匯出為新的 Gitea 儲存庫、匯入 Gitea 儲存庫，並進行雙向同步。它支援 1.23 或更新版本的 Gitea，無論是在 gitea.com 或您自己的執行個體上。

### 設定 Gitea 同步

> [!WARNING]
>
> 使用 Gitea 同步之前，您需要先啟用 [git-bridge](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/git-integration.md)。
>
> ```dotenv title="config/overleaf.rc" theme={null}
> GIT_BRIDGE_ENABLED=true
> ```

在您的 Gitea 執行個體上，於「*設定 → 應用程式 → 管理 OAuth2 應用程式*」（若要建立全站適用的應用程式，則於「*網站管理 → 整合 → 應用程式*」）建立 OAuth2 應用程式：

* **應用程式名稱**：例如 `Overleaf`，使用者在授權時會看到此名稱
* **重新導向 URI**：`${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback`
* **機密用戶端**：勾選

複製 **Client ID** 與 **Client Secret**，接著將以下設定加入您的 Overleaf 環境變數檔案。

```dotenv title="config/variables.env" wrap theme={null}
# used to encrypt the user's Gitea access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITEA_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Gitea Sync Settings
GITEA_SYNC_ENABLED=true
GITEA_SYNC_CLIENT_ID=
GITEA_SYNC_CLIENT_SECRET=

# Web address of your Gitea (its ROOT_URL), defaults to https://gitea.com
# GITEA_SYNC_URL=https://gitea.example.com

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
# (Optional) GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808
```

> [!WARNING]
>
> 在設定 Gitea 重新導向 URI 之前，請確認 `OVERLEAF_SITE_URL` 已正確設定。

Overleaf 會在使用者連結帳號時，一次要求同步所需的所有權限，因此使用者永遠不必因為缺少權限而重新連結：

| 範圍 | 用途 |
| - | - |
| `write:repository` | 儲存庫、其檔案（包括 `.gitea/workflows` 下的 CI 工作流程）、分支與拉取請求 |
| `write:user` | 匯出時建立使用者的儲存庫（Gitea 在 `POST /user/repos` 時會要求此範圍） |
| `write:organization` | 列出使用者的組織，並在匯出時於組織下建立儲存庫 |

Gitea 會在使用者授權應用程式時顯示這些範圍，並將權杖限制在這些範圍內。

Gitea 存取權杖會在一小時後過期（`[oauth2] ACCESS_TOKEN_EXPIRATION_TIME`）。Overleaf 會使用 Gitea 一併核發的重新整理權杖（refresh token）來更新存取權杖，即使 Gitea 會在使用後作廢重新整理權杖（`INVALIDATE_REFRESH_TOKENS = true`）也能正常運作，因此使用者會保持連結狀態，直到他們解除連結或在 Gitea 中撤銷該應用程式為止。

### 您的 Gitea 執行個體

將 `GITEA_SYNC_URL` 設為您執行個體的網頁位址，也就是它的 `ROOT_URL`，即您在瀏覽器中開啟儲存庫時使用的位址。REST API 位址會由此推導而來：

| 變數 | 預設值 |
| - | - |
| `GITEA_SYNC_URL` | `https://gitea.com` |
| `GITEA_SYNC_API_URL` | `${GITEA_SYNC_URL}/api/v1` |

架設於子路徑下的 Gitea 同樣可行，例如 `GITEA_SYNC_URL=https://example.com/gitea`。只有當您的執行個體在其他位置提供 API 時（例如位於 API 閘道之後），才需要設定 `GITEA_SYNC_API_URL`。

> [!WARNING]
>
> * 請在 `GITEA_SYNC_URL` 所設定的執行個體上建立 OAuth2 應用程式；在其他執行個體上建立的應用程式無法使用。
> * `GITEA_SYNC_URL` 只能是網頁位址。請勿加上 `/api/v1` 或使用者、組織路徑。
> * Overleaf 透過 Gitea 的檔案 API 進行提交，而這需要網頁編輯器：請保持 `[repository.editor]` 為啟用狀態（預設值）。

> [!NOTE]
>
> 如果您的執行個體使用由私人 CA 簽發的憑證，請將該 CA 憑證掛載到容器中，並將 `NODE_EXTRA_CA_CERTS` 指向它，例如 `NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitea-ca.pem`。

> [!CAUTION]
>
> 已連結的帳號與專案隸屬於當初連結時所使用的執行個體。在將 `GITEA_SYNC_URL` 切換至其他執行個體之前，請先要求使用者解除其 Gitea 帳號與專案的連結。

如果您位於網路存取受限的地區，可能需要設定代理伺服器才能存取 Gitea。請設定以下環境變數：`GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808`。它必須是標準的 HTTP/HTTPS 正向代理伺服器，且不得使用 `127.0.0.1`。

### 誰可以連結與同步

與 Overleaf Cloud 相同，只有專案擁有者可以將專案連結至 Gitea 儲存庫。連結完成後，每位具有編輯權限的協作者都可以進行同步。

| 操作 | 可執行者 |
| - | - |
| 將專案匯出至新的 Gitea 儲存庫 | 專案擁有者 |
| 將 Gitea 儲存庫匯入為新專案 | 任何使用者，並成為新專案的擁有者 |
| 對已連結的專案執行拉取、推送與合併 | 擁有者及具有編輯權限的協作者 |
| 解除專案與其儲存庫的連結 | 專案擁有者 |

* Overleaf 會使用執行同步之使用者的 Gitea 帳號與 Gitea 溝通，因此每位執行同步的協作者都需要連結自己的 Gitea 帳號，且必須具有推送至該儲存庫預設分支的權限。
* 僅具檢視權限的協作者無法對該專案使用 Gitea 同步。
* 在 Overleaf 中解除帳號連結會捨棄其權杖；Gitea 沒有撤銷權杖的 API，因此如有需要，請同時在 Gitea 的「*設定 → 應用程式*」中撤銷授權。

### Gitea 的同步運作方式

* **權限**：使用者必須具有推送至已連結儲存庫預設分支的權限。當分支保護規則不允許使用者推送時，Overleaf 會請他們聯絡專案擁有者，處理方式與失去存取權限的儲存庫相同。
* **合併**：當專案同時在 Overleaf 與 Gitea 中有所變更時，Overleaf 會將其變更提交至名為 `overleaf-YYYY-MM-DD-HHMMSS` 的暫存分支，並以儲存庫的預設合併方式透過拉取請求（pull request）進行合併，因為 Gitea 沒有提供不透過拉取請求就能合併分支的 API。合併完成後，Overleaf 會刪除該暫存分支；已合併的拉取請求則會作為紀錄保留在儲存庫中。
* **合併規則**：Overleaf 絕不會略過儲存庫的分支保護。當拉取請求發生衝突，或需要核准或通過狀態檢查時，該拉取請求會保持開啟，Overleaf 會請使用者在 Gitea 中完成合併後再繼續同步。
* **CI 工作流程**：Overleaf 不會顯示 `.gitea/workflows/` 等點檔案（dotfile），並會將其維持在儲存庫中的原樣。來自 Overleaf 的提交會像其他提交一樣觸發 Gitea Actions。

### Q\&A

> **我可以強制推送至預設分支嗎？**
>
> \*\*回答：\*\*請保持停用對預設分支的強制推送，例如透過分支保護規則。Overleaf 雖然能接手被改寫的分支，但 Gitea 同步是針對歷史紀錄只會持續增加的預設分支所設計的。

> **我可以重新命名已連結專案的預設分支嗎？**
>
> \*\*回答：\*\*不行。Overleaf 會持續與專案連結時的分支同步，因此一旦該分支被重新命名或移除，同步就會失敗。若要與其他分支同步，請先解除專案連結，再將儲存庫匯入為新專案，新專案會使用目前的預設分支。

> **Gitea 同步支援 Git LFS 嗎？**
>
> \*\*回答：\*\*不支援。Overleaf 專案不支援 Git 大型檔案儲存（Git LFS）。由 Git LFS 追蹤的檔案在 Overleaf 中會顯示為 LFS 指標檔案，而非其實際內容。請改為將圖片與 PDF 直接提交至儲存庫。

> **它支援 SHA-256 儲存庫嗎？**
>
> \*\*回答：\*\*目前尚不支援。Overleaf 是以 SHA-1 ID 比對檔案，因此在以 SHA-256 物件格式建立的儲存庫中，每次拉取都會改寫所有檔案，即使是未變更的檔案也一樣。雖然不會遺失任何資料，但請使用預設的 SHA-1 格式。

> **它支援 Forgejo 嗎？**
>
> \*\*回答：\*\*Gitea 同步僅針對 Gitea 開發與測試。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.