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

# User Audit Log Entries 集合

`userAuditLogEntries` 是使用者帳號的稽核記錄：登入、密碼和電子郵件變更、連結的帳號以及管理員操作。一份文件是一個帳號上的一個事件。由 `web` 負責；結構描述為 `services/web/app/src/models/UserAuditLogEntry.mjs`，核心程式碼透過 `services/web/app/src/Features/User/UserAuditLogHandler.mjs` 寫入。

#### 欄位

| 欄位 | 型別 | 意義 | 來源 |
| - | - | - | - |
| `_id` | ObjectId | 項目 id。 | `UserAuditLogEntry.mjs:4` |
| `userId` | ObjectId | 事件所涉及的帳號。 | `UserAuditLogEntry.mjs:6` |
| `operation` | String | 發生了什麼，為 kebab-case 名稱，例如 `login`（見下表）。 | `UserAuditLogEntry.mjs:11` |
| `initiatorId` | ObjectId | 執行者：使用者本人，或管理員操作時的管理員。少數操作可能缺少，例如 `reset-password`（`UserAuditLogHandler.mjs:19-33`）。 | `UserAuditLogEntry.mjs:9` |
| `ipAddress` | String | 請求的 IP 位址（`req.ip`）。少數操作可能缺少（`UserAuditLogHandler.mjs:8-17`）。 | `UserAuditLogEntry.mjs:10` |
| `info` | Object | 事件詳細資料；鍵取決於操作。 | `UserAuditLogEntry.mjs:8` |
| `timestamp` | Date | 項目寫入的時間（預設 `Date.now`）。 | `UserAuditLogEntry.mjs:12` |
| `managedSubscriptionId` | ObjectId | 使用者的受管理群組訂閱。僅在啟用 `saas` 功能時設定（`UserAuditLogHandler.mjs:92-107`），因此在 CE 中從不出現。 | `UserAuditLogEntry.mjs:7` |
| `__v` | Number | Mongoose 版本鍵，由 `UserAuditLogEntry.create` 加入。 | `UserAuditLogHandler.mjs:109` |

#### 誰寫入

| 程式碼 | 作用 |
| - | - |
| `UserAuditLogHandler.mjs:62-110` (`addEntry`) | 建立一個項目。缺少 `operation`，或某個操作需要的 `ipAddress` 或 `initiatorId` 缺少時擲回錯誤。 |
| `UserAuditLogHandler.mjs:112-126` (`addEntryInBackground`) | 同上，但不等待；錯誤只會記錄下來。 |
| `services/web/modules/admin-tools/app/src/AdminAuditLog.mjs:14-38` | 我們的管理面板：`logOnUser` 將管理員操作寫在目標帳號上，並以管理員為執行者；當目標已沒有記錄時（已永久清除的使用者、範本），`logOnAdmin` 寫在管理員自己的帳號上。 |
| `services/web/modules/authentication/auditLog.mjs:9-21` | 我們的 LDAP、SAML 和 OIDC 模組：`logLoginEntry` 記錄一次 SSO 登入對帳號做了什麼，並以該帳號本身為執行者。 |
| `services/web/app/src/Features/User/UserDeleter.mjs:141` | 已刪除使用者過期時，刪除該使用者的所有項目（`expireDeletedUsersAfterDuration`）。 |
| `AdminAuditLog.mjs:41-43` (`deleteUserEntries`) | 我們的管理面板在永久清除使用者時刪除其所有項目（`services/web/modules/admin-tools/app/src/AdminUserManager.mjs:644`）。 |
| `tools/migrations/20220913125500_migrate_auditLog_to_collections.mjs` | 一次性遷移：將舊的 `users.auditLog` 陣列移到此集合。 |

核心程式碼寫入的操作：

| `operation` | 寫入位置 (`services/web/app/src/...`) |
| - | - |
| `login` | `Features/Authentication/AuthenticationController.mjs:225` |
| `failed-password-match` | `Features/Authentication/AuthenticationManager.mjs:150` |
| `logout` | `Features/User/UserController.mjs:599` |
| `update-password` | `Features/User/UserController.mjs:131` |
| `clear-sessions` | `Features/User/UserController.mjs:167` |
| `reset-password` | `Features/PasswordReset/PasswordResetHandler.mjs:106` |
| `delete-account` | `Features/User/UserDeleter.mjs:50` |
| `account-suspension` | `Features/User/UserUpdater.mjs:621` |
| `must-reset-password-unset` | `Features/User/UserUpdater.mjs:604` |
| `add-email`, `remove-email`, `change-primary-email` | `Features/User/UserUpdater.mjs:99`, `:494`, `:247` |
| `migrate-default-email` | `Features/User/UserUpdater.mjs:355` |
| `clear-institution-sso-data`, `clear-third-party-identifiers` | `Features/User/UserUpdater.mjs:160`, `:196` |
| `confirm-email` | `Features/User/UserEmailsController.mjs:750` |
| `request-add-email-code`, `add-email-via-code`, `confirm-email-via-code` | `Features/User/UserEmailsController.mjs:138`, `:331`, `:354` |
| `resend-add-email-code`, `resend-confirm-email-code` | `Features/User/UserEmailsController.mjs:391` (名稱見 `:417`, `:423`) |
| `link-sso`, `unlink-sso` | `Features/User/ThirdPartyIdentityManager.mjs:64`, `:131` (由我們的 OIDC 模組使用) |
| `link-institution-sso`, `unlink-institution-sso`, `migrate-institution-sso-id`, `unlink-institution-sso-not-migrated` | `Features/User/SAMLIdentityManager.mjs:103`, `:293`, `:424`, `:462` |
| `accept-group-invitation`, `join-group-subscription`, `leave-group-subscription`, `remove-from-group-subscription` | `Features/Subscription/TeamInvitesController.mjs:276`, `Features/Subscription/SubscriptionUpdater.mjs:104`, `:133`, `:193`, `Features/Subscription/SubscriptionGroupController.mjs:127` |
| `ai-quota-breach` | `infrastructure/rate-limiters/AiFeatureUsageRateLimiter.mjs:35`, `infrastructure/rate-limiters/TokenUsageRateLimiter.mjs:99`, `:191` |

我們的模組寫入的操作（`services/web/modules/...`）：

| `operation` | 寫入位置 |
| - | - |
| `create-account` | `authentication/ldap/app/src/LDAPAuthenticationManager.mjs:58`, `authentication/saml/app/src/SAMLAuthenticationManager.mjs:56`, `authentication/oidc/app/src/OIDCAuthenticationManager.mjs:75`, `admin-tools/app/src/AdminUserManager.mjs:167` |
| `remove-password` | `authentication/ldap/app/src/LDAPAuthenticationManager.mjs:78`, `authentication/saml/app/src/SAMLAuthenticationManager.mjs:94` |
| `link-institution-sso` | `authentication/saml/app/src/SAMLAuthenticationManager.mjs:71` |
| `change-admin-access`, `change-name` | `authentication/auditLog.mjs:37`, `:47` (SSO 登入); `admin-tools/app/src/AdminUserManager.mjs:394`, `:391` (管理員) |
| `failed-password-match` | `authentication/auditLog.mjs:80` (LDAP) |
| `logout` | `authentication/auditLog.mjs:58` |
| `send-activation-email`, `send-password-reset-email` | `admin-tools/app/src/AdminUserManager.mjs:184`, `:207` |
| `update-password`, `change-features`, `change-ai-features`, `account-reactivation` | `admin-tools/app/src/AdminUserManager.mjs:389`, `:397`, `:400`, `:403` |
| `clear-sessions`, `transfer-projects`, `restore-account`, `reset-ai-usage` | `admin-tools/app/src/AdminUserManager.mjs:514`, `:563`, `:694`, `:712` |
| `purge-deleted-user`, `purge-deleted-project`, `delete-template` (寫在管理員的帳號上) | `admin-tools/app/src/AdminUserManager.mjs:645`, `admin-tools/app/src/AdminProjectManager.mjs:525`, `admin-tools/app/src/AdminTemplateManager.mjs:67` |
| `publish-template`, `edit-template`, `delete-template` | `template-gallery/app/src/TemplateGalleryController.mjs:52`, `:107`, `:137` |
| `link-dropbox`, `unlink-dropbox` | `dropbox/app/src/DropboxController.mjs:87`, `:107`, `dropbox/index.mjs:38` |
| `link-github`, `unlink-github` | `github-sync/app/src/GitHubSyncController.mjs:155`, `:175` |
| `integration-account-linked`, `integration-account-unlinked` | GitLab 和 Gitea 同步 (`gitlab-sync/app/src/GitLabSyncController.mjs:155`, `:181`, `gitea-sync/app/src/GiteaSyncController.mjs:155`, `:181`), Zotero 和 Mendeley (`tpr-webmodule/app/src/ZoteroController.mjs:77`, `:99`, `tpr-webmodule/app/src/MendeleyController.mjs:77`, `:99`) |
| `create-git-token`, `delete-git-token` | `oauth2-server/app/src/OAuthPersonalAccessTokenController.mjs:48`, `:74` |

#### 誰讀取

| 程式碼 | 作用 |
| - | - |
| `services/web/modules/admin-tools/app/src/AdminAuditLog.mjs:124-126` (`listUserEntries`) | 我們管理面板的稽核記錄分頁，`GET /admin/user/:userId/audit-log/list`（`services/web/modules/admin-tools/app/src/AdminToolsRouter.mjs:32-36`）。 |

CE 核心沒有顯示此記錄的頁面。

#### 索引

| 名稱 | 鍵 | 選項 | 遷移 |
| - | - | - | - |
| `timestamp_1` | `{ timestamp: 1 }` | TTL, `expireAfterSeconds: 78840000` (2.5 年) | `tools/migrations/20220913105500_create_auditLog_indexes.mjs` |
| `userId_1_timestamp_-1` | `{ userId: 1, timestamp: -1 }` | | `tools/migrations/20251117093546_add_timestamp_to_userAuditLogEntries.mjs` |

`tools/migrations/20220929193200_add_auditLog_indexes.mjs` 最初在 `{ userId: 1 }` 上建立了 `user_id_1`；`20251117093546` 以複合索引取代它。結構描述以 `index: true` 標記了 `userId` 和 `managedSubscriptionId`，但 Mongoose 自動建立索引已關閉（`services/web/app/src/infrastructure/Mongoose.mjs:7`），因此只有上述遷移會建立索引。`managedSubscriptionId` 的索引遷移只帶有 `saas` 標籤。

#### 說明

* 項目透過 TTL 索引在 `timestamp` 之後 2.5 年過期。


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