Redis 避坑指南①：从安装到连接，这 9 个坑 90% 的人都踩过

**公关众注号：**IT安装手册

地址： https://itinstall.dev

系列说明： 本文是《Redis 避坑指南》系列第①篇，覆盖安装、连接、基础配置三大阶段。按「坑的描述 → 根本原因 → 解决方案」三段式整理，代码可直接复制使用。

环境说明

项目	版本
Redis	6.x / 7.x
OS	Ubuntu 20.04/22.04、CentOS 7/8/9

一、安装阶段

坑 1：编译安装后 `redis-server` 命令找不到

报错信息：

复制代码

-bash: redis-server: command not found

根本原因：

从官网下载源码编译后，二进制文件默认只在 src/ 目录下，没有被加入 PATH，也没有执行 make install。

解决方案：

复制代码

# 编译完成后执行安装（默认安装到 /usr/local/bin）
make install

# 或者手动软链接
ln -s /path/to/redis/src/redis-server /usr/local/bin/redis-server
ln -s /path/to/redis/src/redis-cli    /usr/local/bin/redis-cli

# 验证
redis-server --version

坑 2：apt/yum 安装的 Redis 版本太旧

现象：

Ubuntu 默认源安装的 Redis 经常停留在 5.x 甚至 4.x，缺少 ACL、Stream 改进等新特性，生产环境用起来处处受限。

根本原因：

系统默认软件源更新滞后，不跟随 Redis 官方发布节奏。

解决方案：

Ubuntu 使用官方 PPA：

复制代码

sudo add-apt-repository ppa:redislabs/redis
sudo apt update
sudo apt install redis

# 或通过 Snap 安装最新版
sudo snap install redis

CentOS 使用 Remi 仓库：

复制代码

sudo yum install epel-release
sudo yum install https://rpms.remirepo.net/enterprise/remi-release-7.rpm
sudo yum --enablerepo=remi install redis7

验证版本：

复制代码

redis-server --version
# Redis server v=7.x.x ...

坑 3：Docker 启动 Redis 没有挂载数据卷，重启后数据消失

现象：

容器重启或删除后，Redis 数据全部丢失，明明写进去的数据重启就没了。

根本原因：

Docker 容器的文件系统是临时的，没有将数据目录挂载到宿主机持久化存储。

解决方案：

不要这样做：

复制代码

# ❌ 没有挂载数据卷
docker run -d --name redis redis:7

正确做法：

复制代码

# ✅ 挂载数据目录和配置文件
mkdir -p /data/redis/{data,conf}

cat > /data/redis/conf/redis.conf << 'EOF'
bind 0.0.0.0
requirepass yourpassword
appendonly yes
appendfsync everysec
maxmemory 512mb
maxmemory-policy allkeys-lru
EOF

docker run -d \
  --name redis \
  -p 6379:6379 \
  -v /data/redis/data:/data \
  -v /data/redis/conf/redis.conf:/etc/redis/redis.conf \
  redis:7 redis-server /etc/redis/redis.conf

二、连接与访问

坑 4：Redis 无法远程连接

报错信息：

复制代码

Could not connect to Redis at 192.168.x.x:6379: Connection refused

根本原因：

Redis 默认配置 bind 127.0.0.1，只监听本地回环地址，拒绝一切外部连接。

解决方案：

修改 redis.conf：

复制代码

# 原配置（只允许本地）
bind 127.0.0.1

# 开发环境：允许所有网卡
bind 0.0.0.0

# 生产环境推荐：只绑定业务网卡 IP
bind 127.0.0.1 192.168.1.100

同时检查防火墙：

复制代码

# Ubuntu（ufw）
sudo ufw allow 6379/tcp

# CentOS（firewalld）
sudo firewall-cmd --permanent --add-port=6379/tcp
sudo firewall-cmd --reload

重启生效：

复制代码

sudo systemctl restart redis

⚠️ 警告： 生产环境绝不要让 Redis 裸跑在公网，bind 0.0.0.0 必须配合 requirepass 和防火墙白名单一起用。

坑 5：设置了密码，程序连接报 `NOAUTH`

报错信息：

复制代码

NOAUTH Authentication required
# Spring Boot 中：
io.lettuce.core.RedisCommandExecutionException: NOAUTH Authentication required

根本原因：
redis.conf 设置了 requirepass，但程序连接配置中没有填写密码，或密码写错了。

解决方案：

命令行连接：

复制代码

redis-cli -h 127.0.0.1 -p 6379 -a yourpassword
# 或登录后再认证
AUTH yourpassword

Spring Boot（application.yml）：

复制代码

spring:
  redis:
    host: 127.0.0.1
    port: 6379
    password: yourpassword
    timeout: 3000ms

Python redis-py：

复制代码

import redis
r = redis.Redis(
    host='127.0.0.1',
    port=6379,
    password='yourpassword',
    decode_responses=True
)

坑 6：Redis 7.x 开启了 ACL，旧密码方式失效

报错信息：

复制代码

WRONGPASS invalid username-password pair

根本原因：

Redis 6.0 引入 ACL（访问控制列表），Redis 7.x 中如果使用了自定义 ACL 文件，default 用户的权限可能被覆盖，原有 requirepass 方式的密码就会失效。

解决方案：

复制代码

# 查看当前 ACL 列表
redis-cli ACL LIST

# 为 default 用户重新设置密码和权限
redis-cli ACL SETUSER default on >yourpassword ~* &* +@all

# 生产推荐：创建独立应用账户，最小权限原则
redis-cli ACL SETUSER appuser on >apppassword ~* +@read +@write +@string +@hash +@list +@set +@sortedset

持久化 ACL 到文件（redis.conf）：

复制代码

aclfile /etc/redis/users.acl

三、配置参数

坑 7：`maxmemory` 没有配置，Redis 把服务器内存吃满

现象：

服务器内存被 Redis 占用到 100%，触发 OOM Killer，系统开始随机 kill 进程，严重时连 SSH 都进不去。

根本原因：

Redis 默认没有内存上限（maxmemory 0），数据无限增长直到耗尽物理内存。

解决方案：

复制代码

# 限制最大内存（根据服务器实际内存，留 20-30% 给 OS）
maxmemory 4gb

# 选择合适的淘汰策略
maxmemory-policy allkeys-lru

淘汰策略速查：

策略	适用场景
`noeviction`	默认值，内存满后写入报错，数据不能丢的场景
`allkeys-lru`	最常用，淘汰最久未用的 key，纯缓存场景首选
`allkeys-lfu`	淘汰使用频率最低的 key（Redis 4.0+），热点缓存场景
`volatile-lru`	只淘汰有过期时间的 key，业务数据和缓存混用时考虑
`volatile-ttl`	优先淘汰 TTL 最短的 key

坑 8：`maxmemory-policy noeviction`，缓存写入直接报错

报错信息：

复制代码

OOM command not allowed when used memory > 'maxmemory'

根本原因：
noeviction 是默认值，内存到达上限后所有写操作都返回错误，而不是淘汰旧数据。纯缓存场景下这个策略完全是错的。

解决方案：

纯缓存场景：

复制代码

maxmemory-policy allkeys-lru

缓存 + 重要业务数据混用场景（重要数据不设过期时间，缓存数据设过期时间）：

复制代码

maxmemory-policy volatile-lru

坑 9：启动报 TCP backlog 警告，高并发时连接被丢弃

启动日志警告：

复制代码

WARNING: The TCP backlog setting of 511 cannot be enforced because
/proc/sys/net/core/somaxconn is set to the lower value of 128.

根本原因：

Linux 系统默认 TCP 连接队列长度（somaxconn）只有 128，Redis 的 tcp-backlog 511 无法生效，高并发时连接请求会被操作系统直接丢弃。

解决方案：

复制代码

# 临时生效
echo 511 > /proc/sys/net/core/somaxconn

# 永久生效（重启不丢失）
echo "net.core.somaxconn = 1024" >> /etc/sysctl.conf
sysctl -p

# 顺手关闭透明大页（避免延迟抖动，Redis 官方推荐）
echo never > /sys/kernel/mm/transparent_hugepage/enabled

# 永久关闭：在 /etc/rc.local 追加
echo "echo never > /sys/kernel/mm/transparent_hugepage/enabled" >> /etc/rc.local
chmod +x /etc/rc.local

本篇小结

这 9 个坑覆盖了从安装到基础配置的全流程。总结一句话：安装用官方源，连接必须带密码，配置上线前先设好 maxmemory 和淘汰策略，内核参数别忽视。

下一篇预告：《Redis 避坑指南②：持久化 + 数据操作，这些坑让你数据说没就没》

持久化配置踩坑、KEYS * 打挂生产环境、缓存雪崩/击穿/穿透三大经典问题全部收录，干货更猛，下周更新，关注不迷路。