> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Square Cloud 上的 Redis：连接、内存与持久化

> Square Cloud 上的托管 Redis：rediss:// TLS 连接、空闲超时、被禁用的命令、内置模块（Search、JSON、TimeSeries）、noeviction 内存策略、持久化以及常见错误。

一个通过 TLS 访问的托管 Redis 服务器，内置 Search、JSON、TimeSeries、概率数据结构和向量集合（vector set）模块。所有引擎共有的信息（限制、snapshot、Insights）请参阅[数据库概览](https://docs.squarecloud.app/zh/services/databases.md)。

## 连接

从控制台中该数据库的页面复制连接 URL：

```
rediss://default:PASSWORD@HOST:PORT
```

协议是 **`rediss://`**（两个 s）：服务器只接受 TLS，没有明文端口。不需要客户端证书；如需校验服务器，请将 **连接** → **SSL/TLS 证书** 中的 `.pem` 作为 CA。2026 年 9 月 29 日之前创建的数据库，保存下来的 URL 可能仍是 `redis://`：请将其改为 `rediss://`。

> [tab] node-redis
>
> ```javascript theme={"system"}
> import fs from "node:fs";
> import { createClient } from "redis";
>
> // One client for the whole process, created once and reused.
> export const redis = createClient({
>   url: process.env.REDIS_URL,
>   socket: { tls: true, ca: fs.readFileSync("certificate.pem", "utf8") },
>   pingInterval: 60_000, // keeps the connection from being closed as idle
> });
>
> redis.on("error", (err) => console.error("Redis error", err));
> await redis.connect();
> ```

> [tab] ioredis
>
> ```javascript theme={"system"}
> import fs from "node:fs";
> import Redis from "ioredis";
>
> export const redis = new Redis(process.env.REDIS_URL, {
>   tls: { ca: fs.readFileSync("certificate.pem", "utf8") },
> });
> ```

> [tab] Python
>
> ```python theme={"system"}
> import os
> import redis
>
> r = redis.from_url(
>     os.environ["REDIS_URL"],
>     ssl_ca_certs="certificate.pem",
>     health_check_interval=60,
> )
> ```

> [tab] redis-cli
>
> ```bash theme={"system"}
> redis-cli -u "rediss://default:PASSWORD@HOST:PORT" --tls --cacert certificate.pem
> ```

## 连接行为

* **空闲客户端会在 300 秒后被断开。** 请使用能自动重连的客户端（node-redis、ioredis 和 redis-py 都可以），或者像上面的示例那样定期发送 `PING`。
* **只有一个逻辑数据库（0）。** `SELECT 1` 或更大的编号会返回 `ERR DB index is out of range`：请改用键前缀（`cache:`、`session:`）来区分数据。
* 最多 256 个同时客户端；超过之后，新客户端会收到 `max number of clients reached`。请为每个进程创建一个客户端并重复使用。
* 身份验证使用 `default` 用户的密码。无法创建额外的 ACL 用户。

## 命令

所有数据命令都可用，Lua 脚本和 Functions、pub/sub、`MULTI`/`EXEC`、`SCAN` 和 `SLOWLOG` 也都可用。以下命令被禁用并返回 `NOPERM`：`FLUSHALL`、`FLUSHDB`、`SHUTDOWN`、`CONFIG`、`DEBUG`、`ACL`、`REPLICAOF`/`SLAVEOF` 和 `FAILOVER`。

没有 `CONFIG`，就无法修改淘汰策略和键空间通知。要清空数据库，请使用 `SCAN` 和 `UNLINK` 分批删除键：

```bash theme={"system"}
URL="rediss://default:PASSWORD@HOST:PORT"
redis-cli -u "$URL" --tls --cacert certificate.pem --scan --pattern 'cache:*' \
  | xargs -n 100 redis-cli -u "$URL" --tls --cacert certificate.pem UNLINK
```

## 内置模块

| 模块 | 命令 |
| :- | :- |
| Search and Query | `FT.*`（全文检索、二级索引、向量搜索） |
| JSON | `JSON.*` |
| TimeSeries | `TS.*` |
| 概率数据结构 | `BF.*`、`CF.*`、`CMS.*`、`TOPK.*`、`TDIGEST.*` |
| 向量集合（vector set） | `VADD`、`VSIM` 以及其他 `V*` 命令 |

搜索查询使用的线程数与数据库的 vCPU 数相同。

## 内存

* Redis 最多可以存放相当于**数据库 RAM 90%** 的数据。其余 10% 用于自身开销、客户端缓冲区以及保存数据时所需的空间。
* 策略为 **`noeviction`**：内存写满时不会淘汰任何数据。写入会失败并提示 `OOM command not allowed when used memory > 'maxmemory'`，而读取仍然正常，服务器也保持运行。
* 因此请**为缓存键设置过期时间**（`SET key value EX 3600`、`EXPIRE`），并按没有过期时间的数据量来确定 RAM 大小。
* 修改数据库的 RAM 会重启数据库。

## 大型回复

如果一个客户端未读取的回复超过 32 MB（或在 60 秒内持续高于 16 MB），它会被断开；对于 pub/sub 订阅者，限制为 32 MB 以及 60 秒内 8 MB。返回巨大回复的命令（例如 `KEYS *`，或对超大键执行 `HGETALL`/`SMEMBERS`）以及读取过慢的订阅者都会被切断。请改用 `SCAN`、`HSCAN` 和 `SSCAN` 进行迭代。

## 持久化

* **只要至少发生过一次写入，Redis 每 60 秒就会把数据保存到磁盘。** 没有 append-only 文件，因此崩溃或因内存不足而停止时，最多会丢失最近约 60 秒的写入。不能丢失的数据请同时保存在一个作为主记录的数据库中。
* 如果保存失败（存储已满，或内存不足以完成保存），写入会返回 `MISCONF`，直到某次保存成功为止，在此期间 snapshot 也会失败。保存时，当前数据文件旁边需要有大约与数据大小相当的空闲存储。

## 密码重置

重置密码会重启 Redis，因为它只在启动时读取密码：它会离线几秒钟，所有连接都会关闭。请在你的应用中更新 URL，并让它们重新连接。

## Snapshot

Redis 的 snapshot 就是它保存的数据文件。恢复 snapshot 会把数据恢复回来，并保留数据库当前的密码。参见 [snapshot 与恢复](https://docs.squarecloud.app/zh/services/databases.md#snapshot-与恢复)。

## 常见错误

| 信息 | 含义 | 处理方法 |
| :- | :- | :- |
| 连接立即关闭、`ECONNRESET` 或超时 | URL 使用了 `redis://`，没有 TLS。 | 使用 `rediss://`。 |
| `OOM command not allowed when used memory > 'maxmemory'` | 内存已满，且不会淘汰任何数据。 | 为缓存键添加过期时间、删除数据或增加 RAM。 |
| `MISCONF Redis is configured to save RDB snapshots, but it's currently unable to persist to disk` | 上一次保存失败。 | 释放存储和内存；保存成功后写入即可恢复。 |
| `ERR DB index is out of range` | 只存在数据库 0。 | 使用键前缀代替 `SELECT`。 |
| `NOPERM ... has no permissions to run the '...' command` | 该命令被禁用。 | 使用 `SCAN` + `UNLINK` 代替 `FLUSHALL`/`FLUSHDB`。 |
| `max number of clients reached` | 256 个连接已全部被占用。 | 每个进程复用一个客户端。 |

## 联系我们

如果你仍然遇到**技术问题**，我们的**专业支持团队**可以为你提供帮助。[**联系我们**](https://squarecloud.app/zh/support)，我们很乐意协助你解决任何问题，支持质量正是开发者给予 Square Cloud [**4.9/5 评分（共 402 条评价）**](https://www.trustpilot.com/review/squarecloud.app)（Google 与 Trustpilot）的重要原因之一。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.