KV 存储管理 API

# 必需：KV 命名空间绑定名（必须与EO KV的命名空间 一致）
KV_NAMESPACE_BINDING=xxxxxx

# 可选：长期管理令牌（用于写操作鉴权）
KV_ADMIN_TOKEN=your_secret_token_here_at_least_32_characters

# 可选：TOTP 2FA 密钥（Base32 编码）
# 注意：至少需要配置上面两个中的一个
TOTP_SECRET=your_totp_secret

# Linux/Mac
openssl rand -base64 32

# Windows (PowerShell)
$bytes = [byte[]]::new(32)
$random = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$random.GetBytes($bytes)
[Convert]::ToBase64String($bytes)

# Linux/Mac
openssl rand -base64 20 | base32 | head -c 32

# Windows (PowerShell)
$bytes = [byte[]]::new(15)
$random = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$random.GetBytes($bytes)
# 使用在线 Base32 编码工具或以下命令：
# [Convert]::ToBase64String($bytes) | Out-Host

# 开发环境（使用 .env.local）
wrangler dev --env development

# 生产环境
wrangler deploy --env production

# .env.local
KV_NAMESPACE_BINDING=phira_web

# .env.local
KV_ADMIN_TOKEN=dadwadwadwadwadwa

# 特点：
# - 固定令牌，长期有效
# - 使用简单
# - 需要定期轮换（建议每 90 天）

# .env.local
TOTP_SECRET=dwadwadwadwadwadwadawdwa

# 特点：
# - 每 30 秒变换一次验证码
# - 更加安全
# - 需要认证器应用

# .env.local
KV_ADMIN_TOKEN=ddawdadwadwadwa
TOTP_SECRET=dawdwadwadwadwadwadwadwa

# 好处：
# - 提供多种认证选择
# - 增强安全性
# - 易于令牌轮换

GET /kv-admin/list

{
  "complete": true,
  "cursor": null,
  "keys": [
    {"key": "faq"},
    {"key": "announcement"},
    {"key": "server"}
  ]
}

GET /kv-admin/get?key=test_key&type=text

{
  "key": "test_key",
  "value": "test_value",
  "type": "text",
  "size": 10
}

{
  "key": "config",
  "value": {
    "setting1": "value1",
    "setting2": "value2"
  },
  "type": "json",
  "size": 45
}

PUT /kv-admin/put
Content-Type: application/json
Authorization: Bearer <token>

{
  "key": "test_key",
  "value": "test_value"
}

# 方式 1：Authorization Header（推荐）
Authorization: Bearer your_secret_token_here

# 方式 2：Query Parameter
?token=your_secret_token_here

{
  "success": true,
  "message": "Key 'test_key' updated successfully"
}

DELETE /kv-admin/delete
Content-Type: application/json
Authorization: Bearer <token>

{
  "key": "test_key"
}

{
  "success": true,
  "message": "Key 'test_key' deleted successfully"
}

curl -X PUT "https://your-domain.com/kv-admin/put" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer a7f3K9xR2mQ8nB4pL6vJ5wC+D/E=" \
  -d '{"key": "test", "value": "hello"}'

curl -X PUT "https://your-domain.com/kv-admin/put" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 123456" \
  -d '{"key": "test", "value": "hello"}'

# 或使用查询参数
curl -X PUT "https://your-domain.com/kv-admin/put?token=123456" \
  -H "Content-Type: application/json" \
  -d '{"key": "test", "value": "hello"}'

curl -X GET "https://your-domain.com/kv-admin/list"

curl -X GET "https://your-domain.com/kv-admin/list?prefix=config&limit=50"

curl -X GET "https://your-domain.com/kv-admin/get?key=announcement"

curl -X GET "https://your-domain.com/kv-admin/get?key=config&type=json"

curl -X PUT "https://your-domain.com/kv-admin/put" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secret_token_here" \
  -d '{"key": "news", "value": "Hello World"}'

curl -X DELETE "https://your-domain.com/kv-admin/delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 123456" \
  -d '{"key": "old_news"}'

const API_BASE = 'https://your-domain.com/kv-admin';
const ADMIN_TOKEN = 'your_secret_token_here'; // 或 6 位 TOTP 码

// 列出所有键
async function listKeys(prefix = '', limit = 256) {
  const url = new URL(`${API_BASE}/list`);
  if (prefix) url.searchParams.set('prefix', prefix);
  url.searchParams.set('limit', limit);
  
  const response = await fetch(url);
  return await response.json();
}

// 读取键值
async function getKey(key, type = 'text') {
  const url = new URL(`${API_BASE}/get`);
  url.searchParams.set('key', key);
  url.searchParams.set('type', type);
  
  const response = await fetch(url);
  return await response.json();
}

// 写入/更新键值
async function putKey(key, value, token = ADMIN_TOKEN) {
  const response = await fetch(`${API_BASE}/put`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ key, value })
  });
  return await response.json();
}

// 删除键值
async function deleteKey(key, token = ADMIN_TOKEN) {
  const response = await fetch(`${API_BASE}/delete`, {
    method: 'DELETE',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ key })
  });
  return await response.json();
}

// 使用示例
(async () => {
  // 列出所有键
  const keys = await listKeys();
  console.log('所有键:', keys);
  
  // 读取特定键
  const data = await getKey('announcement', 'json');
  console.log('公告数据:', data);
  
  // 写入新键
  const result = await putKey('test', 'Hello World');
  console.log('写入结果:', result);
})();

{
  "error": "Configuration error",
  "message": "Environment variable \"KV_NAMESPACE_BINDING\" is not configured. Please set it to the name of your KV namespace binding (e.g., \"phira_web\")"
}

{
  "error": "KV namespace not found",
  "message": "KV binding 'phira_web' specified in KV_NAMESPACE_BINDING is not bound in wrangler.toml. Please check your configuration."
}

{
  "error": "Unauthorized",
  "message": "Valid admin token required for write operations"
}

{
  "error": "Key and value are required"
}

{
  "error": "Key not found",
  "message": "Key 'test_key' does not exist in KV storage"
}

{
  "error": "Method not allowed"
}

# 复制示例文件
cp .env.example .env.local

# 编辑 .env.local
KV_NAMESPACE_BINDING=xxxxxx

# Linux/Mac
openssl rand -base64 20 | base32 | head -c 32

# 或使用 Python
python3 -c "import os, base64; print(base64.b32encode(os.urandom(20)).decode())"

# 删除 Git 历史中的 .env 文件（使用 git-filter-repo）
git filter-repo --path .env --invert-paths

# 或添加到 .gitignore 后强制更新
echo ".env" >> .gitignore
git rm --cached .env
git commit -m "Remove .env from tracking"

KV存储/
├── README.md                          # 本文件
├── .env.example                       # 环境变量示例（提交到 Git）
├── .env.local                         # 本地开发环境（不提交）
├── .gitignore                         # Git 忽略规则（保护 .env 文件）
├── index.html                         # 前端管理界面
├── api/
│   ├── kv/
│   │   └── [key]/
│   │       └── route.ts              # Next.js 开发路由
│   └── kv-admin/
│       └── [action]/
│           └── route.ts              # Next.js 开发路由
└── functions/
    └── api/
        ├── kv/
        │   └── [key].js              # EdgeOne Edge Function
        └── kv-admin/
            └── [action].js           # EdgeOne Edge Function