a4api 是纯本地工具，所有运行时数据都落在你自己的磁盘上：SQLite 数据库、配置备份、代理状态、更新缓存与日志。清楚每个文件的位置与角色，排查问题、迁移机器或彻底清理时才有的放矢。本文章给出安装版与开发模式两套目录的完整清单、数据库表结构、各类状态文件说明，以及可用于测试的路径覆盖环境变量。

1. 目录总览

1.1 安装版（打包运行）

路径 内容
%APPDATA%\a4api\a4api.db SQLite 主数据库：服务商、配置方案、切换日志、备份记录
%APPDATA%\a4api\backups\ 三端配置文件的切换前自动备份，滚动保留最近 5 份
%APPDATA%\a4api\proxy.json 本地翻译代理状态文件（端口、PID、token）
%APPDATA%\a4api\update_state.json 更新状态：忽略的版本、已下载待安装标记
%APPDATA%\a4api\updates\<版本>\ 已下载并通过校验的更新安装包
~\.a4api\logs\a4api.log 运行日志

1.2 开发模式（源码运行）

开发模式下数据根切换为项目内 backend/database/，子结构相同（a4api.db、backups/、proxy.json），日志位置不变；两套环境互不干扰。

graph LR A[a4api 运行模式] --> B{是否打包运行?} B -->|是
安装版| C[%APPDATA%\a4api] B -->|否
源码调试| D[backend/database] C --> E[(a4api.db)] C --> F[backups 备份] C --> G[proxy.json 代理状态] C --> H[update_state.json 更新状态] D --> E2[(a4api.db)] D --> F2[backups 备份] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style C fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style D fill:#ffecd6,stroke:#e67e22,stroke-width:2px style E fill:#fdebd0,stroke:#b7950b,stroke-width:2px style F fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style G fill:#fdebd0,stroke:#b7950b,stroke-width:2px style H fill:#fdebd0,stroke:#b7950b,stroke-width:2px style E2 fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style F2 fill:#fadbd8,stroke:#c0392b,stroke-width:2px

2. 数据库表结构

a4api.db 共四张表：

表 字段 说明
providers id, name(唯一), api_base, api_type, native_responses, is_custom, created_at 服务商；预置模板 is_custom 为假且随版本同步
configurations id, name, provider_id(外键), api_key_encrypted, model, targets, max_tokens, is_active, created_at 配置方案；密钥为 DPAPI 加密后的 base64
switch_logs id, config_id, switch_time, status(success/failed), detail 每次切换一条记录
backups id, config_id, backup_time, file_path 备份动作记录

两点一致性保证：连接级开启 PRAGMA foreign_keys=ON 外键约束；删除服务商时若其下还有配置方案会被拒绝（见服务商管理与预置模板）。

3. 备份目录

每次写入目标配置前，原文件先复制进 backups\，命名规则与滚动策略：

备份文件名 对应原文件
settings.<时间戳>.json.bak ~/.claude/settings.json
codex.config.<时间戳>.toml.bak ~/.codex/config.toml
dsh.settings.<时间戳>.yaml.bak ~/.dsh/settings.yaml
dsh.credentials.<时间戳>.yaml.bak ~/.dsh/.credentials.yaml

每类独立排序，超出最近 5 份的旧备份自动删除；手动回滚把对应 .bak 复制回原路径即可，操作见配置方案与一键切换第 5 节。

4. 状态文件

文件 写入者 角色
proxy.json 本地翻译代理进程 声明监听端口、PID 与鉴权 token，主程序凭它与代理建立联系；内容过期时主程序会按端口反查真实占用进程自愈
update_state.json 更新模块 记录被忽略的版本号与已下载待安装标记，原子写入防损坏

两个文件都可以安全地随数据目录一起删除：前者会在下次需要代理时重建，后者只损失「忽略此版本」记忆。

5. 日志

日志固定写在 ~\.a4api\logs\a4api.log，与数据目录分离：

  • 默认只记时间、级别与摘要信息，不记录任何请求或响应内容；
  • 排查代理转发问题时，可设置环境变量 A4API_PROXY_DEBUG 开启完整请求头、请求体与上游响应的调试日志，用完关闭；
  • 提交问题反馈时请附上日志相关片段（报错前后即可），并先脱敏，见安装升级与卸载的反馈指引。

6. 路径覆盖环境变量

全部路径都可用环境变量覆盖，主要用于自动化测试与特殊部署：

环境变量 覆盖对象
A4API_DATA_DIR 运行时数据根目录（数据库、备份等整体搬家）
A4API_SETTINGS_PATH Claude Code 的 settings.json 完整路径
A4API_CODEX_CONFIG_PATH Codex 的 config.toml 完整路径
A4API_CODEX_CATALOG_PATH Codex 模型目录 models.json 完整路径
A4API_DSH_SETTINGS_PATH dsh 的 settings.yaml 完整路径
A4API_DSH_CREDENTIALS_PATH dsh 的 .credentials.yaml 完整路径
DSH_HOME dsh 数据目录（影响上面两个 dsh 文件的默认定位）
A4API_PROXY_DEBUG 开启代理调试日志（非路径，行为开关）

7. 旧版数据迁移

项目前身名为 api-switch（数据目录 %APPDATA%\api-switch\，数据库 api_switch.db）。新版首次启动时会做一次性迁移：旧库不存在新库时复制为 a4api.db，旧的 backups\ 与 proxy.json 一并搬入；迁移失败不阻塞启动。老用户升级后配置方案与密钥无缝延续，见版本更新说明。

8. 常见问题

问：如何把 a4api 搬到另一台电脑？

答：API Key 密文与 Windows 用户绑定，直接拷贝数据库在新机上解不开。正确做法是在新机重装应用后重建配置方案（服务商模板会自动播种，只需重填 Key）；备份文件如需带走，注意它们是明文配置，含真实 Key 时妥善保管。

问：能直接用 SQLite 工具编辑 a4api.db 吗？

答：技术上可以读，但不建议写——界面层有名称唯一性、外键保护等校验，绕开界面改库可能制造出界面无法处理的脏数据。需要批量调整时优先通过界面操作。

问：想彻底重置 a4api 怎么做？

答：退出应用后删除整个数据目录（安装版 %APPDATA%\a4api\，开发版 backend/database/），再启动即得到全新环境：数据库重建、模板重新播种；~/.a4api/logs/ 日志如需一并清掉可单独删除。

问：updates 目录里的安装包能删吗？

答：能。那是已下载的历史安装包缓存，删除后不影响任何功能，只是若再点「立即更新」需要重新下载对应版本。