> ## 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-CN/on-premises/configuration/overleaf-toolkit/github-synchronisation.md) 和 [GitLab 同步](https://ayakaleaf-pro.mintlify.site/zh-CN/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-CN/on-premises/configuration/overleaf-toolkit/git-integration.md)。
>
> ```dotenv title="config/overleaf.rc" theme={null}
> 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 环境变量文件中。

```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 随之签发的刷新令牌来刷新它们，即使 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 进行提交，而该 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 的 *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 构建和测试。


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