APIKEY Manager

APIKEY Manager 是一个本地优先的 API Key 管理器。它主要用来保存、管理和测试大模型 API Key，也可以保存搜索服务、机器人、平台应用这类通用密钥和配置项。默认只监听本机；按本文的公网安全模式配置后，可以放在可信 HTTPS 反向代理后远程访问。

数据默认只保存在你的电脑里，并使用 SQLCipher 加密。启用 Backblaze B2 异地备份后，应用会上传加密数据库副本；不会连接本项目之外的统计或分析服务。

本项目使用 GPT 5.6 Sol + Claude Opus 5 共同编写，作者可以保证本项目的可用性。

功能

• 管理多个大模型供应商，支持记录 API 端点和官网地址。
• 支持 OpenAI Chat Completions、OpenAI Response、Anthropic Messages 三类接口格式。
• 每个供应商可以保存多个 API Key，并指定其中一个作为测试密钥。
• 每个供应商单独设置测试模型；测试 Prompt 在设置页统一管理。
• 测试密钥时显示进行中状态，测试结果通过详情弹窗查看，包含测试时间、输出内容和可选推理内容。
• 刷新并缓存模型列表，支持模型 ID 复制和前端搜索。
• 大模型供应商、通用密钥类别和密码条目都支持自定义分组及组内排序。
• 通用密钥按类别管理，一个类别下可以保存多个键值对。
• 密码管理器只负责保存密码，不限制密码长度、字符或格式，并支持可选的 2FA 关联。
• 2FA 提供独立验证码查看页，支持二维码截图识别和手动输入 Base32 密钥。
• 支持配置 Backblaze B2 异地备份，每次启动检查当天备份状态，也可以手动备份和恢复。
• 支持 JSON 导入；导出支持 JSON、Markdown 和加密数据库文件。
• 界面使用本地图标字体，复制、编辑、删除等常用按钮不依赖外部网络加载图标。
• 删除等危险操作使用应用内确认浮窗，不调用浏览器原生弹窗。
• 右上角显示后端连接状态，断开连接时会给出明确提示。
• 时间默认按 UTC+8 展示。

画廊

快速开始

直接运行当前目录下已经构建好的程序：

APIKEY-Manager.exe

启动后会在本机开启服务，并自动打开默认浏览器：

http://127.0.0.1:5157

第一次打开时需要创建主密码。主密码不会明文保存，也无法找回；忘记主密码就无法打开原来的数据库。

Docker Compose 部署

服务器安装 Docker Compose 后，在项目目录执行一条命令即可构建并启动：

docker compose up -d --build

启动后默认只能在 Docker 宿主机访问 http://127.0.0.1:5157。Compose 将宿主机项目目录下的 ./data 绑定到容器的 /data，数据库实际保存为 ./data/apikeys.db，重建或删除容器不会删除该文件。

Linux 服务器使用绑定目录时，先将数据目录交给容器内的非 root 用户（UID/GID 10001），再启动服务：

sudo install -d -m 700 -o 10001 -g 10001 /srv/apikey-manager-data
APIKEY_MANAGER_DATA_PATH=/srv/apikey-manager-data docker compose up -d --build

也可以通过 APIKEY_MANAGER_PORT 修改宿主机端口，容器内部端口保持不变。Compose 会始终把该端口绑定到宿主机 127.0.0.1，不会因环境变量误配置而直接发布到公网。

公网安全模式

公网访问必须使用可信反向代理终止 HTTPS，代理应保留原始 Host，并覆盖或追加正确的 X-Forwarded-For。只有 APIKEY_MANAGER_TRUSTED_PROXY_CIDRS 显式列出的直连代理才能影响客户端限流身份；应用会从转发链右侧剥离可信代理，使用第一个非可信地址。应用端口只对反向代理或本机开放，不要把容器的 5157 端口直接暴露到互联网。

全新部署必须先保持默认本机模式启动，从 Docker 宿主机访问 http://127.0.0.1:5157 并创建数据库；远程服务器可先使用 SSH 端口转发完成这一步。创建完成后执行 docker compose down，数据库仍保留在数据目录。

假设公开地址为 https://vault.example.com，再在反向代理配置完成后启用公网模式：

APIKEY_MANAGER_PUBLIC_MODE=1 \
APIKEY_MANAGER_PUBLIC_ORIGIN=https://vault.example.com \
APIKEY_MANAGER_TRUSTED_PROXY_CIDRS=172.17.0.1/32 \
APIKEY_MANAGER_DATA_PATH=/srv/apikey-manager-data \
docker compose up -d --build

172.17.0.1/32 只是常见 Docker 网桥宿主地址示例，必须替换为反向代理连接应用时真实使用的直连 IP 或最小网段；多个 CIDR 用逗号分隔。未配置时应用完全忽略 X-Forwarded-For，限流会按反向代理的直连地址统计。

公网模式会启用以下硬门槛：

• 只接受公开地址对应的 Host，所有写请求同时校验 CSRF token 和精确 Origin。
• 公网模式拒绝首次创建数据库，防止未初始化实例被第一个访问者抢占；只能解锁已经在本机模式创建的数据库。
• Cookie 强制 Secure、HttpOnly、SameSite=Strict，响应启用 HSTS，API 和首页禁止缓存。
• 登录失败按客户端严格锁定，并在全局高频失败后渐进节流；状态持久化到数据目录，重启不会清零。昂贵的主密码验证使用非排队认证槽，忙碌请求会立即收到 429。
• 会话默认闲置 15 分钟、绝对 2 小时；超时会关闭 SQLCipher 数据库连接。2FA 后台刷新不会延长闲置时间，每次成功解锁或改密都会轮换令牌并使旧会话失效。
• 明文导出、数据库下载、JSON 覆盖、云端恢复、手动上传整库以及修改或清除云备份目标必须重新输入主密码，复验 token 60 秒内一次有效。
• 主密码不强制长度、字符或格式；少于 12 个字符时界面只显示可忽略的安全提示。应用通过持续限流、会话时限和一次性复验限制在线猜测。
• 携带真实 API Key 的供应商请求只允许 HTTPS 公网目标，实际连接固定到校验后的公网 IP，并使用原域名验证 TLS 证书；禁止重定向和超限响应。
• Backblaze 请求不继承系统代理，普通 JSON 响应在解析前限制为 2 MiB；数据库下载另受 1 GiB 上限和 SHA-1 完整性校验保护。

修改主密码只会直接重加密当前数据库。导入或恢复产生的历史安全副本、用户自行导出的数据库以及既有云备份仍使用各自创建时的密码；应用不会擅自删除这些恢复材料。若已启用自动 B2 备份，改密成功后会立即安排一份使用新密码的新备份。确认新备份可恢复后，请按自己的保留策略从数据目录和 Backblaze 控制台清理不再需要的旧副本。

如需使用非默认会话时限，可设置 APIKEY_MANAGER_SESSION_IDLE_SECONDS 和 APIKEY_MANAGER_SESSION_ABSOLUTE_SECONDS。额外域名只能通过逗号分隔的 APIKEY_MANAGER_TRUSTED_HOSTS 显式加入，可信代理只能通过 APIKEY_MANAGER_TRUSTED_PROXY_CIDRS 显式加入。停止服务使用 docker compose down，不要删除宿主机数据目录。

安全无法用软件声明为“绝对无法破解”。应用不会强制主密码规则，但容易猜中的口令仍会降低离线数据库抗破解能力；公网安全还依赖及时更新依赖、反向代理 TLS 与访问日志、主机补丁、防火墙、最小化云账户权限以及不泄露浏览器会话。建议再在反向代理前增加 VPN、零信任访问网关或来源 IP 白名单。

基本用法

大模型密钥

1. 添加供应商，填写名称、API 端点、官网地址和接口格式。
2. 添加一个或多个 API Key。
3. 选择一个 API Key 作为测试密钥。
4. 填写该供应商的测试模型。
5. 刷新模型列表，或测试指定密钥。

模型列表会缓存在本地，可以直接搜索和复制模型 ID。测试完成后，可点击状态旁的信息按钮查看测试时间、响应输出和模型推理内容。

通用密钥

1. 先创建类别，比如 Tavily、QQ机器人、支付平台。
2. 在类别下添加键名、键值和描述。
3. 使用时点击复制即可。

密码管理器

1. 创建密码分组，或直接使用“默认分组”。
2. 保存条目名称、用户名、密码、网站地址和备注。
3. 密码不会进行强度评估，也不会因为格式特殊而被拒绝。
4. 如需关联 2FA，先在 2FA 页面添加密钥，再在密码条目中选择对应的 2FA。

2FA 验证码

在 2FA 页面上传二维码截图，或粘贴 otpauth:// URI、Base32 密钥。验证码在本地生成；除启用 Backblaze 时上传 SQLCipher 加密数据库副本外，不会向外部服务发送明文 2FA 密钥。

云端异地备份

在设置页的“云端异地备份”中配置 Backblaze B2。备份文件是已经由 SQLCipher 加密的数据库文件；自动备份每天最多生成一份，手动备份受冷却时间限制。恢复前会验证备份文件，并保留当前数据库安全副本。

数据导入导出

在设置页打开数据导入导出弹窗：

• 导入仅支持本应用导出的 JSON，可从文件或剪贴板导入；导入会替换当前数据库内容，并在覆盖前保留 SQLCipher 一致性安全副本。
• JSON 和 Markdown 导出默认使用精简模式，不包含测试配置、测试记录、模型缓存和推理内容。
• 勾选“导出测试相关数据”后，会导出完整测试配置和记录。
• JSON、Markdown 和数据库文件都可能包含真实密钥，请只保存到可信位置。
• 下载数据库会生成当前加密数据库的一致性快照，该文件仍受 SQLCipher 主密码保护。

数据保存位置

默认数据库文件为 apikeys.db：

• Windows：%APPDATA%\APIKEY-Manager\apikeys.db
• macOS：~/Library/Application Support/APIKEY-Manager/apikeys.db
• Linux：~/.apikey-manager/apikeys.db

高级用户也可以通过环境变量指定数据目录：

$env:APIKEY_MANAGER_DATA_DIR="C:\path\to\data"
.\APIKEY-Manager.exe

高级用法：从源代码启动

如果你想改代码或自己调试，可以从源码启动：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python run.py

源码方式启动后同样会自动打开：

http://127.0.0.1:5157

高级用法：重新打包 exe

项目提供了 PyInstaller 打包脚本，会使用根目录下的 favicon.ico 作为图标，并把 app/static 下的样式、脚本和本地图标字体一起打包。

先安装 PyInstaller：

python -m pip install pyinstaller

开始打包：

python build_pyinstaller.py

打包完成后，APIKEY-Manager.exe 会移动到项目根目录，dist/、build/、build-spec/ 等临时目录会自动删除。

打包前脚本会检查 app/static/fonts/fa-solid-900.woff2 是否存在；缺少该文件时会停止打包，避免生成缺图标的程序。

如果想隐藏控制台窗口：

python build_pyinstaller.py --windowed

注意：程序本质上仍是本地 Web 应用。启动 exe 后会在本机启动服务，并自动打开浏览器访问 http://127.0.0.1:5157。如果想看到彩色控制台说明和停止提示，不要使用 --windowed。

开发命令

python run.py
python -m unittest discover -s tests
python -m py_compile build_pyinstaller.py
python build_pyinstaller.py

前端脚本语法检查：

node --check app\static\app.js

依赖

• Flask
• Waitress（Docker WSGI 服务）
• requests
• SQLCipher Python 绑定：sqlcipher3
• 本地图标字体：app/static/fonts/fa-solid-900.woff2

如果 sqlcipher3 安装失败，通常是当前平台缺少可用 wheel，或缺少 SQLCipher / C++ 编译环境。

安全提醒

• 主密码不会保存到数据库中，忘记后无法恢复数据库内容；应用解锁期间会在进程内存中持有口令和密钥，因此服务器进程与操作系统必须可信。
• 数据库文件使用 SQLCipher 加密。
• API Key 只会在你主动测试密钥或刷新模型列表时发送到你配置的 API 地址；公网模式会额外阻止私网目标、DNS 重绑定、重定向和非 HTTPS 端点。
• 复制到剪贴板的内容可能被其他应用读取，使用后可以手动清空剪贴板。
• 导出的 JSON、Markdown 和数据库文件可能包含真实密钥，分享前请先确认内容。
• 可以在设置页配置 Backblaze B2 异地备份；自动备份每天最多一次，手动备份有冷却时间限制。仍建议定期导出或保存额外的数据库副本。
• 公开部署应持续关注 Flask、Werkzeug、requests、urllib3、Waitress 和 SQLCipher 的安全更新；一次通过测试不代表未来依赖永远安全。