> ## 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.

# Git 整合

> 讓使用者透過 git-bridge 使用 Git 複製（clone）、拉取（pull）與推送（push）專案。

Git 整合目前在 [ayaka-notes/overleaf](https://github.com/ayaka-notes/overleaf) 中提供。

> [!NOTE]
>
> 此功能最初由 [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) 開發。

**1. 啟用 git-bridge（僅限 Toolkit 使用者）**

如果你使用的是 Toolkit，請在 `config/overleaf.rc` 中加入以下設定以啟用 `git-bridge`：

```text title="config/overleaf.rc" theme={null}
GIT_BRIDGE_ENABLED=true
```

除非同時設定了 `SERVER_PRO=true`，否則 Toolkit 會忽略此設定。除此之外不需要其他設定：Toolkit 會自行為 `sharelatex` 容器設定 `GIT_BRIDGE_HOST`、`GIT_BRIDGE_PORT` 與 `V1_HISTORY_URL`，因此請略過下方兩個 Docker Compose 步驟。執行 `bin/up` 以重新建立容器。

**2. 新增 git-bridge 容器（僅限 Docker-compose 使用者）**

若你使用自訂的 `docker-compose.yml`，請將以下容器設定加入你的 compose 檔案：

```yaml title="docker-compose.yml (git-bridge service)" wrap theme={null}
git-bridge:
    restart: always
    image: ghcr.io/ayaka-notes/overleaf-pro/git-bridge:6.3.2 # tag should match the `sharelatex` container tag
    volumes:
        - ~/git_bridge_data:/data/git-bridge
    container_name: git-bridge
    expose:
        - "8000"
    environment:
        GIT_BRIDGE_API_BASE_URL: "http://sharelatex:3000/api/v0/" 
        GIT_BRIDGE_OAUTH2_SERVER: "http://sharelatex"
        GIT_BRIDGE_POSTBACK_BASE_URL: "http://git-bridge:8000"
        GIT_BRIDGE_ROOT_DIR: "/data/git-bridge"
    user: root
    command: ["/server-pro-start.sh"]
```

請使用與 `sharelatex` 映像檔相同的標籤。[MCP Server](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md)（v6.3.1 及更新版本）是 `sharelatex` 映像檔的一部分，會與 Git 整合一同啟用，因此不需要額外的容器。

**3. 更新 sharelatex 容器設定**

你還需要在 `sharelatex` 容器中連結 `git-bridge` 容器，並定義以下環境變數，請特別留意 `V1_HISTORY_URL`：

```yaml title="docker-compose.yml (sharelatex service)" theme={null}
sharelatex:
    links:
        - git-bridge
    environment:
         GIT_BRIDGE_ENABLED: true
         GIT_BRIDGE_HOST: "git-bridge"
         GIT_BRIDGE_PORT: "8000"
         # We use v1 now, if you used to set V1_HISTORY_URL, please update now
         V1_HISTORY_URL: "http://sharelatex:3100/api"
```

**4. 驗證**

驗證 git 用戶端時，使用者需要個人存取權杖（Personal Access Token）。使用者可以透過應用程式介面管理個人存取權杖（請參閱說明文件）：

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-29.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=39af379b36baaa023f7cff66dc2dba76)

Git 整合的個人存取權杖

**5. 監控與資源考量**

建議你在啟用 `git-bridge` 後監控主機資源。負載增加的程度取決於：

* 使用此功能的使用者人數
* 執行個體中託管的專案類型（較大的專案通常會耗用較多資源）

### 將專案置換至 S3

Git 整合會為每個被使用者複製（clone）的專案，在磁碟上儲存一份完整的 git 儲存庫。如果你的磁碟空間有限，可以啟用置換工作，將較少使用的儲存庫移至 AWS S3。若再次需要已置換的儲存庫，它會被移回磁碟。以下環境變數用於控制置換工作：

| 名稱 | 說明 |
| - | - |
| `GIT_BRIDGE_SWAPSTORE_TYPE` | 設為 "s3" 即可啟用置換工作。 |
| `GIT_BRIDGE_SWAPSTORE_AWS_ACCESS_KEY` | 你的 AWS 存取金鑰 |
| `GIT_BRIDGE_SWAPSTORE_AWS_SECRET` | 你的 AWS 密鑰 |
| `GIT_BRIDGE_SWAPSTORE_S3_BUCKET_NAME` | 此 bucket 將存放壓縮後的 git 儲存庫 |
| `GIT_BRIDGE_SWAPSTORE_AWS_REGION` | bucket 所在的區域 |
| `GIT_BRIDGE_SWAPJOB_MIN_PROJECTS` | 磁碟上至少要保留的專案數量。 **- 預設：** 50 |
| `GIT_BRIDGE_SWAPJOB_LOW_GIB` | 置換的低水位。置換工作會持續移出專案，直到磁碟使用量低於此值。 **- 預設：** 128 GB |
| `GIT_BRIDGE_SWAPJOB_HIGH_GIB` | 置換的高水位。當磁碟使用量達到此值時，置換工作便會開始置換。 **- 預設：** 256 GB |
| `GIT_BRIDGE_SWAPJOB_INTERVAL_MILLIS` | 每次檢查磁碟使用量並執行置換工作之間的間隔時間。 **- 預設：** 3600000 ms = 1 小時 |

### 問與答

> [accordion] 如果我將專案分享給其他人，Git Bridge 的權限模型是如何運作的？
>
> 僅具唯讀權限的使用者只能複製（clone）此專案；具讀寫權限的使用者則可以複製並推送（push）專案。注意：使用者必須登入才能加入此專案。

> [accordion] 如何複製專案？要使用哪個使用者名稱與密碼？
>
> 在編輯器中，開啟左側欄的 **Integrations** 並點選 **Git integration**。畫面會顯示複製指令，格式如下：
>
> ```sh theme={null}
> git clone https://<your-overleaf>/git/<project_id>
> ```
>
> 當 Git 要求輸入憑證時，請輸入 `git` 作為使用者名稱，並以個人存取權杖（Personal Access Token）作為密碼。請在 **Account Settings** 中產生權杖，其有效期限為一年。您的帳號密碼無法使用。
>
> 變更不會自動同步：請使用 `git pull` 取得在編輯器中所做的變更，並使用 `git push` 送出您的變更。`/git` 路徑由 `sharelatex` 容器提供，因此其前方的反向代理不需要額外的規則。

> [accordion] `git push` 失敗並顯示 `HTTP 413` 或 `curl 55 Broken pipe`
>
> 推送的內容超過了上傳大小上限，此上限由 `MAX_UPLOAD_SIZE` 設定（單位為 MB，預設為 `50`），同樣適用於推送。請在 `config/variables.env` 中調高此值，例如 `MAX_UPLOAD_SIZE=200`，然後執行 `bin/up -d`。如果您使用 [TLS 代理](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/tls-proxy.md)或自己的反向代理，也請調高其 `client_max_body_size`（在 Toolkit 的 `config/nginx/nginx.conf` 中為 `50M`）。
>
> git-bridge 也會拒絕大於 50 MB 的檔案，以及包含超過 2,000 個檔案的專案。這些上限由 `config/variables.env` 中的 `GIT_BRIDGE_REPOSTORE_MAX_FILE_SIZE`（單位為位元組）與 `GIT_BRIDGE_REPOSTORE_MAX_FILE_NUM` 設定。

> [accordion] git-bridge 日誌顯示 `Failed to fetch log level`
>
> 此警告無害，clone、pull 與 push 都能正常運作。在 6.2.x 中，git-bridge 每分鐘會向 Google Cloud 中繼資料伺服器（`metadata.google.internal`）查詢一次日誌層級，而這只在 Google Cloud 上有效。在其他環境中，該請求會失敗，git-bridge 會記錄錯誤（例如 `null` 或 HTTP 狀態碼），並沿用 `GIT_BRIDGE_LOG_LEVEL` 所設定的層級。自 6.3.0 起此檢查已關閉，而升級時也會一併更新 git-bridge 映像檔，其版本會跟隨主映像檔。

> [accordion] Git 與完整專案歷史記錄是否需要 track-changes 服務或 `OVERLEAF_IS_SERVER_PRO=true`？
>
> \*\*答：\*\*不需要。Ayakaleaf Pro 沒有 track-changes 服務。專案歷史記錄由 `project-history` 與 `history-v1` 服務保存，這兩個服務一律在 `sharelatex` 容器內執行。git-bridge 會從位於 `V1_HISTORY_URL`（`http://sharelatex:3100/api`）的 `history-v1` 讀取歷史記錄，此值由 Toolkit 設定。請勿設定 `OVERLEAF_IS_SERVER_PRO`：沒有任何功能依賴它，它只會將啟動時執行的資料庫遷移切換為 Server Pro 的版本。


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