Claude Code Router 配置存储深入解析config.sqlite 的位置、迁移机制与安全操作指南【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-routerconfig.sqlite 是 Claude Code RouterCCR桌面应用维护运行时配置的 SQLite 数据库也是判断“当前配置到底生效在哪”的关键。本文将以官方文档 configuration-file.md 为骨架结合仓库源码app-paths.ts、constants.ts、config-repository.ts、entrypoint.sh讲清楚各平台数据库默认位置、Docker 环境的数据持久化方式、旧版config.json的一次性迁移语义以及如何在安全前提下完成备份与修改——读完你既能快速找到自己的配置数据库也能理解 CCR 内部“JSON 时代 → SQLite 时代”的演进逻辑。背景CCR 的运行时配置为什么存放在 SQLiteCCRClaude Code Router是一个“本地 AI Agent 控制面”负责在多个模型 Provider 之间路由请求、编排工具。与很多仅用单个 JSON 文件存配置的工具不同CCR 的运行时配置统一存放在一个 SQLite 数据库文件中即config.sqlite。从源码看配置数据库文件的常量在 constants.ts 中定义export const APP_CONFIG_DB_FILE path.join(CONFIGDIR, config.sqlite);而CONFIGDIR由 app-paths.ts 按平台解析export function resolveRuntimeConfigDir(): string { if (process.platform win32) { return path.join(resolveRuntimeAppPath(appData), APP_STORAGE_NAME); } return path.join(resolveRuntimeAppPath(home), .${APP_STORAGE_NAME}); }其中APP_STORAGE_NAME固定为claude-code-routerapp-paths.ts。也就是说配置目录的命名规则是“家目录下的隐藏目录”或“系统 AppData 目录下的应用目录”这也是官方文档默认位置表格的代码来源。各平台默认位置一览官方文档给出的默认位置如下这三行也是排查问题时的“标准答案”运行环境配置数据库默认路径macOS / Linux~/.claude-code-router/config.sqliteWindows%APPDATA%\claude-code-router\config.sqliteDocker/data/.claude-code-router/config.sqlitemacOS / Linux家目录下的隐藏目录在非 Windows 平台配置目录固定在家目录下的~/.claude-code-router不受XDG_CONFIG_HOME影响。这一点与许多遵循 XDG 规范的工具不同属于 CCR 自己的约定即使你在 Linux 上设置了XDG_CONFIG_HOME配置仍然落在~/.claude-code-router/config.sqlite。Windows优先使用%APPDATA%在 Windows 上配置目录解析为appData下的claude-code-router。appData的取值逻辑见 app-paths.tsfunction fallbackAppDataDir(): string { if (process.platform win32) { return process.env.APPDATA || process.env.LOCALAPPDATA || (process.env.USERPROFILE ? path.join(process.env.USERPROFILE, AppData, Roaming) : path.join(os.homedir(), AppData, Roaming)); } return process.env.XDG_CONFIG_HOME || path.join(os.homedir(), .config); }即依次尝试环境变量APPDATA→LOCALAPPDATA→USERPROFILE\AppData\Roaming最终得到%APPDATA%\claude-code-router\config.sqlite。历史版本遗留目录Windows 上的“Claude Code Router”目录需要特别注意的是 Windows 上存在一个历史遗留配置目录。源码中保留了对%APPDATA%\Claude Code RouterAPP_NAMEClaude Code Router带空格目录的兼容处理constants.tsexport const LEGACY_WINDOWS_CONFIGDIR path.join(resolveRuntimeAppPath(appData), APP_NAME); export const LEGACY_WINDOWS_CONFIG_FILE path.join(LEGACY_WINDOWS_CONFIGDIR, config.json);并且在模块加载时会把旧目录中的内容按“仅复制缺失项”的方式并入新目录constants.tsif (process.platform win32) { copyMissingDirectoryContents(LEGACY_WINDOWS_CONFIGDIR, CONFIGDIR, Windows app data directory); }copyMissingDirectoryContents使用cpSync(source, target, { errorOnExist: false, force: false, recursive: true })即不会覆盖新目录下已存在的文件实现细节见 migration.ts。因此如果你升级自较早的 Windows 版本新配置库位于%APPDATA%\claude-code-router\旧数据会被自动带过来。提示如果你在磁盘上找不到config.sqlite请先确认自己是否属于“老版本迁移”场景——旧版可能只生成了config.json位于~/.claude-code-router/config.jsonmacOS/Linux或%APPDATA%\Claude Code Router\config.jsonWindows 旧目录。Docker 环境HOME/data与整目录持久化官方文档特别强调Docker 镜像将HOME设置为/data因此配置数据库位于/data/.claude-code-router/config.sqlite。这一行为在 entrypoint.sh 中可以看到完整链路CCR_DATA_DIR${CCR_DATA_DIR:-/data} ... export HOME${CCR_DATA_DIR} export CCR_DATA_DIR ... CONFIG_DIR${HOME}/.claude-code-router CONFIG_FILE${CONFIG_DIR}/config.json APP_CONFIG_DB_FILE${CONFIG_DIR}/config.sqlite mkdir -p ${CONFIG_DIR} ${CONFIG_DIR}/app-data /run/nginx /var/lib/nginx /var/log/nginx由于路径解析逻辑是HOME.claude-code-router一旦HOME/dataconfig.sqlite自然落在/data/.claude-code-router/下。同时入口脚本会预先创建app-data子目录因为配置目录并不是孤立的——它还承载着网关运行需要的其他数据。必须持久化整个/data而不是单个文件文档要求“持久化完整的/data目录以保证配置数据库和相关文件都被保存”。从 docker/README.md 可以看到容器内数据目录的真实全貌/data/.claude-code-router/ ├── config.sqlite ├── gateway.config.json ├── app-data/ │ ├── api-keys.sqlite │ ├── request-logs.sqlite │ ├── usage.sqlite │ └── certs/ ├── profiles/ └── bin/config.sqlite主配置数据库本主题核心gateway.config.json网关运行时生成文件app-data/历史遗留的 API 密钥库、请求日志库、用量统计库、代理/系统级证书certs/等。仓库根目录的 docker-compose.yml 正是通过命名卷挂载整个/data实现持久化volumes: - ccr-data:/data这里有一个经常踩坑的点重建容器后“配置消失”绝大多数是因为/data没有被正确挂载或换用了新的空卷docker compose down --volumes会连同数据卷一起删除。确认容器使用的还是同一个ccr-data卷或同一 bind-mount 路径即可。此外入口脚本还有一个细节首次启动时若config.json与config.sqlite均不存在会先写一份最小化的遗留版config.json作为引导entrypoint.sh当 UI 保存过设置后SQLite 便成为权威来源详见下一节。默认情况下每次容器启动还会把配置中的监听地址与routerEndpoint同步到 Docker 对外地址CCR_DOCKER_SYNC_PUBLIC_ENDPOINT控制见 docker/README.md。生效方式SQLite 是权威来源config.json只迁移一次理解“生效方式”是使用 CCR 配置能力的关键。官方文档的表述可以拆成三条事实运行时配置存储在 SQLite 中旧版config.json只在“没有 SQLite 配置”时作为一次性迁移来源被读取迁移完成后继续编辑config.json不会影响当前配置。从代码看“一次性迁移”在 config-repository.ts 中CCR 明确登记了三类需要归档的遗留 JSON 配置文件const legacyJsonConfigFiles [ LEGACY_ACTIVE_CONFIG_FILE, // 当前配置目录下的 config.json LEGACY_WINDOWS_CONFIG_FILE, // Windows 旧目录 config.json LEGACY_CONFIG_FILE // 家目录 .claude-code-router/config.json ];当 SQLite 配置库被创建并完成 schema 初始化后这些遗留 JSON 会被读取、备份并最终清理archiveLegacyJsonConfigFilesdrainLegacyCleanup见 config-repository.ts 与 config-repository.ts。整个流程带有“安全网”设计迁移前会先计算遗留文件的 SHA-256将内容存入数据库内置的legacy_storage_backups备份表再登记到legacy_storage_cleanup清理队列真正删除前会再次比对 SHA-256若文件在“读取”与“清理”之间发生变化且无对应备份则保留源文件并等待下次迁移重试绝不误删用户数据由于迁移只执行一次SQLite 一旦写入成功并记录迁移 ID之后你对config.json的任何编辑都只是改一个“档案文件”不再进入当前运行配置。Docker 场景下的一致行为Docker 入口脚本同样贯彻了“SQLite 优先”的语义docker/README.md首启引导 JSON 只在没有任何配置时生成一旦 UI 保存过设置SQLite 即成为权威。容器每次启动的“端点同步”也是分别处理 JSON 与 SQLite 两种情况entrypoint.sh 中的syncJsonFile与syncSqliteConfig。配置库的内部表结构为方便你理解“配置到底以什么形态存在”从 config-repository.ts 可以看到首次建库时创建的几张核心表表用途app_config主配置键值表key/value_json/updated_at默认应用配置以default为键api_keysCCR 客户端 API Keyencrypted_keyencryptionlimits_jsonruntime_state各类运行时状态如 onboarding 完成时间等config_schema_migrations迁移记录防止迁移重复执行legacy_storage_backups/legacy_storage_cleanup遗留 JSON / SQLite 文件的备份与延迟清理队列因此一个config.sqlite内实际上同时管理着“配置”“客户端密钥”“运行时状态”三类数据这也是为什么文档反复强调不要在运行时直接编辑数据库。不要在运行时直接编辑config.sqliteWAL 模式与正确改法文档给出的操作红线是修改配置请使用桌面 UI或在Settings中导出备份不要在 CCR 运行时直接编辑config.sqlite同一目录下还存在config.sqlite-wal与config.sqlite-shm两个配套文件编辑数据库时必须一并考虑。为什么会同时出现-wal与-shm文件SQLite 在 CCR 中被显式配置为WALWrite-Ahead Logging模式见 config-repository.tsfunction configureSqliteDatabase(database: SqlDatabase): void { database.pragma(journal_mode WAL); database.pragma(synchronous NORMAL); database.pragma(busy_timeout 5000); }在 WAL 模式下写入先追加到config.sqlite-wal随后才周期性地 checkpoint 回主文件config.sqlite-shm则是共享内存索引文件用于多连接协调。带来的实际影响只复制config.sqlite主文件往往得到不完整/不一致的快照部分最新事务还在-wal里在进程运行时用外部工具改写主文件极易损坏数据库因为 WAL 与主文件之间的状态会对不上直接删除-wal/-shm同样危险可能丢失尚未 checkpoint 的事务。所以请牢记“数据三件套”是一个整体。如果你确实需要文件级备份最稳妥的顺序是先停止 CCR或至少让写入完全静止再同时复制config.sqlite、config.sqlite-wal、config.sqlite-shm。恢复时也应整体放回不要把旧备份覆盖到一个仍在运行、还有新 WAL 数据的目录上docker/README.md 对此有同样告诫。推荐的配置修改路径CCR 提供的受支持改法本质上都走同一条代码路径——config-repository.ts 中的replacePersistedAppConfig/replacePersistedConfigSnapshot/replaceApiKeys等方法在事务内完成写入并刷新文件权限桌面/浏览器管理 UICCR 的管理界面桌面 App 或 Docker 镜像通过 Nginx 提供的 Web UI会把用户操作序列化为对app_config/api_keys的替换写库Settings → Export data 导出备份这是官方推荐的应用级备份手段见 docker/README.md。Docker 升级/迁移前先执行导出比手工拷贝文件更安全网关/管理 RPC若以 Docker 等模式远程管理应通过认证的管理 RPC 修改而不是直接进容器改库文件。敏感性与文件权限配置库中保存的是 Provider 凭据与 CCR 客户端 Key 等机密。源码在创建目录与每次写入后都会执行权限收紧config-repository.ts 与 config-repository.ts配置目录权限设为0o700主库文件、-wal、-shm三个文件权限均被设为0o600secureDatabaseFilePermissions。也就是说非当前系统用户无法读取配置内容。对应的任何配置数据库的备份都必须按“包含密钥的敏感数据”对待不要放进公开仓库或不可信存储。常见问题排查速查结合上面的机制把高频疑问整理如下现象原因与解法找不到config.sqlite先确认平台默认位置Windows 老版本可能在%APPDATA%\Claude Code Router\带空格目录首次运行会并入%APPDATA%\claude-code-router\修改~/.claude-code-router/config.json后不生效这是预期行为SQLite 迁移完成后config.json只是归档文件应改走桌面 UI 或 Settings 导出/导入流程容器重建后配置消失检查是否仍挂载同一个/data卷docker compose down --volumes会删除数据只备份了config.sqlite恢复后配置不全WAL 模式下最新事务可能还在-wal中应用级备份请使用 Settings → Export data想迁移到新机器/新环境备份整个数据目录含config.sqlite-wal/-shm与app-data/在 CCR 停止状态下拷贝恢复前先清空目标目录小结与延伸阅读一句话总结CCR 的运行配置以 SQLite 为唯一权威来源位置由“平台默认目录 claude-code-router目录名”决定Docker 中因HOME/data落在/data/.claude-code-router/必须持久化整个/data旧版config.json只在首次无 SQLite 配置时迁移一次之后编辑它不再影响任何行为。本文核心结论均有源码与配置佐证可供进一步深入的文件包括官方文档原文configuration-file.md英文、configuration-file.md中文平台路径解析app-paths.ts常量定义与 Windows 兼容拷贝constants.ts建库、迁移与权限管理实现config-repository.ts、migration.tsSQLite 原生驱动封装sqlite-native.tsDocker 相关配置库路径语义 entrypoint.sh、持久化布局与备份策略 docker/README.md、数据卷挂载 docker-compose.yml相关测试配置迁移与遗留 JSON 行为可参考 config-repository-migration.test.mjs、legacy-json-preservation.test.mjs、config-repository-backup-deduplication.test.mjs如果你需要继续了解供应商与模型配置、路由规则如何在 UI 中编辑并落到这张数据库里可以阅读同目录下的 overview.md 或仓库根目录的 README_zh.md。【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考