# 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. 헬스체크 (가장 먼저)

**자동(권장)** — 스모크 러너로 배포·라우터 상태를 한 번에:
```bash
# 로컬 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`.

**수동** — 서버에서:
```bash
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. 로그 확인

```bash
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. 재기동

```bash
# 백엔드만
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. 수동 롤백 (자동 실패 시)
```bash
# 백엔드 이전 버전으로 (배포 스크립트가 백업본을 남기는 위치 확인)
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`](BUILD_DEPLOY.md) · 환경: [`ENV_SETUP.md`](ENV_SETUP.md)
- 정합·스키마 갭: [`GUARDIA_ALIGNMENT.md`](GUARDIA_ALIGNMENT.md) · 보안: [`SECURITY.md`](SECURITY.md)
- 배포 블록(정본 사본): `deploy/deploy_server_kintex_block.py` · 배포 스크립트: `deploy/deploy_kintex.sh`
- 스모크 러너: `tools/test/kintex_smoke_test.py` · 경량 push: `scripts/push_kintex.py`
