跳至主要內容

RedisInsight：安装、数据操作、查询诊断与配置恢复

高谷深陵大约 24 分钟约 7095 字
RedisInsight 连接、数据操作、查询诊断与配置恢复知识海报
RedisInsight 数据操作与诊断参考图用 Browser 操作具体数据，用 Workbench 核对结果，用分析与慢日志定位问题；控制台配置单独备份恢复。高清原图

RedisInsight 中的数据与连接

RedisInsight 把 Redis 的 Key、数据类型、字段和过期时间显示为可操作的界面。查询商品缓存时，可以直接查看 Hash 字段；排查消息积压时，可以展开 Stream 的消费者组和待确认消息；检查内存分布时，可以按类型与前缀查看分析结果。命令输入保留在 Workbench 和底部 CLI 中，适合核对界面操作对应的实际数据。

安装 RedisInsight 后，还需要一台 Redis 服务。两者分别保存不同的数据：

浏览器
  └─ RedisInsight：Docker HTTP 5540
       ├─ /data：连接配置、查询历史、本地日志
       └─ Redis TCP 6379
            ├─ String / Hash / List / Set / Sorted Set
            ├─ Stream 与消费者组
            └─ JSON、Search、Vector Set：取决于服务端能力

Redis 的安装、数据模型、Sentinel、Cluster 与业务数据恢复，参见 Redis 主文章。RedisInsight 产品说明列出了图形操作、命令工作区及分析能力。

选择安装方式与版本

个人工作站可以使用桌面安装包，由桌面程序保存本机连接。Linux 服务器使用 Docker 时，浏览器访问的是服务器提供的 Web 服务，需要另外保护访问入口。多人共用控制台，还会共用其中保存的连接与历史，应先确认这些内容是否适合共享。

下面固定 RedisInsight 3.6.0 和 Redis 7.2.16，只使用独立实验数据。3.6.0 已提供 Development / Production 环境标记；生产模式对批量删除、危险命令和启动 Profiler 等操作增加输入确认。具体变化见 3.6.0 发布说明。环境标记有助于减少误触，账号权限由 Redis 服务端决定。

连接表单中的字段

字段应填写什么常见错误
Alias / 名称能识别用途的名称，如 ri-lab-editor多个环境使用同名连接
Host、PortRedisInsight 进程能够访问的 Redis 地址容器里填 localhost，却希望访问另一容器
Username、PasswordRedis ACL 用户名与密码用户名留空，意外使用 default
Database单实例的逻辑 DB 编号；实验使用 0查错 DB；把 DB 当作租户隔离
TLS 与 CA服务端要求的加密及证书信任配置跳过证书校验后误连错误端点
客户端证书、私钥服务端启用双向 TLS 时提供只填 CA，没有客户端身份

添加连接时，RedisInsight 需要执行 INFO 识别服务端。只有 GET 权限的业务账号通常不足以支持图形客户端；为工具配置专门的身份更合适。该要求见官方连接说明。

安装并完成第一次数据操作

准备独立 Linux 实验

在安装了 Docker Engine、Compose 插件、Bash、OpenSSL、curl 和 ss 的 Linux 主机执行。当前用户需要 Docker 权限；这类权限接近宿主机管理员权限，不要把 Docker socket 提供给普通 Web 用户。尚未准备 Docker 时，先完成 Docker Engine 安装。

以下 Shell 命令在宿主机执行；docker compose exec 后面的程序才在容器内运行。Redis 仅加入实验网络，不发布 6379；RedisInsight 只向宿主机回环地址发布 5540。

docker version || exit 1
docker compose version || exit 1
command -v openssl curl ss >/dev/null || exit 1
if ss -ltnH 'sport = :5540' | grep -q .; then
  echo '5540 已被使用；请先选择另一个空闲端口。' >&2
  exit 1
fi

umask 077
RI_LAB="$(mktemp -d "$PWD/ri-lab.XXXXXX")" || exit 1
cd "$RI_LAB" || exit 1
RI_PROJECT="ri-$(openssl rand -hex 6)" || exit 1
RI_ADMIN="$(openssl rand -hex 24)" || exit 1
RI_EDITOR="$(openssl rand -hex 24)" || exit 1
RI_READER="$(openssl rand -hex 24)" || exit 1
RI_KEY="$(openssl rand -hex 32)" || exit 1

cat > .env <<EOF
COMPOSE_PROJECT_NAME=$RI_PROJECT
RI_IMAGE=redis/redisinsight:3.6.0
RI_HTTP_PORT=5540
RI_ENCRYPTION_KEY=$RI_KEY
RI_ADMIN=$RI_ADMIN
RI_EDITOR=$RI_EDITOR
RI_READER=$RI_READER
EOF

cat > users.acl <<EOF
user default off
user admin reset on >$RI_ADMIN ~* &* +@all
user editor reset on >$RI_EDITOR ~lab:ri:* +ping +info +command +select +client|setname +client|setinfo +acl|whoami +scan +dbsize +type +ttl +pttl +exists +get +getrange +strlen +memory|usage +set +del +expire +persist +hgetall +hscan +hget +hlen +hset +zrange +zrevrange +zscan +zscore +zcard +zadd +xrange +xrevrange +xlen +xinfo +xpending +xadd +xgroup|create +xreadgroup +xack +xclaim
user reader reset on >$RI_READER ~lab:ri:* +ping +info +command +select +client|setname +client|setinfo +acl|whoami +scan +dbsize +type +ttl +pttl +exists +get +getrange +strlen +memory|usage +hgetall +hscan +hget +hlen +zrange +zrevrange +zscan +zscore +zcard +xrange +xrevrange +xlen +xinfo +xpending
EOF
chmod 600 .env users.acl

.env 保存实验凭据和稳定加密密钥，不要提交 Git 或贴入截图。密钥首次生成后，重启和恢复复用原值。editor 只允许这里演示的数据操作，reader 没有写权限；管理员留在 CLI，不拿来修补 GUI 的所有权限报错。

保存 Compose 配置：

cat > compose.yaml <<'YAML'
services:
  acl-init:
    image: redis:7.2.16
    user: "0:0"
    entrypoint: ["/bin/sh", "-ec"]
    command: ["cp /source/users.acl /acl/users.acl; chown 999:999 /acl/users.acl; chmod 600 /acl/users.acl"]
    volumes:
      - ./users.acl:/source/users.acl:ro
      - redis-acl:/acl
    network_mode: none
  redis:
    image: redis:7.2.16
    user: "999:999"
    command: ["redis-server", "--aclfile", "/acl/users.acl", "--appendonly", "yes"]
    volumes:
      - redis-acl:/acl:ro
      - redis-data:/data
    depends_on:
      acl-init:
        condition: service_completed_successfully
    environment:
      REDISCLI_AUTH: ${RI_ADMIN}
    healthcheck:
      test: ["CMD-SHELL", "redis-cli --user admin -e ping | grep -qx PONG"]
      interval: 2s
      timeout: 2s
      retries: 30
  insight:
    image: ${RI_IMAGE}
    user: "1000:1000"
    ports:
      - "127.0.0.1:${RI_HTTP_PORT}:5540"
    environment:
      RI_ENCRYPTION_KEY: ${RI_ENCRYPTION_KEY}
      RI_ACCEPT_TERMS_AND_CONDITIONS: "false"
    volumes:
      - insight-data:/data
    depends_on:
      redis:
        condition: service_healthy
volumes:
  redis-acl:
  redis-data:
  insight-data:
YAML

docker compose up -d || exit 1
docker compose ps
curl -q --noproxy '*' --fail-with-body --retry 20 --retry-connrefused \
  --retry-delay 1 --max-time 5 -sS http://127.0.0.1:5540/api/health/

预期 Redis 为 healthy，RedisInsight 为 running，健康接口返回成功。尚未启动完成时，检查 docker compose logs --tail=80 insight redis，不要反复新建数据卷。官方 Docker 安装说明规定了 5540、健康端点和持久化位置；绑定自己的宿主目录时，要让 UID 1000 可写，不能直接用 chmod 777 处理。

浏览器打开 http://127.0.0.1:5540。首次页面若要求阅读并确认使用条款，由有权作出该决定的使用者完成；未同意时停在此处。配置保留人工选择，不用自动接受参数替代它。3.6.0 对该参数的读取方式可查定版配置源码。

RedisInsight 运行在远程 Linux 上时，可从自己的电脑建立 SSH 隧道，再打开本地 5540：

ssh -N -L 5540:127.0.0.1:5540 ops@linux-host

将 ops@linux-host 换成自己的 SSH 身份和主机；本机 5540 也必须空闲。远程服务继续只绑定回环地址。

创建连接和四种合成数据

在 RedisInsight 数据库列表选择添加数据库。名称填写 ri-lab-editor，环境选 Development；Host 为 redis、Port 为 6379、Database 为 0。Username 填 editor，Password 使用本实验 .env 的 RI_EDITOR 值。隔离 Docker 网络实验没有启用 TLS，连接实际服务器时按其证书要求配置。

redis 是 Compose 服务名，由容器网络解析。桌面版不在这个网络中，不能直接使用该名字；应连接自己有权访问的 Redis 端点，或另行配置回环端口与 SSH 隧道。不要为了让桌面连接方便，把实验 Redis 暴露到公网。

打开该连接的 Workbench，逐条执行以下命令。首次执行使用全新实例，重复 XGROUP CREATE 会返回 BUSYGROUP，不应据此删除已有消费者组：

PING
ACL WHOAMI
SET lab:ri:product:1001:json "{\"name\":\"keyboard\",\"stock\":12}" EX 3600
HSET lab:ri:product:1002 name mouse stock 8 price_cent 19900
EXPIRE lab:ri:product:1002 3600
ZADD lab:ri:ranking 30 alice 20 bob 10 carol
XADD lab:ri:events * order_id demo-1 status created
XADD lab:ri:events * order_id demo-2 status paid
XGROUP CREATE lab:ri:events ri-workers 0

PING 返回 PONG，ACL WHOAMI 返回 editor；SET 返回 OK；第一次 HSET 新增三个字段，ZADD 新增三个成员；XADD 返回两条各不相同的消息 ID。样本都在 lab:ri:* 前缀内。

Browser：查看、编辑和核对

进入 Browser，在 Key 名称过滤中输入 lab:ri:*，执行搜索或刷新。用列表视图先确认四个 Key 的类型，展开一项再读内容；树形视图按命名空间整理 Key，适合层次较深的前缀。

样本Browser 中的操作核对结果
product:1001:json打开 String，选择 JSON 格式显示name=keyboard、stock=12；类型仍是 String
product:1002打开 Hash，找到 stock 字段并编辑为 7，保存字段变为 7，其他字段保留
ranking打开 Sorted Set，查看 member 与 scorealice=30、bob=20、carol=10
events打开 Stream，查看两条 entry 的字段order_id 与 status 成对出现

返回 Workbench 验证 Hash 修改：

HGET lab:ri:product:1002 stock
HGETALL lab:ri:product:1002
TTL lab:ri:product:1002

stock 应为 7，TTL 应是小于 3600 的正数。更新 Hash 字段会保留 Key 已有 TTL；如果已经超过一小时，Key 会消失，此时重建样本再继续。TTL 的 -1 表示无过期时间，-2 表示不存在。

JSON 格式化器只改变显示。这里用 SET 存入的 JSON 文本仍由 GET 读取；支持 JSON.SET / JSON.GET 的原生 JSON 类型需要服务端具备相应能力。查看 JSON 时应同时检查类型标签。HEX、Unicode、MessagePack 等格式同理：解释错误时先核对应用序列化方式，避免把原始字节改坏。

删除练习单独创建一个临时 Key：

SET lab:ri:delete-demo disposable EX 600

在 Browser 按完整名称搜索，确认只有这一项，再执行单 Key 删除；Workbench 中 EXISTS lab:ri:delete-demo 应为 0。批量删除会扩大到当前筛选集合，模糊前缀和未完成扫描都需要额外检查，不用整个 lab:ri:* 做第一次删除练习。

Stream：区分消息内容与待确认状态

在 Workbench 让 worker-a 领取一条消息但先不确认：

XREADGROUP GROUP ri-workers worker-a COUNT 1 STREAMS lab:ri:events >
XPENDING lab:ri:events ri-workers

第一次运行得到一条消息，pending 总数为 1。回到 Browser 打开 lab:ri:events，查看 Consumer Groups，再打开 ri-workers 的消费者与 pending 列表：该消息归 worker-a，等待确认。

确认合成任务已处理后，可在界面选择该消息进行 acknowledge；也可以复制实际 ID，在 Workbench 执行：

XACK lab:ri:events ri-workers <刚才返回的消息ID>
XPENDING lab:ri:events ri-workers
XLEN lab:ri:events

将占位符替换为真实 ID，不带尖括号。XACK 首次应返回 1，pending 变为 0，XLEN 仍为 2：确认处理完成会移出 pending，原 Stream 条目仍保留。这解释了为什么消息列表没有随确认操作清空。XACK 命令说明给出了确切语义。

消费者故障时，可在 pending 中检查 idle 时间和已投递次数，再按任务重试策略 claim 到其他消费者。claim 只转移消费归属，业务处理仍需执行并保持幂等；不能为了让列表清零直接批量 acknowledge。界面的消费者组管理、确认和接管操作见官方 Streams 教学。

从查询结果到故障原因

Workbench：控制查询范围并保存有用结果

Workbench 适合把几条相关命令放在一起，逐条比较返回值。以下片段检查 Hash 状态和排行榜前两名：

TYPE lab:ri:product:1002
HGETALL lab:ri:product:1002
PTTL lab:ri:product:1002
ZRANGE lab:ri:ranking 0 1 REV WITHSCORES

预期类型 hash、stock=7，剩余毫秒 TTL 持续减少；排行榜按分数降序返回 alice 和 bob。保存查询时只保留可复用命令和合成参数，真实用户标识、令牌和值可能随查询历史一起落到本地磁盘。

只知道前缀时，可以分轮查找：

SCAN 0 MATCH lab:ri:product:* COUNT 20

返回值第一项是下一轮 cursor；把它作为下一次 SCAN 的首参数，直到返回 0。COUNT 是每轮工作量提示，一轮返回空列表而 cursor 非零时仍需继续。修改中的数据可能重复出现；需要统计唯一 Key 数时应去重。先缩小前缀、再限制总轮数与输出量，比把 KEYS * 粘贴到 GUI 更适合大实例。

Search、JSON、Time Series 和 Vector Set 的结果展示还取决于服务端功能。3.6.0 已增加 Vector Set 支持；普通 Redis 7.2 实验没有这些扩展命令。出现 unknown command 'FT.SEARCH' 时，先核对服务端版本和功能，不能靠更换 GUI 显示模式解决。索引创建、查询解释及查询库按所装版本查阅 Search workspace，不要把最新界面的入口位置套到旧版本。

数据分析：从大 Key 找到具体对象

Database Analysis 适合查看类型分布、内存较大的 Key、前缀占用和 TTL 分布。分析前确认实例、DB 与扫描成本；分析过程中会发出额外查询，不在高峰连续触发全库扫描。

报告里某个前缀占用较大时，先在 Browser 过滤该前缀，抽样打开报告指出的 Key，确认类型与长度。接着用 TTL 判断是否长期保留；集合还要检查成员数或 Stream 长度。

把对象数量、单对象占用和业务保留期分开比较，才能区分“数量增长”与“单值变大”。修改应用保留策略后重新测同一类样本，再比较后续报告。

分析存在采样及外推行为，报告可能不是逐 Key 精确统计。RSS 还包含分配器、复制缓冲等开销，需结合 Redis 主文章中的 INFO memory、MEMORY USAGE 和容量实验判断。小型实验只适合熟悉报告，不能据此推导生产分片大小。

实验 reader 允许 MEMORY USAGE 读取对象占用，但没有修改配置的权限。Browser 读取详情时还会使用 GETRANGE、ZSCAN、XREVRANGE 等命令，不能只按手工输入的 GET 配权限；示例白名单依据 3.6.0 Browser 命令定义补齐这些读取动作。其他功能若提示 NOPERM，管理员应按实际拒绝命令核对，不把 +@all 加到日常只读账号。

Slow Log：解释执行慢与等待慢

Slow Log 页面读取服务端慢日志。Redis 慢日志统计命令执行时间，不把客户端到服务端的网络传输都算进去。应用耗时高而慢日志为空，应继续检查连接池等待、网络往返、输出量和请求在服务端的排队时间。

独立实验中可以临时把慢日志阈值改为 0，制造可辨认样本；这会记录所有命令，禁止在生产照抄。宿主机进入原实验目录，以管理员执行并保存原值：

set -a
. ./.env
set +a
rac() { docker compose exec -T redis redis-cli --user admin -e --raw "$@"; }
OLD_SLOW="$(rac CONFIG GET slowlog-log-slower-than | tail -n 1)"
[[ "$OLD_SLOW" =~ ^-?[0-9]+$ ]] || exit 1
rac CONFIG SET slowlog-log-slower-than 0 || exit 1
trap 'rac CONFIG SET slowlog-log-slower-than "$OLD_SLOW" >/dev/null' EXIT
rac GET lab:ri:product:1001:json
rac SLOWLOG GET 5
rac CONFIG SET slowlog-log-slower-than "$OLD_SLOW" || exit 1
trap - EXIT
rac ACL SETUSER reader '+slowlog|get' '+slowlog|len'

输出中应能找到对该 Key 的 GET，本实验不清空已有慢日志。添加 reader 连接，使用 reader 用户和 RI_READER 密码，打开 Slow Log，比较命令与参数。演示结束执行 rac ACL SETUSER reader '-slowlog|get' '-slowlog|len' 撤销临时权限。修改阈值需要 CONFIG，读日志不必顺带授权修改。服务端含义见 SLOWLOG。

Profiler：短时间观察真实命令流

Profiler 使用实时命令流定位“谁在发什么”。在隔离实验中，管理员临时给 reader 增加 MONITOR 权限：

rac ACL SETUSER reader +monitor

在 RedisInsight 重连 reader 连接，点击底部 Profiler 并开始采集；另一个宿主终端在原实验目录执行：

docker compose exec -T redis redis-cli --user admin -e GET lab:ri:product:1001:json

采到这条带实验 Key 的 GET 后停止 Profiler。撤销权限并断开该账号的现有连接，防止已进入监控模式的连接继续接收内容：

rac ACL SETUSER reader -monitor
rac CLIENT KILL USER reader SKIPME yes

重新连接 reader，再启动 Profiler 应被拒绝。MONITOR 会给 Redis 增加开销，也可能显示敏感参数，不要长期挂着 Profiler 排查性能。具体行为见 MONITOR 官方说明。

连接生产、Sentinel 与 Cluster

生产连接优先使用个人只读身份，别名中明确实例与环境，设置 Production 标记。允许读内容仍需要限制扫描量，大对象查询同样会消耗 CPU 和网络。

Sentinel 连接要提供可达的 Sentinel 地址、master name，以及发现服务和数据节点各自的认证信息。既要连接当前主节点，也要在受控切换后刷新并确认新的目标。Cluster 从种子节点取得槽分布后，需要访问所有被通告的数据节点；仅连通种子 IP 不能保证其他分片可用。实际地址规划使用 Redis 主文章中的多机部署，不把本地 Compose 服务名填到跨主机连接中。

TLS 错误按阶段处理：unknown CA 检查 CA，hostname mismatch 检查连接名和证书 SAN，服务端要求客户端证书时提供证书与私钥，认证后的 WRONGPASS 再检查 ACL 凭据。跳过证书校验会丢失对目标身份的确认。

Redis 7.2 的 ACL Key pattern 限制 GET 等命令访问哪些 Key，获准执行的 SCAN 不会按 pattern 自动隐藏其他 Key 名。Browser 名称过滤只是查询条件；需要隐藏其他租户名称时，应限制枚举或使用独立实例。Redis ACL与7.2.16 SCAN 定义解释了这一区别。

在实验中用管理员做权限预检，不真正执行破坏操作：

rac ACL DRYRUN reader GET lab:ri:product:1001:json
rac ACL DRYRUN reader SET lab:ri:product:1001:json changed
rac ACL DRYRUN reader GET private:sample
rac ACL DRYRUN editor FUNCTION FLUSH
rac ACL DRYRUN editor FLUSHDB

只有第一条应返回 OK，其余应为权限拒绝。然后在 reader Workbench 实际执行 GET 与 SET，分别核对可读和 NOPERM。Production 确认对话框不会改变这些服务端结果。

保存控制台配置、升级与处理异常

备份包含什么

RedisInsight 的 /data 保存连接和本地工作内容，Redis 业务数据在另一个服务的数据目录中。备份 RedisInsight 不会得到商品缓存、Stream 或整个 Redis Cluster 的副本。

冷备可以让 SQLite 文件、附属文件与本地配置处于同一停止点。先结束查询和 Profiler，再停止 insight；Redis 服务保持运行。继续在原实验目录执行：

RI_CONTAINER="$(docker compose ps -q insight)"
test -n "$RI_CONTAINER" || exit 1
RI_VOLUME="$(docker inspect "$RI_CONTAINER" \
  --format '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Name}}{{end}}{{end}}')"
test -n "$RI_VOLUME" || exit 1
BACKUP_DIR="$(mktemp -d "$PWD/insight-backup.XXXXXX")" || exit 1
chmod 700 "$BACKUP_DIR"
docker compose stop insight || exit 1

docker run --rm --network none --user 0:0 \
  -v "$RI_VOLUME:/source:ro" -v "$BACKUP_DIR:/backup" \
  --entrypoint sh redis:7.2.16 \
  -ec 'tar -C /source -czf /backup/data.tgz .; chmod 600 /backup/data.tgz' || exit 1
cp .env "$BACKUP_DIR/restore.env" || exit 1
chmod 600 "$BACKUP_DIR/restore.env"
(cd "$BACKUP_DIR" && sha256sum data.tgz > data.sha256) || exit 1
docker compose start insight || exit 1

这里的环境文件包含密钥与合成密码；正式备份把加密密钥交给独立保管流程，限制数据包读取权限，并确认恢复时能取回原钥。不要把环境文件与数据包上传到公开附件。直接轮换 RI_ENCRYPTION_KEY 可能使旧保存内容无法解密；配置行为见官方配置说明。

恢复到新卷和新端口

继续使用刚才的 Bash 终端及其中的 BACKUP_DIR，恢复时另建一个 RedisInsight 容器，原卷保留；若已关闭终端，先找回本次备份目录并检查摘要，不要猜测目录名或新建空备份：

test -s "$BACKUP_DIR/data.tgz" || exit 1
(cd "$BACKUP_DIR" && sha256sum -c data.sha256) || exit 1
set -a
. "$BACKUP_DIR/restore.env"
set +a
if ss -ltnH 'sport = :5541' | grep -q .; then
  echo '5541 已占用，停止恢复。' >&2
  exit 1
fi
RESTORE_NAME="${COMPOSE_PROJECT_NAME}-restore-$(openssl rand -hex 4)"
RESTORE_VOLUME="$RESTORE_NAME-data"
if docker container inspect "$RESTORE_NAME" >/dev/null 2>&1 \
  || docker volume inspect "$RESTORE_VOLUME" >/dev/null 2>&1; then
  echo '恢复资源已存在，拒绝复用。' >&2
  exit 1
fi
docker network inspect "${COMPOSE_PROJECT_NAME}_default" >/dev/null || exit 1
docker volume create "$RESTORE_VOLUME" >/dev/null || exit 1
docker run --rm --network none --user 0:0 \
  -v "$RESTORE_VOLUME:/restore" -v "$BACKUP_DIR:/backup:ro" \
  --entrypoint sh redis:7.2.16 \
  -ec 'tar -C /restore -xzf /backup/data.tgz; chown -R 1000:1000 /restore' || exit 1

docker run -d --name "$RESTORE_NAME" --user 1000:1000 \
  --network "${COMPOSE_PROJECT_NAME}_default" \
  -p 127.0.0.1:5541:5540 -v "$RESTORE_VOLUME:/data" \
  --env-file "$BACKUP_DIR/restore.env" \
  -e RI_ACCEPT_TERMS_AND_CONDITIONS=false "$RI_IMAGE" || exit 1
curl -q --noproxy '*' --fail-with-body --retry 20 --retry-connrefused \
  --retry-delay 1 --max-time 5 -sS http://127.0.0.1:5541/api/health/

打开 5541，先核对连接名称和保存的历史，再使用 reader 连接执行 ACL WHOAMI 与 GET。这同时检查文件恢复，以及原密码可解密且仍然有效。密码已在 Redis 服务端轮换时，需要更新连接，恢复出的旧凭据也会失效。

恢复环境沿用实验网络，是为了访问同一个合成 Redis；正式演练只开放到获准验证的数据库，避免复制的控制台自动连接生产。记录恢复卷名后，可先 docker stop "$RESTORE_NAME" 保留现场，不急着删除。

升级先在配置副本上验证

这里选择 3.6.0 → 3.8.0 演示配置副本升级。3.8.0 发布说明包括连接地址编辑等变化，升级其他版本时先核对其发布说明。旧版程序不能直接读取新版迁移过的唯一 SQLite。

在维护窗口禁止使用旧控制台，重新完成上述冷备，并保留同一 Shell 的 BACKUP_DIR。备份步骤会重启旧进程，下面立即再次停止它；期间不打开旧界面执行查询或修改配置。以下启动另一个 5542 端口的候选控制台，原卷保持不变：

TARGET_RI_IMAGE=redis/redisinsight:3.8.0
docker compose stop insight || exit 1
docker pull "$TARGET_RI_IMAGE" || exit 1
docker image inspect "$TARGET_RI_IMAGE" --format '{{json .RepoDigests}}'
(cd "$BACKUP_DIR" && sha256sum -c data.sha256) || exit 1
set -a
. "$BACKUP_DIR/restore.env"
set +a
if ss -ltnH 'sport = :5542' | grep -q .; then
  echo '5542 已占用，停止升级。' >&2
  exit 1
fi
UPGRADE_NAME="${COMPOSE_PROJECT_NAME}-upgrade-$(openssl rand -hex 4)"
UPGRADE_VOLUME="$UPGRADE_NAME-data"
if docker container inspect "$UPGRADE_NAME" >/dev/null 2>&1 \
  || docker volume inspect "$UPGRADE_VOLUME" >/dev/null 2>&1; then
  echo '候选资源已存在，拒绝复用。' >&2
  exit 1
fi
docker network inspect "${COMPOSE_PROJECT_NAME}_default" >/dev/null || exit 1
docker volume create "$UPGRADE_VOLUME" >/dev/null || exit 1
docker run --rm --network none --user 0:0 \
  -v "$UPGRADE_VOLUME:/upgrade" -v "$BACKUP_DIR:/backup:ro" \
  --entrypoint sh redis:7.2.16 \
  -ec 'tar -C /upgrade -xzf /backup/data.tgz; chown -R 1000:1000 /upgrade' || exit 1
docker run -d --name "$UPGRADE_NAME" --user 1000:1000 \
  --network "${COMPOSE_PROJECT_NAME}_default" \
  -p 127.0.0.1:5542:5540 -v "$UPGRADE_VOLUME:/data" \
  --env-file "$BACKUP_DIR/restore.env" \
  -e RI_ACCEPT_TERMS_AND_CONDITIONS=false "$TARGET_RI_IMAGE" || exit 1
curl -q --noproxy '*' --fail-with-body --retry 20 --retry-connrefused \
  --retry-delay 1 --max-time 5 -sS http://127.0.0.1:5542/api/health/

打开 5542，只用合成或只读连接检查保存的凭据、Browser 类型显示、Workbench 历史、TLS 与常用诊断，版本信息应为 3.8.0。通过后，在维护窗口执行 docker compose stop insight 停止旧控制台，使用 5542 或把受控代理上游切到 5542；保留候选容器名和卷名供后续维护。测试环境若不需要切换，只停止候选即可。

候选失败或尚未开始新配置写入时，可直接回到原入口：

docker stop "$UPGRADE_NAME" || exit 1
docker compose start insight || exit 1
curl -q --noproxy '*' --fail-with-body --retry 20 --retry-connrefused \
  --retry-delay 1 --max-time 5 -sS http://127.0.0.1:5540/api/health/

共享代理已切换时，还要将其上游恢复到 5540。旧容器仍使用原卷，不把候选卷挂回旧镜像。

新版投入使用后新增的连接和历史只存在于新版数据中，回到旧冷备会丢失这些变化，需要先导出或逐项迁移所需内容。控制台回退不会回退 Redis 业务数据；在新版界面执行过的业务写操作已经作用于 Redis，不会随着 GUI 回退而消失。

共享服务与连接预置

共享 RedisInsight 应在入口配置身份认证、HTTPS 和来源限制，5540 不直接向公网开放。反向代理超时需要覆盖允许的查询，实时连接也要正确转发。代理应从根路径部署并按目标版本检查 API 与实时连接，不只调整静态页面地址。

统一分发连接可以使用 RI_REDIS_HOST、PORT、USERNAME、PASSWORD 等带标识后缀的预置变量或配置文件。重启时移除某组预置变量，会使对应预置连接移除；更新时应同时检查部署配置和密钥来源。RI_DATABASE_MANAGEMENT=false 限制新增、编辑、删除连接，不提供独立 Web 用户认证，也不改变 Redis ACL。

AI 辅助、云账号发现和 RDI 是额外功能，需要相应服务、身份与授权。把数据库上下文发送给 AI 服务前，应确认数据使用范围；本地部署 RedisInsight 并不自动意味着所有可选功能都离线运行。

常见故障的检查顺序

现象优先检查下一步
页面不能打开容器状态、回环端口、SSH 隧道、健康接口看 insight 日志，不先改 Redis 密码
添加连接失败Host/Port、认证与 INFO 权限桌面和容器使用各自可达的地址
WRONGPASSACL 用户名、密码、用户 on/off服务端核对用户，不贴完整 URI 到工单
NOPERM实际被拒绝的命令与 Key管理员检查 ACL LOG，按功能补必要命令
Browser 看不到 KeyDB、前缀、扫描游标、类型筛选、TTL用同一身份查完整 Key，过期后重新取样
String 内容乱码原始类型、应用 serializer、显示格式先切换解释方式，保留原字节
Cluster 部分操作超时所有节点通告地址、路由、TLS SAN逐节点检查，不只测种子节点
卷仍在但连接消失当前卷名、预置变量是否被移除恢复原卷或配置，不重新生成密钥
保存的密码无法使用原加密密钥、服务端密码轮换区分解密失败与认证失败
Profiler 没有数据MONITOR 权限、当前实例、采集状态用单条合成 GET 验证后停止
共享访问偶发断开代理超时、实时连接转发、后端日志对照直接回环访问，不无限增大超时

实验结束且确认没有把候选控制台作为当前入口后，在保留 RI_LAB、RESTORE_NAME、UPGRADE_NAME 的原 Bash 终端执行下列清理。对实际创建的候选先核对名称和 /data 卷，再停止、移除容器；两个候选变量若未设置，就跳过对应容器。最后只停止本次 Compose 服务并移除网络：

test -n "${RI_LAB:-}" && test "$PWD" = "$RI_LAB" || exit 1
for kind in restore upgrade; do
  if test "$kind" = restore; then
    name="${RESTORE_NAME:-}"; volume="${RESTORE_VOLUME:-}"
  else
    name="${UPGRADE_NAME:-}"; volume="${UPGRADE_VOLUME:-}"
  fi
  test -n "$name" || continue
  [[ "$name" == "${COMPOSE_PROJECT_NAME}-${kind}-"* ]] || exit 1
  test -n "$volume" || exit 1
  mounted="$(docker inspect "$name" \
    --format '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Name}}{{end}}{{end}}')" || exit 1
  test "$mounted" = "$volume" || exit 1
  docker stop "$name" || exit 1
  docker rm "$name" || exit 1
done
docker compose down

仅停止候选并保留容器时，它仍附着在 Compose 网络，down 可能无法删除网络。已切换给使用者的控制台不能按实验清理。Docker Compose down 说明列出了默认删除的服务容器和网络，以及只有显式使用 -v 才会删除的命名卷；此处不带 -v 会保留原卷和候选卷，便于复查。删除卷会永久清除该实验的数据或历史。正式停用还要撤销对应 Redis 账号和网络权限，仅从界面删除连接不会撤掉服务端凭据。

权威资料与规范地址

产品、安装与版本

数据操作与诊断

配置与权限

跳到正文