尧图网页设计 
DeepChat 数据落盘位置权威指南从主数据库到加密元数据、备份布局与快照导入规则【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat本文基于 DeepChat 仓库中供数据导入工具使用的参考文档>electron userData/app_db/agent.db electron userData/app_db/agent.db-wal electron userData/app_db/agent.db-shm其中agent.db是 SQLite 主数据库文件agent.db-wal与agent.db-shm是 WALWrite-Ahead Logging模式的日志与共享内存边车文件。这一点在源码中有多处直接证据databaseSecurity.ts 中DatabaseSecurityService构造函数将数据库目录拼接为path.join(app.getPath(userData), app_db)默认数据库路径为agent.dbdatabaseInitializer.ts 同样使用path.join(app.getPath(userData), app_db)作为数据库目录sync/index.ts 中SyncService.DB_PATH path.join(app.getPath(userData), app_db, agent.db)。主数据库默认开启 WAL 模式。在 connectionConfig.ts 的configureSQLiteConnection中可以看到统一的连接配置db.pragma(journal_mode WAL) db.pragma(synchronous NORMAL) db.pragma(cache_size -65536)journal_mode WAL每次连接都将主数据库置于 WAL 日志模式因此正常情况下磁盘上必然存在agent.db-wal与agent.db-shm边车文件synchronous NORMAL维持「提交在进程崩溃后仍然存活、断电可能丢失最新已提交事务但不会损坏文件」的持久性契约cache_size -65536设置 64 MiB 页缓存上限负数表示 KiB足以容纳会话级 Tape 读取所需的页面。对导入器而言理解 WAL 模式的意义在于当 DeepChat 正在运行时agent.db主文件可能并不包含最新的已提交数据最新数据可能仍然滞留在agent.db-wal中因此快照时必须把三个文件一并复制详见下文「快照与导入规则」一节。遗留数据库app_db/chat.db在早期版本中 DeepChat 使用chat.db作为主数据库。当前版本引入agent.db之后chat.db作为**遗留数据库legacy database**保留仅在存在时出现electron userData/app_db/chat.dblegacyChatImportService.ts 中旧库默认路径被定义为this.sourceDbPath sourceDbPath ?? path.join(app.getPath(userData), app_db, chat.db)该服务会在后台把旧库的conversations、messages、message_attachments、acp_sessions等表导入到新结构导入后的会话以legacy-session-前缀命名、消息以legacy-msg-前缀命名见同文件toLegacySessionId/toLegacyMessageId。因此如果你的目标是恢复当前数据优先读取agent.db只有目标环境中不存在agent.db时才回退到chat.db。数据库加密元数据database-security.jsonDeepChat 的数据库加密开关与密码存储方式不在 SQLite 文件内部而是保存在 userData 根目录下的一个独立 ElectronStore JSON 文件中electron userData/database-security.json该文件的metadata结构如下{ metadata: { version: 1, enabled: true, cipher: sqlcipher, passwordStorage: safeStorage, wrappedPassword: base64-electron-safeStorage-blob, safeStorageBackend: basic_text, lastMigrationAt: 1770000000000, lastMigrationDirection: enable } }字段含义与取值字段含义取值说明version元数据格式版本固定为1enabled数据库加密是否启用true/falsecipher加密算法固定为sqlcipherpasswordStorage密码的存储方式safeStorage系统安全存储、manual手动输入、none无wrappedPassword被系统安全存储包裹后的密码base64 编码的 ElectronsafeStorage密文 blob仅safeStorage模式存在safeStorageBackend底层安全存储后端仅 Linux 有意义例如basic_text仅在 Linux 上由safeStorage.getSelectedStorageBackend()填充lastMigrationAt最近一次加密迁移时间戳毫秒时间戳lastMigrationDirection最近一次迁移方向enable、change-password、disable对应源码在 databaseSecurity.ts 的类型定义中passwordStorage被明确约束为safeStorage | manual | noneDEFAULT_METADATA为{ version: 1, enabled: false, cipher: sqlcipher, passwordStorage: none }即默认不加密。对导入器而言读取agent.db前必须先判断该文件若enabled为false直接以普通 SQLite 方式打开agent.dbpasswordStorage此时通常为none若enabled为true需要使用 SQLCipher 兼容参数与密码打开。仓库在 connectionConfig.ts 中定义了加密兼容层ciphersqlcipher且legacy4SQLCIPHER_COMPATIBILITY_VERSION 4再通过db.key(Buffer.from(password, utf8))注入密码。使用better-sqlite3-multiple-ciphers等支持 SQLCipher 的驱动时务必设置同样的legacy4兼容参数否则可能无法解密。此外源码显示加密启用/改密/禁用采用「导出到临时库 → 校验 → 原子替换」的迁移流程migrateDatabase方法过程中会产生agent.db.migration-tmp与agent.db.migration-rollback临时文件并在启动时通过recoverInterruptedMigrationFiles自动清理或回滚。这也是下文「快照规则」中禁止删除这些临时文件的原因。默认 UserData 路径macOS / Windows / LinuxElectron 依据打包后的产品名DeepChat推导配置目录profile path除非运行时通过app.setPath(userData, ...)覆盖。三个平台的默认路径为macOS: ~/Library/Application Support/DeepChat Windows: %APPDATA%\DeepChat Linux: ~/.config/DeepChat注意事项以上只是默认值。便携版portable builds、开发构建development builds、测试环境或用户手动覆盖都可能把 userData 指向别处。例如仓库的 appMain.ts 在 e2e 测试中执行了app.setPath(userData, e2eUserDataDir)来隔离测试数据。因此导入器不应硬编码平台路径最可靠的方式是让用户在运行时提供 userData 路径或直接询问运行中的 DeepChat 实例如通过其暴露的 API/CLI 获取app.getPath(userData)的结果。同步备份Sync Backup内部布局DeepChat 的同步备份是一个 ZIP 归档其中主数据库有效载荷的路径为database/agent.db部分兼容性备份中可能还包含database/chat.db以及旧的 JSON 设置文件位于configs/下。该布局在 sync/index.ts 的ZIP_PATHS常量中有完整定义const ZIP_PATHS { agentDb: database/agent.db, chatDb: database/chat.db, appSettings: configs/app-settings.json, customPrompts: configs/custom_prompts.json, systemPrompts: configs/system_prompts.json, mcpSettings: configs/mcp-settings.json, manifest: manifest.json }导入规则当database/agent.db与database/chat.db同时存在时优先使用agent.db备份中的configs/*.json仅为兼容性保留见下文「仍在agent.db之外的关联文件」一节导入时注意备份中可能包含「仅对创建它的机器有意义」的本地密钥与路径仓库在 sync/index.ts 中定义了MACHINE_LOCAL_APP_SETTINGS_KEYScloudSyncConfig、cloudSyncSecret、agentCommandShell这些值在备份时会被剥离导入时应保留接收方机器的本地值不要用备份内容覆盖。快照与导入规则参考文档给出了一套在读取 DeepChat 数据时必须遵守的快照规则结合源码可以进一步明确每一条的底层原因DeepChat 正在运行时必须将agent.db、agent.db-wal、agent.db-shm三个文件一起复制。因为 WAL 模式下最新已提交事务可能只存在于 WAL 文件中只复制主文件会得到一份过期甚至不一致的数据。DeepChat 已关闭时单独复制agent.db通常足够但顺带复制两个边车文件也无害。高完整性导入先以只读方式打开源连接执行一次 SQLite 备份VACUUM INTO或sqlite3 backup API到临时文件再从临时文件导入而不是直接读源文件。这样可以在不干扰运行中实例的前提下拿到一致的快照。仓库自身的导入路径正是这一思路LegacyChatImportService.importFromSourceDb以{ readonly: true, fileMustExist: true }打开旧库并执行PRAGMA query_only TRUE将全部表行读入内存后立刻关闭源库句柄再进行长事务写入见 legacyChatImportService.ts。绝不删除用户配置目录中的这些文件*.migration-tmp例如agent.db.migration-tmp加密迁移的临时目标库*.migration-rollback例如agent.db.migration-rollback加密迁移的回滚副本agent.db-wal、agent.db-shmWAL 边车文件。这些文件的创建、清理与回滚决策完全由 DeepChat 自己拥有。DatabaseSecurityService.recoverInterruptedMigrationFiles()databaseSecurity.ts会在启动时检查若主库缺失而 rollback 存在则回滚恢复若两者都存在则删除冗余 rollback。导入器若擅自删除或移动这些文件可能导致数据库损坏或加密迁移状态错乱。清理遗留导入的边车文件时要谨慎仓库自身的cleanupSidecarFiles只删除空WAL 与非空 SHM非空 WAL 可能仍含有已提交帧绝不删除见 legacyChatImportService.ts。导入器可以参考这一策略但原则上更安全的做法是不碰源目录下的任何边车文件。仍在agent.db之外的关联文件DeepChat 已将绝大多数敏感配置迁入 SQLite。不过 userData 目录中仍可能保留若干轻量或兼容性 JSON 文件包括app-settings.jsoncustom_prompts.jsonsystem_prompts.jsonmcp-settings.json这些文件在源码中的使用点包括SyncService的备份路径常量sync/index.ts以及数据清除逻辑device/index.ts该处还列出了model-config.json。导入时的优先级建议Provider模型供应商、MCP、应用设置、提示词、知识库配置等当前配置一律优先从 SQLite 表导入上述 JSON 文件**仅作为遗留回退legacy fallback**使用。例如 provider/settings.ts 的注释说明在版本 0.0.10 之前模型数据存放在app-settings.json中之后才迁入数据库。导入决策速查表场景读取位置备注当前主数据DeepChat 运行中app_db/agent.db-wal-shm三者一起复制当前主数据DeepChat 已关闭app_db/agent.db边车文件可一并复制遗留数据旧版本app_db/chat.db仅当agent.db不存在或需要迁移旧库时加密判断database-security.jsonenabledfalse直接打开true需 SQLCipher legacy4同步备份database/agent.dbZIP 内agent.db与chat.db并存时优先agent.db兼容 JSONuserData 根目录下四个 JSON仅作遗留回退优先读 SQLite总结DeepChat 的用户数据布局围绕electron userData/app_db/agent.db这一中心展开配套 WAL 边车、独立的加密元数据文件与平台默认目录同步备份则以 ZIP 形式在database/路径下携带主数据库。对任何数据导入器而言核心原则只有四条优先agent.db、先查database-security.json判断加密、运行时快照要带 WAL 边车、绝不碰migration-tmp/migration-rollback/WAL 边车等由 DeepChat 管理的生命周期文件。遵循这些规则即可安全、完整地从磁盘或备份中恢复 DeepChat 的数据。【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DeepChat 数据落盘位置权威指南：从主数据库到加密元数据、备份布局与快照导入规则
DeepChat 数据落盘位置权威指南从主数据库到加密元数据、备份布局与快照导入规则【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat本文基于 DeepChat 仓库中供数据导入工具使用的参考文档>electron userData/app_db/agent.db electron userData/app_db/agent.db-wal electron userData/app_db/agent.db-shm其中agent.db是 SQLite 主数据库文件agent.db-wal与agent.db-shm是 WALWrite-Ahead Logging模式的日志与共享内存边车文件。这一点在源码中有多处直接证据databaseSecurity.ts 中DatabaseSecurityService构造函数将数据库目录拼接为path.join(app.getPath(userData), app_db)默认数据库路径为agent.dbdatabaseInitializer.ts 同样使用path.join(app.getPath(userData), app_db)作为数据库目录sync/index.ts 中SyncService.DB_PATH path.join(app.getPath(userData), app_db, agent.db)。主数据库默认开启 WAL 模式。在 connectionConfig.ts 的configureSQLiteConnection中可以看到统一的连接配置db.pragma(journal_mode WAL) db.pragma(synchronous NORMAL) db.pragma(cache_size -65536)journal_mode WAL每次连接都将主数据库置于 WAL 日志模式因此正常情况下磁盘上必然存在agent.db-wal与agent.db-shm边车文件synchronous NORMAL维持「提交在进程崩溃后仍然存活、断电可能丢失最新已提交事务但不会损坏文件」的持久性契约cache_size -65536设置 64 MiB 页缓存上限负数表示 KiB足以容纳会话级 Tape 读取所需的页面。对导入器而言理解 WAL 模式的意义在于当 DeepChat 正在运行时agent.db主文件可能并不包含最新的已提交数据最新数据可能仍然滞留在agent.db-wal中因此快照时必须把三个文件一并复制详见下文「快照与导入规则」一节。遗留数据库app_db/chat.db在早期版本中 DeepChat 使用chat.db作为主数据库。当前版本引入agent.db之后chat.db作为**遗留数据库legacy database**保留仅在存在时出现electron userData/app_db/chat.dblegacyChatImportService.ts 中旧库默认路径被定义为this.sourceDbPath sourceDbPath ?? path.join(app.getPath(userData), app_db, chat.db)该服务会在后台把旧库的conversations、messages、message_attachments、acp_sessions等表导入到新结构导入后的会话以legacy-session-前缀命名、消息以legacy-msg-前缀命名见同文件toLegacySessionId/toLegacyMessageId。因此如果你的目标是恢复当前数据优先读取agent.db只有目标环境中不存在agent.db时才回退到chat.db。数据库加密元数据database-security.jsonDeepChat 的数据库加密开关与密码存储方式不在 SQLite 文件内部而是保存在 userData 根目录下的一个独立 ElectronStore JSON 文件中electron userData/database-security.json该文件的metadata结构如下{ metadata: { version: 1, enabled: true, cipher: sqlcipher, passwordStorage: safeStorage, wrappedPassword: base64-electron-safeStorage-blob, safeStorageBackend: basic_text, lastMigrationAt: 1770000000000, lastMigrationDirection: enable } }字段含义与取值字段含义取值说明version元数据格式版本固定为1enabled数据库加密是否启用true/falsecipher加密算法固定为sqlcipherpasswordStorage密码的存储方式safeStorage系统安全存储、manual手动输入、none无wrappedPassword被系统安全存储包裹后的密码base64 编码的 ElectronsafeStorage密文 blob仅safeStorage模式存在safeStorageBackend底层安全存储后端仅 Linux 有意义例如basic_text仅在 Linux 上由safeStorage.getSelectedStorageBackend()填充lastMigrationAt最近一次加密迁移时间戳毫秒时间戳lastMigrationDirection最近一次迁移方向enable、change-password、disable对应源码在 databaseSecurity.ts 的类型定义中passwordStorage被明确约束为safeStorage | manual | noneDEFAULT_METADATA为{ version: 1, enabled: false, cipher: sqlcipher, passwordStorage: none }即默认不加密。对导入器而言读取agent.db前必须先判断该文件若enabled为false直接以普通 SQLite 方式打开agent.dbpasswordStorage此时通常为none若enabled为true需要使用 SQLCipher 兼容参数与密码打开。仓库在 connectionConfig.ts 中定义了加密兼容层ciphersqlcipher且legacy4SQLCIPHER_COMPATIBILITY_VERSION 4再通过db.key(Buffer.from(password, utf8))注入密码。使用better-sqlite3-multiple-ciphers等支持 SQLCipher 的驱动时务必设置同样的legacy4兼容参数否则可能无法解密。此外源码显示加密启用/改密/禁用采用「导出到临时库 → 校验 → 原子替换」的迁移流程migrateDatabase方法过程中会产生agent.db.migration-tmp与agent.db.migration-rollback临时文件并在启动时通过recoverInterruptedMigrationFiles自动清理或回滚。这也是下文「快照规则」中禁止删除这些临时文件的原因。默认 UserData 路径macOS / Windows / LinuxElectron 依据打包后的产品名DeepChat推导配置目录profile path除非运行时通过app.setPath(userData, ...)覆盖。三个平台的默认路径为macOS: ~/Library/Application Support/DeepChat Windows: %APPDATA%\DeepChat Linux: ~/.config/DeepChat注意事项以上只是默认值。便携版portable builds、开发构建development builds、测试环境或用户手动覆盖都可能把 userData 指向别处。例如仓库的 appMain.ts 在 e2e 测试中执行了app.setPath(userData, e2eUserDataDir)来隔离测试数据。因此导入器不应硬编码平台路径最可靠的方式是让用户在运行时提供 userData 路径或直接询问运行中的 DeepChat 实例如通过其暴露的 API/CLI 获取app.getPath(userData)的结果。同步备份Sync Backup内部布局DeepChat 的同步备份是一个 ZIP 归档其中主数据库有效载荷的路径为database/agent.db部分兼容性备份中可能还包含database/chat.db以及旧的 JSON 设置文件位于configs/下。该布局在 sync/index.ts 的ZIP_PATHS常量中有完整定义const ZIP_PATHS { agentDb: database/agent.db, chatDb: database/chat.db, appSettings: configs/app-settings.json, customPrompts: configs/custom_prompts.json, systemPrompts: configs/system_prompts.json, mcpSettings: configs/mcp-settings.json, manifest: manifest.json }导入规则当database/agent.db与database/chat.db同时存在时优先使用agent.db备份中的configs/*.json仅为兼容性保留见下文「仍在agent.db之外的关联文件」一节导入时注意备份中可能包含「仅对创建它的机器有意义」的本地密钥与路径仓库在 sync/index.ts 中定义了MACHINE_LOCAL_APP_SETTINGS_KEYScloudSyncConfig、cloudSyncSecret、agentCommandShell这些值在备份时会被剥离导入时应保留接收方机器的本地值不要用备份内容覆盖。快照与导入规则参考文档给出了一套在读取 DeepChat 数据时必须遵守的快照规则结合源码可以进一步明确每一条的底层原因DeepChat 正在运行时必须将agent.db、agent.db-wal、agent.db-shm三个文件一起复制。因为 WAL 模式下最新已提交事务可能只存在于 WAL 文件中只复制主文件会得到一份过期甚至不一致的数据。DeepChat 已关闭时单独复制agent.db通常足够但顺带复制两个边车文件也无害。高完整性导入先以只读方式打开源连接执行一次 SQLite 备份VACUUM INTO或sqlite3 backup API到临时文件再从临时文件导入而不是直接读源文件。这样可以在不干扰运行中实例的前提下拿到一致的快照。仓库自身的导入路径正是这一思路LegacyChatImportService.importFromSourceDb以{ readonly: true, fileMustExist: true }打开旧库并执行PRAGMA query_only TRUE将全部表行读入内存后立刻关闭源库句柄再进行长事务写入见 legacyChatImportService.ts。绝不删除用户配置目录中的这些文件*.migration-tmp例如agent.db.migration-tmp加密迁移的临时目标库*.migration-rollback例如agent.db.migration-rollback加密迁移的回滚副本agent.db-wal、agent.db-shmWAL 边车文件。这些文件的创建、清理与回滚决策完全由 DeepChat 自己拥有。DatabaseSecurityService.recoverInterruptedMigrationFiles()databaseSecurity.ts会在启动时检查若主库缺失而 rollback 存在则回滚恢复若两者都存在则删除冗余 rollback。导入器若擅自删除或移动这些文件可能导致数据库损坏或加密迁移状态错乱。清理遗留导入的边车文件时要谨慎仓库自身的cleanupSidecarFiles只删除空WAL 与非空 SHM非空 WAL 可能仍含有已提交帧绝不删除见 legacyChatImportService.ts。导入器可以参考这一策略但原则上更安全的做法是不碰源目录下的任何边车文件。仍在agent.db之外的关联文件DeepChat 已将绝大多数敏感配置迁入 SQLite。不过 userData 目录中仍可能保留若干轻量或兼容性 JSON 文件包括app-settings.jsoncustom_prompts.jsonsystem_prompts.jsonmcp-settings.json这些文件在源码中的使用点包括SyncService的备份路径常量sync/index.ts以及数据清除逻辑device/index.ts该处还列出了model-config.json。导入时的优先级建议Provider模型供应商、MCP、应用设置、提示词、知识库配置等当前配置一律优先从 SQLite 表导入上述 JSON 文件**仅作为遗留回退legacy fallback**使用。例如 provider/settings.ts 的注释说明在版本 0.0.10 之前模型数据存放在app-settings.json中之后才迁入数据库。导入决策速查表场景读取位置备注当前主数据DeepChat 运行中app_db/agent.db-wal-shm三者一起复制当前主数据DeepChat 已关闭app_db/agent.db边车文件可一并复制遗留数据旧版本app_db/chat.db仅当agent.db不存在或需要迁移旧库时加密判断database-security.jsonenabledfalse直接打开true需 SQLCipher legacy4同步备份database/agent.dbZIP 内agent.db与chat.db并存时优先agent.db兼容 JSONuserData 根目录下四个 JSON仅作遗留回退优先读 SQLite总结DeepChat 的用户数据布局围绕electron userData/app_db/agent.db这一中心展开配套 WAL 边车、独立的加密元数据文件与平台默认目录同步备份则以 ZIP 形式在database/路径下携带主数据库。对任何数据导入器而言核心原则只有四条优先agent.db、先查database-security.json判断加密、运行时快照要带 WAL 边车、绝不碰migration-tmp/migration-rollback/WAL 边车等由 DeepChat 管理的生命周期文件。遵循这些规则即可安全、完整地从磁盘或备份中恢复 DeepChat 的数据。【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考