> ## 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.

# GitLab Sync User Credentials 集合

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

#### 字段

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

#### 写入方

| 代码 | 作用 |
| - | - |
| `TokenManager.mjs:88-95` (`saveUserToken`) | 对用户的加密凭据执行 upsert。 |
| `TokenManager.mjs:99-108` (`linkUserToken`) | 保存 OAuth 回调得到的新凭据（`services/web/modules/gitlab-sync/app/src/GitLabSyncController.mjs:146`）。用户重新关联时，被替换的访问令牌会在后台于 GitLab 上撤销。 |
| `TokenManager.mjs:53-78` (`refreshUserToken`) | 当访问令牌距 `expiresAt` 不足 5 分钟时（`:13,47-49`），用刷新令牌获取新令牌并保存（`:75`）。它在每个用户的 `gitlabSyncToken` 锁下运行（`:15,54`），因为 GitLab 的刷新令牌用一次就失效。 |
| `TokenManager.mjs:111-126` (`removeUserToken`) | 在 GitLab 上撤销访问令牌（尽力而为），然后删除文档。在取消关联时（`GitLabSyncController.mjs:173`）以及已删除用户过期时（`services/web/modules/gitlab-sync/index.mjs:56-58`）调用。 |

#### 读取方

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

#### 索引

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

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

#### 说明

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


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