> ## 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 Sync User Credentials 集合

`giteaSyncUserCredentials` 为每个为 Gitea Sync 关联了 Gitea 账户的用户保存一个文档。 它以加密形式存储用户的 OAuth 令牌。 该集合属于 `gitea-sync` web 模块（`services/web/modules/gitea-sync`）。schema 位于 `services/web/modules/gitea-sync/app/models/giteaSyncUserCredentials.mjs`，所有访问都经过 `services/web/modules/gitea-sync/app/src/TokenManager.mjs`。

#### 字段

| 字段 | 类型 | 含义 | 来源 |
| - | - | - | - |
| `_id` | ObjectId | upsert 插入时由 Mongoose 设置。 | |
| `userId` | ObjectId | Overleaf 用户。必填。schema 写了 `unique: true`，但不会建立任何索引（见“索引”）；按 `userId` 的 upsert 保证每个用户只有一个文档。 | `giteaSyncUserCredentials.mjs:8`, `TokenManager.mjs:89-96` |
| `gitea` | String | JSON `{ accessToken, refreshToken, expiresAt }`，使用 `@overleaf/access-token-encryptor` 加密。`expiresAt` 是自 Unix 纪元起的毫秒数，或为 `null`；`refreshToken` 可能为 `null`。密码来自 `GITEA_TOKEN_CIPHER_PASSWORD`；加密标签为 `GITEA_TOKEN_CIPHER_LABEL`，默认 `2026.10-v3`。必填。 | `giteaSyncUserCredentials.mjs:9-10`, `TokenManager.mjs:17-30`, `services/web/modules/gitea-sync/app/src/GiteaApiClient.mjs:198-209` |
| `__v` | Number | Mongoose 版本键。schema 没有关闭它。 | Mongoose 默认 |

#### 写入方

| 代码 | 作用 |
| - | - |
| `TokenManager.mjs:89-96` (`saveUserToken`) | 对用户的加密凭据执行 upsert。由 OAuth 回调调用（`services/web/modules/gitea-sync/app/src/GiteaSyncController.mjs:146`）。与 GitLab Sync 不同，重新关联不会撤销被替换的令牌。 |
| `TokenManager.mjs:53-79` (`refreshUserToken`) | 当访问令牌距 `expiresAt` 不足 5 分钟时（`:12`），用刷新令牌获取新令牌并保存（`:76`）。它在每个用户的 `giteaSyncToken` 锁下运行（`:14,54`），因为 Gitea 在使用刷新令牌时会替换它。 |
| `TokenManager.mjs:100-102` (`removeUserToken`) | 删除文档。Gitea 没有撤销 OAuth 令牌的 API，因此由用户在 Gitea 中撤销授权（`:98-99`）。在取消关联时（`GiteaSyncController.mjs:173`）以及已删除用户过期时（`services/web/modules/gitea-sync/index.mjs:56-58`）调用。 |

#### 读取方

| 代码 | 作用 |
| - | - |
| `TokenManager.mjs:40-44,82-86` (`getUserCredentials`, `getUserToken`) | 为每次 Gitea API 调用解密凭据，令牌即将过期时先刷新：`services/web/modules/gitea-sync/app/src/GiteaSyncHandler.mjs`（例如 `:27`）和 `services/web/modules/gitea-sync/app/src/GitMerge.mjs:52`。没有文档或凭据无法解密或刷新时，抛出 `InvalidTokenError`，用户视为未关联（`GiteaSyncHandler.mjs:25-37`）。 |
| `services/web/modules/admin-tools/app/src/AdminUserListManager.mjs:395` | 检查用户是否有文档，用于管理面板中显示的集成。 |

#### 索引

| 名称 | 键 | 选项 | 迁移 |
| - | - | - | - |
| `_id_` | `_id: 1` | | default |

Mongoose 的 `autoIndex` 已关闭（`services/web/app/src/infrastructure/Mongoose.mjs:7`），因此 schema 中 `userId` 上的 `unique: true` 不会创建任何索引。 没有迁移为该集合创建索引。

#### 说明

* 更改 `GITEA_TOKEN_CIPHER_PASSWORD` 会使已存储的凭据无法读取。这些用户在重新关联之前都视为未关联。
* 已删除的用户会保留该文档，直到该用户过期。


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