CentOS에서 Composer로 프로젝트를 세팅한 뒤, 갑자기 Redis 관련 에러(예: Class 'Redis' not found, ext-redis is missing, undefined symbol 등)를 만나면 원인이 한두 가지로 고정되지 않는 경우가 많습니다. 이 글은 재현 → 원인 좁히기 → 해결 순서로, 안전하게 확인할 것들을 체크리스트 형태로 정리했습니다.
급할수록 “정확히 무엇이 어디서 실패했는지”부터 고정해두는 게 제일 빠릅니다.
1) 먼저 재현을 고정하기: 어떤 에러가 언제 나나
Redis 관련 문제는 “Composer 단계”에서 터지는 것처럼 보여도, 실제로는 PHP 확장 로딩 또는 실행하는 PHP 바이너리 불일치(CLI vs FPM)에서 시작하는 경우가 많습니다. 아래 중 어떤 상황에서 에러가 나는지 먼저 고정하세요.
- composer install/update 실행 중에 에러가 나는가
- php -v는 정상인데, 웹에서만 Redis가 안 되는가(반대도 가능)
- Laravel/Symfony 등 프레임워크 부팅 시점에만 터지는가
- Redis 서버 접속(네트워크) 문제인가, ext-redis(phpredis)/predis 선택 문제인가
가능하면 에러 로그/출력에서 정확한 메시지 한 줄을 확보해두세요. 예: “Package requires ext-redis * but it is missing”, “Class Redis not found”, “PHP Warning: PHP Startup: Unable to load dynamic library 'redis.so' …”
2) 안전한 기본 체크리스트(가장 흔한 원인부터)
아래는 “빨리 확인할수록 손해가 없는” 기본 체크리스트입니다. 하나씩만 확인해도 원인이 크게 좁혀집니다.
- Composer가 어떤 PHP로 실행되는지 확인: which php, php -v, php --ini
- redis 확장 로드 여부: php -m | grep -i redis
- ini 파일 위치: php --ini에서 “Loaded Configuration File”, “Scan for additional .ini files in” 확인
- 웹(PHP-FPM)과 CLI의 설정 차이: 웹의 phpinfo()에서 ini 경로/추가 ini 디렉터리 비교
- composer.json에서 요구사항 확인: require에 ext-redis가 있는지, 또는 predis/predis를 쓰는지
- SELinux가 Enforcing인지(접속/소켓/권한 문제에 영향): getenforce
- Redis 서버 확인: 로컬/원격 주소, 포트, 인증, 방화벽(보안그룹 포함)
3) 원인 좁히기: 메시지별로 갈라지는 핵심 분기
여기부터는 “재현된 메시지” 기준으로 원인을 좁힙니다. 아래 패턴 중 가장 가까운 걸 골라 보세요.
- Class 'Redis' not found: 보통 phpredis 확장 미설치 또는 로드되지 않음, 또는 앱이 phpredis를 기대하는데 predis만 설치한 케이스
- Package requires ext-redis * but it is missing: Composer가 ext-redis 요구를 확인했지만, 현재 실행 중인 PHP(대개 CLI)에 redis 확장이 없음
- Unable to load dynamic library 'redis.so': redis.so 파일이 없거나, 경로/권한/아키텍처 불일치, 또는 의존 라이브러리/심볼 문제
- undefined symbol: ... 또는 Segfault 류: PHP 버전과 redis.so(또는 igbinary 등) 빌드/호환 불일치 가능성
- Connection refused / timed out: 확장 문제라기보다 Redis 서버 접속 문제(주소/포트/방화벽/Redis bind 설정 등)
이 글의 초점은 “Composer 설치 이후 Redis 쪽에서 막히는 문제”이므로, 우선 확장 로딩 문제(CLI/FPM 포함)인지부터 확실히 분리하는 게 좋습니다.
4) 해결 1: CLI와 FPM의 PHP가 다른 경우(가장 흔함)
CentOS에서는 PHP를 여러 경로로 설치(RPM, Remi, 소스빌드, 컨테이너 등)하다 보면 Composer는 PHP A(CLI)로 실행되고, 실제 서비스는 PHP B(PHP-FPM)로 도는 구성이 종종 생깁니다. 이때 “composer install은 되는데 웹에서 Redis가 안 됨” 또는 그 반대가 나옵니다.
- Composer 실행 시 php -v가 가리키는 버전과, 웹의 phpinfo() 상 버전이 같은지 확인
- 다르면, Composer를 서비스 PHP에 맞춰 실행(예: 해당 PHP 바이너리로 composer 실행)하거나, 서비스와 CLI를 같은 PHP 라인업으로 정리
- phpredis 설치도 “실제로 사용하는 PHP”에 맞춰 설치/로드(웹이면 FPM 쪽 ini 포함)
특히 Remi를 쓴 환경에서 /usr/bin/php와 /opt/remi/phpXX/root/usr/bin/php가 섞이면 이 문제가 쉽게 생깁니다. “내가 지금 어느 PHP로 Composer를 돌렸는지”를 먼저 고정해두면 절반은 해결됩니다.
5) 해결 2: ext-redis(phpredis) 설치/활성화와 Composer 요구사항 정리
Composer 에러가 ext-redis is missing 쪽이라면, 크게 두 가지 선택지입니다.
- phpredis를 실제로 설치/활성화해서 ext-redis 요구를 만족시키기
- 프로젝트가 굳이 ext-redis가 필요 없다면(예: predis로 충분) composer.json의 요구사항을 재검토하기
운영에서 성능/호환 때문에 phpredis를 쓰는 경우가 많아 첫 번째가 일반적입니다. 다만 여기서도 흔한 함정이 있습니다.
- 설치는 했는데 ini에 extension=redis가 적용되지 않음(경로가 다른 ini를 보고 있음)
- FPM만 재시작하고 CLI는 그대로(또는 그 반대)라서 확인이 엇갈림
- igbinary/msgpack 같은 옵션을 켠 상태로 설치해놓고, 나중에 관련 확장을 제거해 심볼 오류가 나는 케이스
Composer 단계에서만 당장 막혔다면 임시로 --ignore-platform-req=ext-redis 같은 우회가 떠오를 수 있는데, 운영/배포에서는 권하지 않습니다. 결국 런타임에서 더 크게 터질 가능성이 높고, 원인 추적도 어려워집니다. “왜 ext-redis가 필요한지”를 확인하고, 필요하다면 제대로 설치/정렬하는 편이 안전합니다.
6) 흔한 실수 목록(실제로 많이 시간 잡아먹는 것들)
- Redis 서버 문제인데 확장 문제로만 보고 시간을 쓰는 경우(방화벽, bind, requirepass, 보안그룹)
- CLI에서는 redis 모듈이 보이는데 웹에서는 안 보임: FPM의 ini 경로가 다르거나 pool 별로 설정이 다른 경우
- 웹에서는 되는데 composer에서 ext-redis missing: Composer가 실행하는 PHP(CLI)에 redis 확장이 없음
- redis.so는 있는데 로드 실패: 파일만 복사해 넣고 의존/버전 호환을 무시한 경우(결국 undefined symbol)
- composer.lock과 실제 서버 환경이 달라 플랫폼 요구가 꼬이는 경우(빌드 서버/로컬과 운영이 다른 PHP 확장 구성)
- SELinux가 Enforcing인데, 소켓/네트워크 접근 권한을 고려하지 않은 경우(연결 오류가 간헐적으로 보이기도 함)
마무리
CentOS에서 Composer 이후 Redis 오류를 빠르게 잡는 핵심은 “Redis 서버 접속 문제”와 “PHP 확장/환경 문제”를 먼저 분리하고, 그 다음에 CLI와 FPM의 PHP 불일치를 의심하는 순서입니다.
체크리스트대로 한 번만 정리해두면, 다음부터는 같은 유형의 장애를 훨씬 짧게 끝낼 수 있습니다.