워드프레스 도메인 이전 (WP-CLI, search-replace, 사이트맵)
도메인 하나 바꾸는 게 이렇게 긴 작업이 될 줄 알았다면, 저는 아마 처음부터 도메인을 더 신중하게 골랐을 겁니다. 구입한 도메인이 불과 몇 달 전까지 전혀 다른 성격의 사이트로 운영되고 있었다는 사실을 Google Search Console 대시보드에서 처음 확인했을 때, 솔직히 이건 예상 밖이었습니다. 도메인 평판 문제로 결국 워드프레스 사이트를 새 도메인으로 통째로 옮기는 작업을 직접 해봤고, 그 과정에서 WP-CLI를 처음 제대로 써봤습니다.
도메인을 바꿔야 했던 이유, 그냥 새 주소로 연결하면 안 될까요
처음에는 정말 간단하게 생각했습니다. 새 도메인을 서버에 연결하고, 워드프레스 설정에서 주소만 바꾸면 끝나는 일이라고요. 그런데 막상 시작해보니 워드프레스에서 도메인이란 단순히 주소창에만 존재하는 것이 아니었습니다.
워드프레스는 사이트 주소를 데이터베이스(Database) 안에 저장합니다. 데이터베이스란 사이트의 글, 설정, 옵션 값 등 모든 데이터를 구조화해서 보관하는 공간을 뜻합니다. 문제는 이 데이터베이스 안에 기존 도메인 주소가 직렬화된 문자열(serialized string) 형태로 곳곳에 박혀 있다는 점입니다. 직렬화된 문자열이란 PHP 객체나 배열을 텍스트로 변환해서 저장한 형식인데, 단순히 텍스트 검색으로 바꿔버리면 데이터 구조 자체가 깨질 수 있습니다.
더구나 저는 워드프레스를 Docker 컨테이너 위에서 운영하고 있었습니다. Docker 컨테이너란 애플리케이션을 독립된 환경에서 실행할 수 있도록 묶어놓은 가상 실행 단위입니다. 웹서버, 리버스 프록시(Reverse Proxy), 캐시까지 여러 요소가 각각의 컨테이너로 나뉘어져 있다 보니, “도메인을 바꾼다”는 작업이 단일 설정 파일 하나를 고치는 것으로 끝나지 않았습니다. 제가 직접 써봤는데, 생각보다 손볼 곳이 정말 많았습니다.
도메인 이전을 결심하게 된 이유는 도메인 평판(Domain Reputation) 때문이었습니다. 도메인 평판이란 특정 도메인 주소가 검색엔진과 사용자들 사이에서 쌓아온 신뢰도와 히스토리를 말합니다. Google Search Console에서 기존 소유자의 콘텐츠 흔적이 남아 있는 것을 확인했고, 그 방향이 제가 만들고자 하는 블로그의 성격과 전혀 맞지 않았습니다. 처음부터 깨끗한 도메인으로 시작하는 편이 낫다는 판단을 내렸습니다.
WP-CLI를 Docker 환경에 설치하면서 겪은 일
WP-CLI(WordPress Command Line Interface)는 워드프레스를 터미널 명령어로 직접 제어할 수 있게 해주는 도구입니다. 쉽게 말해, 워드프레스 관리자 화면에서 클릭으로 하던 작업들을 명령줄에서 텍스트 명령 한 줄로 처리할 수 있게 해주는 인터페이스입니다. 이번 도메인 이전 작업에서 핵심이 된 명령어는 wp search-replace였습니다.
wp search-replace는 데이터베이스 전체를 검색해서 특정 문자열을 다른 문자열로 일괄 교체해주는 명령어입니다. 그리고 중요한 점은 이 명령어가 앞서 말한 직렬화된 문자열 구조를 자동으로 처리해준다는 것입니다. 일반적인 SQL 쿼리로 단순 치환을 하면 직렬화 구조가 깨져서 사이트가 아예 열리지 않을 수도 있는데, wp search-replace는 그 부분까지 고려해서 설계되어 있습니다.
그런데 Docker 컨테이너 터미널에 접속해서 wp 명령어를 입력하자마자 반갑지 않은 메시지가 나왔습니다.
wp: command not found
WP-CLI가 설치되어 있지 않았던 것입니다. 결국 Docker 컨테이너 안에 WP-CLI를 직접 설치해야 했습니다. 처음에는 도메인 주소 하나를 바꾸려고 시작한 작업인데, 어느 순간 Docker 컨테이너 내부에서 WP-CLI 설치 명령어를 치고 있는 제 모습을 보면서 “이게 맞는 방향인가”라는 생각이 잠깐 들기도 했습니다. 그래도 WP-CLI 공식 문서에서 안내하는 절차대로 설치를 마치고 나니 이후 작업은 훨씬 수월해졌습니다.
WP-CLI 설치 후 도메인 교체 작업 순서를 정리하면 이렇습니다.
- wp search-replace ‘domain1.com’ ‘domain2.com’ –skip-columns=guid 명령어로 데이터베이스 전체의 기존 도메인을 새 도메인으로 일괄 교체합니다.
- wp option update siteurl ‘https://domain2.com’과 wp option update home ‘https://domain2.com’ 명령어로 워드프레스 핵심 옵션 값을 직접 업데이트합니다.
- wp cache flush 명령어로 워드프레스 오브젝트 캐시(Object Cache)를 비웁니다. 오브젝트 캐시란 워드프레스가 데이터베이스 조회 속도를 높이기 위해 임시로 저장해두는 데이터 공간을 말합니다.
- 리버스 프록시와 웹서버 설정에서 기존 도메인을 참조하고 있는 부분을 새 도메인으로 수정하고 서비스를 재시작합니다.
이 순서대로 작업을 진행했고, 새 도메인으로 접속이 되는 것을 처음 확인했을 때는 꽤 안도했습니다. 그런데 기뻐하기엔 아직 일렀습니다.
CSS가 깨지고, 사이트맵이 사라진 이유
새 도메인으로 사이트가 열리기는 했는데 디자인이 전혀 표시되지 않았습니다. 흰 배경에 텍스트만 나오는 상태였습니다. 처음에는 테마 문제인가 싶었습니다. 도메인을 바꾸면서 워드프레스 내부 설정이 꼬인 건가 싶기도 했고요.
브라우저 개발자 도구로 확인해보니 CSS 파일과 JavaScript 파일들의 경로가 여전히 기존 도메인인 domain1.com을 가리키고 있었습니다. 캐시(Cache) 문제였습니다. 캐시란 빠른 재사용을 위해 데이터를 임시로 저장해두는 공간인데, 리버스 프록시나 서버 단에서 이전 도메인의 응답을 그대로 캐싱하고 있던 것입니다. Docker 환경에서는 워드프레스 자체 캐시 외에도 Nginx 리버스 프록시의 캐시, 그리고 경우에 따라서는 CDN 캐시까지 각각 따로 비워줘야 한다는 것을 이번에 직접 경험했습니다.
CSS 문제를 해결하고 나니 이번에는 사이트맵이 문제였습니다. 새 도메인 주소로 sitemap.xml에 접속했더니 페이지를 찾을 수 없다는 화면이 나왔습니다. 사이트맵(sitemap.xml)이란 검색엔진이 사이트의 페이지 구조를 파악할 수 있도록 URL 목록을 정리해서 제공하는 파일입니다. 검색엔진 최적화(SEO)에서 빠질 수 없는 요소입니다.
원인을 찾다 보니 워드프레스의 퍼머링크(Permalink) 설정이 초기화된 상태였습니다. 퍼머링크란 워드프레스에서 각 페이지와 글에 대한 영구적인 URL 구조를 정의하는 설정입니다. 워드프레스 관리자 페이지에서 설정 → 퍼머링크로 들어가서 아무것도 바꾸지 않고 저장 버튼만 한 번 눌렀더니, 사이트맵이 정상적으로 생성됐습니다. 알고 보면 간단한 해결책이었는데, 찾기까지가 꽤 오래 걸렸습니다.
제 경험상 이건 좀 다릅니다. 도메인 이전은 데이터베이스 주소를 바꾸는 작업이라고 알려져 있지만, 실제로는 그 주소를 참조하고 있는 모든 레이어를 하나씩 새 주소로 업데이트하는 작업입니다. 데이터베이스, 캐시, 웹서버 설정, 퍼머링크 설정까지 하나라도 빠지면 그쪽에서 문제가 터집니다.
Google Search Console 재등록, 마지막 퍼즐 조각
사이트 자체는 정상화됐지만, 검색엔진 입장에서 보면 도메인이 바뀐 사이트는 완전히 새로운 사이트입니다. 기존 domain1.com에서 쌓인 Search Console 데이터는 새 도메인 domain2.com으로 자동으로 이어지지 않습니다.
Google Search Console에 domain2.com을 새로 등록하고, 사이트맵 주소를 제출했습니다. Google Search Console은 구글이 제공하는 무료 도구로, 사이트가 구글 검색에 어떻게 노출되는지 확인하고 색인 요청을 직접 보낼 수 있는 서비스입니다. 새 도메인으로 사이트맵을 제출하면 구글이 새 주소를 기준으로 페이지를 다시 크롤링하고 색인에 반영하기 시작합니다.
사이트맵 제출이 완료된 시점에서야 이번 작업이 완전히 마무리됐다는 느낌이 들었습니다. 새 도메인 접속, 관리자 페이지, 글, 이미지, CSS, 사이트맵, 검색엔진 등록까지 하나씩 확인하면서 체크했고, 모든 항목이 정상으로 뜨는 순간에는 꽤 뿌듯했습니다.
이번에 WP-CLI를 처음 제대로 써보면서 느낀 것이 있습니다. 워드프레스는 관리자 화면만으로 운영하는 CMS라고 생각하기 쉬운데, 실제로 서버에서 운영하다 보면 터미널을 통해 직접 제어해야 하는 상황이 반드시 옵니다. 특히 데이터베이스에 저장된 값을 대량으로 변경해야 할 때는 WP-CLI의 wp search-replace 명령어 하나가 수십 분의 수작업을 대체해줍니다. 공식 문서인 WP-CLI Commands 문서를 보면 wp cache, wp option, wp rewrite, wp transient 등 도메인 이전에 유용한 명령어들이 잘 정리되어 있으니, 비슷한 작업을 앞두고 있다면 한 번 훑어보는 것을 권합니다.
자주 묻는 질문
Q. 워드프레스 도메인을 바꿀 때 wp search-replace를 꼭 써야 하나요?
A. 반드시 필수는 아니지만, 직렬화된 문자열 처리 때문에 wp search-replace를 쓰는 것이 훨씬 안전합니다. 일반 SQL 쿼리로 단순 치환을 하면 데이터 구조가 깨져서 사이트가 열리지 않을 수 있습니다. 저도 처음에는 다른 방법을 생각했는데, 결국 wp search-replace 쪽이 가장 믿을 만한 선택이었습니다.
Q. Docker 환경에서 WP-CLI를 사용하려면 어떻게 해야 하나요?
A. Docker 컨테이너 내부에 WP-CLI를 직접 설치해야 합니다. 기본 워드프레스 Docker 이미지에는 WP-CLI가 포함되어 있지 않습니다. WP-CLI 공식 설치 가이드에 따라 컨테이너 안에서 curl로 다운로드하고 실행 권한을 부여하면 됩니다. 한 번 설치해두면 이후 작업은 훨씬 편해집니다.
Q. 도메인을 바꾸면 CSS가 깨지는 이유가 뭔가요?
A. CSS 파일 경로가 데이터베이스나 캐시에 기존 도메인으로 저장되어 있기 때문입니다. wp search-replace로 데이터베이스를 교체한 뒤에도 리버스 프록시나 서버 캐시에 이전 응답이 남아 있으면 CSS가 깨진 채로 보일 수 있습니다. 각 레이어의 캐시를 모두 비워주고 나면 정상적으로 표시됩니다.
Q. 도메인을 바꾼 후 사이트맵이 안 나올 때 어떻게 해결하나요?
A. 워드프레스 관리자 페이지에서 설정 → 퍼머링크 메뉴로 이동해서 저장 버튼만 한 번 눌러주면 대부분 해결됩니다. 이 과정에서 워드프레스가 .htaccess 파일과 리라이트 규칙을 다시 생성하면서 사이트맵 경로도 정상화됩니다. 저도 이 방법을 찾기까지 한참 헤맸는데, 의외로 간단한 해결책이었습니다.
Q. 구 도메인에서 새 도메인으로 SEO 점수는 이어받을 수 있나요?
A. 완전히 이어받기는 어렵습니다. 다만 구 도메인에서 새 도메인으로 301 리다이렉트(영구 이동 처리)를 설정해두면 구글이 링크 권위 일부를 넘겨받는 것으로 처리합니다. 저처럼 도메인 평판 문제로 이전하는 경우에는 굳이 리다이렉트를 설정하지 않고 새 도메인에서 처음부터 시작하는 편이 나을 수도 있습니다.
돌이켜보면, 처음 생각했던 것보다 훨씬 긴 작업이었습니다. 도메인 하나를 바꾸는 일이 결국 데이터베이스, Docker, WP-CLI, 캐시, 퍼머링크, 사이트맵, 검색엔진 등록까지 이어졌습니다. 비슷한 작업을 앞두고 있다면, wp search-replace 한 번으로 끝날 것이라는 기대는 내려놓는 편이 좋습니다. 대신 각 레이어를 하나씩 확인해가는 과정이라고 생각하면 당황하지 않고 진행할 수 있습니다.
—
참고: https://developer.wordpress.org/cli/commands/
https://search.google.com/search-console/about