오픈소스 미들웨어 환경에서 한글 깨짐 문제는 대부분 URL(GET), Body(POST), JSP 컴파일, JVM 파일 시스템 인코딩 설정의 불일치에서 발생합니다. 각 영역별 최적의 설정 방법을 정리합니다.
1. URL Encoding 설정 (GET 방식 한글 처리)
GET 호출 시 Query String의 인코딩 문제를 해결하기 위한 설정입니다. WildFly(Undertow)는 리스너별로 설정이 필요합니다.
CLI 명령어 (권장)
운영 중인 서버에 즉시 반영하거나 스크립트화하기 좋습니다.
Bash
# UTF-8 설정
/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=url-charset,value=UTF-8)
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=url-charset,value=UTF-8)
/subsystem=undertow/server=default-server/ajp-listener=ajp:write-attribute(name=url-charset,value=UTF-8)
# 특수 상황(ISO-8859-1) 설정 - 필요한 경우에만 사용
/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=url-charset,value=ISO-8859-1)
standalone.xml 직접 수정 시
url-charset="UTF-8"과 함께 decode-url="true" 옵션이 기본값이지만 명시적으로 확인하는 것이 좋습니다.
XML
<server name="default-server">
<http-listener name="default" socket-binding="http" url-charset="UTF-8" decode-url="true" redirect-socket="https" enable-http2="true"/>
<https-listener name="https" socket-binding="https" url-charset="UTF-8" decode-url="true" security-realm="ApplicationRealm" enable-http2="true"/>
<ajp-listener name="ajp" socket-binding="ajp" url-charset="UTF-8" decode-url="true"/>
</server>
2. 구버전 JBoss (EAP 6.4 이하) 설정
JBoss 6.x 버전은 Web Engine으로 JBoss Web(Apache Tomcat 기반)을 사용하므로 설정 방식이 다릅니다.
XML
<system-properties>
<!-- URI 자체를 UTF-8로 해석 -->
<property name="org.apache.catalina.connector.URI_ENCODING" value="UTF-8"/>
<!-- POST Body 인코딩 설정을 GET Query String에도 동일하게 적용 -->
<property name="org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING" value="true"/>
</system-properties>
3. JSP 및 Servlet Container 설정
JSP 파일 자체의 인코딩이나 Servlet의 기본 인코딩 환경을 설정합니다.
JSP 컴파일 인코딩 (java-encoding)
JSP 파일 내에 한글이 포함된 경우 컴파일 시 사용할 인코딩입니다.
XML
<servlet-container name="default">
<!-- 한국어 환경에서 MS949 혹은 UTF-8로 설정 -->
<jsp-config development="true" java-encoding="UTF-8"/>
<websockets/>
</servlet-container>
[추가 권장] Default Encoding 설정
Servlet 4.0 이상 환경에서 별도의 setCharacterEncoding 호출이 없을 때 사용할 기본 인코딩을 지정할 수 있습니다.
Bash
/subsystem=undertow/servlet-container=default:write-attribute(name=default-encoding, value=UTF-8)
4. JVM 파일 및 시스템 인코딩 (JAVA_OPTS)
로그 출력, 파일 읽기/쓰기 시 JVM 레벨에서 사용할 기본 인코딩입니다. 이 설정이 빠지면 OS 환경 변수에 따라 한글이 깨질 수 있습니다.
Bash
# 파일 저장 및 로그 생성 시 표준 UTF-8 사용
export JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF-8"
export JAVA_OPTS="$JAVA_OPTS -Dsun.jnu.encoding=UTF-8"
-Dfile.encoding: 자바 내부에서 파일을 읽고 쓸 때의 기본값.-Dsun.jnu.encoding: 파일 이름(파일명)의 인코딩을 처리할 때 사용.
5. [중요] 추가 체크리스트 (Post 인코딩)
Filter를 통한 인코딩 강제
GET은 url-charset으로 해결되지만, POST 데이터는 애플리케이션 프레임워크(Spring 등)의 CharacterEncodingFilter를 사용하는 것이 가장 확실합니다. 만약 소스 수정이 불가능하다면 Undertow의 default-encoding 설정을 확인하십시오.
클라이언트(Browser) 설정
서버 설정이 완벽해도 호출하는 HTML 페이지의 <meta charset="UTF-8"> 설정이 누락되면 브라우저가 다른 인코딩으로 데이터를 전송할 수 있습니다.
수정 제안 요약
- JSP 설정: 기존
MS949예시를 가급적UTF-8로 통일하는 추세를 반영하되, 레거시 대응 시MS949를 명시하는 설명을 추가했습니다. - CLI 가독성: UTF-8 설정과 ISO 설정을 분리하여 설명했습니다.
- JVM 옵션: 파일명 깨짐 방지를 위해
sun.jnu.encoding옵션을 추가 제안했습니다. - 설명 보완: 각 옵션이 왜 필요한지(예: URI_ENCODING vs USE_BODY_ENCODING) 의미를 명확히 했습니다.
이 내용을 워드프레스 기술 블로그에 그대로 활용하시면 실무자들에게 매우 유용한 가이드가 될 것입니다.