워드프레스 사이트 이전 시 한글 파일명 때문에 이미지가 깨지는 경우

최근 카페24의 10G 광아우토반 FullSSD+ 호스팅에서 매니지드 워드프레스 호스팅으로 변경하는 작업을 진행했습니다. 문제는 이미지 파일들에 한글이 포함되어 FTP를 통해 업로드할 경우 이미지 파일들의 이름이 깨져서 이미지가 제대로 표시되지 않는 문제가 나타났습니다. 사이트의 이미지들이 거의 다 깨져서 살펴보니 이미지 파일들의 자모가 분리되는 현상이 발생했습니다. 맥에서 파일 이름에 한글이 포함된 이미지를 업로드하면 FTP에 접속하여 살펴보면 이미지 파일이 이름에서 한글 자모가 분리는 문제가 발생할 수 있습니다.

이 문제를 해결하려면 카페24에서 제공하는 백업 압축 파일을 업로드하고, SSH에 접속하여 압축을 해제하면 파일 이름이 깨져 보여도 정상적으로 작동합니다.

복원 후 망보드 문제

복원한 후에 망보드 대시보드를 클릭하면 업데이트 팝업이 표시되어 업데이트를 실시하니 망보드 관련 DB와 망보드 이미지 업로드 폴더가 삭제되는 다소 당황스러운 상황이 발생했습니다.

이와 관련하여 조금 검색해보니 다음과 같은 망보드 포럼 글이 있네요.

망보드 업데이트 이후 오류 발생

아마 망보드 비즈니스 등 종류가 다른 경우에 이런 현상이 발생하는 것 같습니다.

망보드 플러그인을 비활성화했다가 다시 활성화하면 치명적인 오류가 격발하면서 플러그인이 활성화되지 않는 현상도 발생했습니다.

아래와 같은 에러 코드인데요.

Fatal error: Uncaught Error: Call to a member function get_option() on null in /www/wp-content/plugins/mangboard/includes/functions/func.store.php:260 Stack trace: #0 /www/wp-content/plugins/mangboard/includes/functions/func.util.php(343): mbw_get_option('encoding') #1 /www/wp-content/plugins/mangboard/includes/install/plugins/business-install.php(128): mbw_htmlspecialchars2('\xEC\x9D\xB4\xEC\x9A\xA9\xEC\x95\xBD\xEA\xB4\x80...') #2 /www/wp-includes/class-wp-hook.php(324): mbw_business_install('') #3 /www/wp-includes/class-wp-hook.php(348): WP_Hook->apply_filters(NULL, Array) #4 /www/wp-includes/plugin.php(517): WP_Hook->do_action(Array) #5 /www/wp-admin/plugins.php(196): do_action('activate_mangbo...') #6 {main} thrown in /www/wp-content/plugins/mangboard/includes/functions/func.store.php on line 260

/wp-content/plugins/mangboard/includes/functions/func.store.php 파일에서

if(!function_exists('mbw_get_option')){ function mbw_get_option($key,$filter=true){ global $mstore; return $mstore->get_option($key,$filter); } }

위의 코드를 아래와 같이 변경해보았습니다.

if (!function_exists('mbw_get_option')) {
	function mbw_get_option($key, $filter = true) {
		// 전역 스토어 객체
		global $mstore;

		// 1) 스토어 객체가 준비되어 있으면 그대로 사용
		if (isset($mstore) && is_object($mstore) && method_exists($mstore, 'get_option')) {
			return $mstore->get_option($key, $filter);
		}

		// 2) 초기화 이전 상황(설치/활성화 훅 등)에서는 WP 옵션으로 폴백
		//	플러그인에서 실제 사용하는 옵션 키 이름에 맞춰주세요.
		//	아래 둘 중 하나일 가능성이 큼: 'mangboard_options' 또는 'mbw_options'
		$opts = get_option('mangboard_options');
		if (!is_array($opts) || empty($opts)) {
			$opts = get_option('mbw_options');
			if (!is_array($opts)) $opts = array();
		}

		// 키가 없으면 null 반환(필요하면 기본값을 지정해도 됨)
		if (!array_key_exists($key, $opts)) return null;

		// 필터가 필요한 경우에만 최소한의 이스케이프(필요 시 제거 가능)
		$value = $opts[$key];
		if ($filter && is_string($value)) {
			// 복잡한 mbw_htmlspecialchars2 호출은 초기화 문제를 유발할 수 있어 피함
			return htmlspecialchars($value, ENT_QUOTES, 'UTF-8');
		}
		return $value;
	}
}

이제는 활성화는 되었지만 곧바로 치명적인 오류가 발생했습니다. 앞서 변경한 코드를 다시 이전 상태로 되돌리니 에러 없이 플러그인이 활성화되었습니다.

이외에 게시판 글들에 접근이 가능하지만 망보드 대시보드에는 게시글이 하나도 없는 것으로 표시되는 현상도 발생했습니다.

한글 이름 때문에 이미지가 깨지는 경우

한글 이름 때문에 이미지가 깨지는 이유는 FTP를 통해 윈도우에서 서버로 파일들을 업로드하면서 파일 이름이 깨지면서 발생하는 것 같습니다.

이 경우 백업을 받은 데이터 파일(압축 파일)을 서버로 업로드하여 SSH에서 압축을 해제하면 이미지 파일 이름 내의 한글이 깨지지 않아서 문제가 발생하지 않을 것입니다.

이를 위해서는 웹 서버에 충분한 공간이 있어야 합니다. 카페24에서 약간의 공간이 부족하여 문제가 압축을 해제할 수 없어 문의해보니 용량을 추가할 것을 안내해 주었습니다.

SSH에서 tar.gz 파일의 압축을 해제하려면 다음과 같은 명령을 사용할 수 있습니다.

tar -xzvf 파일명.tar.gz

tar 파일의 경우 다음과 같은 명령어로 압축 해제가 가능합니다.

tar -xvf 파일명.tar

웹서버 공간이 부족한 경우에는 이 방법을 이용할 수 없습니다. 클라우드웨이즈나 케미클라우드와 같은 해외 호스팅을 이용하면 웹 용량에 대한 압박으로부터 어느 정도 벗어날 수 있습니다.😄

카페24에서 PHP 버전을 변경한 후에 이미지 에러가 발생하는 경우

오래된 PHP 버전에서 최신 PHP 버전을 변경한 후에 이미지가 엑박이 되는 경우가 있습니다.

카페24에서 과거 example.cafe24.com이라는 임시 도메인이 연결되었지만, 현재는 example.mycafe24.com이 사용됩니다. 도메인 주소를 바꾸는 경우 임시 도메인으로 된 URL도 함께 바꾸어야 하지만, 간혹 임시 도메인으로 된 URL이 유지되는 경우가 있습니다. 이 상태에서 PHP 버전을 변경하여 임시 도메인 URL이 cafe24.com에서 mycafe24.com으로 바뀌게 되면 이미지가 엑박으로 표시됩니다.

참고

https://avada.tistory.com/3761

카페24 호스팅 상품 변경 및 워드프레스 테마 데모 설치 작업

https://avada.tistory.com/3046

해외웹호스팅: 클라우드웨이즈 vs. 블루호스트 vs. 카페24 비교 (Cloudways vs. Bluehost vs. Cafe24)