凭域 Keyrealm
致力于 ALL IN ONE 的本地凭据管理与验证平台。 允许将红队渗透测试中获取的散落在各处的 API Key、云厂商 AK/SK、机器人 Token、邮箱授权码、登录态等集中加密保管、便捷验证与快速利用。
数据只存在自己本地机器的程序目录里，不联网同步、不上传云端。
功能
加密存储
- AES-256-GCM 字段级加密，密钥由主密码经 PBKDF2-HMAC-SHA256 派生，仅存内存。
- 敏感字段与非敏感字段分列存放：列表展示不必解密，同时保证密钥类字段全程不落明文。
- 主密码没有任何找回途径（无后门、无恢复码）——详见安全说明。
主动验证
- 单条 / 批量 / 定时三种方式。批量验证并发数与请求超时可在对话框里就地调整。
- 定时计划的验证范围可选多种范围，更加自由。
- 校验结果不只是「有效 / 无效」，更有针对专一凭据的特殊标注。
- 有写副作用或咱无法自动化的类型（如 DuckDNS、Telegram api_id/hash、短信网关）标记为不参与批量验证，只允许手动逐条验证，避免把人工判定的结果刷掉。
插件化
- 一个服务一个插件，现目前共有 66 个插件、10 个类别（见支持的服务）。
- 插件放在程序目录的
plugins/下，放入即加载、删除即卸载，无需安装器；临时停用无需删目录，在界面里禁用即可（状态记在plugins/.state.json）。 - 禁用不动磁盘目录：名下凭据照常显示、可编辑、可导出，只是「操作」「验证」置灰、批量验证自动跳过，禁用≠删除，快速找回插件。
凭据操作
部分插件在验证之外还提供操作，随凭据行出现「操作」按钮：
- 对话：对 LLM 凭据直接发一次简单对话（流式返回）。
- 表单：带写副作用的操作（如修改 DNS 解析记录、刷新令牌），提交前二次确认。
- 列表：可下钻的查询，如「云主机实例」「对象存储桶 → 对象浏览」「域名列表 → 解析记录」。
没权限的操作会自动隐藏（插件探测该凭据的真实权限），一个都没有时给出说明。
- 去重：在指定范围内（默认全选）按「插件类型 + 敏感字段值」检测重复凭据；逐组选择保留项，可把其他项的备注 / 描述合并到保留项。
代理
- 可维护多个代理，设一个全局默认；每条凭据可三选一：跟随上层设置 / 指定某个代理 / 直连。解析优先级为
本条凭据 > 该插件预设 > 所属类别预设 > 全局默认。 - 代理支持
http/https/socks4/socks5/socks5h。 - 任一代理可一键对照测试：同一批探测分别走直连与代理，比对出口 IP 归属与国内外站点可达性，直接给出「代理是否真的生效」的结论。
- 邮箱（SMTP / IMAP）走裸 TCP，不使用 HTTP 代理，会自动改用 SOCKS / HTTP CONNECT 隧道穿出去。
备份与恢复
-
导出为单个 JSON 文件：加密导出（保留密文）或明文导出（可跨主密码导入）。
-
可选「全部（凭据 + 分组 + 代理 + 预设 + 定时计划 + 设置 + 保险库 KDF + MCP + 插件启停）」或「仅选中的凭据」。整库档自带盐（salt），文件自包含。
-
导入是填充式的：以当前库为蓝本，把备份条目填进去，不删也不覆盖既有数据。
插件不存在或被禁用、含当前插件不认识的字段、缺少必填字段的条目会整条判失败、不写库，并逐条列出原因；
每次导入在
data/logs/下留一份完整导入日志与（有失败时）一份失败日志，结果弹窗里可一键打开便于人工补录。 -
换保险库也能还原：在另一台机器 / 新装的 Keyrealm 上导入整库备份时，会再问一次它当时的主密码，并用它 + 文档里的盐派生源密钥解开密文，再以当前库的密钥重新加密写回（当前库自己的盐/校验值不受影响）。
其它
- 凭据简易操作、分组管理、6 套界面主题（3 浅 3 深）、侧边栏与凭据目录树顺序均可拖拽调整。
- 后台任务：下载 / 打包这类长操作登记为任务，可看进度、可取消，关掉弹窗照常跑；任务记录持久化到
<data_dir>/tasks.json，重启后历史仍在（上次没跑完的标为「已中断」）。 - 独立日志页：级别可调、支持关键词搜索（含 traceback 的整条记录匹配）。
- 单实例：重复启动不会开出第二个窗口，而是把已运行的拉到前台。
- 桌面 / CLI / Web 三种形态：同一份程序可用桌面窗口、纯命令行或浏览器操作；CLI 版不带桌面图像层，命令行可直接管理凭据，
--web可选启用完整浏览器界面。 - 数据目录可配置：默认
<程序入口>/data；CLI--data-dir或用入口目录keyrealm.conf.json持久化到任意位置。 - 开机自启动（默认关闭）。
- 跨平台：Windows 优先，兼容 macOS 与 Linux。
效果演示
支持的服务
下载与安装
桌面版
如果你是个人PC本地使用，请选择这个版本。
预编译包采用 启动器 + onedir 布局：根目录的 Keyrealm（Windows 为 Keyrealm.exe）是启动器，
应用本体与全部依赖在 runtime/ 下。启动时直接加载磁盘文件，不再像单文件包那样每次解压整包，
启动更快。升级时只替换启动器与 runtime/，plugins/、data/ 与配置原样保留。
请保持目录结构完整；不要单独移动启动器或
runtime/，也不要删除runtime/。
Windows
从 Releases 下载对应平台与架构的压缩包，解压后直接运行，双击运行 Keyrealm.exe 即可。
发行目录包含启动器 Keyrealm.exe、应用本体 runtime/、插件 plugins/ 与运行时数据 data/。
请保持目录结构完整，不要单独移动启动器或 runtime/——启动靠二者配合。
PS：需要 WebView2 Runtime（Windows 10/11 通常已内置；若启动时报缺 WebView2，从微软官网安装即可）。
PS：onedir 的 runtime/_internal/ 目录层级较深，建议解压到较短的路径（如 D:\Keyrealm），
避免 Windows 的长路径限制导致文件缺失。
MacOS
从 Releases 下载对应平台与架构的压缩包，解压后运行包内的 Keyrealm 文件。
PS：由于未签名，首次打开会被 Gatekeeper 拦，需要右键→「打开」，或在终端对解压后的整个目录
执行 xattr -dr com.apple.quarantine <解压目录> 放行（runtime/ 里的文件也要一并清除）。
Linux
从 Releases 下载压缩包，解压后运行包内的 Keyrealm，免安装。
由于 Linux 生态的多样性，将预先给出两种包，请根据自身情况选择：
对于 Linux 系统，我们更推荐自行构建源码运行，以适应各自高度个性化的系统，
CLI版
如果你想要软件在服务器托管运行，请选择该版本。
同一份程序支持多种运行模式，不是两个分支：
-
桌面版：默认打开窗口；也可用
--cli执行命令，或用--web启动网页服务。 -
CLI 版：
Keyrealm-CLI，默认就是纯命令行——执行一条命令、读写本地库、退出。浏览器界面是显式可选项：加
--web才启动 HTTP 服务。
从 Releases 下载带 -cli 后缀的包，解压后运行 Keyrealm-CLI（Windows 为 Keyrealm-CLI.exe）；
同样需要保留同目录的 runtime/：
# ── 命令行（默认，无端口）──
Keyrealm-CLI status # 版本 / 初始化 / 插件状态
Keyrealm-CLI init # 首次使用：设置主密码
Keyrealm-CLI list # 列出凭据
Keyrealm-CLI list --type api_fofa --search 主号
Keyrealm-CLI show 3 # 敏感字段默认掩码
Keyrealm-CLI show 3 --reveal # 显示完整值
Keyrealm-CLI add --type api_fofa --name fofa-main -f api_key=xxxx
Keyrealm-CLI update 3 -f notes=备用
Keyrealm-CLI verify --all # 任一失败时退出码为 1
Keyrealm-CLI action 3 download_object --param key=path/to/file
Keyrealm-CLI export backup.json # 默认加密
Keyrealm-CLI import backup.json
Keyrealm-CLI dedupe # 扫描重复项
Keyrealm-CLI groups # 也可用 plugins / logs / version
# ── MCP（默认不开端口，需显式 start）──
Keyrealm-CLI mcp status # 状态、地址、Token 前缀
Keyrealm-CLI mcp start # 前台启动（Ctrl+C 停止）
Keyrealm-CLI mcp start --host 127.0.0.1 --port 8765 --new-token
Keyrealm-CLI mcp token # 查看前缀；--rotate 轮换并显示新 Token
Keyrealm-CLI mcp permissions # 工具权限
Keyrealm-CLI mcp permission <工具> on|off
# ── 代理与 TLS ──
Keyrealm-CLI proxy list # 代理列表与当前全局代理
Keyrealm-CLI proxy add 本机 socks5://127.0.0.1:1080
Keyrealm-CLI proxy use 本机 # 设为全局；none = 直连
Keyrealm-CLI proxy test 本机 # 测试连通性（不填则测全局）
Keyrealm-CLI proxy update 本机 --url socks5://127.0.0.1:1081
Keyrealm-CLI proxy rm 本机
Keyrealm-CLI tls show # 全局 TLS 版本
Keyrealm-CLI tls set 1.2 # auto / 1.0 / 1.1 / 1.2 / 1.3
Keyrealm-CLI update 3 --proxy 本机 --tls 1.3 # 单条凭据覆盖
Keyrealm-CLI update 3 --proxy-mode global --tls inherit # 恢复跟随全局
# ── 自更新（替换的是 -cli 资产）──
Keyrealm-CLI self-update check # 检查正式版
Keyrealm-CLI self-update check --test # 检查测试版（main 分支）
Keyrealm-CLI self-update install # 下载并安装，交棒后自动重启
Keyrealm-CLI self-update install --no-restart # 只替换，不自动重启
Keyrealm-CLI self-update install --test # 从源码构建测试版
Keyrealm-CLI self-update status # 最近一次更新状态
自更新会按当前构建选择 -cli 资产；--password（或 KEYREALM_MASTER_PASSWORD）会解锁并
使用已保存的更新访问令牌，也可直接设置环境变量 KEYREALM_UPDATE_TOKEN。更新期间会占住
单实例锁，桌面端需先退出；install 交棒后本进程退出，由更新进程替换并可自动重启。
# ── 可选：浏览器界面 ──
Keyrealm-CLI --web # 默认 http://127.0.0.1:8766
Keyrealm-CLI --web --no-browser --port 8766 --host 127.0.0.1
Keyrealm-CLI --web --token <固定令牌> # 默认每次启动随机生成
桌面版使用相同命令时加 --cli 前缀：Keyrealm --cli list、Keyrealm --cli status。
桌面版同样支持 --web 启动网页服务。
主密码：交互终端会提示输入；脚本里推荐用环境变量，避免出现在进程列表：
export KEYREALM_MASTER_PASSWORD='…'
Keyrealm-CLI --json list
也支持 --password（注意命令行参数可能被其他用户看到）。--json 输出机器可读结果，
适合管道与自动化。
安全提示（仅 --web）：默认只监听 127.0.0.1，访问地址必须带启动时打印的 ?token=…。
监听 0.0.0.0 时同一网络内的其他设备可访问，请务必使用强令牌并做好网络隔离。按 Ctrl+C
停止服务。普通 CLI 命令不监听任何端口。
CLI 版不包含桌面特有的功能（系统托盘、开机自启、窗口关闭行为、轻量模式）。 命令行可直接完成凭据增删改查、验证、插件启停、分组、备份导入导出、去重、日志等常用操作； 完整界面（含任务、MCP、定时计划、更新等常驻管理）仍可用可选的
--web浏览器模式。 浏览器界面是显式选项，不是 CLI 的默认行为。
mcp start是前台常驻命令：会先解锁保险库，然后占住单实例锁运行 MCP，按Ctrl+C停止； 启动时会保存监听地址并写入mcp_enabled，下次桌面/Web 启动会按设置自动恢复 MCP。 新 Token 只在创建 / 轮换时显示一次，请立即保存。
完整的命令参考、数据目录优先级与安全说明见 CLI / Web / 数据目录。
自定义数据目录
默认数据目录是程序入口目录下的 data/（数据库、日志、备份、任务记录）。可以改到别处，
桌面版与 CLI 共用同一份配置：
# 查看当前生效目录、来源（命令行 / 配置文件 / 默认）与配置文件位置
Keyrealm-CLI data-dir show
# 持久化到入口目录的 keyrealm.conf.json，下次启动生效
Keyrealm-CLI data-dir set /mnt/vault-data
# 清除配置，恢复默认目录
Keyrealm-CLI data-dir clear
# 仅本次 CLI 命令使用，不写配置（优先级最高，仅 CLI 支持）
Keyrealm-CLI --data-dir /tmp/alt-data list
查找顺序：CLI --data-dir（仅命令行模式，一次性）→ 入口目录 keyrealm.conf.json →
默认 <入口目录>/data。配置文件格式：
{
"data_dir": "/path/to/data"
}
- 桌面版直接开窗口时不接受
--data-dir（只认配置文件）；桌面版的--cli模式可以用参数。 - 配置里的相对路径按配置文件所在目录解析；CLI
--data-dir的相对路径按当前工作目录解析。 - 插件目录仍然固定在入口目录的
plugins/；改变的只有data/（数据库/日志/备份/任务/下载临时文件）。 - 换目录后是一个新的空保险库；要沿用原数据，请先把原
data/内容复制过去。
通过源码运行
如果你想要进行二次开发，或者release发行版中的版本都和你的机器架构不符合，又或者你想体验最新的测试版，请选择此版本。
基础环境要求：
如果需要从源码运行，请参考以下流程：
git clone https://github.com/YZBRH/keyrealm.git
cd keyrealm
python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python main.py --gui # 桌面窗口运行（Linux 默认：有 Qt 用 Qt，没有则退回 GTK）
KEYREALM_GUI=gtk .venv/bin/python main.py --gui # 指定走系统 GTK 运行
.venv/bin/python main.py --web # 浏览器界面运行（会监听端口）
.venv/bin/python main.py --cli status # 命令行模式运行（无端口）
如果你想要把他编译成二进制文件，参考追加执行命令：
.venv/bin/pip install pyinstaller
.venv/bin/python scripts/build.py --frontend # 默认打成 Qt 版
.venv/bin/python scripts/build.py --frontend --gui gtk # 打成 GTK 版
.venv/bin/python scripts/build.py --frontend --cli # CLI 版（无窗口；命令行操作，可选 --web）
如果你是在 Linux 系统上运行的，还需要指定界面后端，它们之间的区别如下：
详见 CONTRIBUTING.md。
程序更新
软件内更新
根据软件内选项选择即可。
将更新渠道设置为"正式版"时，将从 Releases 中拉取对应架构的最新版本；
将更新渠道设置为"测试版"时，将从仓库当中拉取最新的 commit 并进行源码编译成最新的二进制文件。
如果是从 Releases 中下载的预编译包运行的，我们推荐后续的所有更新都通过"正式版"方式更新。
从 1.4.7 及更早版本升级：1.5.0 起改为「启动器 +
runtime/」布局，不支持 1.4.7 的应用内升级。 请手动下载 1.5.0 的发行包替换程序目录，保留原data/（自定义数据目录则保留该目录与keyrealm.conf.json）即可。
CLI 版可直接：
Keyrealm-CLI self-update check # 检查
Keyrealm-CLI self-update install # 下载/安装并重启
Keyrealm-CLI self-update status # 最近一次状态
如果 Releases 中没有对应的预编译包，通过"正式版"渠道更新可能会出问题，欢迎提交 Issue 或 PR 来说明需要支持的更多操作系统版本。
软件外更新
如果你通过预编译程序运行的，请优先考虑通过软件内更新。
对于源码运行，只需要拉取最新 commit 提交，然后运行数据库迁移脚本即可（如果有），示例：
cd keyrealm
git pull
# 如果数据库结构版本有改动，运行对应的一跳迁移脚本（脚本默认只演练，加 --apply 才写库；
# 跑之前请先完全退出应用）
python scripts/migrations/m_1.2.1__to_1.2.2.py --apply
python main.py --gui
快速上手
-
设置主密码。 首次启动要求设置主密码——它用于派生加密密钥。
忘记即无法恢复，请自行妥善保存。
-
添加凭据。 在左侧「凭据目录」选一个服务 → 点「添加凭据」→ 按表单填写。 表单字段由插件声明（如 API Key、Base URL、备注），敏感字段保存前即加密。 也可以先给某个类别或插件设好默认值（Base URL、备注、走哪个代理），新建时自动带出。
-
验证。 保存后默认自动验证一次；之后可随时点行内「验证」，或用工具栏的「批量验证」 勾选多条一起验，或在「任务」页配置定时验证计划。
-
看结果。 列表里的「状态」列给出结论，「附加信息」列给出余额 / 使用率 / 账号信息； 有些凭据行还会出现「操作」按钮，可做验证之外的查询与操作。
MCP支持
Keyrealm 内置一个 MCP Server，Agent 可以直接查询、创建、验证凭据，不必把密钥复制到聊天上下文里。
启动方式（任选其一）：
- 桌面 / Web：在「设置 → MCP 服务」页手动启动服务（默认监听
127.0.0.1:8765，仅本机）。 - CLI：
Keyrealm-CLI mcp start前台启动，Ctrl+C停止；普通 CLI 命令不会自动开端口。
- 端口被占用时直接报错，不自动换端口。
mcp start --host H --port P可持久化新的监听地址。 - 页面 /
mcp token提供访问 Token（Bearer）；mcp token --rotate可轮换。 - 工具权限默认关闭，需要在 MCP 设置页逐个开启（CLI：
mcp permission <工具> on）。 共 20 个工具：读类默认开，写与高危类默认关（开启前二次确认）。 - Token 明文只在创建 / 轮换时展示一次，数据库只存哈希与前缀，鉴权失败返回 401。
- CLI 启动 MCP 会先解锁保险库，并占住单实例锁；停止时写入
mcp_enabled=0。 桌面 / Web 下次启动会按mcp_enabled自动恢复上次的开关状态。
完整接口规范见 MCP 接口规范。
安全说明
主密码无法找回。加密密钥由主密码派生，没有任何后门或恢复码——丢了主密码就丢了解密能力。
建议定期用「备份」页导出（记得用同一个主密码，或选择明文导出自担风险）。
常见问题
Q：忘记主密码了怎么办？
无法恢复。只能删掉 data/ 目录重新开始（已加密的数据无法解密）。
Q：数据存在哪里？怎么整机迁移？
默认在程序的 data/ 目录：credentials.db（凭据库）、logs/（日志）、tasks.json（任务记录）、webview/（界面偏好）。
可用 Keyrealm-CLI data-dir show 查看实际位置；如果配置过自定义目录，迁移时把该目录与入口目录的 keyrealm.conf.json 一起拷走。
整机迁移也可以只用「备份」页导出 JSON，粒度更细。
Q：升级会不会丢数据 / 重置我的插件启用状态？
不会。升级只替换启动器与 runtime/（以及 plugins/ 的源码文件），当前数据目录（默认 data/）
原样保留，plugins/.state.json（启用 / 禁用状态）也不会被覆盖。更新期间旧运行时保留在 runtime.old/，新运行时正常启动后自动清理。
Q：怎么更新到新版本？ 两种渠道，在「设置 → 更新」里选：
- 正式版：从 GitHub Release 下载对应平台的预编译包替换当前程序（不编译），更新前会把启动器、
plugins/、data/备份到data/backup/（只留最近一份），数据库结构有变动会逐级自动迁移。 - 测试版：跟
main最新提交从源码重新构建（本机没有源码会先拉一份到程序目录），如果本机缺少开发环境，运行可能会报错，建议优先选择正式版。
两种更新前都会自动备份；准备完成后会询问是否立即重启，选「稍后」则保留已下载的包 / 已构建的产物，下次更新直接复用、不重复下载或构建。默认开启「自动检测更新」——每次程序启动后会自动查一次，发现新版本弹通知提醒；也可以随时在「设置 → 更新」手动检查。
为了保障数据安全，我们仍建议在自动更新前，再进行一次手动导出备份。
也可以手动从 Releases 下载压缩包。 详见 程序内更新。
Q：某个服务验证失败或有超时，是不是我的 Key 坏了？ 先看是不是网络问题。部分厂商（Telegram、Discord、Hugging Face 等）在国内需要代理才能访问，请在「设置 → 网络与代理」里配好代理，再对该凭据指定出口。
Q：MCP 服务启动失败？ 多半是端口被占用。到「设置 → MCP 服务」改一个端口再启动（应用不会自动换端口）。
Q：日志在哪里？
<data_dir>/logs/keyrealm.log（默认 data/logs/keyrealm.log，1 MB × 5 轮转），也可以在「日志」页里直接查看与搜索。
Q：验证会不会产生费用或副作用？ 校验一律使用只读接口，不会修改你在厂商侧的任何配置。唯一的例外是插件显式提供、由你手动点击的操作（如修改 DNS 记录、刷新登录态令牌）；另有「欠费探测」会额外发一次极小的对话请求（默认关闭，开启时会消耗极少量额度）。
文档
开发与贡献
构建、打包、插件开发与提交约定见 CONTRIBUTING.md。
发现问题或想加新插件服务，欢迎提 Issue / PR。
声明
本工具仅限合法用途。 仅可用于你本人拥有、或已从所有者处取得明确书面授权的系统与凭据；禁止用于任何未授权目标、账号或系统。
- 凭据来源自负其责：你对导入本工具的全部凭据之来源合法性与使用权限负全责；作者不参与、不追认、不背书任何凭据的获取行为。
- 联网与第三方条款：验证 / 操作会以你的凭据向对应厂商发起真实请求，可能消耗额度、触发风控或违反该厂商服务条款；部分「操作」带写副作用（改 DNS 记录、刷令牌、改写对象存储）；「匿名对象存储」插件会对目标桶发起匿名列举 / 读取 / 写探测，仅可用于已获授权目标。使用本工具进行相关操作时视为你已经知晓并同意承担相应风险。
- 数据与暴露面：主密码无找回途径，遗失即永久失去数据；「明文导出」文件含全部凭据明文；「MCP 服务」一旦启用，本机任何能访问该端口的程序（含 AI Agent）均可读取整库凭据——均请自行评估并设防。
继续使用即表示你已理解并接受上述条款，以及 MIT 许可 的相关条款内容。
第三方商标
本项目分发的插件图标为第三方商标图形，取自各厂商官网、官方品牌资源包、App Store 官方图标与 Simple Icons（CC0-1.0）、Iconify 的 thesvg 集合（MIT）等公开来源，仅用于标识对应的服务。
商标归各自权利人所有，本项目与这些厂商无隶属或背书关系。
图标的逐个来源与选取标准见 插件开发指南 的 logo 小节。
404星链计划
凭域 (keyrealm) 现已加入 404星链计划
