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

# Project History Chunks 集合

`projectHistoryChunks` 中每个历史 chunk 一个文档，chunk 是一个项目历史中的一段连续版本。Mongo 只保存 chunk 的元数据；chunk 本身（一个快照加上其后的更改）是 chunks bucket 中经 gzip 压缩的 JSON 对象。没有 Mongoose schema：history-v1 在 `services/history-v1/storage/lib/chunk_store/mongo.js` 中写入该集合，它用于所有 24 个十六进制字符的历史 id，CE 中正是如此（`services/history-v1/storage/lib/chunk_store/index.js:644-652`）。

#### 字段

| 字段 | 类型 | 含义 | 来源 |
| - | - | - | - |
| `_id` | ObjectId | Chunk id。它也是 bucket 中 chunk 对象的名称（参见说明）。 | `mongo.js:183-185` |
| `projectId` | ObjectId | 项目的历史 id，即 `projects.overleaf.history.id` 中的值。在 CE 中，web 用项目自身的 `_id` 创建历史（`services/web/app/src/Features/History/HistoryManager.mjs:51-55`）。 | `mongo.js:186` |
| `startVersion` | Number | chunk 中第一个更改之前的项目版本。 | `mongo.js:187` |
| `endVersion` | Number | chunk 中最后一个更改之后的项目版本。 | `mongo.js:188` |
| `endTimestamp` | Date | chunk 中最后一个更改的时间；chunk 没有更改时为 `null`，例如新项目的第一个 chunk（`libraries/overleaf-editor-core/lib/chunk.js:146-149`）。 | `mongo.js:189` |
| `state` | String | `pending`、`active`、`closed` 或 `deleted`，参见说明。 | `mongo.js:190`, `343`, `378`, `409` |
| `updatedAt` | Date | 在插入、激活和删除时设置。关闭 chunk 不会改变它。 | `mongo.js:191`, `343`, `409`, `434`, `450` |

#### 写入方

| 代码 | 作用 |
| - | - |
| `services/history-v1/storage/lib/chunk_store/mongo.js:179-194` | `insertPendingChunk`：在上传 chunk 对象之前插入一条 `pending` 记录（`chunk_store/index.js:394-410`）。 |
| `mongo.js:331-359` | `activateChunk`：上传完成后从 `pending` 变为 `active`。这里出现重复键意味着已有另一个 chunk 从该版本开始。 |
| `mongo.js:371-388` | `closeChunk`：有新 chunk 接在其后时从 `active` 变为 `closed`（`confirmCreate`，`mongo.js:206-227`）。 |
| `mongo.js:402-419` | `deleteActiveChunk`：被起始版本相同的更长 chunk 取代时从 `active` 变为 `deleted`（`confirmUpdate`，`mongo.js:295-321`）。 |
| `mongo.js:428-452` | `deleteChunk` 和 `deleteProjectChunks`：把 chunk 标记为 `deleted`。后者在 history-v1 的 `DELETE /projects/:project_id` 上运行（`services/history-v1/api/controllers/projects.js:361-373`）。 |
| `mongo.js:144-174` | `clone`：把一个项目的记录复制到新的历史 id 下，用于 history-v1 的 `POST /projects/:project_id/clone`。Web 有该路由的客户端（`HistoryManager.mjs:63-72`），但 web 中没有任何代码调用它。 |
| `mongo.js:497-502` | `deleteOldChunks`：移除旧的 `deleted` 和 `pending` 记录。只由 `services/history-v1/storage/tasks/delete_old_chunks.js` 运行。 |

新 chunk 来自 project-history，它把排队的编辑发送到 history-v1 的 `POST /projects/:project_id/legacy_changes`（`services/history-v1/api/routes/project_import.js:29-31`）；history-v1 随后调用 `chunkStore.update` 或 `chunkStore.create`（`services/history-v1/storage/lib/persist_changes.js:215`, `229`）。新项目的第一个 chunk 来自 `chunkStore.initializeProject`（`chunk_store/index.js:54-80`）。

#### 读取方

| 代码 | 作用 |
| - | - |
| `mongo.js:23-43` | `getLatestChunk`：项目最新的 `active` 或 `closed` chunk。 |
| `mongo.js:54-71` | `getChunkForVersion`：包含某个版本的 chunk。 |
| `mongo.js:77-103` | `getChunkForTimestamp`：某个时间点的当前 chunk。 |
| `mongo.js:108-137` | `getProjectChunkIds` 和 `getProjectChunks`：项目的所有有效 chunk。 |
| `mongo.js:457-492` | `getOldChunksBatch`：供清理任务使用的旧 `deleted` 和 `pending` 记录。 |
| `services/history-v1/api/controllers/projects.js:115-265` | history-v1 的读取路由（最新内容、某版本的内容、历史、更改），它们通过 `chunk_store/index.js` 加载 chunk。 |

#### 索引

| 名称 | 键 | 选项 | 迁移 |
| - | - | - | - |
| `projectId_1_startVersion_1_v2` | `{ projectId: 1, startVersion: 1 }` | unique，部分索引：`state` 为 `active`、`closed` | `tools/migrations/20250411200550_active_chunk_index_update.mjs`（替换 `20221122191857_project_history_chunks_indexes.mjs` 的 `projectId_1_startVersion_1`） |
| `deleted_updated_at` | `{ updatedAt: 1 }` | 部分索引：`state: 'deleted'` | `tools/migrations/20230428154643_history_chunks_garbage_collection_index.mjs`（替换 `state_1`） |
| `pending_updated_at` | `{ updatedAt: -1 }` | 部分索引：`state: 'pending'` | `tools/migrations/20230428154643_history_chunks_garbage_collection_index.mjs`（替换 `20230217205311_fix_deleted_history_chunks_index.mjs` 的 `state_pending`） |

#### 说明

* 状态流转：`pending`（记录已写入，正在上传）→ `active`（最新的 chunk，仍可扩展）→ `closed`（后面有更新的 chunk）或 `deleted`（被取代，或项目已删除）。读取只看 `active` 和 `closed`。
* chunk 对象是经 gzip 压缩的 JSON（`services/history-v1/storage/lib/history_store.js:151-170`），位于键 `<project key>/<chunk id>`（`history_store.js:65-67`）。项目键是用零填充的历史 id，反转后按 3/3/其余字符切分（`libraries/object-persistor/src/ProjectKey.js:8-15`）。bucket 是 `OVERLEAF_EDITOR_CHUNKS_BUCKET`（`services/history-v1/config/custom-environment-variables.json:53-56`）：开发环境中为 `/buckets/chunks`（`develop/docker-compose.yml:90`），使用 `S3_ENABLED=true` 时为 `overleaf-chunks`（`develop/s3/docker-compose.yml:51`）。
* 处于 `deleted` 或 `pending` 状态的记录及其 bucket 对象只会被 `delete_old_chunks.js` 移除（`yarn delete_old_chunks`，`services/history-v1/package.json:79`）。CE 镜像没有为此设置 cron 任务（`server-ce/config/crontab-history`, `server-ce/config/crontab-deletion`），因此在 CE 中它们会一直保留。
* 当 web 让已删除项目过期时，会调用 history-v1 的 `DELETE /projects/:history_id`（`services/web/app/src/Features/Project/ProjectDeleter.mjs:385-391`, `HistoryManager.mjs:127-135`, `152-162`），从而把该项目的所有 chunk 标记为 `deleted`。
* 配置了 `backupStore` 时，确认 chunk 还会把 `overleaf.history.currentEndVersion`、`currentEndTimestamp`、`updatedAt` 和 `overleaf.backup.pendingChangeAt` 写入项目（`mongo.js:232-262`）。CE 没有配置 `backupStore`，所以 `mongo.js:238-240` 会提前返回。


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