Flue + LibSQL/Turso 实战教程：边缘数据库上 Agent 状态持久化的完整指南

Flue LibSQL/Turso 实战教程边缘数据库上 Agent 状态持久化的完整指南【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flueFlue 是一个沙箱化的 Agent 框架它通过 LibSQL 与 Turso托管版 libSQL为你的 Agent 提供持久化存储对话流、附件与任务提交状态都能跨进程重启、跨副本恢复。本教程面向新手带你用一条命令完成 LibSQL/Turso 数据库接入理解 Flue 到底存了什么、为什么重启后 Agent 还记得之前聊过什么。为什么 Agent 需要持久化没有数据库时Flue 默认跑在内存数据库上功能一切正常但一重启就全部丢失——所有对话、已接受的任务、持久化状态统统归零。开发时无所谓生产环境就不行了。接入 LibSQL/Turso 后Flue 会在数据库里维护三类运行时状态详见 数据库指南规范对话流每段对话是一条只追加的记录流用户消息、助手输出、工具调用、压缩记录是恢复的唯一事实来源已接受的提交提示词或dispatch(...)任务在接受时先落库再执行进程中断后可恢复而非静默丢失持久化状态usePersistentState写入的数据随对话流保存重启后仍在。注意Flue只存运行时状态你的业务数据订单、工单、客户信息请放在自己的表里。快速开始一条命令接入 LibSQL在项目根目录执行flue add database libsql这条命令会自动安装flue/libsql与官方libsql/client生成一个db.ts文件并把适配器接入生成的 Node 服务。Flue 在构建时按约定发现该文件优先级.flue/→src/→ 项目根目录无需手写任何迁移脚本——启动时migrate()会自动、幂等地创建flue_*表。生成的 db.ts 核心逻辑是把你的libsql/client客户端包进一个runnerquery执行 SQL、transaction单个写事务内提交/回滚、close关闭连接。完整示例见 blueprints/database--libsql.md。本地开发只需一个环境变量变量用途LIBSQL_URL必填——本地文件file:./data/flue.db或自建 libSQL 服务http://host:8080flue run默认读取项目.envvite dev与构建产物则读取 shell 环境变量。不要硬编码连接串。三种连接方式怎么选同一个flue/libsql适配器改createClient配置即可切换目标完整对照表见 libSQL 生态文档部署形态推荐配置本地开发 / 单机 Node 部署file:本地 SQLite 文件自托管 libSQL 服务sqldhttp://127.0.0.1:8080服务端序列化写入低延迟读 远端写内嵌副本本地file:syncUrl指向远端托管、带副本的 SQLite直接用 Turso见下节⚠️并发小坑本地file:数据库遇到重叠的异步写入可能报SQLITE_BUSY。Flue 生成的 runner 会用 Promise 链把单进程内的操作串行化但多进程写同一个文件不在保障范围内——这种场景请上自建服务或 Turso。升级到 Turso托管、可复制的边缘数据库Turso 就是托管版 libSQL复用同一个适配器。先用 Turso CLI 建库取凭证turso db create flue-agents turso db show --url flue-agents # → TURSO_DATABASE_URL turso db tokens create flue-agents # → TURSO_AUTH_TOKEN然后在项目里执行flue add database turso只需额外提供TURSO_DATABASE_URL和TURSO_AUTH_TOKEN两个环境变量。相比本地文件Turso 的优势在于写入在服务端序列化没有SQLITE_BUSY问题、多副本可共享对话状态进程替换后能恢复已接受的工作。如果读延迟敏感可启用内嵌副本本地 SQLite 文件与远端保持同步读打本地磁盘、写转发 Turso——只需给客户端加上syncUrl其余代码不变。详见 Turso 生态文档 与 blueprints/database--turso.md。常见问题排查清单Cloudflare 目标报db.ts错误正常现象——Cloudflare 目标自动使用 Durable Object SQLite构建时直接拒绝db.ts无需任何配置。重启后表不见了不会。migrate()幂等新库首次启动自动建表老库重启直接复用若数据库由更新版本的 Flue 写入服务会拒绝启动而不是损坏数据。多副本能双主吗共享数据库让副本共享状态、让替代进程恢复工作但每段对话仍需要恰好一个存活的 Node 属主不是 active-active 扩容。测错库了永远不要用生产库做测试。延伸阅读适配器包源码与说明packages/libsql/通用数据库适配器蓝图blueprints/database.md项目布局与db.ts约定guide/database.md想拿到完整源码自行研究执行git clone https://gitcode.com/GitHub_Trending/flue1/flue即可。按照这套流程你的 Flue Agent 从今天起重启不掉线、扩副本不丢单、本地到边缘一套代码通吃 【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考