K/V

一个托管的键值存储，每个项目一个，运行在自己的单元中：独立的进程、独立的内存上限、独立的存储。它由 Valkey 驱动，支持两种协议——HTTPS 之上的 Upstash REST 协议，以及 TLS 之上的 RESP——因此你手上已有的客户端都能使用：REST 客户端用默认设置即可，RESP 客户端只要把主机名作为 TLS 服务器名称发送就行。

它面向那些需要计数器而不是表的工作：限流、会话、队列、功能开关、短生命周期的缓存。这些 Postgres 都能做，只是没有一样能做得这么便宜。

这就是全部的集成工作。两个环境变量，加上你的框架本来就预期的限流器；除了凭据的来源之外，这里没有任何 CapyDB 特有的东西。

import { Ratelimit } from '@upstash/ratelimit'
import { Redis } from '@upstash/redis'

const ratelimit = new Ratelimit({
  redis: new Redis({
    url: process.env.CAPYKV_REST_URL!,
    token: process.env.CAPYKV_REST_TOKEN!,
  }),
  limiter: Ratelimit.slidingWindow(10, '10 s'),
})

export async function POST(request: Request) {
  const { success } = await ratelimit.limit(userIdFrom(request))
  if (!success) return new Response('Too many requests', { status: 429 })
  // ...
}

K/V 是一项独立的功能，不是拧在数据库上的附件。你可以添加一个存储，然后从不打开旁边的数据库：不用设计模式，不用配置连接串，不用执行迁移。很多应用只想要一个限流器，别的都不需要，而这就是使用 CapyDB 的一种完整方式。

存储仍然归属于某个项目，因为项目是 CapyDB 划分计费、访问权限和区域的单位。项目会保留一个数据库单元，你尽可以忽略它——把项目设为非生产后，闲置的单元会自动暂停，不消耗任何资源。

K/V 存储就是一个单元，与数据库获得的运行时原语完全相同。这不是对共享服务器中某个命名空间的比喻：

• -独立的进程，内存上限和 CPU 份额由内核强制执行——邻居无法耗尽你的内存。
• -独立的存储、独立的凭据、独立的套接字。没有共享实例，也没有可能发生冲突的公共键空间。
• -只能通过经过认证的端点访问。存储本身既没有通往公网的路由，也没有通往你数据库的路由。

两种协议都是标准协议，因此迁移过来只需要改一个 URL 和一个令牌：

• -Upstash REST 协议，包括流水线、事务和 base64 编码——@upstash/redis 和 @upstash/ratelimit 在默认设置下即可工作。
• -TLS 之上的 RESP，面向常见的 Redis® OSS 客户端：ioredis、node-redis、redis-py、go-redis、redis-cli，阻塞命令和发布订阅也包括在内。端点按 TLS 服务器名称（SNI）路由：redis-py 和 go-redis 会自动发送，ioredis 需要 tls.servername，redis-cli 需要 --sni。
• -由 Valkey 驱动。Redis 是 Redis Ltd. 的注册商标；CapyDB 与 Redis Ltd. 无隶属关系，也未获得其背书。

K/V 按各套餐的规格包含在每个套餐中——没有单独的 K/V 订阅，也不按命令计费。下面的数字就是存储实际能装下的容量：

• -CapyDB Vibe: 32 MB
• -CapyDB Ship: 128 MB
• -CapyDB Business: 512 MB

K/V 存储会保留定期快照，因此能挺过一次重启，但它不是数据库。没有备份，没有时间点恢复，也没有副本；存储写满后，淘汰策略会丢弃键。

请把它当作快速且可丢弃的状态：计数器、会话、缓存、锁。任何丢失了会让你难受的数据，都应该放在旁边那个数据库单元里，那里确实有备份和时间点恢复。

在控制台中打开某个项目的 K/V 标签页并添加存储。它几秒钟内完成配置，并且只会向你出示一次端点和令牌——令牌仅以哈希形式保存，请当场复制。