用户手册：让你的网站动起来

纯 HTML 没法存数据？现在每个部署到本平台的静态站都自带一个 KV 数据空间——相当于给你的静态站配了一个轻量后端数据库。访客的浏览器可以直接读取，写入只需在请求里带上你的"写令牌"。

一、拿到你的写令牌

进入「编辑网站」页面，找到 KV 数据空间 区块：

• 框里就是本站点的写令牌（只读，别泄露给不该写的人）；
• 点"复制"把它用到站点 JS 里；
• 怀疑泄漏时点"重新生成写令牌"，旧令牌立刻失效。

读是公开的（任何人都能读），写才需要令牌。所以令牌只决定"谁能改数据"，不决定"谁能看"。

二、读取（公开，无需令牌）

列出本站全部数据，或按前缀筛选（做"数据表" / 排行榜）：

// 列出全部
const all = await (await fetch('/api/site/gomoku/kv')).json();
// 按前缀筛选（例如所有分数）
const scores = await (await fetch('/api/site/gomoku/kv?prefix=score:')).json();
// 读取单个键
const { v } = await (await fetch('/api/site/gomoku/kv/theme')).json();

把上面所有 gomoku 换成你自己站点的 path_name（站点 URL 里 /<path_name>/ 那段）。

三、写入（带写令牌）

const TOKEN = '你的写令牌';
await fetch('/api/site/gomoku/kv/theme', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json', 'X-Site-Token': TOKEN },
  body: JSON.stringify({ v: '#3b82f6' })   // 字符串/对象/数字都行，自动 JSON 化
});

// 带 1 小时过期时间
await fetch('/api/site/gomoku/kv/temp', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json', 'X-Site-Token': TOKEN },
  body: JSON.stringify({ v: 'x', ttl: 3600 })
});

删除：DELETE /api/site/gomoku/kv/<key>（同样带令牌）。

四、原子自增（计数器 / 积分 / 排行榜）

避免"读-改-写"并发丢更新，直接让服务端加：

// 总访问量 +1
await fetch('/api/site/gomoku/kv/visits/incr', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Site-Token': TOKEN },
  body: JSON.stringify({ amount: 1 })
});

// 给某玩家分数 +10（对 JSON 对象的 score 字段自增）
await fetch('/api/site/gomoku/kv/rank:alice/incr', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Site-Token': TOKEN },
  body: JSON.stringify({ amount: 10, field: 'score' })
});

读出来排序即可做排行榜：

const list = await (await fetch('/api/site/gomoku/kv?prefix=rank:')).json();
list.items.sort((a, b) => JSON.parse(b.v).score - JSON.parse(a.v).score);

五、能拿来做什么

• 注册 / 登录：以 user:用户名 为键存用户记录（注意：纯前端校验安全性有限，敏感信息勿明文存储）。
• 数据统计：visits 自增做访问量、点赞数。
• 排行榜：rank:<id> 存 { score }，前缀列举 + 客户端排序。
• 留言 / 评论：msg:<时间戳> 存每条留言，前缀列举展示。
• 草稿 / 偏好：draft:xxx 存未发布内容，theme 存主题色。

六、注意

• 键长度上限 191 字符；单次列举最多 2000 条。
• 跨站隔离：每个站点独立命名空间，A 站读不到 B 站的数据。
• 自定义域名的站点也能跨域调用（接口已带 CORS 头）。

这样你的静态站就有"记忆"了——去试试吧。