a4api 面向 Windows 10/11 64 位桌面环境分发，普通用户通过安装包图形化安装即可；开发者也可以从源码直接运行。本文章覆盖下载安装、首次运行注意事项、覆盖升级、卸载与数据清理，以及面向开发者的源码运行与打包构建方法。
1. 下载安装
从项目的发行版（Release）页面下载最新安装包 a4api-setup-<版本>.exe：
| 事项 | 说明 |
|---|---|
| 系统要求 | Windows 10 / 11，64 位 |
| 安装方式 | 每用户安装（免管理员权限），双击按向导完成 |
| 快捷方式 | 自动创建开始菜单与桌面快捷方式 |
| 完整性 | 建议核对发布页提供的 SHA256 校验值后再运行 |
安装包采用每用户模式，全程不需要 UAC 提权；应用本体、前端资源与运行时依赖全部随包内置，安装后可离线使用。
2. 首次运行
- 从开始菜单或桌面快捷方式启动 a4api；
- 若出现 Windows SmartScreen 提示，点击「更多信息 → 仍要运行」——应用未做商业代码签名，属正常现象，不影响功能；
- 打开界面后选择预置服务商模板，填入 API Key 即可创建配置方案并一键切换，快速路径见项目总览与快速开始。
两个常见提示的处理：
- 杀毒软件报毒：PyInstaller 打包的程序偶被安全软件误报，添加信任或排除即可，也可将样本提交厂商申诉；
- 单实例限制：应用通过系统互斥体保证同时只有一个实例在运行，重复启动不会开出第二个窗口。
3. 覆盖升级
升级就是用新版安装包再装一遍：
下载新版 a4api-setup-*.exe → 双击运行 → 向导覆盖安装 → 启动即新版
- 升级前应用会自动停止后台翻译代理并清理旧文件，避免文件占用导致覆盖失败；
- 运行数据（数据库、配置备份）保存在
%APPDATA%\a4api\，覆盖安装完整保留，无需重新配置； - 更省事的方式是等应用内更新提醒，点几下完成同样的事，机制见自动更新。
4. 卸载与数据清理
| 动作 | 方法 | 结果 |
|---|---|---|
| 卸载程序 | Windows「设置 → 应用」中卸载 a4api | 程序文件被移除 |
| 数据保留 | 卸载默认不动 %APPDATA%\a4api\ |
配置方案、密钥库、备份保留，重装后原样恢复 |
| 彻底清除 | 手动删除 %APPDATA%\a4api\ 目录 |
所有本地数据（含加密密钥库）一并清除 |
日志位于
~/.a4api/logs/，卸载后如需彻底清痕可一并删除，目录结构详见数据目录与日志说明。
5. 从源码运行（开发者）
环境要求：Windows 10 以上、Python 3.10、uv 包管理器。
uv sync # 安装依赖
uv run python desktop.py # 启动桌面应用
# 或后端单独调试
uv run uvicorn backend.app.main:app --port 8000
开发模式下运行时数据写入项目内 backend/database/，与安装版数据目录互不干扰；测试体系运行 uv run pytest 即可。
6. 打包构建（开发者）
前置条件：编译安装包需要 Inno Setup 6：
winget install --id JRSoftware.InnoSetup -e --accept-source-agreements
三种产物形态：
uv run python build.py # 文件夹版（onedir），输出 dist/a4api/
uv run python build.py --installer # 文件夹版 + Inno Setup 安装包 dist/a4api-setup-<版本>.exe
uv run python build.py --onefile # 单 exe（临时分发用）
| 构建细节 | 说明 |
|---|---|
| 版本号 | 默认读取 pyproject.toml 的 [project].version，可用 --version 覆盖 |
| 图标 | 由 Pillow 从源图自动生成多尺寸 ico（缺 Pillow 时跳过图标并提示） |
| 前端资源 | LayUI 等静态资源整体打入包内，运行时由 FastAPI 托管，离线可用 |
| ISCC 定位 | 自动探测 Inno Setup 编译器，也可用 --iscc 显式指定路径 |
源码仓库与目录结构见项目总览与快速开始；安装包脚本
installer.iss定义了每用户安装、快捷方式与卸载入口。
7. 常见问题
问：安装需要管理员权限吗？
答：不需要。采用每用户安装模式，写入范围限于当前用户目录，没有 UAC 弹窗；公司受限环境下通常也能正常安装。
问：升级后界面还是旧版本？
答：确认旧实例已完全退出（含后台翻译代理），重新启动即是新版；若通过应用内更新走完流程会自动完成退出与拉起，手动覆盖安装时请先关闭正在运行的窗口。
问：卸载后重装，之前的配置方案还在吗？
答：在。只要没手动删除 %APPDATA%\a4api\，重装后所有方案、服务商与加密密钥原样可用；这也是「先卸载再装新版」能当升级用的原因。
问：能同时在开发模式与安装版之间切换使用吗？
答：可以，两者数据库相互独立（开发模式在项目 backend/database/，安装版在 %APPDATA%\a4api\）；但同一时刻只会有一份生效配置写入 ~/.claude 等目标文件，切换时以最后操作为准。
举手提问