MongoDB

快速开始

使用 MongoDB 蓝图为现有 Flue 项目添加持久化共享状态。在终端或你选择的编码智能体中运行以下命令：

flue add database mongodb

概述

MongoDB 蓝图会安装 @flue/mongodb 和官方 mongodb 驱动，在项目的源代码根目录创建完整的 db.ts 运行器，并遵循项目现有的 MONGODB_URL 和 MONGODB_DATABASE 密钥约定。生成的适配器连接驱动、选择数据库，并将项目拥有的运行器传递给 mongodb()：

import { mongodb, type MongoOperations, type MongoRunner } from '@flue/mongodb';
import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_URL!);
await client.connect();

const db = client.db(process.env.MONGODB_DATABASE);
const runner: MongoRunner = {/* ... */};

export default mongodb(runner);

蓝图不会修改 MongoDB 部署，它必须支持事务。Flue 在 Node 构建期间发现适配器，并持久化规范的智能体对话、不可变附件和已接受的提交，以便状态在进程替换后得以保留。副本可以共享持久状态，但每个智能体实例仍然需要一个活动的 Node 所有者。应用业务数据仍由应用自行管理。

配置

官方驱动在运行时读取这些值。永远不要提交凭证。对于本地开发，vite dev 会加载项目 .env 文件，而 flue run --env <file> 会加载任何 .env 格式的文件；在生产环境中，请使用部署平台的密钥存储。

client.db(undefined) 可以从连接字符串（或驱动默认值）选择数据库，但显式设置 MONGODB_DATABASE 可以避免部署歧义。建议使用专用数据库。如果 Flue 必须共享一个数据库，请向 mongodb() 传递一个稳定唯一的 collectionPrefix；更改它会选择新的命名空间，而不是移动现有数据。

蓝图会安装 @flue/mongodb 和官方 mongodb 驱动，然后在源代码根目录创建完整的 db.ts 运行器。Flue 在构建时发现该文件，并将适配器连接到生成的 Node 服务器。

这是一个 Node.js 适配器。Cloudflare 目标使用 Durable Object SQLite 并拒绝 db.ts，因此 MongoDB 不会在该目标上使用。有关特定目标的持久化行为，请参阅数据库。

选择支持的部署

MongoDB 事务需要以下部署之一：

• MongoDB Atlas；
• 副本集；
• 支持事务的分片集群；或
• 单节点副本集。

独立的 mongod 不受支持。迁移会在创建集合或标记 Flue 格式版本之前检查拓扑，如果部署无法运行事务则会失败。

对于本地开发，单节点副本集是一个以副本集模式启动的 MongoDB 服务器，作为单成员集初始化一次。请遵循现有安装或容器设置的说明；生产要求和操作权衡仍然与副本集相同。

事务和驱动运行器

@flue/mongodb 暴露了一个小型驱动接缝，而不是捆绑一个生产客户端。生成的 db.ts 使用所有集合操作、拓扑检查、集合和索引管理、事务和 close() 来包装官方驱动。

每个事务使用一个 ClientSession、快照读关注和多数写关注。回调操作是会话绑定的，并且是序列化的，因为驱动不支持在一个事务中并行操作。运行器使用独立的有界重试循环：它会为 TransientTransactionError 重新运行完整回调，而 UnknownTransactionCommitResult 仅重试 commitTransaction()。这避免了在只有提交结果不确定时重复应用工作。

在调整连接选项时，请保留完整的生成运行器。特别是，不要用数据库级别的集合替换事务集合，也不要移除操作队列。

迁移和索引

Flue 在服务器启动时自动调用 migrate()。在验证拓扑后，迁移会创建具有严格验证器的集合，并创建所需的索引。然后，它会检查实际验证器、验证级别和操作，以及每个所需索引的键、唯一性、部分过滤器和排序规则，然后写入格式版本。不兼容的定义和由较新 Flue 版本写入的数据会阻止启动。没有单独的迁移命令。

大值和分阶段写入

MongoDB 将 BSON 文档限制为 16 MiB。适配器会 JSON 序列化任意运行时值，并将其作为限制为 4 MiB 的不可变部分进行分阶段处理。一个简短的事务会发布已完成的代和其清单，因此大值永远不会部分可见。被放弃的分阶段代和退役的值会在稍后被收集。

图像保持 Flue 的持久化块表示，并使用相同的分阶段值路径。避免将大运行时值直接放入自定义 MongoDB 文档中；这会绕过适配器的 BSON 限制处理。

存储内容

MongoDB 存储仅追加的规范对话记录、不可变附件负载、已接受的直接和分派提交，以及恢复声明和租约。会话在智能体实例生命周期内追加；没有会话代、转录快照、按会话删除或递归会话树清理。

适配器不存储沙盒文件、外部 API 副作用、凭证或应用拥有的业务记录。

验证

构建 Node 目标并使用指向临时支持部署的 MONGODB_URL 和 MONGODB_DATABASE 启动它。确认迁移创建集合和索引，创建状态，重启 Flue，并验证状态重新加载。测试大于 4 MiB 的值以覆盖多部分分阶段。临时的独立 mongod 应该在标记格式版本之前迁移失败。不要在生产数据库上进行验证。