arko_renual/deploy/wise

csv.wise.ai.kr 배포 구성

전체 구조

   [개발 PC]
      │ git push
      ▼
┌─────────────────────────────────────────────────────────────────────┐
│ 웹서버 175.118.124.176  (utimsurpai.cafe24.com, Rocky 8, SSH :9271) │
│   Gitea  git.wise.ai.kr (127.0.0.1:9003)                            │
│   act_runner  `arko-web:host`  → JDK8+Maven 3.6.3 으로 WAR 빌드      │
│   Apache httpd → https://csv.wise.ai.kr                             │
└───────────┬──────────────────────────────────┬──────────────────────┘
            │ ① scp WAR + 배포 스크립트 (SSH)   │ ② SSH 터널 :11060
            ▼                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│ WAS 27.255.76.2 (Ubuntu 22.04, 64코어)                              │
│   arko-tomcat   컨테이너  127.0.0.1:11060  ← ROOT 전개               │
│   arko-mariadb  컨테이너  127.0.0.1:11061  DB `csv`                  │
│   /opt/arko-app  (webapps · config · upload · backup · logs)        │
└─────────────────────────────────────────────────────────────────────┘

WAS 는 27 → 인터넷 방향으로만 열려 있고, 웹서버를 거쳐야 닿는다. Tomcat 은 127.0.0.1 에만 바인딩되며 인터넷에 직접 노출되지 않는다 — 웹서버가 아웃바운드 SSH 터널로 자기 쪽 11060 을 WAS 의 Tomcat 에 잇는다.

배포 흐름

git push          # 이하 전부 자동

push → 웹서버에서 빌드(JDK8) → 바이트코드 major=51 검증 → WAR md5 대조 전송
     → WAS 에서 ROOT 재전개 + 환경설정 주입 + Tomcat 재기동 + 헬스체크
     → 실패 시 직전 백업으로 자동 롤백
     → https://csv.wise.ai.kr 공개 확인

왜 이런 구조인가

빌드를 WAS 에서 하지 않는 이유 — WAS 는 64코어지만 llama-server 가 200G+ 를 점유해 가용 메모리가 3G 안팎이다. 여기서 Maven(힙 1G)을 돌리면 LLM 서비스가 OOM 될 수 있다. 웹서버(4코어 / 여유 4G)는 빌드 외 부하가 없다.

컨테이너로 설치한 이유 — WAS 의 claudeops 계정은 sudo 를 쓸 수 없고 docker 그룹에만 속한다. 패키지 설치가 불가능해 Tomcat·MariaDB 를 컨테이너로 올렸다. 같은 서버의 다른 서비스(urpai 등)와 같은 관행이다.

배포 스크립트를 매번 덮어쓰는 이유 — 이전 파이프라인에서 서버 사본과 저장소본이 갈라져, 저장소에서 고친 내용이 배포에 반영되지 않는 사고가 있었다. 워크플로가 매 실행마다 deploy/wise/arko-deploy.sh 를 WAS 로 복사하므로 저장소가 유일한 원본이다.

포트

포트	위치	용도
9271	웹서버	SSH
9003	웹서버 127.0.0.1	Gitea
11060	WAS 127.0.0.1	Tomcat (웹서버는 터널로 접근)
11061	WAS 127.0.0.1	MariaDB

11000~11050 은 같은 서버의 다른 서비스가 쓰고 있다. 포트를 새로 잡을 때 겹치지 않게 할 것.

파일

파일	설치 위치	역할
01-was-setup.sh	WAS	컨테이너 2기 최초 생성 (재실행 안전)
arko-deploy.sh	WAS /opt/arko-app/deploy/	재전개·설정주입·기동·헬스체크·롤백
mariadb.cnf	WAS /opt/arko-app/conf/	MariaDB 설정 (lower_case_table_names=1 주의)
csv.wise.ai.kr.conf	웹 /etc/httpd/conf.d/	Apache vhost (80→443, 터널로 프록시)
arko-was-tunnel.service	웹 /etc/systemd/system/	SSH 터널 (자동 재연결)
arko-runner.service	웹 /etc/systemd/system/	arko 전용 act_runner
arko-runner-config.yaml	웹 /opt/arko-runner/config.yaml	러너 설정

환경설정 (저장소에 없음)

globals-dev.properties / globals-live.properties 는 .gitignore 대상이라 저장소에도 WAR 에도 들어가지 않는다. WAS 의 /opt/arko-app/config/ 에만 두고 배포 때 WEB-INF/classes/egovframework/egovProps/ 로 주입한다. context-datasource.xml 이 globals-dev.properties 를 읽으므로 이 주입이 없으면 기동 실패한다.

WAS 값에서 로컬과 다른 부분:

Globals.OsType             =UNIX
Globals.DriverClassName    =org.mariadb.jdbc.Driver
Globals.Url                =jdbc:mariadb://arko-mariadb:3306/csv?useUnicode=true&characterEncoding=UTF-8&useSSL=false
Globals.fileStorePath      =/app/upload/
Globals.home.url           =https://csv.wise.ai.kr
Globals.home.base          =/usr/local/tomcat/webapps/ROOT
Globals.privacyDownloadPath=/app/privacy-download/

운영 명령

# 웹서버 (ssh -p 9271 root@175.118.124.176)
systemctl status arko-runner arko-was-tunnel   # 502 가 나면 터널부터 확인
tail -f /var/log/httpd/csv_error.log

# WAS (ssh 는 웹서버를 경유한다)
docker ps --filter name=arko-
docker logs -f --tail 100 arko-tomcat
tail -f /opt/arko-app/logs/deploy.log
docker exec -it arko-mariadb mariadb -ucsv -pcsv csv

# 수동 재배포 (Gitea 1.22 는 수동 실행 버튼이 없다)
bash /opt/arko-app/deploy/arko-deploy.sh /opt/arko-app/incoming/arko.war

알려진 제약

• Gitea 1.22.3 은 workflow_dispatch 를 지원하지 않는다. 넣으면 워크플로가 Actions 목록에 아예 뜨지 않는다. 재배포는 실제 파일을 바꿔 push 하거나 WAS 에서 직접 실행한다.
• Maven 은 3.6.3 을 쓴다. 3.8+ 는 HTTP 저장소를 차단하는데 eGov 2.7 은 HTTP 저장소 (terracotta 등)에 의존해 의존성 해석부터 실패한다.
• 메모리가 빠듯하다. 두 컨테이너 합쳐 1.75G 상한이다. 올리기 전 free -g 로 확인할 것.
• DB 는 MariaDB 다. 원본(MySQL 8)의 utf8mb4_0900_ai_ci 는 MariaDB 에 없어 utf8mb4_general_ci 로 변환해 이관했다. 한글 정렬 결과는 같다(코드포인트 순).