Git 集成

让用户通过 git-bridge 使用 Git 克隆、拉取和推送项目。

Git 集成目前在 ayaka-notes/overleaf 中提供。

该功能最初由 ayaka-notes/ayakaleaf-pro 开发。

1. 启用 git-bridge（仅限 Toolkit 用户）

   如果你使用的是 Toolkit，请在 config/overleaf.rc 中进行如下设置以启用 git-bridge：

   config/overleaf.rc

   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 文件中：

   docker-compose.yml (git-bridge service)

   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 服务器（v6.3.1 及更高版本）是 sharelatex 镜像的一部分，会与 Git 集成一同启用，因此无需额外的容器。

3. 更新 sharelatex 容器配置

   你还需要在 sharelatex 容器中链接 git-bridge 容器，并定义以下环境变量，请特别注意 V1_HISTORY_URL：

   docker-compose.yml (sharelatex service)

   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）。用户可以通过应用界面管理个人访问令牌（参见文档）：

   

   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 小时

​

问答

如果我与他人共享项目，Git Bridge 的权限模型是如何工作的？

具有只读权限的用户只能克隆该项目；具有读写权限的用户可以克隆和推送项目。注意：用户需要登录后才能加入该项目。

如何克隆项目？应使用什么用户名和密码？

在编辑器中，打开左侧栏中的 Integrations，然后点击 Git integration。其中会显示克隆命令，格式如下：

git clone https://<your-overleaf>/git/<project_id>

当 Git 要求输入凭据时，请输入 git 作为用户名，并使用个人访问令牌（Personal Access Token）作为密码。请在 Account Settings 中生成该令牌；其有效期为一年。你的账户密码无法使用。

更改不会自动同步：请使用 git pull 获取在编辑器中所做的更改，使用 git push 推送你的更改。/git 路径由 sharelatex 容器提供，因此其前面的反向代理无需额外规则。

git push 失败并提示 HTTP 413 或 curl 55 Broken pipe

推送的内容超过了上传大小限制。该限制由 MAX_UPLOAD_SIZE 设置（单位为兆字节，默认为 50），同样适用于推送。请在 config/variables.env 中调高该值，例如 MAX_UPLOAD_SIZE=200，然后运行 bin/up -d。如果你使用 TLS 代理或自己的反向代理，还需调高其 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 设置。

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 镜像，其版本与主镜像保持一致。

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 的迁移集。