Gitea 同步

此功能由 ayaka-notes/ayakaleaf-pro 开发。它在 v6.3.2 中作为早期预览版引入，并将在 v6.4.0 中正式发布，因此其配置和行为仍可能发生变化。如果你遇到任何问题，我们需要你的反馈。

Gitea 同步的工作方式与 GitHub 同步 和 GitLab 同步 相同：用户关联自己的 Gitea 账户，将项目导出为新的 Gitea 仓库，导入 Gitea 仓库，并进行双向同步。它支持 1.23 或更高版本的 Gitea，无论是 gitea.com 还是你自己的实例。

​

设置 Gitea 同步

在使用 Gitea 同步之前，你需要先启用 git-bridge。

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

在你的 Gitea 实例上创建一个 OAuth2 应用，位置为 Settings → Applications → Manage OAuth2 applications（如需创建实例级应用，则为 Site Administration → Integrations → Applications）：

• Application name：例如 Overleaf，用户在授权时会看到这个名称
• Redirect URIs：${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client：勾选

复制 Client ID 和 Client Secret，然后将以下设置添加到你的 Overleaf 环境变量文件中。

config/variables.env

# 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

在配置 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 随之签发的刷新令牌来刷新它们，即使 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。

• 请在 GITEA_SYNC_URL 所设置的实例上创建 OAuth2 应用，来自其他实例的应用无法使用。
• GITEA_SYNC_URL 只能是网页地址。不要添加 /api/v1 或用户、组织路径。
• Overleaf 通过 Gitea 的文件 API 进行提交，而该 API 依赖网页编辑器：请保持 [repository.editor] 启用（默认即为启用）。

如果你的实例使用由私有 CA 签发的证书，请将 CA 证书挂载到容器中，并将 NODE_EXTRA_CA_CERTS 指向它，例如 NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitea-ca.pem。

已关联的账户和项目属于其关联时所使用的实例。在将 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 的 Settings → Applications 中撤销授权。

​

与 Gitea 同步的工作原理

• 权限：用户需要拥有向已关联仓库的默认分支推送的权限。当分支保护规则不允许用户推送时，Overleaf 会提示他们联系项目所有者，与处理已失去访问权限的仓库时相同。
• 合并：当项目在 Overleaf 和 Gitea 中都发生了更改时，Overleaf 会将其更改提交到一个名为 overleaf-YYYY-MM-DD-HHMMSS 的临时分支，并通过拉取请求以仓库的默认合并方式进行合并，因为 Gitea 没有提供无需拉取请求即可合并分支的 API。合并完成后，Overleaf 会删除该临时分支；已合并的拉取请求会作为记录保留在仓库中。
• 合并规则：Overleaf 从不绕过仓库的分支保护。当拉取请求存在冲突，或需要审批或通过状态检查时，它会保持打开状态，Overleaf 会提示用户在 Gitea 中完成合并，然后继续同步。
• CI 工作流：Overleaf 不会显示 .gitea/workflows/ 等点文件，并会在仓库中保持它们原样。来自 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 构建和测试。