换成自己的 Redis：绿色安装包的缓存怎么接管

绿色包里的 Redis 是平台自己用的：监听 127.0.0.1:51003，开 AOF、每秒刷盘，不带密码。只监听回环，外面连不进来，出厂这么配省事。

换自己的 Redis，一般是为这几种情况：

• 平台要多实例部署，缓存必须放在共享的 Redis 上
• 单位有统一的 Redis 集群和监控，不希望多一个「藏在安装包里的」实例
• 安全基线要求缓存必须带密码，甚至必须走 ACL
• 平台和缓存要分开两台机器，便于独立扩容与备份

步骤比换库少，但有个「改了不生效」的陷阱：改在 config.yml 里的端口，下次 start 会被 config.env 的值覆盖回去。

图 1　Redis 的端口有三个落点：config.env 是源头，启动脚本每次 start 都会把它同步进 config.yml，后端只读 config.yml。所以端口必须改在 config.env；改在 config.yml 的会被下一次启动覆盖。

一、三个配置点，各管什么

位置	键	作用
config/config.env	UVP_REDIS_PORT	启动脚本用它启动/探活包内 Redis，并同步写入 config.yml
config/config.yml	redis.host / port / password / indexdb	后端真正用来连缓存的参数
config/config.yml	server.cachetype	redis 用 Redis，memory 用进程内缓存（单实例、重启即丢，多实例不可用）

后端连缓存的代码很直白：把 host:port、password、indexdb 三项交给客户端就完了。所以行为完全由 config.yml 决定，问题只在于这个文件会被脚本改写一部分。

config.env 的端口区长这样：

UVP_NGINX_HTTP_PORT=51000
UVP_HTTPS_PORT=51001
UVP_HTTP_PORT=51002
UVP_REDIS_PORT=51003
# 后面还有 ZLM 的 12 个端口，本机不换流媒体时不用管

端口只改这一处。config.yml 里的 redis.port 每次启动都会被覆盖，改在那儿留不住。

二、同机自建 Redis（推荐做法）

最常见的情况是 Redis 装在平台同一台机器上，端口 6379，带密码。这样最省心：启动脚本的探活会直接命中你自己的实例，包内那份不会被拉起来。

第 1 步，先把自己那份 Redis 起好，确认三件事：开了持久化、绑定了正确的地址、密码能过。

# 一个够用的最小配置（redis.conf）
bind 127.0.0.1 192.168.10.106
port 6379
requirepass 换成一个强口令
appendonly yes
appendfsync everysec

redis-server /etc/redis/redis.conf
redis-cli -h 127.0.0.1 -p 6379 -a '你的口令' ping   # 期望 PONG

第 2 步，停平台，改两处配置。

./uvp-gb28181-ctl.sh stop

config/config.env：

UVP_REDIS_PORT=6379

config/config.yml：

server:
  cachetype: "redis"

redis:
  host: "127.0.0.1"
  port: 6379
  password: "你的口令"
  indexdb: 1

第 3 步，启动并验证。

./uvp-gb28181-ctl.sh start
./uvp-gb28181-ctl.sh status

start 走到 Redis 那一步会先 ping 127.0.0.1:6379，通了就打「Redis 已在运行」，不再启动 vendor/redis 里的那份。这是第一个信号：如果打的是「Redis 启动成功」，说明探活没命中你的实例，包内 Redis 被拉起来了。

第二个信号看业务。登录一次，然后去你的 Redis 里找平台的键：

redis-cli -h 127.0.0.1 -p 6379 -a '你的口令' -n 1 dbsize
redis-cli -h 127.0.0.1 -p 6379 -a '你的口令' -n 1 keys 'uvp-gb28181:*' | head

有键、登录正常、在线用户列表正确，就算接管完成。

图 2　两种拓扑的行为差别：同机自建时探活能命中，包内 Redis 自动让位；跨机时探活打的是本机回环，可能额外拉起一个空转实例——它不参与业务，但会占用本机端口。

三、跨机 Redis

Redis 在另一台机器上，配置只多一步：host 填远端地址。

redis:
  host: "192.168.10.220"
  port: 6379
  password: "你的口令"
  indexdb: 1

UVP_REDIS_PORT=6379

有两件事要留意。

1. 本机可能多出一个空转的 Redis。 启动脚本的探活打的是 127.0.0.1:<UVP_REDIS_PORT>。跨机场景下本机这个端口多半没人监听，脚本就会用包内 vendor/redis 在本机起一个。它不参与业务（后端连的是远端），但占端口、吃一点内存。查它是谁的：

ss -lntp | grep ':6379'

不想让它起来，就让探活直接去问远端。脚本的探活地址由环境变量 UVP_REDIS_BIND 控制：

UVP_REDIS_BIND=192.168.10.220 ./uvp-gb28181-ctl.sh start

这样探活打远端，通了就不再启动包内实例；远端 ping 不通就启动失败。失败总比静默用上本机缓存、事后找不到数据强。注意这个变量只认进程环境，写进 config.env 不生效（启动脚本不 source 这个文件）。注册成 systemd 服务之后，用 systemctl edit uvp-gb28181 加一行 Environment=UVP_REDIS_BIND=192.168.10.220。

2. 防火墙与 ACL。 远端 Redis 必须放行平台所在机器的 IP，6379 别开到公网。bind、protected-mode、安全组，随便哪一条设紧了都连不上，而报错只有「连不上缓存」。先从平台机器上手工验一次：

redis-cli -h 192.168.10.220 -p 6379 -a '口令' ping

这条不通就别改平台配置，先处理网络或认证。

四、三个容易踩的坑

同一个 Redis 给多个平台用：改 db 序号和键前缀

平台的缓存默认落在 1 号库（不是 0 号），键前缀是 uvp-gb28181:。两套平台共用一个 Redis、这两项又都一样，就会互相顶掉对方的登录态和字典缓存。表现是「用着用着突然被踢下线」「字典偶尔变旧」，很难联想到是缓存串了。

redis:
  indexdb: 2                     # 第二套平台改成 2 号库

token:
  cachekeyprefix: "uvp-gb28181-b:"   # 键前缀也一起改，双保险

别用 0 号库。默认值定成 1，就是为了避开大多数工具和脚本习惯占的 0 号库。

密码只在一侧配：启动报 cache

包内 Redis 没有密码。如果你在 config.yml 里写了 password，实际连上的又是包内那份，客户端带密码去 AUTH 会失败，平台启动阶段直接报 cache。判据：

redis-cli -h 127.0.0.1 -p 6379 ping
# 不回 PONG 而回 NOAUTH，说明这个实例要密码（是对的）
# 直接回 PONG，说明这个实例没密码，你 config.yml 里的 password 就填错了对象

反过来一样：你自己的 Redis 有密码，config.yml 里 password 留空，报错同样是连不上缓存。

改完重启又变回 51003

就是第一节那个陷阱。config.yml 的 redis.port 每次启动都会被 config.env 的 UVP_REDIS_PORT 覆盖，所以要分开记：

• 端口改 config.env
• 地址、密码、db 序号改 config.yml（这几项脚本不碰）

判断有没有改对，看 start 输出的端口号，或者直接读一遍 config.yml：

grep -A3 '^redis:' config/config.yml

五、接管之后，平台里哪些东西在缓存里

知道这些，出问题时才能判断丢的是缓存还是丢的是库：

内容	在缓存里的表现	丢了会怎样
登录态 / token	uvp-gb28181: 前缀下的会话键	所有人需要重新登录
登录失败计数与锁定	login_fail_count:*、account_locked:*	锁定提前解除（不算安全问题，但审计记录会断）
字典与部分配置缓存	字典键	页面文案回落到默认值，刷新后恢复
设备在线状态	心跳相关键	状态短暂错乱，下一轮心跳自愈

设备、通道、录像不在缓存里，它们在数据库。所以「缓存挂了」的正确预期是：页面能开但可能报错，用户被登出，状态短暂不准，不会丢设备与录像记录。

反过来，换完 Redis 发现设备列表空了，那不是缓存的问题。去看数据库，十有八九是切库时踩了上一篇的坑。

六、回退

回退比换库简单，数据本来就在库里：

# config/config.env
UVP_REDIS_PORT=51003

# config/config.yml
redis:
  host: "127.0.0.1"
  port: 51003
  password: ""
  indexdb: 1

然后 ./uvp-gb28181-ctl.sh restart。包内的 AOF 还在 data/redis/，之前的数据不会丢。切换期间写进外部 Redis 的会话不会回来，所有人要重新登录一次，这在预期之内。

顺手清一下锁定键，免得有人被上一轮的失败计数锁着：

redis-cli -p 51003 -n 1 keys 'account_locked:*'
redis-cli -p 51003 -n 1 keys 'login_fail_count:*'

---

缓存接管完，还剩流媒体。包里那个 ZLMediaKit 也可以换成自己的，平台本来就支持多节点，见《接自己的 ZLMediaKit》。