6caf43e1ed
- harness·zio-harness·proposal-builder·zioinfo → plugins/zioinfo (git mv 히스토리 보존) - 스킬 4·커맨드 3(/zioinfo:pmo·proposal·wiki)·에이전트 15·graphify 훅·knowledge 통합 - 신규: /zioinfo:wiki (graphify LLM wiki — graphify-out/wiki/ 커뮤니티별 아티클) - 신규: ZIO WISE 테마 (themes/zioinfo.json, experimental) - manifest 최신화: $schema·displayName(ZIO INFOTECH Suite)·experimental.themes - marketplace.json 단일 엔트리, 루트 plugin.json 제거 - CLAUDE.md·PROJECT_MAP·docs/plugins.md·README 3종·CHANGELOG·설치가이드 pptx 재구성 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
136 lines
6.4 KiB
Markdown
136 lines
6.4 KiB
Markdown
# 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`
|