Valkey

快速开始

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

flue add database valkey

概述

Valkey 蓝图会安装 @flue/redis 和官方 Redis redis 客户端，在项目的源代码根目录创建 db.ts，并遵循项目现有的 VALKEY_URL 密钥约定。它不会修改部署配置，因为持久化和恢复设置仍然由 Valkey 部署管理。

主要生成的适配器连接客户端并将 Flue 数据库操作转换为 Valkey 支持的 Redis 协议命令：

import { redis } from '@flue/redis';
import { createClient } from 'redis';

const client = createClient({ url: process.env.VALKEY_URL });
await client.connect();

export default redis({
  command: (command, args = []) => client.sendCommand([command, ...args.map(String)]),
  eval: (script, keys, args = []) => client.eval(script, { keys, arguments: args.map(String) }),
  close: () => client.close(),
});

此简化版本省略了生成的流水线辅助函数，它会批量处理命令并拒绝任何 Error 结果。Flue 在 Node 构建期间发现适配器，在服务器启动时检查并迁移其 Valkey 命名空间，并持久化规范的智能体对话、不可变附件和已接受的提交，以便它们在 Flue 进程重启后得以保留。跨 Valkey 服务器丢失的持久性取决于部署的 AOF 或快照配置。

配置

蓝图会安装 @flue/redis 和官方 Redis redis（node-redis）客户端，然后在源代码根目录创建 db.ts。Valkey 实现了此适配器使用的 Redis 协议和命令。此支持特定于 Valkey，并不意味着支持每个 Redis 兼容的提供商。

这是一个 Node.js 适配器。Cloudflare 目标使用 Durable Object SQLite 并拒绝 db.ts。

将 VALKEY_URL 设置为持久化独立 Valkey 服务器或托管单分片端点。Valkey Cluster 和仅缓存配置不受支持。配置 maxmemory-policy noeviction，加上具有显式 fsync 策略的 AOF 和/或适合你恢复目标的持久化快照。noeviction 避免静默驱逐；它不会使已确认的写入在服务器丢失后保持持久。

规范运行器使用 node-redis 通过 Valkey 的 Redis 协议：

import { redis } from '@flue/redis';
import { createClient } from 'redis';

const client = createClient({ url: process.env.VALKEY_URL });
await client.connect();

export default redis({
  command: (command, args = []) => client.sendCommand([command, ...args.map(String)]),
  eval: (script, keys, args = []) =>
    client.eval(script, {
      keys,
      arguments: args.map(String),
    }),
  pipeline: async (commands) => {
    const multi = client.multi();
    for (const { command, args = [] } of commands) multi.addCommand([command, ...args.map(String)]);
    const results = await multi.exec();
    for (const result of results) if (result instanceof Error) throw result;
    return results;
  },
  close: () => client.close(),
});

检查和隔离

启动时，inspectServer 使用 CONFIG GET，回退到 INFO，以验证 Cluster 已禁用且驱逐策略为 noeviction。当任一要求无法验证时，启动会失败。仅当托管单分片提供商拒绝这两个命令且你已独立验证配置时，才设置 inspectServer: false。

使用专用 Valkey 数据库或传递稳定、唯一的 keyPrefix 作为适配器的第二个参数。默认值是 flue。更改它会选择单独的命名空间；它不会移动现有键。

迁移和存储数据

Flue 在启动时运行 migrate()。它会幂等地初始化格式版本元数据，并拒绝来自不受支持的更新格式的数据；没有单独的迁移命令。

Valkey 存储仅追加的规范对话记录和压缩事实、不可变附件负载、已接受的提示和分派，以及恢复声明和租约。它不存储会话转录快照、沙盒文件、外部 API 副作用、密钥或应用业务数据。

验证持久性

构建 Node 目标，使用临时正确配置的 Valkey 启动它，创建状态，重启 Flue，并确认状态重新加载。另外测试选定的 AOF 或快照恢复过程：重启 Flue 并不能证明 Valkey 在服务器丢失后得以保留。