Redis를 운영하다 보면 가장 당황스러운 순간 중 하나가 바로 ‘WRONGPASS Invalid username-password pair’ 에러를 마주할 때입니다. 분명히 올바른 비밀번호를 입력했는데도 계속 인증이 실패한다면, 이는 단순한 비밀번호 오타가 아닐 가능성이 높습니다.
실제로 최근 Redis 6.0 이상 버전을 사용하는 개발자들 사이에서 이 문제가 빈번하게 발생하고 있으며, 특히 기존 버전에서 업그레이드한 환경에서 더욱 자주 나타나고 있습니다. 이 글에서는 이런 답답한 상황을 완전히 해결할 수 있는 실용적인 방법들을 단계별로 살펴보겠습니다.
1. 문제의 핵심: Redis 6.0 ACL 시스템 변화
Redis 6.0부터 도입된 ACL(Access Control List) 시스템이 이 문제의 주요 원인입니다. 기존의 단순한 requirepass 방식에서 사용자 기반의 세분화된 권한 관리 시스템으로 변경되면서, 인증 방식도 함께 바뀌었습니다.
기존 방식 vs 새로운 방식
# Redis 5.x 이하 (기존 방식)
AUTH password123
# Redis 6.0+ (새로운 방식)
AUTH username password123
# 또는
AUTH default password123
Redis 6.0에서는 커넥션을 맺은 뒤 유저의 이름과 패스워드를 인증하는 방식으로 작동하며, 기본 유저는 명시적으로 인증되지 않았지만 기능의 일부분을 사용할 수 있다는 특성을 가지고 있습니다.
2. 주요 원인별 해결 방법
2-1. 연결 URL 형식 오류
가장 흔한 실수 중 하나는 연결 URL에서 콜론(:) 사용법을 잘못 이해하는 것입니다.
잘못된 예시:
// ❌ 잘못된 형식
redis://:username:password@host:port/db
// ❌ 사용자명 앞에 불필요한 콜론
redis://:default:123456@localhost:6379/0
올바른 예시:
// ✅ 올바른 형식 (사용자명과 비밀번호 모두 있는 경우)
redis://username:password@host:port/db
// ✅ 비밀번호만 있는 경우 (기본 사용자)
redis://:password@host:port/db
// ✅ 구체적인 예시
redis://myuser:mypassword@localhost:6379/0
redis://:secretpass@localhost:6379/0
연결 URL에서 사용자명 앞의 콜론이 문제가 되는 경우가 많으며, 비밀번호만 있고 사용자명이 없는 경우에만 앞에 콜론을 사용해야 합니다.
2-2. 기본 사용자(default) 설정 확인
Redis 6.0+에서는 default 사용자가 자동으로 생성됩니다. 현재 사용자 설정을 확인해보세요:
# Redis CLI에서 현재 사용자 목록 확인
127.0.0.1:6379> ACL LIST
1) "user default on nopass ~* +@all"
# 특정 사용자 정보 확인
127.0.0.1:6379> ACL GETUSER default
만약 기본 사용자가 비활성화되어 있다면:
# 기본 사용자 활성화
127.0.0.1:6379> ACL SETUSER default on
# 기본 사용자에 비밀번호 설정
127.0.0.1:6379> ACL SETUSER default >yourpassword
2-3. 클라우드 서비스별 특별 설정
AWS ElastiCache
AWS ElastiCache에서 IAM 인증을 사용하는 경우, 사용자 ID와 사용자명이 동일하고 소문자여야 하며, 임시 보안 자격 증명을 비밀번호로 사용해야 합니다.
# ElastiCache IAM 인증 예시
redis-cli -h your-cluster.cache.amazonaws.com -p 6379 --tls \
--user your-iam-user-id \
--askpass
Azure Cache for Redis
# Azure에서 사용자명:비밀번호 형식 사용
redis-cli -h your-cache.redis.cache.windows.net -p 6380 --tls \
-a "username:password"
3. 프로그래밍 언어별 해결 방법
3-1. Node.js (node-redis)
Node.js의 redis 클라이언트에서 3.1.0 버전 이후 인증 방식이 변경되어 기존 방식으로는 WRONGPASS 에러가 발생할 수 있습니다.
// ❌ 문제가 있는 코드 (구버전 방식)
const redis = require('redis');
const client = redis.createClient({
host: 'localhost',
port: 6379,
password: 'yourpassword'
});
// ✅ 해결된 코드 (최신 방식)
const redis = require('redis');
const client = redis.createClient({
url: 'redis://:yourpassword@localhost:6379',
// 또는 사용자명이 있는 경우
// url: 'redis://username:password@localhost:6379'
});
// ✅ 또는 명시적 인증 방식
const client = redis.createClient({
socket: {
host: 'localhost',
port: 6379
},
username: 'default', // 또는 실제 사용자명
password: 'yourpassword'
});
3-2. Python (redis-py)
import redis
# ✅ 올바른 연결 방법
# 방법 1: URL 방식
r = redis.from_url('redis://:password@localhost:6379/0')
# 방법 2: 매개변수 방식
r = redis.Redis(
host='localhost',
port=6379,
username='default', # Redis 6.0+에서는 명시적으로 지정
password='yourpassword',
db=0
)
# 방법 3: 사용자명이 있는 경우
r = redis.Redis(
host='localhost',
port=6379,
username='myuser',
password='mypassword',
db=0
)
3-3. Java (Jedis)
import redis.clients.jedis.Jedis;
import redis.clients.jedis.JedisPool;
import redis.clients.jedis.JedisPoolConfig;
// ✅ 올바른 연결 방법
public class RedisConnection {
private JedisPool jedisPool;
public void initializePool() {
JedisPoolConfig config = new JedisPoolConfig();
// Redis 6.0+ ACL 사용자 인증
jedisPool = new JedisPool(config, "localhost", 6379,
2000, "default", "yourpassword");
// 또는 사용자명이 있는 경우
// jedisPool = new JedisPool(config, "localhost", 6379,
// 2000, "username", "password");
}
}
4. 실시간 디버깅 및 진단 방법
4-1. 연결 상태 실시간 모니터링
# Redis 서버에서 실시간 명령 모니터링
127.0.0.1:6379> MONITOR
# 클라이언트 연결 정보 확인
127.0.0.1:6379> CLIENT LIST
# 현재 인증된 사용자 확인
127.0.0.1:6379> ACL WHOAMI
4-2. 단계별 문제 진단
1단계: 기본 연결 테스트
# 기본 연결 (비밀번호 없음)
redis-cli -h localhost -p 6379
127.0.0.1:6379> PING
2단계: 사용자명 없이 비밀번호만으로 인증
redis-cli -h localhost -p 6379
127.0.0.1:6379> AUTH yourpassword
3단계: 사용자명과 비밀번호로 인증
redis-cli -h localhost -p 6379
127.0.0.1:6379> AUTH default yourpassword
# 또는
127.0.0.1:6379> AUTH username password
4-3. 로그 분석
Redis 서버 로그에서 인증 관련 메시지를 확인하세요:
# Redis 로그 실시간 확인
tail -f /var/log/redis/redis-server.log
# 또는 Docker 환경에서
docker logs -f your-redis-container
5. 자주 발생하는 오류 시나리오와 해결책
시나리오 1: Docker 환경에서의 문제
# docker-compose.yml 올바른 설정
version: '3.8'
services:
redis:
image: redis:7-alpine
ports:
- "6379:6379"
environment:
- REDIS_PASSWORD=yourpassword
command: >
--requirepass yourpassword
--user default on >yourpassword ~* +@all
시나리오 2: 버전 업그레이드 후 문제
# 기존 Redis 5.x에서 6.0+로 업그레이드 시
# 1. 기존 requirepass 설정 확인
127.0.0.1:6379> CONFIG GET requirepass
# 2. ACL로 마이그레이션
127.0.0.1:6379> ACL SETUSER default on >현재비밀번호 ~* +@all
# 3. 설정 저장
127.0.0.1:6379> CONFIG REWRITE
시나리오 3: 클라이언트 라이브러리 호환성 문제
| 언어 | 라이브러리 | 최소 권장 버전 | 참고사항 |
|---|---|---|---|
| Node.js | node-redis | 4.0.0+ | 3.1.0 이하에서 ACL 문제 있음 |
| Python | redis-py | 3.5.0+ | username 매개변수 지원 |
| Java | Jedis | 3.6.0+ | ACL 사용자 인증 지원 |
| Go | go-redis | 8.0.0+ | Redis 6.0 ACL 완전 지원 |
6. 마지막으로 간단히 정리하자면…
다음 체크리스트를 순서대로 확인해보세요:
✅ 기본 확인사항
- [ ] Redis 버전이 6.0 이상인지 확인
- [ ] 연결 URL 형식이 올바른지 확인 (
redis://username:password@host:port/db) - [ ] 클라이언트 라이브러리 버전이 최신인지 확인
✅ 인증 방식 확인
- [ ]
AUTH username password형식으로 인증 시도 - [ ] 기본 사용자(
default) 상태 확인 - [ ] ACL 사용자 목록 및 권한 확인
✅ 환경별 특수사항
- [ ] 클라우드 서비스별 특별 인증 방식 확인 (AWS IAM, Azure AD 등)
- [ ] Docker/Kubernetes 환경에서의 네트워크 설정 확인
- [ ] SSL/TLS 설정이 필요한지 확인
✅ 로그 및 모니터링
- [ ] Redis 서버 로그에서 인증 관련 에러 메시지 확인
- [ ]
MONITOR명령으로 실시간 명령 추적 - [ ] 클라이언트 연결 상태 확인