kintex/docs/OPS_RUNBOOK.md

KINTEX 운영 런북 — 헬스체크 · 재기동 · 롤백

킨텍스 개발/운영 서비스의 상태 점검·재기동·배포 검증·롤백 절차. GUARDiA 운영 관행 준용. 대상: 개발 kintex.zioinfo.co.kr → 101.79.17.164, 백엔드 포트 8021. 운영 kintex.wise.ai.kr(후속). 보안: 서버 접속 자격증명은 사내 비밀관리에서 조달(이 문서·스크립트에 미기재). root SSH 는 GUARDiA 인프라 예외(소유자 승인).

---

0. 서비스 토폴로지

구성요소	실행 단위	포트/경로	헬스
백엔드 API	systemd kintex.service (/opt/kintex/app/app.jar)	8021	GET /health → data.status=UP
나노바나나 워커	systemd kintex-nanobanana.service (Python)	Redis 큐 소비	큐 소비 로그 / 프로세스 active
프론트(웹)	nginx 정적 (/var/www/kintex)	kintex.zioinfo.co.kr :80/443	페이지 200
nginx vhost	deploy/nginx/kintex.zioinfo.co.kr.conf	/=정적, /api/·/ws=8021	—
DB	PostgreSQL kintex_db (+PostGIS)	5432(내부)	SELECT 1
큐	Redis	6379(내부)	redis-cli ping→PONG
배포	deploy_server.py(webhook 수신)	9999	로그

의존: 백엔드 → PostgreSQL·Redis. 워커 → Redis·Gemini(G1). 프론트 → nginx → 백엔드.

---

1. 헬스체크 (가장 먼저)

자동(권장) — 스모크 러너로 배포·라우터 상태를 한 번에:

# 로컬 PC에서 SSH 경유 (env: KINTEX_SSH_HOST, KINTEX_SSH_PASSWORD)
python tools/test/kintex_smoke_test.py
# 서버(같은 호스트)에서
python tools/test/kintex_smoke_test.py --local
# 도메인 직접
KINTEX_BASE=https://kintex.zioinfo.co.kr python tools/test/kintex_smoke_test.py --http

종료코드 0=전체 통과. 결과 tools/test/_results/latest.json.

수동 — 서버에서:

curl -s http://127.0.0.1:8021/health          # {"success":true,"data":{"status":"UP","service":"kintex-backend",...}}
systemctl is-active kintex.service kintex-nanobanana.service
redis-cli ping                                 # PONG
sudo -u postgres psql -d kintex_db -c 'SELECT 1;'

정상 판정: /health 200 + status:UP + 두 서비스 active + Redis PONG + DB 응답.

---

2. 로그 확인

journalctl -u kintex.service -n 200 --no-pager           # 백엔드
journalctl -u kintex-nanobanana.service -n 100 --no-pager # 워커
tail -n 100 /tmp/kintex_gradle.log                        # 최근 빌드 로그
nginx -t && tail -n 50 /var/log/nginx/error.log           # nginx

로그에 자격증명·API키가 보이면 즉시 보안 이슈로 에스컬레이션(SECURITY §2).

---

3. 재기동

# 백엔드만
systemctl restart kintex.service && sleep 5 && curl -s http://127.0.0.1:8021/health

# 워커만 (이미지 생성 멈춤·큐 적체 시)
systemctl restart kintex-nanobanana.service

# 프론트/nginx (정적 서빙 이상)
nginx -t && systemctl reload nginx

# DB/Redis 이슈는 공유 인스턴스 — 재기동 전 타 솔루션 영향 확인 후 소유자 승인

부팅 자동기동: 두 유닛 모두 enable 상태여야 한다(systemctl is-enabled kintex.service).

---

4. 배포 (webhook 자동)

정상 경로는 자동이다:

scripts/push_kintex.py "메시지"  →  Gitea(zio/kintex) push  →  webhook(#47)  →  deploy_server
   →  git pull → npm build → gradlew bootJar → jar 검증 → deploy_kintex.sh(원자교체) → /health 게이트

• 배포 후 검증: python tools/test/kintex_smoke_test.py (health + 라우터 등록).
• 수동 Jenkins 트리거 추가 발사 금지 — 동일 repo 동시 빌드 시 target/*.jar 교체가 깨진다(GUARDiA 함정).
• deploy_kintex.sh 는 자기방어: 프론트/백엔드 빌드 → jar 검증(KintexApplication.class 존재) → 원자 교체 → 헬스체크 → 실패 시 이전 jar 롤백.

---

5. 롤백

5-1. 자동 롤백(기본)

deploy_kintex.sh 가 헬스체크 실패 시 이전 jar 를 유지/복원한다. 배포 후 /health 가 200이 아니면 스크립트가 롤백하고 실패로 종료 → deploy_server 가 ITSM 에 실패 알림.

5-2. 수동 롤백 (자동 실패 시)

# 백엔드 이전 버전으로 (배포 스크립트가 백업본을 남기는 위치 확인)
ls -lt /opt/kintex/app/*.jar* /opt/kintex/app/backup/ 2>/dev/null
cp /opt/kintex/app/app.jar.bak /opt/kintex/app/app.jar   # 백업 규약에 맞춰
systemctl restart kintex.service && sleep 5 && curl -s http://127.0.0.1:8021/health

# 소스 롤백(직전 커밋으로 재배포)
git -C /opt/kintex/src log --oneline -5
git -C /opt/kintex/src reset --hard <직전_정상_커밋>
bash /opt/kintex/src/deploy/deploy_kintex.sh /opt/kintex/src

5-3. 스키마 롤백 주의

Flyway 마이그레이션은 전진(forward)만 권장. 잘못된 마이그는 되돌리지 말고 보정 마이그레이션(다음 번호) 를 추가한다. baseline-on-migrate=true 이므로 운영 DB 임의 롤백 금지(GUARDIA_ALIGNMENT §4).

---

6. 자주 겪는 이슈 (GUARDiA 교훈 반영)

증상	원인 후보	조치
/health 200인데 특정 API 404	라우터 미배포(구 jar)	스모크 러너로 라우터 등록 확인 → 재배포
API 500 relation ... does not exist	마이그 미적용	Flyway 상태 flyway info, 보정 마이그 추가(§5-3)
이미지 생성 안 됨 / degraded	G1 미승인·GEMINI_API_KEY 미설정·워커 다운	워커 로그·env 확인, 워커 재기동. 키는 워커 env only
배포 로그 "완료"인데 반영 안 됨	deploy_server 블록 부재·1ms no-op	서버 /opt/zioinfo/deploy_server.py 에 kintex 블록 반영·zioinfo-deploy 재시작 확인
빌드 OOM	공유 8GB 동시 빌드	직렬 빌드 준수, 타 솔루션 빌드와 겹치지 않게
push 했는데 자동배포 안 돎	webhook 미설정/시크릿 불일치	Gitea webhook #47 활성·secret 일치·URL localhost 확인

---

7. 참조

• 배포 개요: BUILD_DEPLOY.md · 환경: ENV_SETUP.md
• 정합·스키마 갭: GUARDIA_ALIGNMENT.md · 보안: SECURITY.md
• 배포 블록(정본 사본): deploy/deploy_server_kintex_block.py · 배포 스크립트: deploy/deploy_kintex.sh
• 스모크 러너: tools/test/kintex_smoke_test.py · 경량 push: scripts/push_kintex.py