render-keyvalue

Render 键值存储

Render 键值存储提供低延迟、兼容 Redis 的内存存储，运行 Valkey 8。可将其用作共享缓存、会话存储或作业队列后端。几乎兼容所有 Redis 客户端库。

适用场景

• 为 Web 应用添加缓存或会话存储
• 为 Celery、Sidekiq、BullMQ、Asynq 或 Oban 配置作业队列后端
• 选择合适的 maxmemory 策略（缓存还是队列）
• 在 Blueprints 中配置 ipAllowList（必填字段）
• 通过内部或外部 URL 连接
• 排查身份验证失败或连接被拒绝错误

有关后台工作进程设置和队列框架模式，请参阅 render-background-workers。有关 Blueprint 编写，请参阅 render-blueprints。

在配置或排查内部 Key Value 连接之前，请阅读 references/private-networking.md。

核心概念

Valkey 8（而非 Redis）

新实例运行 Valkey 8，这是一个开源的 Redis 分支。它可直接替代 Redis，现有 Redis 客户端库无需修改即可使用。旧版实例（在 2025 年 2 月之前创建）运行 Redis 6。

连接 URL

每个实例都有两个 URL：

URL 类型	使用场景	是否需要身份验证
内部（redis://red-xxx:6379）	来自同一工作区和区域中的 Render 服务	否（默认）
外部（rediss://red-xxx:6379）	从 Render 外部连接（本地开发、CI）	始终需要

生产服务应始终优先使用内部 URL：延迟更低、无需承担 TLS 开销，并通过专用网络通信。

外部连接默认禁用。在 Dashboard 的访问控制列表中添加 IP 范围即可启用。

内部身份验证

默认情况下，内部连接无需身份验证。你可以在 Dashboard 中要求内部连接进行身份验证，以满足合规要求或增强安全性。这样会使内部 URL 包含凭据：

redis://default:PASSWORD@red-xxx:6379

**警告：**启用内部身份验证会导致现有的未认证连接失效。请先将客户端迁移到经过身份验证的 URL。

Maxmemory 策略

**这是关键决策。**请根据使用场景选择：

使用场景	策略	原因
缓存（可丢失数据）	allkeys-lru	淘汰最近最少使用的键以释放空间
作业队列（不可丢失数据）	noeviction	内存满时写入会返回错误；永不丢弃键
会话存储	allkeys-lru 或 volatile-lru	会话可以重新生成；使用 LRU 是安全的

所有可用策略：

策略	行为	内存会被占满吗？
allkeys-lru	按 LRU 淘汰任意键	否
noeviction	内存满时写入会返回错误	是
volatile-lru	按 LRU 淘汰带有 TTL 的键	是
volatile-lfu	按 LFU 淘汰带有 TTL 的键	是
allkeys-lfu	按 LFU 淘汰任意键	否
volatile-random	随机淘汰带有 TTL 的键	是
allkeys-random	随机淘汰任意键	否
volatile-ttl	淘汰即将过期的键	是

Blueprint 配置

services:
  - type: keyvalue
    name: cache
    plan: starter
    region: oregon
    maxmemoryPolicy: allkeys-lru
    ipAllowList: []

必须设置 ipAllowList

Blueprint 中的 Key Value 服务必须包含 ipAllowList。常见模式：

值	含义
[]	不允许外部访问（仅内部访问——大多数应用推荐此设置）
[{source: "0.0.0.0/0", description: "everywhere"}]	开放外部访问（谨慎使用）
[{source: "203.0.113.0/24", description: "office"}]	指定 IP 范围

配置服务连接

使用 fromService，并设置 type: keyvalue 和 property: connectionString：

envVars:
  - key: REDIS_URL
    fromService:
      name: cache
      type: keyvalue
      property: connectionString

Key Value 可用的 fromService 属性：

属性	值
connectionString	完整的内部 URL（redis://red-xxx:6379）
host	仅主机名
port	仅端口（通常为 6379）

数据持久化

• **付费实例：**基于磁盘持久化，appendfsync everysec。中断时最多可能丢失 1 秒内的写入。
• **免费实例：**不进行磁盘持久化。重启或升级时数据会丢失。
• **从免费实例升级：**升级期间所有数据都会丢失，因为免费实例没有磁盘。

计算方案与变更

计算方案决定可用内存和连接限制。当前 Plan ID 和 Key Value 特定的变更指南请参阅 references/compute-plans.md。

连接示例

客户端代码示例请参阅 references/connection-examples.md，涵盖 Node.js（ioredis、node-redis）、Python（redis-py）、Ruby（redis-rb、Sidekiq）和 Go。

常见错误

错误	修正方法
Blueprint 中缺少 ipAllowList	添加 ipAllowList: [] 以仅允许内部访问
对作业队列使用 allkeys-lru	改为 noeviction——LRU 驱逐会丢弃排队的作业
从 Render 服务使用外部 URL 连接	使用内部 URL，以降低延迟且无需身份验证
忘记在 fromService 中设置 type: keyvalue	type 为必填项；缺少它会导致连接配置失败
使用已弃用的 redis 类型别名	新建 Blueprint 时优先使用 keyvalue（redis 仍可用，但已弃用）

参考资料

文档	内容
references/compute-plans.md	当前 Plan ID、规格、可用性及 Key Value 方案变更
references/private-networking.md	当前私有网络范围、内部寻址、隔离和故障排除
references/connection-examples.md	Node.js、Python、Ruby、Go 的客户端代码
references/troubleshooting.md	身份验证错误、连接被拒绝、内存已满、从 Redis 6 迁移

相关技能

• render-background-workers — 使用 Celery、Sidekiq、BullMQ 设置队列消费者
• render-blueprints — 完整的 render.yaml 架构、fromService 模式
• render-networking — 私有网络、内部 URL
• render-env-vars — 配置 REDIS_URL 和其他连接变量

当前文档检索

每当此技能要求你查阅当前的 Render 文档时：

1. 使用可用的 URL 获取工具或 HTTP 客户端（例如 curl）直接检索链接的 Markdown 文档。不要用网页搜索摘要代替文档。
2. 确认检索成功且返回了预期文档，然后阅读其内容。仅保存文件或打印文件路径并不足够。
3. 如果请求失败或工具无法读取 Markdown 响应，请打开并阅读链接的 HTML 版本。
4. 如果两个版本都无法检索，请说明当前参考资料不可用，并遵循技能中针对该主题的后备方案。仅对稳定约束使用随附指南，不要猜测可能变化的平台细节。

当任务需要多个参考资料时，对每份资料分别执行此流程，并区分已验证的文档与仍不可用的文档。