Zektor

zektor

用于管理 Zektor.io 数据库和缓存的命令行客户端。

Beta 版。 CLI 及其 MCP 服务均受支持且已上线，但还比较新。随着我们了解人们的使用方式，我们会陆续添加命令并打磨细节。

Beta 并不意味着现有功能不稳定：1.0.0 将确定命令接口。 未经主版本升级，不会更改标志、输出格式和退出代码，因此可以放心在脚本中解析 --json，现在创建的令牌也会继续有效。

安装

npm install -g zektor

也可以直接运行，无需安装：

npx zektor whoami

需要 Node 18 或更高版本。

身份验证

在控制面板的 Settings → Access tokens 下创建令牌，然后：

zektor login

令牌会以 0600 权限存储在 ~/.config/zektor/config.json 中。令牌在写入前会通过 API 验证，因此输错令牌时会立即报错，而不是等到下次运行命令时才让你摸不着头脑。

脚本中可以使用 --token，但如果你正在键盘前操作，最好使用提示输入——参数会留在 shell 历史记录中。

在 CI 中使用

设置 ZEKTOR_TOKEN，即可完全跳过 login：

ZEKTOR_TOKEN=zk_… zektor whoami

ZEKTOR_TOKEN 的优先级始终高于配置文件。zektor whoami 会报告凭据来源，这通常能帮你发现是否有残留的环境变量覆盖了当前登录账号。

命令

命令	功能
zektor try	创建一个可用一小时的 Postgres 数据库，无需账号（见下文）
zektor login	为此机器保存令牌
zektor logout	删除已保存的令牌。不会撤销令牌——同一个令牌可能还在其他地方使用。前往 Settings 撤销令牌以终止其访问权限。
zektor whoami	显示账号、API URL 和令牌来源
zektor list	列出你的实例
zektor show <id>	显示一个实例
zektor db create / zektor cache create	配置数据库或缓存
zektor delete <id>	删除实例。系统会要求你输入实例名称；使用 --yes 可跳过确认。
zektor connect <id>	使用 redis-cli 连接缓存
zektor scale <id> --tier=…	将实例切换到其他方案
zektor storage show|resize|autoscale <id>	Postgres 存储：查看费用、扩容并设置自动扩容（见下文）
zektor mcp	作为 MCP 服务运行，让编辑器或 Agent 调用 API（见下文）

所有读取命令都支持 --json。

无需账号即可试用

psql "$(npx zektor try)"

zektor try 会将连接字符串输出到 stdout，并在 stderr 中显示有效时长和认领链接。数据库可接受连接 60 分钟。在 3 小时内打开认领链接、注册并添加付款方式后，数据会迁移到你自己的数据库中；否则数据将被删除。最多支持 200 MB 和 3 个连接，不提供超级用户权限（pgcrypto 等可信扩展可用），每个网络每天可试用 3 次。--json 会将所有信息以 JSON 格式输出。无需 CLI 也可以使用相同功能：

curl -X POST https://api.zektor.io/api/trial

创建

zektor db create --name=my-db --tier=AKPG-5 --region=nbg1 --engine=postgres@17

--tier、--region 和 --engine 可使用你在控制面板中看到的名称，系统会自动将其解析为 ID。--tier 和 --region 为必填项；若缺少其中一项或输入无效，错误信息会列出有效值。

创建任务会在后台运行。添加 --wait 可阻塞命令，直到实例就绪；如果创建失败，命令会说明原因并以非零状态码退出。

不接受 --storage：存储空间初始为方案包含的容量。之后可使用 zektor storage resize 扩容。

连接

对于缓存，connect 会打开 redis-cli。对于 Postgres，它只会打印命令格式——创建或轮换角色时，密码只会显示一次，服务端也不会存储该密码，因此 CLI 无法获取凭据。

请先在控制面板中创建或轮换角色。

扩展与存储

zektor scale 42 --tier=AKPG-10
zektor storage show 42
zektor storage resize 42 --size=50
zektor storage autoscale 42 --on --limit=100

scale 会要求你输入实例名称，因为它会重启实例；--yes 则会跳过此步骤。降级时会提示较小规格的内存少于实例可能正在使用的内存。当目标规格包含的存储少于数据库当前计费的存储时，scale 也会说明差额费用，无论是否使用 --yes。

scale 和 storage resize 也会在后台运行，并支持 --wait：此选项会阻塞，直到变更完成；若失败，则会打印原因并以非零状态退出。不使用此选项时，扩展失败很容易被忽略，因为实例会继续使用原规格。

存储仅适用于 PostgreSQL——缓存的大小由其规格决定，因此请使用 scale。

• 包含的存储。 每种规格都包含存储：AKPG-5 到 AKPG-40 包含 5 GB，AKPG-80、160 和 320 分别包含 10、20 和 40 GB。新数据库会从对应的存储量开始。
• 扩容。 storage resize 可随时扩容，最高可达 1000 GB。扩容在线进行，无需重启，并会在标准错误流中打印新容量的费用。
• 无法缩容。 存储只增不减。你、规格变更或恢复操作都无法缩小存储。要减少费用，唯一的方法是将数据 pg_dump 到新数据库，然后删除旧数据库。
• 价格。 超出规格包含量的部分按每月每 GB 净价 €0.15 计费，以整 GB 为单位，并像规格费用一样按小时折算。费用按容量而非使用量计算：删除行只会释放空间，不会减少费用。storage show 会显示当前计费容量。
• 付款。 扩容至超过规格所含容量，或启用自动扩容，都需要付款方式或账户余额。
• 自动扩容需主动启用，并且上限必须高于当前容量：storage autoscale 42 --on --limit=100。容量达到 80% 时，会扩容至增加 5 GB 或达到 70% 满载所需容量这两者中的较大值，但不会超过上限。每次扩容都是永久的，按手动扩容的方式计费，并且每次都会通知你。自动扩容失败后，会等待一天再试。设置上限后无法清除，因为 API 会将未提供的值视为“保持不变”；请设置新的数值，或使用 --off 关闭扩容。
• 规格变更。 升级到包含更多存储的规格时，存储容量会免费提升至该规格的容量。降级时会保留现有存储，超出较小规格容量的部分需付费。
• 分支。 分支处于分支状态期间，按其规格计费；此外，分支自身写入的数据若超出其规格包含的存储，也会计费。提升为主实例后，则按完整容量计费；该容量为创建分支时源实例的容量（若后来扩容，则按更大容量计算）。
• 旧版数据库。 在支持存储扩容之前创建的数据库目前还不能扩容。它们很快就会迁移，并且绝不会产生存储费用。

1.7.0 版本变更。 storage resize 现在通过 /api/instances/{id}/storage/grow 扩容，并会拒绝不大于当前容量的值。storage autoscale 仍接受 --min 和 --up-only，但会忽略它们。MCP 工具 resize_storage 现在要求提供 confirm_name。

MCP 服务

zektor mcp 通过标准输入/输出使用 Model Context Protocol，因此编辑器或 Agent 可以直接列出、创建和扩展实例。它会使用你已登录的令牌，无需额外设置。

将其添加到 MCP 客户端的配置中：

{
  "mcpServers": {
    "zektor": { "command": "npx", "args": ["-y", "zektor", "mcp"] }
  }
}

对于 Claude Code，执行 claude mcp add zektor -- npx -y zektor mcp 即可实现相同效果。

工具

工具
create_trial_database	仅当未配置令牌时可用：提供一个免费数据库，有效期为一小时，并附带可提供给用户的领取链接
whoami、list_instances、get_instance	只读
get_action	只读；根据 create_instance、scale_instance 或 resize_storage 返回的 actionId，查看其启动的后台任务进展如何
list_plans、list_regions	只读；创建之前先调用这些工具，而不是猜测名称
get_connection	只读；会返回缓存的实时密码
get_storage	只读，适用于 PostgreSQL；查看大小、用量，以及超出套餐部分的计费情况
create_instance	需要付费
scale_instance	会改变账单；缩容可能导致实例内存不足，并保留其存储，超出较小套餐的存储部分按 GB 计费
resize_storage	适用于 PostgreSQL；扩充存储，且无法撤销；超出套餐的部分按 GB 计费
set_autoscale	适用于 PostgreSQL；开启或关闭自动扩容，并设置上限
delete_instance	默认禁用——见下文

防护措施

CLI 通过提示来防止误删：要求你在终端输入实例名称。MCP 服务没有终端，其调用方是模型，因此这里采用了等效的防护措施，而不是直接省略。

• 只有设置了 ZEKTOR_MCP_ALLOW_DESTRUCTIVE=1，才会注册 delete_instance。 默认情况下，工具根本不会出现在列表中，因此即使指令被误解或遭到注入，最坏也只是花钱，不会丢失数据。
• scale_instance、resize_storage 和 delete_instance 都要求提供 confirm_name 参数，且必须与实例的真实名称一致。只有实际查找过该实例，才能填入此参数；这正是输入名称提示所具备的保障。
• 每个工具都带有协议的 readOnlyHint / destructiveHint 注解，因此会在执行工具前征求确认的客户端，会针对正确的工具进行确认。

get_connection 值得单独说明：对于缓存，它会返回一个包含实时密码的连接字符串，这意味着密码会进入模型的上下文。这正是该工具的用途——让 Agent 能将应用连接到新缓存——但在某处启用会记录对话的服务之前，值得了解这一点。

诊断信息

服务启动时会将其 API URL、令牌的查找位置，以及是否启用了删除功能写入 stderr；MCP 客户端会将其收集为服务日志。如果服务指向了错误的 API，在查看这些日志之前，它看起来就像是坏掉了一样。

输出

stdout 只承载数据，不输出其他内容。 进度信息、警告和错误都会写入 stderr，因此管道保持干净：

zektor whoami --json | jq -r .email

发生故障时会以非零状态码退出，因此 zektor … && next-command 会停止执行，不会在 shell 没有察觉的错误之后继续运行。

配置

变量	用途
ZEKTOR_TOKEN	访问令牌。优先于配置文件。
ZEKTOR_API_URL	API 基础 URL。默认为 https://api.zektor.io。
XDG_CONFIG_HOME	设置后会遵循此变量；配置文件位于 $XDG_CONFIG_HOME/zektor/ 下。
ZEKTOR_MCP_ALLOW_DESTRUCTIVE	设置为 1，即可在 MCP 服务上注册 delete_instance。未设置时，该工具不存在。

路线图

接下来将开发以下功能，大致按使用频率排序：

• 备份——列出、触发备份，并还原到某个时间点
• 角色——创建和轮换 Postgres 凭据，这也能让 connect 支持 Postgres，而不只是打印操作说明
• 日志——实时查看实例日志；这是目前唯一需要打开浏览器才能完成的事

暂不计划支持管理员命令。管理控制台特意设计为只能通过浏览器访问。

开发

npm install
npm run gen:api     # regenerate types/api.d.ts from the API's OpenAPI document
npm run build
node dist/index.js whoami

将整个项目指向本地 API：ZEKTOR_API_URL=http://localhost:5098， MCP 服务也不例外 — ZEKTOR_API_URL=http://localhost:5098 node dist/index.js mcp 会连接到你的开发后端，而不是生产环境。

npm run gen:api 会将 API 的完整 OpenAPI 类型写入 types/，该目录已被 gitignore 忽略 — 这些类型描述了包括管理端接口在内的每个端点， 但没有任何代码会导入它们。这个工具用于检查 src/api.ts 中的手写接口 是否符合实际契约，而不是作为构建输入。使用 ZEKTOR_API_URL=http://localhost:5098 npm run gen:api 将其指向本地 API。