> ## 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 克隆、拉取和推送项目。

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 服务器](https://ayakaleaf-pro.mintlify.site/zh-CN/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 集成会在磁盘上为每个被用户克隆的项目存储一个完整的 git 仓库。如果磁盘空间有限，你可以启用一个交换任务，将较少使用的仓库移动到 AWS S3。如果再次需要已交换的仓库，它会被移回磁盘。以下环境变量用于控制交换任务：

| 名称 | 描述 |
| - | - |
| `GIT_BRIDGE_SWAPSTORE_TYPE` | 设置为 "s3" 以启用交换任务。 |
| `GIT_BRIDGE_SWAPSTORE_AWS_ACCESS_KEY` | 你的 AWS 访问密钥 |
| `GIT_BRIDGE_SWAPSTORE_AWS_SECRET` | 你的 AWS 密钥（secret） |
| `GIT_BRIDGE_SWAPSTORE_S3_BUCKET_NAME` | 该存储桶将存放压缩后的 git 仓库 |
| `GIT_BRIDGE_SWAPSTORE_AWS_REGION` | 存储桶所在区域 |
| `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 的权限模型是如何工作的？
>
> 具有只读权限的用户只能克隆该项目；具有读写权限的用户可以克隆和推送项目。注意：用户需要登录后才能加入该项目。

> [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` 设置（单位为兆字节，默认为 `50`），同样适用于推送。请在 `config/variables.env` 中调高该值，例如 `MAX_UPLOAD_SIZE=200`，然后运行 `bin/up -d`。如果你使用 [TLS 代理](https://ayakaleaf-pro.mintlify.site/zh-CN/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`
>
> 该警告无害，克隆、拉取和推送都能正常工作。在 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.