← 返回 KMS 管理后台 Cloudflare Pages + D1 轻量密钥管理

KMS 使用文档

这个 KMS 用来保存 token、密码、SSH key、2FA/TOTP 等敏感信息。敏感字段会在服务端用 AES-GCM 加密后写入 D1，查询时按权限解密返回。

打开管理后台查看 2FA 接口

核心概念 后台使用 查询接口 API v1 读写 2FA/TOTP Enpass 导入导出 API Key / Scope 审计与版本 安全建议

1. 核心概念

字段说明例子
primary唯一服务名 / 主搜索名。接口通常用它定位一条密钥。github、cloudflare-pages
category分类，用来筛选和模板化字段。github、cloudflare、ssh
aliases别名，支持模糊搜索。git、主账号
tags标签，便于组织。prod、deploy
description非敏感说明，明文保存。Cloudflare Pages 部署 token
key_data真正的敏感内容，整块加密保存。{"token":"...","2fa":"..."}

2. 后台使用

  1. 打开 KMS 管理后台。
  2. 输入管理员密码登录。
  3. 在「密钥」里新增或编辑 secret。
  4. 在 key_data 里填写敏感字段，例如 token、password、private_key、2fa。
  5. 保存后可以用管理后台或 API 查询。
注意：管理后台会展示解密后的敏感字段。只在可信设备和网络中使用。

3. 查询接口

查询接口支持两种鉴权方式：

按 primary 精确查询

curl "https://kms-admin-4lo.pages.dev/api/query?primary=github" \
  -H "Authorization: Bearer $KMS_API_KEY"

模糊搜索

curl "https://kms-admin-4lo.pages.dev/api/query?search=git" \
  -H "Authorization: Bearer $KMS_API_KEY"

模糊搜索并展开明文 key_data

curl "https://kms-admin-4lo.pages.dev/api/query?search=git&expand=true" \
  -H "Authorization: Bearer $KMS_API_KEY"

按分类查询

curl "https://kms-admin-4lo.pages.dev/api/query?category=cloudflare" \
  -H "Authorization: Bearer $KMS_API_KEY"

4. API v1 读写接口

新接口更适合脚本和自动化。支持 API Key 读写，不必登录后台。

鉴权

Authorization: Bearer $KMS_API_KEY
# 或
X-API-Key: $KMS_API_KEY

写入 / 新建 secret

curl -X POST "https://kms-admin-4lo.pages.dev/api/v1/secrets" \
  -H "Authorization: Bearer $KMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "primary": "github",
    "category": "github",
    "aliases": ["git"],
    "tags": ["prod"],
    "description": "GitHub 主账号",
    "key_data": {
      "user": "ziren28",
      "token": "github_pat_xxx",
      "2fa": "JBSWY3DPEHPK3PXP"
    }
  }'

Upsert 覆盖写入

curl -X PUT "https://kms-admin-4lo.pages.dev/api/v1/secrets" \
  -H "Authorization: Bearer $KMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"primary":"docker","category":"docker","data":{"user":"me","pat":"xxx"}}'

单值快捷写入

curl -X PUT "https://kms-admin-4lo.pages.dev/api/v1/secrets" \
  -H "Authorization: Bearer $KMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"primary":"my-token","category":"api","value":"secret-value"}'

读取完整 secret

curl "https://kms-admin-4lo.pages.dev/api/v1/secrets/github" \
  -H "Authorization: Bearer $KMS_API_KEY"

只读取某个字段

curl "https://kms-admin-4lo.pages.dev/api/v1/secrets/github?fields=key_data.token" \
  -H "Authorization: Bearer $KMS_API_KEY"
# 返回：{"value":"github_pat_xxx"}

读取多个字段

curl "https://kms-admin-4lo.pages.dev/api/v1/secrets/github?fields=primary,category,key_data.user" \
  -H "Authorization: Bearer $KMS_API_KEY"

快速列出所有密钥名称

用于先看 KMS 里到底有哪些 primary，快速检索，不解密、不返回 key_data，更安全也更快。

curl "https://kms-admin-4lo.pages.dev/api/v1/secrets/names" \
  -H "Authorization: Bearer $KMS_API_KEY"

# 搜索 / 按分类过滤
curl "https://kms-admin-4lo.pages.dev/api/v1/secrets/names?search=cloudflare&category=cloudflare&limit=50" \
  -H "Authorization: Bearer $KMS_API_KEY"

# 返回：
# {
#   "names": ["cloudflare-pages", "cloudflare-api"],
#   "items": [{"primary":"cloudflare-pages","category":"cloudflare","aliases":[],"tags":["deploy"]}],
#   "total": 2
# }

只读元数据，不返回敏感 key_data

curl "https://kms-admin-4lo.pages.dev/api/v1/secrets/github?reveal=false" \
  -H "Authorization: Bearer $KMS_API_KEY"

局部更新 key_data

curl -X PATCH "https://kms-admin-4lo.pages.dev/api/v1/secrets/github" \
  -H "Authorization: Bearer $KMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":{"2fa":"JBSWY3DPEHPK3PXP"}}'

删除

curl -X DELETE "https://kms-admin-4lo.pages.dev/api/v1/secrets/github" \
  -H "Authorization: Bearer $KMS_API_KEY"

5. 2FA / TOTP 接口

接口地址：GET /api/totp。返回当前验证码和过期时间。

方式 A：直接携带 2FA secret

curl "https://kms-admin-4lo.pages.dev/api/totp?2fa=JBSWY3DPEHPK3PXP" \
  -H "Authorization: Bearer $KMS_API_KEY"

方式 B：不携带 2FA，指定服务名

例如 service=github，KMS 会查 primary=github 的记录，并从 key_data 里读取 2FA 字段。

curl "https://kms-admin-4lo.pages.dev/api/totp?service=github" \
  -H "Authorization: Bearer $KMS_API_KEY"

支持的 2FA 字段名

2fa 2fa_secret totp otp otp_secret two_factor two_factor_secret

返回示例

{
  "service": "github",
  "source": "kms",
  "code": "123456",
  "period": 30,
  "expires_in": 18,
  "expires_at": 1778484620,
  "authorized_via": "api_key"
}

字段说明

字段说明
code当前 6 位验证码。
expires_at验证码过期的 Unix 秒时间戳。
expires_in距离过期还剩多少秒。
periodTOTP 周期，默认 30 秒。
sourcedirect 表示直接传 secret，kms 表示从 KMS 服务记录读取。

6. Enpass CSV 导入 / 导出

导入

  1. 在 Enpass 里导出 CSV。
  2. 打开 KMS 后台 →「导入/导出」。
  3. 粘贴 CSV 内容。
  4. 选择冲突策略：跳过、覆盖、自动重命名。
  5. 先预览，再确认导入。

导出

点击「下载 Enpass CSV」。导出文件包含明文密码和 TOTP，请妥善保存，用完删除。

安全提醒：CSV 是明文格式，不建议长期存放。

7. API Key 管理 / Scope 权限

API Key 用于自动化脚本访问查询接口，不建议把管理员密码写进脚本。现在支持 scope、资源限制、过期时间、禁用检测。

创建带最小权限的 API Key

curl -X POST "https://kms-admin-4lo.pages.dev/api/apikeys" \
  -H "Authorization: Bearer ADMIN_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-read-github",
    "scopes": ["secret:read", "totp:read"],
    "categories": ["github"],
    "primaries": ["github-*"],
    "expires_at": 1799999999
  }'

支持的 scope

secret:read secret:write secret:delete totp:read export:read admin:*

API Key 有效检测

curl "https://kms-admin-4lo.pages.dev/api/apikeys/verify" \
  -H "Authorization: Bearer $KMS_API_KEY"
# 返回 valid、api_key_id、scopes、resources；过期或禁用会返回 401

旧 API Key 没有 scope 字段时，按 admin:* 兼容处理。新建 Key 建议只给最小权限。

8. 审计日志与 Secret 版本历史

审计日志

API v1 的读取、列表、写入、更新、删除都会写入 audit_logs。记录 actor、action、primary、IP、User-Agent、成功状态和脱敏 metadata。

audit_logs 字段：
id, actor_type, actor_id, action, primary_key, ip, user_agent, success, metadata, created_at

版本历史

PUT 覆盖、PATCH 更新、DELETE 删除前，会把旧版本保存到 secret_versions，便于追溯和后续回滚。

curl "https://kms-admin-4lo.pages.dev/api/v1/secrets/github/versions" \
  -H "Authorization: Bearer $KMS_API_KEY"

# 默认不返回明文 key_data；如确需查看历史明文：
curl "https://kms-admin-4lo.pages.dev/api/v1/secrets/github/versions?reveal=true" \
  -H "Authorization: Bearer $KMS_API_KEY"

9. 安全建议