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

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

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

Flue 是一个沙箱化的 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客户端包进一个"runner"：query（执行 SQL）、transaction（单个写事务内提交/回滚）、close（关闭连接）。完整示例见 blueprints/database--libsql.md。

本地开发只需一个环境变量

变量	用途
`LIBSQL_URL`	必填——本地文件`file:./data/flue.db`或自建 libSQL 服务`http://host:8080`

flue run默认读取项目.env；vite dev与构建产物则读取 shell 环境变量。不要硬编码连接串。

三种连接方式怎么选？

同一个@flue/libsql适配器，改createClient配置即可切换目标（完整对照表见 libSQL 生态文档）：

部署形态	推荐配置
本地开发 / 单机 Node 部署	`file:`本地 SQLite 文件
自托管 libSQL 服务（`sqld`）	`http://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 扩容。
测错库了？永远不要用生产库做测试。