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