# @frontmcp/storage-sqlite 中文文档

规范地址：https://npmcn.com/package/%40frontmcp/storage-sqlite/

版本：1\.12\.2
npm 元数据更新时间：2026-11-14T21:11:34.409Z
中文译文更新时间：2026-11-15T15:19:39.570Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40frontmcp/storage-sqlite
原文对照：https://npmcn.com/package/%40frontmcp/storage-sqlite/?lang=original
项目主页：https://frontmcp.dev/reference/deployment/sqlite
源码仓库：https://github.com/agentfront/frontmcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：153 kB，34 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：2 个
- peer 依赖：@frontmcp/lazy-zod 1\.12\.2
- 首次发布：2026-02-13T21:40:37.126Z
- 最新版本发布：2026-11-14T21:11:34.069Z
- 近 30 天下载量：5337（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：106（近 12 个月 106 个）

## 中文简介

FrontMCP 的 SQLite 存储: 会话、背景任务、引出和流事件在一个本地文件中,没有 Redis

## 安装

```sh
npm install @frontmcp/storage-sqlite
```

也可以使用：`pnpm add @frontmcp/storage-sqlite`、`yarn add @frontmcp/storage-sqlite`、`bun add @frontmcp/storage-sqlite`

## README

# @ frontmcp/ storage-sqlite (英语)

FrontMCP的 SQLite 存储:会话,背景任务,待本地文件中的诱导和流事件,所以它们在重启后未运行Redis而幸存. 在旁边安装 `@frontmcp/sdk` 设置 `@FrontMcp({ sqlite })`; SDK装入. 在一个机器上使用:局部开发,一个单 VM 或装有音量的容器,一个 CLI 或桌面服务器,或者 `cli` 任务执行者,其工作流程共享文件。 当多个机器必须看到相同的状态时,取而代之的是使用Redis:一个SQLite文件不能跨机器共享.

[![npm](https://img.shields.io/npm/v/@frontmcp/storage-sqlite.svg)](https://www.npmjs.com/package/@frontmcp/storage-sqlite) [![License](https://img.shields.io/npm/l/@frontmcp/storage-sqlite.svg)](https://github.com/agentfront/frontmcp/blob/main/LICENSE)

## 安装

```bash
npm install @frontmcp/storage-sqlite
```

需要节点.js 24或后. `better-sqlite3` 是一种正常的依赖,所以它和包一起安装. 这是一个本地模块,在安装时下载或编译其二进制,所以在服务器运行的平台上安装(在多克图像中,运行) `npm ci` 在图像内部). 同伴依赖 `@frontmcp/lazy-zod` 来了 `@frontmcp/sdk`。 。 。 .

`@frontmcp/sdk` 仅在一个 `sqlite` 选项已设定, 因此导入 SDK 永远不会加载 `better-sqlite3`。在Cloudflare工人身上,商店在一个持久对象中运行,使用自己的SQLite数据库:见 [在 Cloudflare 持久对象中](https://npmcn.com/package/%40frontmcp/storage-sqlite/#readme-in-a-cloudflare-durable-object)其他 V8-同位素运行时间没有 SQLite; 使用 Redis 或 Upstash .

## 使用量

大多数服务器从未导入此软件包 。 将FrontMCP指向一个文件, SDK 构建商店:

```ts
import { App, FrontMcp } from '@frontmcp/sdk';

@App({ id: 'help-desk', name: 'Help Desk', tools: [] })
class HelpDeskApp {}

@FrontMcp({
  info: { name: 'help-desk', version: '1.0.0' },
  apps: [HelpDeskApp],
  sqlite: { path: './data/desk.sqlite' },
})
export default class Server {}
```

高层 `sqlite` 屏蔽背面会话、背景任务和待定的提示。 无 `path`,文件为 `<project>/dist/sessions.sqlite` 外部生产和 `~/.<info.name>/sessions.sqlite` 在生产中. `FRONTMCP_SQLITE_PATH` 覆盖两者,以及 `path` 我也一样.

要给一个子系统 自己的文件, 把它放在那里:

```ts
import { App, FrontMcp } from '@frontmcp/sdk';

@App({ id: 'help-desk', name: 'Help Desk', tools: [] })
class HelpDeskApp {}

@FrontMcp({
  info: { name: 'help-desk', version: '1.0.0' },
  apps: [HelpDeskApp],
  transport: { persistence: { sqlite: { path: './data/sessions.sqlite' } } },
  tasks: { enabled: true, runner: 'cli', sqlite: { path: './data/tasks.sqlite' } },
})
export default class Server {}
```

这个 `cli` 任务执行程序启动脱节的工人流程,所以它需要一个共享的商店: `tasks.sqlite`,顶级 `sqlite`,或 `tasks.redis`。 。 。 .

### 直接使用商店

```ts
import { SqliteSessionStore } from '@frontmcp/storage-sqlite';

const store = new SqliteSessionStore({ path: './data/sessions.sqlite', defaultTtlMs: 3_600_000 });
await store.set('session-id', { userId: 'u1' }, 60 * 60_000); // TTL in milliseconds
const session = await store.get('session-id');
store.close();
```

## 存储

| 导出 | 背对面 |
| --- | --- |
| `SqliteSessionStore` | MCP运输会议(`keyPrefix`默认值 `'mcp:session:'`· ; `defaultTtlMs`,默认1小时) |
| `SqliteTaskStore` | 背景任务:状况、结果和取消 |
| `SqliteElicitationStore` | 等待征聘请求`keyPrefix`默认值 `'mcp:elicit:'`(中文(简体) ) |
| `SqliteEventStore` | 可流式HTTP恢复的流动事件(`maxEvents`,默认为 10000; `ttlMs`,默认5分钟) |
| `SqliteKvStore` | 与 TTL 同步的密钥/ 价值存储器, 上面的存储器基于 |
| `SqliteStorageAdapter` | 同步 `StorageAdapter` 接口 `@frontmcp/utils` 覆盖同一文件( 没有发布/ 订阅) |

`SqliteStorageAdapter.keys(pattern)` 财务报告和审定财务报表 `SqliteKvStore.keys(pattern)` 匹配字母大小写, 如内存和 Redis 存储 : `keys('session:*')` 不返回 `Session:1`高达1.12.0 他们无视ASCII案件,因为他们用SQL搜索 `LIKE`,而适配器模式则失去了后鞭. 在一个适配器模式中,反斜势会像其他存储器一样使下一个字符字面化,所以 `escapeGlob()` 输出在任何地方都找到相同的密钥;在 1.12.1 中,反斜率被匹配为本身.

套件还出口 `openDatabase` 财务报告和审定财务报表 `withBusyRetry` (帮助打开文件并重试于 `SQLITE_BUSY`, (中文(简体) ), `useSqliteDriver` 财务报告和审定财务报表 `durableObjectSqlite` (a) 除 `better-sqlite3`, (中文(简体) ), [下级](https://npmcn.com/package/%40frontmcp/storage-sqlite/#readme-in-a-cloudflare-durable-object), (中文(简体) ), `deriveEncryptionKey`, (中文(简体) ), `encryptValue`, (中文(简体) ), `decryptValue` 财务报告和审定财务报表 `SqliteDecryptionError`,以及 `sqliteStorageOptionsSchema`,用于以下选项的 Zod 方案.

## 选项

每个商店都选这些选择,所以 `@FrontMcp`是因为 `sqlite`, (中文(简体) ), `transport.persistence.sqlite` 财务报告和审定财务报表 `tasks.sqlite`数字 :

| 选项 | 默认 | 页:1 |
| --- | --- | --- |
| `path` | 所需经费 | 数据库文件. 如果缺少, 它的文件夹会被创建 。 可选择在 `@FrontMcp({ sqlite })`,如上所示 |
| `encryption` | 无 | `{ secret }`: 用 AES-256-GCM 加密每个存储值, 并带有一个密钥来自 `secret`键可读 |
| `walMode` | `true` | SQLite的写作日志,为不等作家的读者 |
| `ttlCleanupIntervalMs` | `60000` | 删除过期条目的次数 |
| `busyTimeoutMs` | `5000` | 写入要等多久才能锁定另一个进程才能失败 `SQLITE_BUSY` |

一个迷失 `encryption.secret` 丢失数据,而更改后的数据会使存储的值无法读取(`SqliteDecryptionError`) (中文(简体) ).

## 业务说明

-   **备份文件.** 普通的SQLite数据库:复制,或使用 `sqlite3 .backup`。 。 。 .
-   **写头日志增加了两个文件** 旁边, `-wal` 财务报告和审定财务报表 `-shm`。复制所有三个,或检查点先.
-   **一个写作.** 多个进程可以读取文件; 写入互相等待, 最多 `busyTimeoutMs`。 。 。 .

## 在 Cloudflare 持久对象中

具有 SQLite 存储的持久对象有自己的数据库,商店可以运行在它上而不是 `better-sqlite3`这是土生土长的模块,不载在工人身上。 在创建服务器前, 导入此软件包, 把它交给 SDK , 并在持久对象的构造器中设置驱动程序 :

```ts
import { DurableObject } from 'cloudflare:workers';

import { FrontMcpInstance, registerOptionalModule } from '@frontmcp/sdk';
import * as storageSqlite from '@frontmcp/storage-sqlite';

registerOptionalModule('@frontmcp/storage-sqlite', storageSqlite);

export class HelpDeskServer extends DurableObject {
  private readonly handler: ReturnType<typeof FrontMcpInstance.createFetchHandler>;

  constructor(ctx: DurableObjectState, env: unknown) {
    super(ctx, env);
    storageSqlite.useSqliteDriver(storageSqlite.durableObjectSqlite(ctx.storage));
    this.handler = FrontMcpInstance.createFetchHandler({
      info: { name: 'help-desk', version: '1.0.0' },
      apps: [HelpDeskApp],
      events: { store: { sqlite: { path: 'help-desk.sqlite' } } },
    });
  }

  async fetch(request: Request): Promise<Response> {
    return (await this.handler)(request, this.ctx, this.env);
  }
}
```

-   **`registerOptionalModule()`** 给SDK的包裹 从工人的捆绑:, `require()` 无法到达捆绑的模块.
-   **`useSqliteDriver(durableObjectSqlite(ctx.storage))`** 让每个商店打开持久对象的数据库. `createFetchHandler()` 在其第一次请求时构建服务器,因此构建器已经足够早了. 持久对象的每个实例都会设置自己的驱动程序,一个商店永远不会得到一个先前实例打开的连接.
-   **每隔离一次.** 驱动程序被设置为整个隔离,所以在具有一个实例的持久对象类中使用(一个 id,作为 `idFromName('main')`) (中文(简体) ). 具有不同ID的实例可以共享一个孤立,每个服务器在第一次请求时打开其存储:上次的存储集打开每个实例的存储,Cloudflare拒绝 I/O(`Cannot perform I/O on behalf of a different Durable Object`),其他实例的服务器不会启动.
-   **每个 `path` 是同一个数据库**持久对象就是其中之一 此选项只命名它, 没有创建文件或文件夹 .
-   **写入运行于 `ctx.storage.transactionSync()`**,以及 `walMode` 财务报告和审定财务报表 `busyTimeoutMs` 什么都不做: 一个持久对象有一个连接, 拒绝两个 plasmas .

`useSqliteDriver()` 将任何功能从路径带入数据库中 `better-sqlite3`是因为 `Database` 商店呼叫( `SqliteDriver` 财务报告和审定财务报表 `SqliteDatabase` 类型)和 `useSqliteDriver(undefined)` 继续 `better-sqlite3`。 。 。 . `currentSqliteDriver()` 返回设置的驱动程序,如果有的话;在边缘运行时,SDK打开一个 `sqlite` 仅当一个是.

## 文档

-   [SQL 点](https://frontmcp.dev/reference/deployment/sqlite)页:1 `sqlite` 选项,文件去向、存储、锁定和加密
-   [重写](https://frontmcp.dev/reference/deployment/redis): 当多个机器共享状态时要使用的商店
-   [背景任务](https://frontmcp.dev/reference/server/tasks):任务执行者及其仓库

## 相关软件包

-   [`@frontmcp/sdk`](https://www.npmjs.com/package/@frontmcp/sdk): 装入此软件包的框架 `sqlite` 选项
-   [`@frontmcp/utils`](https://www.npmjs.com/package/@frontmcp/utils)页:1 `StorageAdapter` 接口 `SqliteStorageAdapter` 执行,以及其它存储后端

## 捐款

资料来源: [`libs/storage-sqlite`](https://github.com/agentfront/frontmcp/tree/main/libs/storage-sqlite)欢迎提出问题和拉动请求;见 [捐款额](https://github.com/agentfront/frontmcp/blob/main/CONTRIBUTING.md)。 。 。 .

## 许可证

阿帕奇2.0 (英语). 见 [自由主义](https://github.com/agentfront/frontmcp/blob/main/LICENSE)。 。 。 .

## 常见问题

### @frontmcp/storage-sqlite 是什么？

FrontMCP 的 SQLite 存储: 会话、背景任务、引出和流事件在一个本地文件中,没有 Redis

### 如何安装 @frontmcp/storage-sqlite？

在项目目录运行 npm install @frontmcp/storage-sqlite，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@frontmcp/lazy-zod（1\.12\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @frontmcp/storage-sqlite 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @frontmcp/storage-sqlite 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @frontmcp/storage-sqlite 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @frontmcp/storage-sqlite 可以商用吗？

@frontmcp/storage-sqlite 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @frontmcp/storage-sqlite 的下载量有多少？

根据 npm 官方下载统计，@frontmcp/storage-sqlite 在 2026/10/16 – 2026/11/14 这 30 天内被下载 5,337 次，日均约 178 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @frontmcp/storage-sqlite 还在维护吗？

最新版本 1\.12\.2 发布于 2026/11/15（1 天前）；至今共发布 106 个版本，其中过去 12 个月发布了 106 个；首次发布于 2026/02/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。