Big-AGI 数据主权指南：Client-First 架构下的本地存储、Direct Connection 与自托管数据流解析-二趣网

Big-AGI 数据主权指南：Client-First 架构下的本地存储、Direct Connection 与自托管数据流解析

【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI

Big-AGI 是一款客户端优先（client-first）的 Web 应用：与传统的云端应用不同，它的 API 密钥、聊天记录与设置默认存放在你浏览器本地的 localStorage 与 IndexedDB 中，而非云服务器上。本文基于官方数据所有权文档 docs/help-data-ownership.md，结合仓库源码深入讲解 Big-AGI 的数据存储机制、三种数据流向（自部署 / 托管版 / Direct Connection 直连）、设备标识符（agi.client-token）以及安全最佳实践，读完你既能清楚理解自己的数据在哪里、如何流动，也能掌握在自托管场景下保护密钥与聊天数据的具体做法。

两种使用方式：自托管 vs 托管版

你可以通过两种方式使用 Big-AGI：

自行部署（开源版）：从仓库 clone 后自行运行，所有数据都在你的基础设施内流转，详见 docs/installation.md。
使用托管服务 big-agi.com：数据会经由 Big-AGI 的边缘网络转发到 AI 服务。

无论哪种方式，本指南的核心结论一致：Big-AGI 的后端主要扮演"路由"角色，把请求转发给 AI 服务（OpenAI、Anthropic 等），本身不存储你的数据——唯一的例外是聊天分享（chat-sharing）功能（如果使用的话）。

Client-First 的浏览器本地存储

Big-AGI 中几乎所有的聊天/密钥数据都在浏览器端处理，依赖两种标准浏览器存储机制：

Local Storage（本地存储）：存放 API 密钥、设置与配置。
IndexedDB：存放聊天历史与较大的文件。

文档提供了一段可自行验证的操作：在 Chrome 中按 F12（Windows）或 ⌘ + ⌥ + I（Mac）打开 DevTools，进入Application > Local Storage，即可看到你的设置与 API 密钥。对应地，IndexedDB 中的数据可在Application > IndexedDB中查看。

源码级佐证：从 Zustand 持久化到 IndexedDB

从源码看，聊天数据的持久化链路非常清晰。聊天会话存储 src/common/stores/chat/store-chats.ts 使用 Zustand 的persist中间件，并显式将存储后端替换为 IndexedDB 适配器：

// src/common/stores/chat/store-chats.ts persist( ..., { name: 'app-chats', ... storage: createIDBPersistStorage<ConversationsStore>(), }, )

其中的createIDBPersistStorage定义在 src/common/util/idbUtils.ts。这是一个高性能的自定义存储后端：

基于idb-keyval读写 IndexedDB；
采用截止时间驱动的批处理调度器：写入会先合并（merge window 为 321ms），最迟在 deadline（1234ms）内落盘，避免聊天过程中频繁小写入造成的性能抖动；
序列化仅在真正写盘前执行，内存中始终保留最新状态；
removeItem刻意不实现——数据以"只增不删"的方式留在本地。

仓库中各持久化 store 使用的 key 名称也能让你在浏览器里直接对应查找：app-chats（聊天）、app-folders（文件夹）、app-models（模型配置）、app-metrics（指标）、app-ai-preferences（AI 偏好）、app-device（设备标识）、app-ui（界面设置）、app-ux-labs（实验室功能）。

此外，src/common/util/storageUtils.ts 提供了requestPersistentStorageSafe()：通过navigator.storage.persist()向浏览器申请持久化存储，防止 IndexedDB 内容被浏览器在存储压力下自动清除，并可调用navigator.storage.estimate()输出当前用量与配额（以 MB 为单位）。这意味着在支持的浏览器上，Big-AGI 会主动降低聊天数据被意外回收的风险。

这对你意味着什么

数据存放在浏览器中，直接带来以下特性与注意点：

数据只存在于单台设备/单个浏览器，不跨设备同步（除非启用 Sync）；
清除浏览器数据会抹掉你的聊天记录——务必做好备份；
任何使用你浏览器的人都能看到你的聊天与密钥；
自行运行服务器需要一定的技术能力。

已登录用户的 Sync 与设备标识符

Sync：可选的服务器端复制

在 big-agi.com 拥有账号并主动选择开启 Sync（Pro 功能）的用户，其实体数据（如对话与 Persona）会被复制到服务器端，以支持多设备访问。服务器端数据通过行级安全（Row Level Security, RLS）按用户隔离，确保其他用户无法访问你的同步数据。Sync 完全可选——不开启时，所有数据都留在本地浏览器中。

设备标识符（Device Identifier）

登录后，Big-AGI 会保留一个设备标识符，用于区分你的各台设备，以支持可选的 Sync 并将设备列在你的账号下。其关键特性（文档原文要点）：

由服务器签发（随机 UUID），存储在持久化的一方 httpOnly Cookie（名为agi.client-token）中——页面脚本既不能创建它，也无法读取它；
标识的是你的客户端：每个浏览器一个，同一台机器上的第二个浏览器或已安装应用会被视为另一台设备；
取代了旧的 localStorage 机制（源码见 src/common/stores/store-client.ts）；
不会为未登录访客设置，也从不用于跟踪、广告、分析或遥测；
通过行级安全隔离到你的账号，其他用户不可见；
属于服务器设置的 Cookie，只有清除 cookies/站点数据时才会重置。

从源码看，旧机制src/common/stores/store-client.ts在本地维护一个app-device持久化 store，其中localDeviceId由 6 位随机字符 + 4 位时间戳字符构成（_generateLocalDeviceIdentifier()，格式如a7f3g9h812），并且只在启用 Sync 功能时才会上传；新的agi.client-tokenCookie 机制则是服务器签发的 UUID，从根本上把"设备身份"与页面可读的本地存储解耦，进一步降低了被脚本窃取的可能。

数据如何流动：三组件模型

AI 交互（聊天、AI 标题、文本转语音、浏览等）在 Big-AGI 中流经三个组件：

浏览器（客户端/已安装 App）——本地存储你的密钥与数据；
后端（路由服务器）——把请求转发给 AI 服务；
AI 服务——真正执行 AI 处理的地方。

自部署版本：数据在你的基础设施内

自行部署时你运行服务器。数据只在你发起 AI 请求时才会离开你的环境。密钥和聊天都在你的掌控之下、流经你自己的代码，并按请求逐个发送到上游 AI 服务。

托管版本：经由 big-agi.com 边缘网络

使用 big-agi.com 时，你的数据经由托管的 Big-AGI 边缘网络到达 AI 服务：密钥和聊天按请求逐个经过 Big-AGI 的边缘网络，再发送到上游 AI 服务。

Direct Connection：浏览器直连 AI 服务

大多数 AI 服务在其Advanced（高级）设置中提供了Direct Connection（直连）开关。启用后，浏览器将直接调用 AI 提供商的 API，完全跳过 Big-AGI 服务器。

收益

没有 4.5MB 上传限制：Vercel 的 body 大小上限不再适用，更大的附件和长提示词可以正常通过；
没有 300 秒超时：Vercel 的函数超时不再适用，长时间运行的生成可以持续流式输出；
更私密：连接元数据（IP、时间戳、边缘区域、Vercel 遥测）不再被 Big-AGI 边缘服务器观测到。

代价

下行带宽略增：流量经过 Big-AGI 边缘时，重复的流式帧会被压缩；直连时流式数据由提供商原样到达。

启用条件（两者缺一不可）

API 密钥必须设置在浏览器端（客户端），而不是服务器环境变量。仅配置服务器密钥的部署无法使用直连，因为浏览器手里没有可发送的凭证；
AI 服务必须允许CORS（浏览器源请求）。大多数主流提供商都支持，Big-AGI 会为其设置所需的额外请求头。

只要提供商允许，Direct Connection 在速度、限制与隐私上都是净收益。

源码级佐证：客户端直连的执行路径

直连能力在源码中有完整的实现脉络。在 src/modules/llms/llm.client.ts 中，模型更新逻辑会先检查传输访问配置是否带有clientSideFetch标记，若存在则动态加载llm.client.direct-listModels中的clientSideListModels直接在浏览器内执行模型列表获取，否则回退到经服务器 tRPC 的路径：

// src/modules/llms/llm.client.ts（节选） let clientSideListModels: ... | undefined; if (!!transportAccess && typeof transportAccess === 'object' && (transportAccess as any).clientSideFetch) try { clientSideListModels = (await import('./llm.client.direct-listModels')).clientSideListModels; } catch (error) { ... } // LLMs [CSM] Direct Execution if (clientSideListModels) models = await clientSideListModels(transportAccess); // LLMs tRPC Execution（经服务器） else models = (await vendor.rpcUpdateModelsOrThrow(transportAccess)).models;

其中 src/modules/llms/llm.client.direct-listModels.ts 的模块注释明确写道："Client-side LLM model listing - Direct in-browser execution without client <--> tRPC-server"，即完全绕开客户端与服务器之间的 tRPC 通道。

各服务商的接入层也都有对应的标记与请求头处理，例如：

src/modules/llms/server/anthropic/anthropic.access.ts 中定义了可选的clientSideFetch字段，并在启用时附带ANTHROPIC_HEADERS_CORS请求头；
src/modules/llms/server/gemini/gemini.access.ts、src/modules/llms/server/openai/openai.access.ts 等同样声明了clientSideFetch；
在 src/modules/llms/vendors/ 下，各家供应商的*.vendor.ts会依据用户配置（如!!partialSetup?.csf）计算clientSideFetch值，并在*ServiceSetup.tsx中提供对应的开关 UI。

从代码结构可以推断：直连并非"全局一刀切"，而是逐服务商、逐配置生效的开关——这正对应文档所说的"位于服务 Advanced 设置中的 Direct Connection 开关"。

安全最佳实践

基础安全：

绝不分享 API 密钥；
不要使用公用电脑；
一次性会话使用隐私浏览模式；
使用可信网络；
备份你的数据（尤其因为清除浏览器数据即等于删除聊天记录）。

自行运行服务器时：

使用环境变量配置 API 密钥（避免硬编码进代码或 UI 中明文暴露）；
运行在可信基础设施上；
保持安装持续更新。

小结（TL;DR）

你的 API 密钥和聊天记录留在浏览器中；服务器只负责把请求转发给 AI 服务；
需要便利性可用 big-agi.com，需要完全控制权可自行部署；
开启 Direct Connection 可让浏览器直连 AI 提供商，进一步减少服务器参与；
启用 Sync 后数据才会上传服务器端，且通过行级安全（RLS）按用户隔离；
由于数据只在单浏览器本地，请务必养成备份习惯，并在共享设备上保持警惕。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析