Binary 모드 패치

변경 사항

이번 패치의 주요 변경 사항을 요약하면 다음과 같습니다.

순번	항목	내용	비고
1	Kafka 메시지 크기 변경, Kafka 설정	메시지 최대 2GB로 상향합니다.	기존 방식과 동일 (config 교체)
2	HTTPS(Nginx) gzip 압축	응답 데이터를 gzip 압축합니다.	기존 방식과 동일 (http.conf 교체)
3	onectl 관련 작업	쉘 스크립트 → 바이너리로 교체하고, 도커 모드에도 신규 도입합니다. `web/backend/data/history.db` 신규 파일이 추가됩니다.	이번 버전 고유 작업
4	Kafka 메모리 증가, Kafka 환경 변수	`.env` 의 `KAFKA_OPTS` 내 `MaxDirectMemorySize` 가 3G → 6G로 변경됩니다.	이번 버전 고유 작업

공통 사전 준비

이후 모든 명령은 아래 한 줄부터 시작합니다. INSTALL_DIR 은 현재 설치된 exemONE 설치 폴더 경로입니다. (기존 EXEMONE_HOME 과 혼동을 피하기 위해 패치 작업 전용 변수로 분리합니다.)

# 실제 설치 경로로 수정해주세요.
export INSTALL_DIR=/home/exemone/exemone
cd $INSTALL_DIR

신규 패키지 파일 배치

담당자에게 받은 신규 패키지 tar 파일을 /tmp 에 올려두세요.

ls -lh /tmp/exemone-pkg-*.tar.gz

신규 패키지 풀기 (바이너리 모드)

바이너리 패키지는 단일 폴더 구조로, exemone/ 아래에 bins, services, scripts, onectl 등이 바로 보입니다.

mkdir -p /tmp/patch
tar -zxf /tmp/exemone-pkg-*.tar.gz -C /tmp/patch

# 구조 확인 (bins, services, scripts, onectl 등이 보여야 합니다.)
ls /tmp/patch/exemone

export NEW_PKG=/tmp/patch/exemone

env 파일 교체 시 공통 원칙

이번 버전에서 교체가 필요한 env 계열 파일(.env, kafka.env 등)은 고객사마다 커스텀 값이 들어가 있을 수 있습니다. 교체 전에 반드시 diff 로 차이를 확인하시고, 고객사 커스텀이 있으면 수동으로 병합하세요.

# 예시
diff $INSTALL_DIR/kafka.env $NEW_PKG/kafka.env

1. 바이너리(Binary) 모드

1-1. 서비스 중지

서비스를 모두 중지하고 상태를 확인합니다.

cd $INSTALL_DIR
./onectl stop all
./onectl stat

모두 STOPPED 상태인지 확인해주세요.

1-2. ⭐ 이번 버전 고유 작업 (바이너리)

⚠️ 주의: 본 단계를 진행하기 전에 $INSTALL_DIR, $NEW_PKG 환경변수가 반드시 지정되어 있어야 합니다.

(1) onectl 관련 작업

기존 onectl 은 쉘 스크립트였지만, 이번 버전부터 실행파일(바이너리)로 교체됩니다.

# 기존 onectl 백업 후 신규 교체
mv $INSTALL_DIR/onectl $INSTALL_DIR/onectl.old
cp $NEW_PKG/onectl $INSTALL_DIR/onectl
chmod 755 $INSTALL_DIR/onectl

(2) scripts/ 폴더 교체

아주 오래된 설치 환경에서는 현재 스크립트 일부가 누락되어 있을 수 있으므로, 기존 폴더를 백업하고 신규 폴더로 교체합니다.

# 기존 scripts 백업
mv $INSTALL_DIR/scripts $INSTALL_DIR/scripts.old

# 새 scripts 복사
cp -a $NEW_PKG/scripts $INSTALL_DIR/scripts
chmod -R 755 $INSTALL_DIR/scripts

(3) Kafka server.properties 업데이트 (고객사 커스텀 확인 후 교체)

server.properties 에 Kafka 메시지 크기(2GB), socket buffer 등이 반영되며, 고객사마다 별도 튜닝 값이 들어 있을 수 있으므로 diff 로 반드시 확인 후 교체합니다.

# 차이 확인
diff $INSTALL_DIR/services/exemone-kafka/config/kraft/server.properties \
     $NEW_PKG/services/exemone-kafka/config/kraft/server.properties

# 기존 파일 백업
cp $INSTALL_DIR/services/exemone-kafka/config/kraft/server.properties \
   $INSTALL_DIR/services/exemone-kafka/config/kraft/server.properties.old

# 커스텀이 없으면 바로 교체
cp $NEW_PKG/services/exemone-kafka/config/kraft/server.properties \
   $INSTALL_DIR/services/exemone-kafka/config/kraft/server.properties

# 커스텀이 있으면: 위 cp 대신 vi 로 양쪽 값 병합 후 저장

(4) Nginx http.conf 업데이트 (고객사 커스텀 확인 후 교체)

이번 버전에서 http.conf 에 gzip 압축 블록이 추가됐습니다. 다만, TLS 인증서 경로, proxy 헤더, 커스텀 location 블록 등 고객사마다 수정된 내용이 있을 수 있으므로 diff 로 반드시 확인 후 교체합니다.

# 차이 확인
diff $INSTALL_DIR/services/exemone-https/conf.d/http.conf \
     $NEW_PKG/services/exemone-https/conf.d/http.conf

# 기존 파일 백업
cp $INSTALL_DIR/services/exemone-https/conf.d/http.conf \
   $INSTALL_DIR/services/exemone-https/conf.d/http.conf.old

# 커스텀이 없으면 바로 교체
cp $NEW_PKG/services/exemone-https/conf.d/http.conf \
   $INSTALL_DIR/services/exemone-https/conf.d/http.conf

참고) http.conf 내 수동 병합 시 — gzip 블록 추가 위치와 내용

커스텀 내용이 있어서 직접 병합해야 한다면, 기존 파일의 server { ... } 블록 안에서 ssl_* 지시어 바로 아래, # proxy 주석 위에 아래 블록을 추가하시면 됩니다.

server {
    listen 8443 ssl;
    ...
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_prefer_server_ciphers on;

    # ↓↓↓ 여기에 gzip 블록 추가 ↓↓↓
    # gzip 압축
    gzip on;
    gzip_comp_level 5;
    gzip_min_length 1024;
    gzip_vary on;
    gzip_proxied any;
    gzip_http_version 1.1;

    gzip_types
        text/plain
        text/css
        application/javascript
        application/json
        application/xml
        image/svg+xml;
    # ↑↑↑ 여기까지 ↑↑↑

    # proxy
    proxy_buffer_size 8k;
    proxy_buffers 16 8k;
    ...
}

(5) Kafka 설정 확인 스크립트 배치 (보조 도구)

신규 확인 도구 check-config.sh 가 추가됩니다. 기동 후 설정값 검증에 사용합니다.

cp $NEW_PKG/services/exemone-kafka/check-config.sh \
   $INSTALL_DIR/services/exemone-kafka/check-config.sh
chmod 755 $INSTALL_DIR/services/exemone-kafka/check-config.sh

(6) .env 업데이트 (수동 병합)

.env 에는 초기 설치 시 채워진 사이트별 값이 들어 있어, 신규 파일로 통째로 덮어쓰면 안 됩니다. diff 로 차이를 확인한 뒤 vi 로 직접 편집해주세요.

보존해야 하는 키 (덮어쓰지 말 것):

키	예시
`OS`	`OS=rocky8`
`MODE`	`MODE=exemone`

신규 값으로 갱신해야 하는 라인:

항목	설명
*`EXEMONE_` 서비스 버전 라인**	예: `EXEMONE_API=exemone-api-v3.0.604.5-snapshot`
`KAFKA_OPTS`	`MaxDirectMemorySize=3G` → `6G`
기타 신규 추가 라인	신규 파일에 새로 추가된 라인을 모두 반영합니다.

# 차이 확인
diff $INSTALL_DIR/.env $NEW_PKG/.env

# 백업
cp $INSTALL_DIR/.env $INSTALL_DIR/.env.old

# 위 diff 결과를 보고 vi 로 수동 병합해주세요.
vi $INSTALL_DIR/.env

(7) 서비스 바이너리 교체

각 서비스의 실행 파일은 bins/<서비스명>/ 아래에 버전이 포함된 파일명(예: exemone-api-v3.0.508.204) 형태로 존재합니다. 신규 패키지의 bins/ 전체를 기존 bins/ 로 복사하되, -n 옵션으로 기존 파일은 덮어쓰지 않도록 합니다. 이렇게 하면 신규 버전 파일만 추가되고, 인프라 바이너리(kafka/postgresql/redis 등)나 구버전 파일은 그대로 유지됩니다.

# exemone-front의 dist를 백업해둡니다.
export VERSION=$(cat $INSTALL_DIR/services/exemone-front/version.txt | cut -d'=' -f2 | cut -d',' -f1)

# 버전 확인
echo $VERSION

mv $INSTALL_DIR/bins/exemone-front/dist "$INSTALL_DIR/bins/exemone-front/dist_$VERSION"

# 덮어쓰지 않고 복사 (신규 파일만 추가됩니다.)
cp -arn $NEW_PKG/bins/. $INSTALL_DIR/bins/

# front version txt 수정
mv $INSTALL_DIR/services/exemone-front/version.txt "$INSTALL_DIR/services/exemone-front/version_$VERSION.txt"

mv $NEW_PKG/services/exemone-front/version.txt $INSTALL_DIR/services/exemone-front

# 결과 확인 (신규 버전 파일이 보여야 합니다.)
ls $INSTALL_DIR/bins/exemone-api
ls $INSTALL_DIR/bins/exemone-core

(7.1) core 서비스 db 경로 복사 (core 전용 특이사항)

다른 서비스와 달리 exemone-core 는 services/exemone-core/db 경로를 신규 패키지에서 기존 설치로 그대로 가져와야 합니다. (스키마/초기 데이터 등)

# 마이그레이션 db 디렉터리 백업
mv $INSTALL_DIR/services/exemone-core/db $INSTALL_DIR/services/exemone-core/db_$(date +%Y%m%d)

# 신규 db 경로 복사
cp -a $NEW_PKG/services/exemone-core/db $INSTALL_DIR/services/exemone-core/

# 확인
ls $INSTALL_DIR/services/exemone-core/db

(8) 로그 로테이션 설정

postgresql, redis, cache, front, https 의 로그 로테이션/리텐션은 호스트의 logrotation 툴을 통해 관리하므로 초기 설정을 진행합니다.

# log관리 프로세스 실행
$INSTALL_DIR/scripts/setup-logrotate.sh

(9) postgresql max_connections 설정

postgresql 시작 시 max_connections=1000 으로 실행하도록 스크립트를 변경합니다.

$INSTALL_DIR/services/exemone-postgresql/start.sh

다른 방법으로는 postgresql 의 설정을 수동으로 변경할 수도 있습니다.

# max_connections 변경
$INSTALL_DIR/services/exemone-postgresql/data/postgresql.conf

max_connections = 1000 # 설정 변경

설정 변경 후에는 postgresql 을 재기동합니다.

(10) postgresql dump 스크립트 교체

postgresql dump 스크립트를 신규 버전으로 교체합니다.

rm $INSTALL_DIR/services/exemone-postgresql/dump_export.sh
rm $INSTALL_DIR/services/exemone-postgresql/dump_import.sh

mv $NEW_PKG/services/exemone-postgresql/dump_export.sh $INSTALL_DIR/services/exemone-postgresql/
mv $NEW_PKG/services/exemone-postgresql/dump_import.sh $INSTALL_DIR/services/exemone-postgresql/

1-3. 서비스 기동

chown -R exemone:exemone $INSTALL_DIR

cd $INSTALL_DIR
./onectl restart all

# 검증
./onectl stat

주의사항 및 참고

.env, kafka.env, server.properties, http.conf 등은 고객사 커스텀 값이 포함될 수 있으므로 반드시 diff 로 차이를 확인한 후 교체하거나 수동 병합하세요.
본 패치를 진행하기 전에 $INSTALL_DIR, $NEW_PKG 환경변수가 정확히 지정되어 있는지 확인해주세요.
이번 버전부터 onectl 이 쉘 스크립트에서 바이너리 실행 파일로 변경되므로, 기존 스크립트 호출 방식과 차이가 없는지 확인해주세요.
서비스 바이너리 교체 시 cp -arn 옵션(-n = 기존 파일 보존)을 반드시 사용해야 인프라 바이너리(kafka/postgresql/redis 등)와 구버전 파일이 보존됩니다.
exemone-core 의 db 디렉터리는 다른 서비스와 달리 신규 패키지의 파일을 반드시 복사해야 스키마/초기 데이터가 정상 반영됩니다.
KAFKA_OPTS 의 MaxDirectMemorySize 가 3G → 6G로 상향됩니다. 호스트 메모리 자원이 충분한지 점검해주세요.
check-config.sh 는 기동 후 Kafka 설정값을 검증하는 보조 도구이므로, 기동 직후 검증 용도로 활용하실 수 있습니다.
exemone-front/dist 와 version.txt 는 백업 파일명에 기존 버전을 포함시켜(dist_$VERSION, version_$VERSION.txt) 추후 롤백이 용이하도록 합니다.

※ Repository 내 테이블 변경사항 업데이트가 필요합니다.

Binary 모드 패치

변경 사항​

공통 사전 준비​

신규 패키지 파일 배치​

신규 패키지 풀기 (바이너리 모드)​

env 파일 교체 시 공통 원칙​

1. 바이너리(Binary) 모드​

1-1. 서비스 중지​

1-2. ⭐ 이번 버전 고유 작업 (바이너리)​

(1) onectl 관련 작업​

(2) scripts/ 폴더 교체​

(3) Kafka server.properties 업데이트 (고객사 커스텀 확인 후 교체)​

(4) Nginx http.conf 업데이트 (고객사 커스텀 확인 후 교체)​

참고) http.conf 내 수동 병합 시 — gzip 블록 추가 위치와 내용​

(5) Kafka 설정 확인 스크립트 배치 (보조 도구)​

(6) .env 업데이트 (수동 병합)​

(7) 서비스 바이너리 교체​

(7.1) core 서비스 db 경로 복사 (core 전용 특이사항)​

(8) 로그 로테이션 설정​

(9) postgresql max_connections 설정​

(10) postgresql dump 스크립트 교체​

1-3. 서비스 기동​

주의사항 및 참고​