CMS 데이터베이스 연결 오류 진단하기 (WordPress, DedeCMS 등)

CMS(콘텐츠 관리 시스템)에서 데이터베이스 연결은 웹사이트 운영의 핵심입니다. 연결이 실패하면 사이트 접속 불가, 관리자 로그인 오류, 데이터 로딩 실패 등 다양한 문제가 발생합니다. 이 글에서는 실제 개발 경험을 바탕으로 데이터베이스 연결 문제를 단계별로 진단하고 해결하는 방법을 소개합니다.

1단계: 기본 설정 파일 점검 (가장 흔한 원인)

데이터베이스 연결에 필요한 주요 설정은 CMS의 핵심 설정 파일에 저장됩니다. 가장 먼저 파일의 내용을 확인해야 합니다.

설정 파일 위치 파악

CMS마다 설정 파일의 위치와 이름이 다릅니다. 대표적인 시스템들의 기본 경로는 다음과 같습니다.

  • WordPress: wp-config.php (웹사이트 루트 디렉토리)
  • DedeCMS: data/common.inc.php (데이터 디렉토리)
  • Joomla: configuration.php (웹사이트 루트 디렉토리)
  • CodeIgniter 기반 CMS: application/config/database.php

핵심 설정 항목 확인

파일을 열어 아래와 같은 주요 연결 정보가 실제 데이터베이스 정보와 일치하는지 검증합니다. (변수명은 CMS에 따라 다를 수 있지만, 의미는 동일합니다)


// 일반적인 설정 예시 (MySQL 기준)
$host = 'localhost';      // 데이터베이스 서버 주소
$db_name = 'my_site_db';  // 데이터베이스 이름
$user_name = 'db_admin';  // 데이터베이스 사용자명
$password = 'P@ssw0rd!';  // 데이터베이스 비밀번호
$port = '3306';           // 포트 번호 (기본값 3306)

자주 발생하는 실수:

  • 호스트 주소 오타 (예: lcoalhost로 잘못 입력)
  • 데이터베이스 이름이나 사용자명의 대소문자 불일치
  • 비밀번호에 포함된 특수문자 미처리 또는 복사 시 공백 포함
  • 클라우드 서버 보안 그룹에서 3306 포트가 닫혀 있는 경우

2단계: 데이터베이스 연결 테스트 도구 사용

설정 파일이 정확하다면, 실제로 데이터베이스에 접근 가능한지 확인해야 합니다.

명령줄 인터페이스 (CLI) 활용

서버 또는 로컬 환경에서 MySQL 클라이언트를 사용하여 직접 연결을 시도합니다.


# Linux/macOS 터미널 또는 Windows CMD
mysql -h [호스트 주소] -u [사용자명] -p[비밀번호] -P [포트번호]

결과 해석:

  • 연결 성공: 데이터베이스 자체는 문제없음. CMS 자체의 오류 가능성이 높습니다.
  • "Access denied for user": 사용자명 또는 비밀번호가 틀렸거나, 해당 사용자에게 접근 권한이 없습니다.
  • "Can't connect to MySQL server": MySQL 서비스가 실행 중인지, 포트가 열려 있는지, 호스트 주소가 올바른지 확인해야 합니다.

GUI 도구 활용

Navicat, DBeaver, MySQL Workbench와 같은 도구를 사용하면 더 직관적으로 확인할 수 있습니다. 새 연결을 만들고 설정 파일의 정보를 입력한 후 "연결 테스트"를 실행합니다. 오류 메시지가 표시되면(예: "timeout", "permission denied") 해당 내용을 바탕으로 문제를 좁혀 나갑니다.

3단계: 시스템 및 서버 로그 분석

로그 파일은 문제의 근본 원인을 찾는 데 매우 유용합니다. 주로 두 가지 유형의 로그를 확인합니다.

CMS 자체 로그

WordPress의 경우 디버그 모드를 활성화하여 상세한 오류를 기록할 수 있습니다. wp-config.php 파일에 다음 코드를 추가합니다.


define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);      // wp-content/debug.log 파일에 저장
define('WP_DEBUG_DISPLAY', false); // 화면에는 오류를 표시하지 않음

오류가 발생한 페이지를 방문한 후 wp-content/debug.log 파일을 열어 database 또는 MySQL 관련 단어를 검색합니다.

다른 CMS의 로그 위치 예시:

  • DedeCMS: data/logs/ 디렉토리
  • Typecho: 디버그 모드 활성화 시 var/Typecho/Log.php

웹 서버 로그

  • Apache: Linux - /var/log/apache2/error.log, Windows - 설치 디렉토리 내 logs/error.log
  • Nginx: /var/log/nginx/error.log

로그에서 PHP Warning 또는 PHP Fatal error 메시지를 찾고, 그중 mysqli_connect()나 PDO 관련 오류가 있다면 데이터베이스 연결 문제로 확진할 수 있습니다.

4단계: 고급 진단 (특수 상황)

위 단계로 문제가 해결되지 않으면 다음 항목들을 추가로 점검해야 합니다.

데이터베이스 서비스 상태 확인

  • Linux (systemd): systemctl status mysqld (CentOS/RHEL) 또는 systemctl status mysql (Ubuntu/Debian) 명령어로 서비스가 활성 상태인지 확인합니다. 서비스가 중지되어 있다면 systemctl start mysqld로 시작하고, /var/log/mysqld.log 파일에서 시작 실패 원인을 분석합니다.
  • Windows: "서비스" 관리 도구(services.msc)를 열어 MySQL 서비스 상태가 "실행 중"인지 확인합니다.

데이터베이스 사용자 권한 확인

아이디와 비밀번호가 정확하더라도 사용자에게 해당 데이터베이스에 접근할 권한이 없을 수 있습니다. 데이터베이스에 관리자로 접속하여 다음 SQL을 실행합니다.


-- 사용자의 접근 호스트 확인
SELECT host, user FROM mysql.user WHERE user = 'db_admin';

-- 모든 호스트(%)에서 접근 가능하도록 권한 부여 (필요한 경우)
GRANT ALL PRIVILEGES ON my_site_db.* TO 'db_admin'@'%' IDENTIFIED BY 'P@ssw0rd!';
FLUSH PRIVILEGES;

host 값이 localhost인 경우, 같은 서버에서만 접속이 가능합니다. 원격 접속이 필요하다면 위와 같이 '%'로 변경해야 합니다.

PHP 확장 모듈 및 버전 호환성 확인

CMS가 요구하는 PHP 버전과 데이터베이스 확장(mysqli, pdo_mysql 등)이 설치 및 활성화되어 있어야 합니다. phpinfo() 함수를 사용하여 현재 PHP 설정을 확인하고, 필요한 확장이 없다면 php.ini 파일에서 해당 줄의 주석을 제거하거나 패키지 관리자를 통해 설치합니다.

방화벽 및 보안 그룹 설정 확인

  • 로컬 서버: 테스트 목적으로 방화벽을 일시적으로 비활성화해 봅니다. (Linux: systemctl stop firewalld, Windows: "Windows Defender 방화벽" 설정)
  • 클라우드 서버 (AWS, GCP, Azure 등): 웹 콘솔의 보안 그룹(또는 방화벽 규칙)에서 인바운드 규칙에 사용 중인 데이터베이스 포트(기본 3306)가 허용되어 있는지 확인합니다. 너무 넓은 범위(0.0.0.0/0)는 보안 위험이 있으므로 특정 IP만 허용하는 것을 권장합니다.

문제 해결 요약

데이터베이스 연결 문제 진단의 핵심은 "설정 파일 → 데이터베이스 연결 테스트 → 로그 분석 → 고급 설정 검토" 순서로 진행하는 체계적인 접근 방식입니다. 이 단계를 따르면 대부분의 연결 오류(90% 이상)를 해결할 수 있습니다.

위 방법으로도 문제가 지속된다면 다음과 같은 최후의 수단을 시도해 볼 수 있습니다.

  • 데이터베이스와 사용자를 새로 생성하고 모든 권한을 부여합니다.
  • CMS 공식 사이트에서 해당 버전의 기본 설정 파일을 다운로드하여 교체한 후 다시 설정합니다.
  • 호스팅 업체 또는 CMS 공식 기술 지원팀에 문의합니다.

태그: CMS WordPress DedeCMS MySQL 데이터베이스 연결

5월 26일 03:10에 게시됨

인기 태그

©2026 괴물 클럽