# WordPress 데이터베이스에서 검색 및 바꾸기 실행하기

Source: https://support.kapsulehost.com/ko-kr/wordpress-search-replace

WordPress는 수십 개의 데이터베이스 테이블에 절대 URL을 저장하므로, 도메인을 변경하거나 SSL로 전환하면 게시물, 옵션, 플러그인 설정 곳곳에 이전 주소가 흩어져 남게 됩니다. 검색 및 바꾸기는 이를 안전하게 정리하는 방법입니다. 이 가이드는 KPanel에서 지원하는 두 가지 방법, 흔히 쓰이는 세 번째 방법이 데이터를 손상시키는 이유, 그리고 결과를 확인하는 방법을 다룹니다.

## 검색 및 바꾸기가 필요한 경우

- SSL을 활성화한 후 `http://`에서 `https://`로 전환할 때.
- 도메인을 변경할 때. 예: `old-brand.co.nz`에서 `new-brand.co.nz`로.
- 스테이징을 프로덕션으로 반영한 후, 스테이징 호스트 이름이 여전히 데이터베이스에 남아 있을 때.
- 이전 에셋 호스트를 폐기하고 모든 이미지 URL을 한 번에 새로 지정할 때.
- 오래된 전화번호나 단종된 제품 이름처럼 여러 게시물에 걸친 일괄 오타를 수정할 때.

> **Warning:** 검색 및 바꾸기는 모든 테이블의 행을 한 번에 다시 쓰며, 행 단위로 되돌리는 기능은 없습니다. 사소해 보이는 변경이라도 시작하기 전에 매번 백업을 생성하세요. 아래에 설명된 기본 제공 도구를 사용하면 KPanel이 자동으로 백업을 생성하지만, 명령을 직접 실행하는 경우에는 백업은 여러분의 책임입니다. [백업 생성하기](https://support.kapsulehost.com/ko-kr/taking-a-backup)를 참고하세요.

## 그냥 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는 각 값을 역직렬화하고, 그 안에서 바꾼 다음, 수정된 길이로 다시 직렬화합니다. 그래서 이 문서에서는 이 방법만 다룹니다.

> **Important:** WordPress 데이터베이스에 대해 `UPDATE wp_options SET option_value = REPLACE(...)` 또는 phpMyAdmin에서 이와 동등한 작업을 절대 실행하지 마세요. 성공한 것처럼 보이고 영향을 받은 행 수도 보고되지만, 건드린 모든 직렬화 설정을 조용히 망가뜨립니다. 백업에서 복원하는 것 외에는 복구할 방법이 없습니다.

## 방법 1: 검색 및 바꾸기 카드

거의 모든 분께 적합한 방법입니다. 모든 WordPress 플랜에서 사용할 수 있습니다.

1. [KPanel](https://kpanel.kapsulehost.com)에 로그인하고 왼쪽 사이드바에서 **웹사이트**를 클릭합니다.
2. 사이트를 클릭합니다.
3. **WordPress** 탭을 연 다음 **빠른 작업** 섹션을 엽니다.
4. **검색 및 바꾸기** 카드를 찾아 **구성**을 클릭합니다.
5. **찾기(이전 값)**에 기존 텍스트를 입력합니다.
6. **바꿀 내용**에 새 텍스트를 입력합니다.
7. **테스트 실행(미리보기만, 변경 없음)**을 체크된 상태로 두고 **미리보기**를 클릭합니다.

![KPanel 빠른 작업의 검색 및 바꾸기 카드](https://support.kapsulehost.com/help/screenshots/wordpress-search-replace.d3d0a573.webp)

테스트 실행은 몇 건이 바뀔지 보고하고 그 수를 테이블과 열별로 나누어 보여 주므로, 실제로 적용하기 전에 변경이 정확히 어디에 반영될지 확인할 수 있습니다.

미리보기 결과가 올바르면:

1. **테스트 실행** 체크를 해제합니다.
2. **실행**을 클릭합니다.
3. 대화상자에서 확인합니다.

바꾸기가 시작되기 전에 전체 백업이 자동으로 생성되며, 실행은 플러그인이 만든 테이블을 포함한 모든 테이블을 대상으로 합니다.

> **Tip:** 가능한 한 가장 구체적인 문자열을 검색하세요. `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
```

> **Warning:** 콘솔은 백업을 대신 생성해 주지 않습니다. 실행 전 자동 백업은 방법 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가 자체 관리자 화면을 불러오지 못하게 될 수 있습니다.

## 바꾸기 이후

완료라고 하기 전에 이 목록을 차례로 확인하세요.

1. **캐시를 비웁니다.** **빠른 작업** 섹션에서 **캐시 비우기**를 실행합니다. 사이트가 전체 페이지 캐시를 사용한다면 **WordPress**, 그다음 **캐싱**에서 비웁니다.
2. **재작성 규칙을 비웁니다.** 같은 섹션에서 **재작성 규칙 비우기**를 실행하거나, wp-admin에서 **설정**, 그다음 **고유주소**를 열고 아무것도 바꾸지 않은 채 **변경 사항 저장**을 클릭합니다.
3. 사이트가 CDN을 사용 중이라면 **성능**, 그다음 **Kapsule CDN**에서 **CDN 캐시를 제거합니다**. [Kapsule CDN 캐시 제거하기](https://support.kapsulehost.com/ko-kr/cdn-cache-purge)를 참고하세요.
4. 브라우저 캐시에 속지 않도록 **비공개 창에서 사이트를 불러옵니다**.
5. **자물쇠 표시를 확인합니다.** SSL 전환 후 자물쇠가 없거나 경고가 표시된다면 URL이 남아 있다는 뜻입니다: [혼합 콘텐츠 경고 해결하기](https://support.kapsulehost.com/ko-kr/ssl-mixed-content).
6. **손이 많이 가는 페이지를 직접 클릭해 확인합니다.** 홈페이지 슬라이더, 헤더 로고, 페이지 빌더로 만든 모든 페이지, 그리고 스토어의 결제 페이지입니다. 이런 곳에 직렬화 옵션 안에 있는 URL이 들어 있습니다.
7. 캐싱 플러그인이 있다면 **해당 플러그인의 설정 화면에서 캐시를 지웁니다**.

## 문제 해결

**테스트 실행에서 바뀔 항목이 0건으로 보고됩니다.** 해당 문자열이 데이터베이스에 정확히 그 형태로 존재하지 않는 것입니다. 끝의 슬래시, `www.` 접두사, 또는 스킴을 확인하세요. 먼저 호스트 이름만 검색해서 데이터베이스에 존재하는지부터 확인해 보세요.

**도메인 변경 후 이미지가 깨집니다.** 미디어 URL은 `wp_posts`와 `wp_postmeta`에 있으며 `--all-tables`로 처리되지만, CDN이나 이미지 최적화 플러그인이 자체적으로 다시 쓴 사본을 캐시하고 있을 수 있습니다. CDN과 플러그인 캐시를 비운 다음 새로고침하세요.

**바꾸기 후 설정이 사라졌습니다.** 이것이 바로 직렬화 문제이며, 여기의 도구가 아니라 원시 SQL로 변경이 이루어졌다는 뜻입니다. 실행 전에 생성된 백업에서 복원하세요: [백업에서 복원하기](https://support.kapsulehost.com/ko-kr/restoring-from-backup).

**스테이징 URL이 계속 다시 나타납니다.** 무언가가 이를 다시 채우고 있으며, 대개 예약된 반영 작업이나 캐시된 옵션 때문입니다. [스테이징 사용하기: 반영 및 가져오기](https://support.kapsulehost.com/ko-kr/wordpress-staging-workflow)의 워크플로를 확인하고, 반영할 때 **URL 재작성**이 체크되어 있는지 확인하세요.