WordPress는 수십 개의 데이터베이스 테이블에 절대 URL을 저장하므로, 도메인을 변경하거나 SSL로 전환하면 게시물, 옵션, 플러그인 설정 곳곳에 이전 주소가 흩어져 남게 됩니다. 검색 및 바꾸기는 이를 안전하게 정리하는 방법입니다. 이 가이드는 KPanel에서 지원하는 두 가지 방법, 흔히 쓰이는 세 번째 방법이 데이터를 손상시키는 이유, 그리고 결과를 확인하는 방법을 다룹니다.
검색 및 바꾸기가 필요한 경우
- SSL을 활성화한 후
http://에서https://로 전환할 때. - 도메인을 변경할 때. 예:
old-brand.co.nz에서new-brand.co.nz로. - 스테이징을 프로덕션으로 반영한 후, 스테이징 호스트 이름이 여전히 데이터베이스에 남아 있을 때.
- 이전 에셋 호스트를 폐기하고 모든 이미지 URL을 한 번에 새로 지정할 때.
- 오래된 전화번호나 단종된 제품 이름처럼 여러 게시물에 걸친 일괄 오타를 수정할 때.
검색 및 바꾸기는 모든 테이블의 행을 한 번에 다시 쓰며, 행 단위로 되돌리는 기능은 없습니다. 사소해 보이는 변경이라도 시작하기 전에 매번 백업을 생성하세요. 아래에 설명된 기본 제공 도구를 사용하면 KPanel이 자동으로 백업을 생성하지만, 명령을 직접 실행하는 경우에는 백업은 여러분의 책임입니다. 백업 생성하기를 참고하세요.
그냥 SQL REPLACE를 실행하면 안 되는 이유
이것은 WordPress 데이터베이스 작업에서 가장 큰 피해를 주는 실수이므로, 방법을 고르기 전에 이해해 둘 가치가 있습니다.
WordPress는 플러그인 설정, 테마 옵션, 위젯 데이터를 PHP 직렬화 문자열로 저장합니다. 직렬화 문자열은 내부의 모든 값의 길이를 다음과 같이 기록합니다:
a:1:{s:3:"url";s:26:"http://old-domain.co.nz/x";}
여기서 s:26은 URL의 길이가 26자라는 뜻입니다. 일반 SQL REPLACE()로 http://를 https://로 바꾸면 텍스트는 27자가 되지만 저장된 길이는 여전히 26으로 남습니다. 그러면 PHP는 해당 옵션 전체의 역직렬화를 거부하고, 설정은 아무런 알림 없이 빈 값으로 되돌아갑니다. 테마 사용자 정의 설정이 사라지고, 슬라이더의 슬라이드가 없어지며, 플러그인 라이선스 등록이 저절로 해제됩니다.
KPanel이 실행하는 WP-CLI search-replace는 각 값을 역직렬화하고, 그 안에서 바꾼 다음, 수정된 길이로 다시 직렬화합니다. 그래서 이 문서에서는 이 방법만 다룹니다.
WordPress 데이터베이스에 대해 UPDATE wp_options SET option_value = REPLACE(...) 또는 phpMyAdmin에서 이와 동등한 작업을 절대 실행하지 마세요. 성공한 것처럼 보이고 영향을 받은 행 수도 보고되지만, 건드린 모든 직렬화 설정을 조용히 망가뜨립니다. 백업에서 복원하는 것 외에는 복구할 방법이 없습니다.
방법 1: 검색 및 바꾸기 카드
거의 모든 분께 적합한 방법입니다. 모든 WordPress 플랜에서 사용할 수 있습니다.
- KPanel에 로그인하고 왼쪽 사이드바에서 웹사이트를 클릭합니다.
- 사이트를 클릭합니다.
- WordPress 탭을 연 다음 빠른 작업 섹션을 엽니다.
- 검색 및 바꾸기 카드를 찾아 구성을 클릭합니다.
- 찾기(이전 값)에 기존 텍스트를 입력합니다.
- 바꿀 내용에 새 텍스트를 입력합니다.
- 테스트 실행(미리보기만, 변경 없음)을 체크된 상태로 두고 미리보기를 클릭합니다.
테스트 실행은 몇 건이 바뀔지 보고하고 그 수를 테이블과 열별로 나누어 보여 주므로, 실제로 적용하기 전에 변경이 정확히 어디에 반영될지 확인할 수 있습니다.
미리보기 결과가 올바르면:
- 테스트 실행 체크를 해제합니다.
- 실행을 클릭합니다.
- 대화상자에서 확인합니다.
바꾸기가 시작되기 전에 전체 백업이 자동으로 생성되며, 실행은 플러그인이 만든 테이블을 포함한 모든 테이블을 대상으로 합니다.
가능한 한 가장 구체적인 문자열을 검색하세요. old-domain.co.nz를 바꾸면 mail.old-domain.co.nz와 staging.old-domain.co.nz도 함께 바뀌는데, 이는 원하는 결과가 아닌 경우가 대부분입니다. https://old-domain.co.nz처럼 스킴을 포함하면 일치 범위를 좁게 유지할 수 있습니다.
방법 2: 콘솔에서 WP-CLI 사용하기
콘솔은 같은 엔진을 사용하면서 플래그를 더 세밀하게 제어할 수 있게 해 줍니다. 관리형 플랜에 나타나는 섹션 중 하나이며, 다른 플랜에서는 탭 영역에 대신 Managed에서 +8 링크가 표시됩니다.
사이트를 열고 WordPress, 그다음 콘솔을 엽니다. 프롬프트가 이미 wp로 시작하므로 명령의 나머지 부분만 입력하세요.
먼저 미리 봅니다:
search-replace 'http://old-domain.co.nz' 'https://old-domain.co.nz' --all-tables --dry-run
그런 다음 실제로 실행합니다:
search-replace 'http://old-domain.co.nz' 'https://old-domain.co.nz' --all-tables
콘솔은 백업을 대신 생성해 주지 않습니다. 실행 전 자동 백업은 방법 1의 검색 및 바꾸기 카드를 사용할 때만 이루어집니다. 여기에서 명령을 실행한다면 먼저 사이트의 백업 페이지에서 직접 백업을 생성하세요.
유용한 플래그:
| 플래그 | 기능 |
|---|---|
--all-tables | WordPress 코어 테이블뿐 아니라 플러그인이 만든 사용자 정의 테이블도 포함합니다 |
--dry-run | 무엇이 바뀔지 보고만 하고 아무것도 쓰지 않습니다 |
--precise | 바꾸기에 SQL 대신 PHP를 사용합니다. 더 느리지만 까다로운 직렬화 구조를 처리합니다 |
--skip-columns=guid | 게시물 GUID는 그대로 둡니다(아래 참조) |
--report-changed-only | 출력을 실제로 변경된 테이블로만 줄입니다 |
GUID에 관한 참고 사항
모든 WordPress 게시물에는 guid 열이 있습니다. URL처럼 보이지만 링크가 아니라 식별자이며, 피드 리더는 이를 사용해 이미 본 항목인지 판단합니다. 이를 다시 쓰면 피드의 모든 게시물이 새 글로 다시 나타날 수 있습니다.
도메인을 영구적으로 변경하고 새로 시작하는 경우에는 GUID를 다시 쓰세요. 같은 도메인에서 HTTP에서 HTTPS로만 전환하는 경우에는 --skip-columns=guid로 건너뛰세요.
도메인 변경: 대신 사이트 URL 카드를 사용하세요
사이트를 새 도메인으로 옮기는 것이 목적이라면 검색 및 바꾸기로 시작하지 마세요. 같은 빠른 작업 섹션에 있는 사이트 URL 변경 카드는 siteurl과 home 옵션을 업데이트하고 모든 테이블에 걸친 바꾸기를 한 번의 작업으로, 올바른 순서대로 실행합니다. 순서를 반대로 하면 WordPress가 자체 관리자 화면을 불러오지 못하게 될 수 있습니다.
바꾸기 이후
완료라고 하기 전에 이 목록을 차례로 확인하세요.
- 캐시를 비웁니다. 빠른 작업 섹션에서 캐시 비우기를 실행합니다. 사이트가 전체 페이지 캐시를 사용한다면 WordPress, 그다음 캐싱에서 비웁니다.
- 재작성 규칙을 비웁니다. 같은 섹션에서 재작성 규칙 비우기를 실행하거나, wp-admin에서 설정, 그다음 고유주소를 열고 아무것도 바꾸지 않은 채 변경 사항 저장을 클릭합니다.
- 사이트가 CDN을 사용 중이라면 성능, 그다음 Kapsule CDN에서 CDN 캐시를 제거합니다. Kapsule CDN 캐시 제거하기를 참고하세요.
- 브라우저 캐시에 속지 않도록 비공개 창에서 사이트를 불러옵니다.
- 자물쇠 표시를 확인합니다. SSL 전환 후 자물쇠가 없거나 경고가 표시된다면 URL이 남아 있다는 뜻입니다: 혼합 콘텐츠 경고 해결하기.
- 손이 많이 가는 페이지를 직접 클릭해 확인합니다. 홈페이지 슬라이더, 헤더 로고, 페이지 빌더로 만든 모든 페이지, 그리고 스토어의 결제 페이지입니다. 이런 곳에 직렬화 옵션 안에 있는 URL이 들어 있습니다.
- 캐싱 플러그인이 있다면 해당 플러그인의 설정 화면에서 캐시를 지웁니다.
문제 해결
테스트 실행에서 바뀔 항목이 0건으로 보고됩니다. 해당 문자열이 데이터베이스에 정확히 그 형태로 존재하지 않는 것입니다. 끝의 슬래시, www. 접두사, 또는 스킴을 확인하세요. 먼저 호스트 이름만 검색해서 데이터베이스에 존재하는지부터 확인해 보세요.
도메인 변경 후 이미지가 깨집니다. 미디어 URL은 wp_posts와 wp_postmeta에 있으며 --all-tables로 처리되지만, CDN이나 이미지 최적화 플러그인이 자체적으로 다시 쓴 사본을 캐시하고 있을 수 있습니다. CDN과 플러그인 캐시를 비운 다음 새로고침하세요.
바꾸기 후 설정이 사라졌습니다. 이것이 바로 직렬화 문제이며, 여기의 도구가 아니라 원시 SQL로 변경이 이루어졌다는 뜻입니다. 실행 전에 생성된 백업에서 복원하세요: 백업에서 복원하기.
스테이징 URL이 계속 다시 나타납니다. 무언가가 이를 다시 채우고 있으며, 대개 예약된 반영 작업이나 캐시된 옵션 때문입니다. 스테이징 사용하기: 반영 및 가져오기의 워크플로를 확인하고, 반영할 때 URL 재작성이 체크되어 있는지 확인하세요.