企业官网建设流程全解析

Flue + Valkey 高速KV存储实战：新手完整的 Agent 持久化教程

【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue

Flue 是一个用 TypeScript 编写的沙箱 Agent 框架（The sandbox agent framework），而 Valkey 是兼容 Redis 协议的高速 KV（键值）存储。本教程带你用一条命令把 Flue 的 Agent 会话、附件和任务提交持久化到 Valkey，让 AI Agent 在进程重启、机器故障后依然"失忆不掉"。🚀

为什么选 Valkey 做 Flue 的持久化 KV 存储？

Flue 中的 Agent 会话是一串只追加的对话流（用户消息、模型输出、工具调用结果）。如果不配置外部数据库，Flue 默认跑在内存 SQLite 上——重启一次，全部丢失。

Valkey 作为 Redis 的现代开源分支，为 Flue 提供了理想的高速 KV 存储底座：

• ⚡️内存级读写：Agent 每轮对话都要读回放整条对话流，Valkey 的微秒级延迟让"重建上下文"几乎零开销
• 🔁多副本共享：多个 Node 进程可共享同一份会话状态，故障时替换进程能恢复已接受的工作
• 🧩零绑定驱动：官方@flue/redis适配器不捆绑任何客户端，你自己的连接池、TLS、凭据全权掌握（Valkey 完整实现了该适配器用到的 Redis 协议命令）

⚠️ 注意：Flue 不支持 Valkey Cluster，也要求禁止淘汰策略（noeviction）——缓存型部署可能悄悄丢掉已确认的工作，官方明确不支持。

Flue 在 Valkey 里存什么？

先建立一个正确预期：Flue 的数据库只存运行时状态，不存你的业务数据。

Lua 脚本负责把准入、租约、生命周期转换串行化，保证并发下的一致性——这些细节都在 packages/redis/README.md 中有详细说明。

一键接入：flue add database valkey 三步走

第 1 步：获取项目并运行蓝图命令

克隆 Flue 仓库作为学习项目：

git clone https://gitcode.com/GitHub_Trending/flue1/flue

在 Flue 项目的终端或编码助手中执行一条命令，官方蓝图会自动安装@flue/redis和官方redis客户端，并生成db.ts：

flue add database valkey

该命令背后应用的是 blueprints/database--valkey.md 这份实现指南——它是一份给 AI 编码助手看的 Markdown 蓝图，而非包安装器。

第 2 步：确认生成的 db.ts 适配器

生成的 src/db.ts 核心就是把 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(), });

Flue 通过约定自动发现db.ts（从.flue/、src/或项目根目录查找），vite dev、vite build、flue run都会把它接入启动流程。适配器实现了command/eval/pipeline三个原语，类型定义见 packages/redis/src/redis-runner.ts。

第 3 步：配置 VALKEY_URL

只需一个环境变量：

从你的密钥系统读取该变量，切勿把连接串写进代码。本地开发时flue run默认会加载项目的.env文件。🔑

Valkey 部署配置速查清单

在把VALKEY_URL指向生产环境之前，对照这份清单检查 Valkey 部署：

• ✅持久化模式：启用 AOF 并设置显式 fsync 策略，和/或可持久化的 RDB 快照。noeviction只是防淘汰，不等于写持久
• ✅淘汰策略：maxmemory-policy noeviction
• ❌禁用 Cluster：单分片即可，多分片不是 Flue 的键空间设计目标
• ✅内存余量：为最大的一次暂存"代"（generation）及其索引预留空间，内存耗尽的 Valkey 即使noeviction也不可写

启动时自动迁移与 keyPrefix 命名空间隔离

Flue 在服务启动时自动调用适配器的migrate()——它会幂等地初始化格式版本元数据键，并拒绝被更新的、不支持的 Flue 版本写入过的数据（宁可拒绝启动也不损坏状态）。没有任何手动迁移命令要跑。✨

启动时inspectServer还会自动用CONFIG GET（失败则退回INFO）验证 Cluster 已关闭、淘汰策略为noeviction，验证不过直接启动失败——把配置错误挡在最早期。只有托管服务商同时禁用这两条命令、且你已独立核实配置时，才设置inspectServer: false。

多应用共享一个 Valkey 实例？传一个稳定唯一的keyPrefix（默认flue）即可隔离命名空间。注意：改前缀不会迁移旧数据，它只是把 Flue 指向一个全新空命名空间。

三步验证持久化是否真的生效

1. 构建启动：对 Node 目标执行vite build并启动，确认migrate()成功、db.ts被正确发现
2. 重启重载：用一次性、配置正确的 Valkey 实例，创建会话状态 → 重启 Flue 服务 → 确认状态完整恢复
3. 灾难演练：单独测试你选择的 AOF/快照恢复流程。记住：重启 Flue 只证明进程级持久，不能证明 Valkey 服务器故障后的存活

常见问题速答

Q：Cloudflare 部署能用 Valkey 适配器吗？不能。该适配器是 Node.js 专属；Cloudflare 目标自动使用 Durable Object 内置 SQLite，构建时会直接拒绝db.ts。

Q：所有 Redis 兼容服务都能用吗？不行。官方蓝图特指 Valkey，不推断支持其他所谓 Redis 兼容服务。

Q：Valkey 能当 Flue 的业务数据库吗？不能。它只存 Agent 运行时状态；你的业务数据请存到自己的数据库里，Flue 只会记录"工具被调用过、返回了什么"。

Q：换 keyPrefix 后旧数据去哪了？留在原命名空间不动，Flue 只是开始使用新前缀的空空间。

小结：Flue + Valkey 持久化落地清单

至此，你的 Flue Agent 已经拥有高速 KV 存储加持的持久记忆：会话流、附件、提交租约全部安全落盘，重启不丢、故障可恢复。下一步建议阅读 apps/docs/src/content/docs/guide/durability.md 了解中断后恢复具体重放了什么，或浏览 packages/redis/src/redis-adapter.ts 看看 Lua 脚本如何守护并发一致性。🎉

【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue