192 lines
6.3 KiB
Markdown
192 lines
6.3 KiB
Markdown
---
|
|
name: system-sync-orchestrator
|
|
description: >
|
|
GUARDiA 5개 시스템(guardia-itsm, zioinfo-web, guardia-manager, guardia-messenger, guardia-docs)
|
|
배포 상태를 검증하고 이슈를 자동 수정하는 오케스트레이터.
|
|
workspace ↔ repos ↔ Gitea ↔ 서버 4-way 동기화 불일치, /var/www 구버전,
|
|
서버 stash 잔존, app vs src 미동기화, uncommitted 변경을 탐지·수정한다.
|
|
다음 상황에서 반드시 사용:
|
|
(1) '5개 시스템 확인', '배포 상태 점검', '서버 최신 확인';
|
|
(2) '동기화', 'sync', '최신본 올려줘', '배포 맞춰줘';
|
|
(3) Manager/ITSM/홈페이지/Messenger/Docs 배포 이슈;
|
|
(4) 다시 실행, 업데이트, 수정, 보완.
|
|
---
|
|
|
|
# GUARDiA 5개 시스템 배포 동기화 오케스트레이터
|
|
|
|
**실행 모드:** 하이브리드
|
|
- Phase 1 (검증): 서브 에이전트 (deploy-verifier)
|
|
- Phase 2 (수정): 에이전트 팀 (deploy-verifier + deploy-fixer 협업)
|
|
- Phase 3 (재검증): 서브 에이전트
|
|
|
|
---
|
|
|
|
## Phase 0: 컨텍스트 확인
|
|
|
|
```
|
|
_workspace/ 존재 여부 확인:
|
|
- 없음 → 초기 실행 (Phase 1부터)
|
|
- 있음 + 사용자가 특정 시스템만 지정 → 부분 재실행 (해당 시스템만)
|
|
- 있음 + 전체 재검증 요청 → 전체 재실행
|
|
```
|
|
|
|
`_workspace/` 디렉토리:
|
|
```
|
|
C:/GUARDiA/.claude/agents/_workspace/
|
|
├── verify_report.json ← deploy-verifier 출력
|
|
└── fix_report.json ← deploy-fixer 출력
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 1: 전체 검증 (서브 에이전트)
|
|
|
|
**deploy-verifier** 서브 에이전트로 실행:
|
|
|
|
### 5개 시스템 검증 항목
|
|
|
|
| 시스템 | 서비스 | 경로 | 정적 경로 |
|
|
|--------|--------|------|-----------|
|
|
| guardia-itsm | `guardia` | `/opt/guardia/src` + `/opt/guardia/app` | — |
|
|
| zioinfo-web | `zioinfo` | `/opt/zioinfo/src` | `/var/www/zioinfo` |
|
|
| guardia-manager | `guardia-manager` | `/opt/manager/src` or `/opt/manager/backend` | `/var/www/manager` |
|
|
| guardia-messenger | EAS 빌드 | Gitea only | — |
|
|
| guardia-docs | — | Gitea only | `/var/www/docs` (선택) |
|
|
|
|
### 검증 스크립트 패턴
|
|
`C:/GUARDiA/scripts/check/verify_all_systems.py` 참조.
|
|
Gitea API 인증: `base64.b64encode(b'zio:Zio@Admin2026!').decode()`
|
|
|
|
### 이슈 분류
|
|
|
|
| 코드 | 설명 | 심각도 |
|
|
|------|------|--------|
|
|
| `STALE_WWW` | /var/www 파일이 최근 배포보다 오래됨 | critical |
|
|
| `APP_SRC_DRIFT` | /opt/{app}/app vs src 미동기화 | critical |
|
|
| `STASH_EXISTS` | 서버 git stash 잔존 | warning |
|
|
| `UNCOMMITTED` | 비빌드 파일 uncommitted | warning |
|
|
| `COMMIT_MISMATCH` | 서버 커밋 != Gitea 커밋 | critical |
|
|
| `SERVICE_DOWN` | systemctl not active | critical |
|
|
| `WORKSPACE_DRIFT` | workspace != repos | info |
|
|
|
|
---
|
|
|
|
## Phase 2: 이슈 수정 (에이전트 팀)
|
|
|
|
Phase 1에서 이슈가 없으면 → 완료 보고 후 종료.
|
|
이슈 있으면 → deploy-fixer와 팀 구성.
|
|
|
|
### 수정 우선순위
|
|
|
|
```
|
|
1. SERVICE_DOWN → 서비스 재기동 먼저
|
|
2. APP_SRC_DRIFT → rsync + restart
|
|
3. STASH_EXISTS → stash 내용 평가 → 복원 또는 삭제
|
|
4. COMMIT_MISMATCH → git fetch + reset --hard origin/main
|
|
5. STALE_WWW → npm/mvn 빌드 + www 복사
|
|
6. UNCOMMITTED → 파일 분류 (중요/임시) → workspace 반영 또는 clean
|
|
7. WORKSPACE_DRIFT → sync_workspace_to_repos.py 실행
|
|
```
|
|
|
|
### 시스템별 수정 처리
|
|
|
|
**guardia-itsm (APP_SRC_DRIFT 표준 처리):**
|
|
```bash
|
|
rsync -a --exclude=__pycache__ --exclude=.git \
|
|
--exclude="*.db" --exclude="uploads" \
|
|
/opt/guardia/src/ /opt/guardia/app/
|
|
systemctl restart guardia
|
|
sleep 4 && systemctl is-active guardia
|
|
```
|
|
|
|
**zioinfo-web (STALE_WWW 표준 처리):**
|
|
```bash
|
|
cd /opt/zioinfo/src
|
|
git fetch origin main && git reset --hard origin/main
|
|
# stash 있으면 핵심 파일 cherry-pick
|
|
cd frontend && npm run build
|
|
cp -r ../backend/src/main/resources/static/. /var/www/zioinfo/
|
|
systemctl restart zioinfo
|
|
```
|
|
|
|
**guardia-manager (STALE_WWW 표준 처리):**
|
|
```bash
|
|
cd /opt/manager/src/frontend # or /opt/manager/backend
|
|
# workspace/guardia-manager의 최신 frontend를 서버에 업로드
|
|
npm ci && npm run build
|
|
cp -r dist/. /var/www/manager/
|
|
systemctl restart guardia-manager
|
|
```
|
|
|
|
**stash 처리 원칙:**
|
|
- `git stash show --stat` 으로 변경 파일 목록 확인
|
|
- `frontend/src/` 파일 포함 → `git checkout stash -- frontend/src/` 로 선별 복원 후 빌드
|
|
- 빌드 산출물(`static/assets/`)만 있으면 → `git stash drop`
|
|
|
|
---
|
|
|
|
## Phase 3: 재검증 (서브 에이전트)
|
|
|
|
Phase 2 완료 후 deploy-verifier 재실행.
|
|
모든 `action_required` 항목이 비어있으면 성공.
|
|
|
|
---
|
|
|
|
## 결과 보고 형식
|
|
|
|
```
|
|
=== GUARDiA 5개 시스템 배포 상태 ===
|
|
|
|
✅ guardia-itsm — active | 커밋 일치 | app 동기화
|
|
✅ zioinfo-web — active | 커밋 일치 | www Jun 1 최신
|
|
✅ guardia-manager— active | 커밋 일치 | www Jun 1 최신
|
|
✅ guardia-messenger — EAS v1.0.0 | Gitea 최신
|
|
✅ guardia-docs — 36개 md | Gitea 최신
|
|
|
|
수정된 이슈: X개
|
|
남은 이슈: 0개
|
|
```
|
|
|
|
---
|
|
|
|
## 에러 핸들링
|
|
|
|
| 에러 | 처리 |
|
|
|------|------|
|
|
| 서비스 재기동 실패 | `journalctl -u {service} -n 20` 로그 수집 후 보고 |
|
|
| npm build 실패 | `node_modules` 삭제 후 `npm ci` 재시도 |
|
|
| git reset 충돌 | `git clean -fd` 후 재시도 |
|
|
| Gitea push 실패 | bundle → 서버 → push 방식 (push_jenkinsfiles_api 패턴) |
|
|
| rsync 권한 오류 | `chown -R root:root /opt/{app}` 후 재시도 |
|
|
|
|
---
|
|
|
|
## 테스트 시나리오
|
|
|
|
**정상 흐름:**
|
|
1. 검증 실행 → 이슈 탐지 (Manager STALE_WWW, ITSM APP_SRC_DRIFT)
|
|
2. 수정 팀 실행 → Manager npm build, ITSM rsync
|
|
3. 재검증 → 모두 ✅
|
|
|
|
**에러 흐름:**
|
|
- Manager npm build 실패 → `npm ci` 재시도 → 실패 시 보고서에 기록 후 다음 시스템 진행
|
|
|
|
---
|
|
|
|
## should-trigger
|
|
|
|
- "5개 시스템 배포 확인해줘"
|
|
- "서버에 최신본 올라간 거 맞아?"
|
|
- "Manager 구버전 올라가 있는데 수정해줘"
|
|
- "guardia-itsm 배포 상태 점검"
|
|
- "홈페이지 최신 코드 반영됐나?"
|
|
- "전체 동기화 해줘"
|
|
- "다시 실행", "수정", "보완"
|
|
|
|
## should-NOT-trigger
|
|
|
|
- "guardia-itsm 새 기능 만들어줘" → itsm-dev 에이전트
|
|
- "홈페이지 디자인 바꿔줘" → ui-overhaul-orchestrator
|
|
- "Jenkins 파이프라인 설정" → cicd-pipeline-orchestrator
|
|
- "코드 리뷰해줘" → code-review 스킬
|