exemONE Docker 모드 패치 방법 및 절차
지원 환경
| 순번 | 항목 | 내용 |
|---|---|---|
| 1 | 운영체제 | CentOS 7 이상 |
| 2 | CPU / Memory | 8 core / 16 GB 이상 (인스턴스 1대 기준) |
| 3 | 설치 유형 | 도커 패키지 설치 환경에 한함 |
| 4 | 인터넷 환경 | 인터넷 접속 불가능한 환경에서도 실행 가능 |
전제 조건: 하위 버전 → 504 업데이트 시 PostgreSQL 17 업그레이드 진행이 필요합니다.
또한 패키지 업데이트의 경우 다운그레이드(예: 504버전 → 412버전)가 불가능하므로 작업 전 기존 데이터(ClickHouse, PostgreSQL)를 반드시 백업 후 진행하시기 바랍니다.
1. 모듈별 사용 포트 정보
| 순번 | Target | 출발지 | 도착지 | Type | Port | 포트 사용 내용 |
|---|---|---|---|---|---|---|
| 1 | exem-host-agent | Linux, Windows 장비 | exemONE 수집 서버 (Receiver) | gRPC | 9009 | 범용 gRPC 요청 및 응답 |
| 2 | exem-host-agent | Unix 장비 | exemONE 수집 서버 (Receiver) | TCP | 9010 | 범용 TCP 요청 및 응답 |
| 3 | exem-k8s-agent / exem-container-agent | 모니터링 대상 장비 | exemONE 수집 서버 (Receiver) | gRPC | 9009 | 범용 gRPC 요청 및 응답 |
| 4 | exem-db-agent / 개별 db agent | 모니터링 대상 장비 | exemONE 수집 서버 (Receiver) | gRPC | 9009 | 범용 gRPC 요청 및 응답 |
| 5 | exem-db-agent | exemONE 수집 서버 | 모니터링 대상 Target DB | TCP | DB Listener Port | DB 지표 수집 |
| 6 | exem-java-agent | 모니터링 대상 장비 | exemONE 수집 서버 (Receiver) | TCP | 9010 | 범용 TCP 요청 및 응답 |
| 7 | Cloud | - | exemONE 수집 서버 (Receiver) | TCP | 443 | - |
| 8 | 모니터링 사용자 PC | 사용자 PC | exemONE 수집 서버 (Gateway) | TCP(https) | 8443 | WEB UI 접속 포트 |
| 9 | 모니터링 사용자 PC | 사용자 PC | exemONE 수집 서버 (Gateway) | HTTP | 8080 | WEB UI 접속 포트 |
| 10 | exemONE repo (ClickHouse) | - | - | TCP | 8123 | 수집한 데이터 저장 |
| 11 | exemONE repo (PostgreSQL) | - | - | TCP | 5432 | meta 데이터 저장 |
2. 모듈별 설정 파일 경로 (Docker 모드)
Docker 모드는 $EXEMONE_HOME/containers/{모듈명}/configs/ 경로에 설정 파일이 위치합니다.
| 순번 | 모듈명 | 설정 파일 경로 |
|---|---|---|
| 1 | exemone-api | $EXEMONE_HOME/containers/exemone-api/configs/application.yaml |
| 2 | exemone-receiver | $EXEMONE_HOME/containers/exemone-receiver/configs/receiver.yaml |
| 3 | exemone-db-agent | $EXEMONE_HOME/containers/exemone-db-agent/configs/agent.yml |
| 4 | exemone-cloud-agent | $EXEMONE_HOME/containers/exemone-cloud-agent/configs/agent.yml |
| 5 | exemone-postgresql | $EXEMONE_HOME/containers/exemone-postgresql/data/postgresql.conf |
| 6 | docker-compose | $EXEMONE_HOME/installer/exemone/docker-compose.yml |
| 7 | .env (버전 관리) | $EXEMONE_HOME/installer/exemone/.env |
참고: Docker 모드에서 포트 변경 시
docker-compose.yml에서 정의된 외부 포트를 변경 후 서비스를 재구동합니다. 각 모듈에 정의된 내부 통신 포트는 변경하지 않아도 됩니다.
3. 패치 전 진행 사항 확인
| 순번 | 구분 | 내용 |
|---|---|---|
| 1 | 단일 모듈 패치 | "단일 모듈 업데이트" 절차 진행 |
| 2 | 패키지 업데이트 (모듈 버전 변경) | "전체 모듈 업데이트" 절차 진행 |
| 3 | 하위 버전 → 504 업데이트 | PostgreSQL 13 → 17.2 업그레이드 별도 진행 필요 |
| 4 | 다운그레이드 | 불가 (작업 전 ClickHouse, PostgreSQL 데이터 백업 필수) |
4. 단일 모듈 업데이트
특정 모듈만 패치할 경우 아래 절차를 따릅니다.
4-1. 사전 설정 - 이미지 저장 폴더 생성 (둘 중 하나 선택)
| 순번 | 경로 | 명령어 |
|---|---|---|
| 1 | home/exemone/exemone/image | mkdir patch |
| 2 | home/exemone/exemone/installer/exemone/ | mkdir image |
4-2. 패치 이미지 업로드
| 순번 | 단계 | 내용 |
|---|---|---|
| 1 | 패치할 모듈 이미지를 위에서 생성한 폴더에 업로드합니다. | - |
4-3. Image Load
경로: 이미지를 저장했던 폴더
ls *.tar.gz | xargs -L 1 docker load -i
4-4. .env 파일 버전 변경
경로: home/exemone/exemone/installer/exemone
vi .env
변경 예시 (exemone-front-v3.0.504.15.16.tar → exemone-front-v3.0.504.15.17.tar):
// 변경 전
FRONT_IMAGE=maxgauge/exemone-front
FRONT_VERSION=v3.0.504.15.16
// 변경 후
FRONT_IMAGE=maxgauge/exemone-front
FRONT_VERSION=v3.0.504.15.17
4-5. 이미지 재실행
경로: home/exemone/exemone/installer/exemone/scripts
./restart.sh {패치할 이미지}
예시:
./restart.sh front
4-6. 재기동 컨테이너 확인
docker ps
5. 전체 모듈 업데이트
전체 패키지 버전 업데이트 시 아래 절차를 따릅니다.
5-1. 전체 모듈 종료
경로: home/exemone/exemone/installer/exemone/scripts
./shutdown.sh
5-2. Image Load
경로: 이미지를 저장했던 폴더
ls *.tar.gz | xargs -L 1 docker load -i
5-3. .env 파일 버전 변경
경로: home/exemone/exemone/installer/exemone
vi .env
변경 예시:
// 변경 전
FRONT_IMAGE=maxgauge/exemone-front
FRONT_VERSION=v3.0.504.15.16
// 변경 후
FRONT_IMAGE=maxgauge/exemone-front
FRONT_VERSION=v3.0.504.15.17
5-4. 네트워크, 환경설정, 컨테이너 빌드 및 실행
경로: home/exemone/exemone/installer/exemone
./restart.sh
5-5. 재기동 컨테이너 확인
docker ps
6. 대용량 패키지 업데이트 (데이터 백업 후 패키지 패치)
PostgreSQL 및 ClickHouse 데이터를 백업한 후 패키지를 패치하는 방법입니다.
6-1. PostgreSQL 백업
api 중지 (api 미중지 시 마이그레이션이 중복 발생할 수 있습니다)
./scripts/shutdown.sh api
postgresql 컨테이너 접속 및 데이터 백업
cd %exemone_home%/installer/exemone
docker exec -it exemone-postgresql bash
cd /var/lib/postgresql
pg_dumpall -U postgres > 250212.sql
exit
docker cp exemone-postgresql:/var/lib/postgresql/250212.sql .
postgresql 종료 및 볼륨 백업
./scripts/shutdown.sh postgresql
mv containers/exemone-postgresql/data containers/exemone-postgresql/data_bak
mkdir containers/exemone-postgresql/data
6-2. 전체 컨테이너 종료
경로: {$EXEMONE_HOME}/scripts
./shutdown.sh
이전 폴더는 폴더 자체를 백업 후 작업합니다.
6-3. 새 패키지 압축 해제
tar -xvzf exemone-pkg.gz
cd /home/exemone/exemone/installer
tar -xvf exemone.tar.gz
6-4. ClickHouse 백업 파일 복사
신규 설치한 exemone 폴더로 이동 후 기존 ClickHouse 데이터를 복사합니다.
cp -r {기존 EXEMONE_HOME}/containers/exemone-clickhouse/ {신규 EXEMONE_HOME}/containers/exemone-clickhouse/
6-5. 새로운 패키징 이미지 로드
경로: {$EXEMONE_HOME}/../../image
ls *.tar.gz | xargs -L 1 docker load -i
6-6. exemONE 설치
경로: {$EXEMONE_HOME}/scripts
./install.sh
6-7. PostgreSQL 재시작 및 데이터 복원
./scripts/startup.sh postgresql
docker cp 250212.sql exemone-postgresql:/var/lib/postgresql/
docker exec -it exemone-postgresql bash
cd /var/lib/postgresql
psql -d postgres -U postgres < 250212.sql
6-8. api 재구동
경로: {$EXEMONE_HOME}/scripts
./restart.sh api
7. 주의사항 및 참고
| 순번 | 항목 | 내용 |
|---|---|---|
| 1 | 지원 OS | CentOS 7 이상만 지원 |
| 2 | 다운그레이드 불가 | 패키지 업데이트 후 이전 버전으로 다운그레이드 불가. 작업 전 ClickHouse, PostgreSQL 데이터 반드시 백업 |
| 3 | PG 업그레이드 | 하위 버전 → 504 업데이트 시 PostgreSQL 13 → 17.2 업그레이드 별도 진행 필요 |
| 4 | api 중지 순서 | PostgreSQL 백업 작업 시 api를 먼저 중지해야 마이그레이션 중복 발생을 방지할 수 있음 |
| 5 | restart.sh 누락 라인 | 2024년 5월 29일 이전 패키지의 경우 restart.sh에 아래 라인이 없으면 추가 필요: run_docker_compose build --no-cache ${SERVICE} |
| 6 | 포트 변경 | Docker 모드에서 포트 변경 시 docker-compose.yml의 외부 포트만 변경 후 서비스 재구동 |
| 7 | DuplicationAgentError 발생 시 | PostgreSQL 컨테이너에서 SELECT access_token FROM xm_agent WHERE agent_id = 'default'; 쿼리로 access_token 확인 후 agent.yml에 설정 |