[필수-1] 언인스톨 스크립트 (이식성 > 설치성)
- setup/uninstall.sh: Linux 완전 제거 (표준/purge 모드)
- 백업 → 서비스중지 → Ollama/Gitea → 파일/DB 제거 → 보고
- setup/uninstall.ps1: Windows 완전 제거 (NSSM 서비스 제거)
- -Purge -NoBackup -KeepJava -KeepDb 파라미터
[필수-2] 화면별 도움말 시스템 (사용성)
- static/help.js: 7개 화면 도움말 DB + F1/? 버튼 자동 삽입
- 팝업: 아이콘+제목+내용+주제별 네비게이션
- 키보드: F1(열기), ESC(닫기)
- 검색: 도움말 전체 텍스트 검색
[필수-3] 에러 코드 목록 (기능 적합성)
- GET /api/admin/errors/codes: 17개 에러코드 + 해결방법
AUTH_001~004, SR_001~004, LIC_001~003, CMDB_001~002, AI_001~002, SYS_001~002, VAL_001
[필수-4] 웹 접근성 개선 (사용성)
- --text-muted: #64748b(3.1:1) → #94a3b8(4.7:1) 색상 대비 개선
- :focus-visible 규칙 추가 (키보드 포커스 표시)
- 마우스 클릭 시 포커스 링 숨김 (UX 개선)
[필수-5] 성능 시험 실시
- 20명 동시 접속: avg 527ms, P95 864ms (GS기준 3초 통과)
- certification/05_시험성적서/성능_시험_결과.md 작성
[필수-6] 백업/복구 API (신뢰성 > 복구성)
- POST /api/admin/backup: DB+.env+업로드 ZIP 백업
- GET /api/admin/backups: 백업 목록
- GET /api/admin/backups/{file}/download: 백업 다운로드
- POST /api/admin/restore/{file}: 백업 복원
[필수-7] About/버전 화면 (유지보수성)
- GET /api/admin/about: 제품명/버전/빌드일/오픈소스목록
- GET /api/admin/health: DB+Ollama+디스크+라이선스 종합 상태
예상 GS 1등급 점수: 93점 / 100점
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
[온보딩 API (routers/onboarding.py)]
- 8단계 온보딩 플로우:
0. 환영 → 1. 비밀번호변경 → 2. 대시보드 → 3. 프로젝트등록
→ 4. 서버등록 → 5. 소스코드등록 → 6. 메신저봇 → 7. 완료
- POST /api/onboarding/message: 현재화면 + 사용자질문 → Ollama 답변
- 화면별 스포트라이트 target 정의 (CSS selector)
- 사용자별 단계 상태 영속 관리
[온보딩 챗봇 UI (static/onboarding.js)]
- 우측 고정 패널 (360px, 모바일 하단 슬라이드)
- 타이핑 애니메이션 효과 + 마크다운 렌더링
- 스포트라이트: 현재 단계 UI 요소를 하이라이트
- 화면 변화 감지 (MutationObserver + click 이벤트)
- 최소화/닫기/재시작 제어
- 사용자 질문 입력 → Ollama 실시간 답변
- 온보딩 완료 후 우측하단 ? 도움말 버튼
- 액션버튼: next/navigate/external/complete/skip
[설치 자동화 연동]
- install_auto.sh: 설치 완료 후 onboarding reset API 호출
- 브라우저 열릴 때 챗봇 자동 표시
사용자 경험:
설치 완료 → 브라우저 자동 오픈 → 챗봇 우측 등장
→ "환영합니다!" → 비밀번호변경 화면 이동 안내
→ CMDB 서버등록 스포트라이트 → Gitea 소스등록
→ 완료 후 ? 버튼으로 재시작 가능
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
[Claude Code Desktop 자동 설치 환경]
- setup/CLAUDE.md: 트리거 키워드 + 설치 패키지 설명
- setup/.claude/skills/guardia-install/SKILL.md: 6단계 설치 오케스트레이터
Phase 0: 의도 파악 → Phase 1: OS 감지 → Phase 2: 사전 확인
Phase 3: 설치 실행 → Phase 4: 라이선스 발급 → Phase 5: 검증 → Phase 6: 완료보고
[통합 자동 설치 스크립트]
- setup/install_auto.sh: Linux 통합 (OS 자동 감지 ubuntu/centos/rhel)
- --license trial30|trial7|<key> 파라미터
- 설치 완료 후 GUARDiA 자동 실행 + 브라우저 자동 열기
- --test 검증 모드
- setup/install_auto.ps1: Windows 통합 (ASCII 전용, PS 5.1 호환)
- 설치 후 NSSM 서비스 자동 시작 + 브라우저 자동 열기
- -Test 파라미터로 검증 전용 실행
[라이선스 엔진 개선]
- core/license.py: generate_trial_key(days=None) 파라미터 추가
- TRIAL_DURATION_DAYS = TRIAL_DURATION_DAYS 환경변수로 조정 가능
- routers/license.py: TrialRequest.days 필드 + 30일 체험판 지원
POST /api/license/trial {"days": 30} 로 30일 발급
사용자 경험:
1. setup/ 폴더를 새 PC에 복사
2. Claude Code Desktop 열고 해당 폴더 open
3. "GUARDiA 시스템 1달 사용자로 설치해 줘" 입력
4. 자동으로 OS 감지 → 설치 → 30일 라이선스 → 브라우저 열림
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
[start.sh (Linux/Mac)]
- mvnw(Wrapper) 우선 사용 → 시스템 Maven → 자동 설치 순서
- Maven 없으면: apt/dnf/yum 패키지 관리자 → 수동 tar.gz 설치
- 모드: dev (핫리로드) | prod (빌드+실행) | build (빌드만) | spring-only
[start.ps1 (Windows)]
- mvnw.cmd → 시스템 mvn → Chocolatey → 수동 zip 설치
- Start-Job으로 Spring Boot 백그라운드 실행 + npm run dev 병렬
[.mvn/wrapper/maven-wrapper.properties]
- Maven 3.9.6 Wrapper 설정 (첫 실행 시 자동 다운로드)
[setup_ubuntu.sh]
- INSTALL_MAVEN=true/false 옵션 추가 (기본 true)
- 이미 설치된 경우 건너뜀
사용법:
bash workspace/zioinfo-web/start.sh dev # 개발
bash workspace/zioinfo-web/start.sh prod # 운영
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
[Scouter APM 연동]
- core/scouter.py: Scouter HTTP API 클라이언트
- get_summary(): 전체 WAS 모니터링 현황 (CPU/TPS/응답시간/위험서버)
- get_server_metrics(): 특정 서버 실시간 메트릭
- get_alert_list(): Scouter 경보 목록
- get_xlog_recent(): 최근 트랜잭션 X-Log
- routers/scouter.py: REST API 엔드포인트 (6개)
- GET /api/scouter/status, /servers, /servers/{hash}/metrics
- GET /api/scouter/servers/{hash}/services, /xlog, /alerts
- POST /api/scouter/agent/deploy: SSH로 scouter-agent.jar 자동 배포
[스케줄러]
- scheduler.py: Scouter 경보 수집 (5분마다)
- CPU > 80% 또는 에러율 > 5% 서버 자동 감지 → GUARDiA 알림
[Docker Compose]
- docker-compose.yml: scouteross/scouter-server:2.20.0 서비스 추가
- 포트 6100 (UDP/TCP 에이전트 수집) + 6180 (HTTP API)
[설치 스크립트]
- setup/scouter/download_scouter.sh: 에이전트/서버 다운로드
- scouter-agent.jar + agent.conf.template 생성
- setup_ubuntu.sh: Scouter 서버 설치 단계 추가 (14단계로 확장)
- --test 검증: Scouter API + Gitea HTTP 검사 추가
환경변수: SCOUTER_HOST, SCOUTER_HTTP_PORT=6180, SCOUTER_USER, SCOUTER_PASSWORD
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
[DB 선택 대화형 프롬프트]
- setup/lib/db_select.sh: 설치 시 SQLite/PostgreSQL/PostgreSQL+pgvector 선택
- DB_TYPE 환경변수로 무인 설치 지원
- pgvector 자동 빌드/설치 (소스 빌드 폴백 포함)
- .env DATABASE_URL 자동 기록
[Vector DB]
- docker-compose.yml: postgres를 pgvector/pgvector:pg15 이미지로 교체
- Qdrant: docker profile=vector 로 선택적 활성화
- docs/vector_db_guide.md: pgvector/Qdrant 사용법 + 시나리오
[Gitea 온프레미스 Git 서버]
- docker-compose.yml: gitea/gitea:1.21-rootless 서비스 추가
- setup/lib/gitea_setup.sh: 공통 설치/초기화 함수
- setup/gitea_init.sh: 독립 실행형 초기화 스크립트
- 관리자 계정 생성
- guardia 조직 + GUARDiA 저장소 생성
- main 브랜치 보호 (PR + 리뷰 1명 필수)
- develop 브랜치 생성
- 개발자 계정 (engineer1/2, pm1, admin) + feature/이름/init 브랜치 자동 생성
- 현재 소스 자동 push
[브랜치 전략]
main : 보호 브랜치, PR 필수, 리뷰 1명 필수
develop : 통합 브랜치, force-push 금지
feature/이름/기능: 개인 개발 브랜치
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- 한글 제거 -> ASCII 전용 (PS5.1은 BOM없는 UTF-8을 CP949로 읽어 파싱 오류 발생)
- ?. null-conditional 연산자 제거 -> 전통적 if/else로 교체
- 줄 연속 백틱 제거 -> 단일 라인으로 변경
- psql 단일인용부호 이슈 -> [char]39 + tmpSql 파일 방식으로 우회
- Path 환경변수 연결 -> + 연산자 방식으로 변경
- 구문 오류 0개 확인 완료 (ParseFile 검증)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
[download_packages.sh — 인터넷 서버에서 실행]
- OS별 패키지 다운로드 (ubuntu .deb / centos .rpm)
- pip wheel 전체 다운로드 (-r requirements.txt)
- Tomcat 9 tar.gz, Ollama 바이너리, Chart.js 다운로드
- Ollama 모델(llama3.1:8b, codellama:7b) 압축 패키지
- Docker 이미지 tar (docker_package.sh 연동)
- setup/offline/ 에 계층적으로 저장, README.md 자동 생성
[설치 스크립트 오프라인 지원 강화]
- setup_ubuntu.sh: OFFLINE_PKG_DIR 환경변수 지원 (.deb 로컬 설치)
- setup_centos.sh: OFFLINE_PKG_DIR 환경변수 지원 (.rpm 로컬 설치)
- 기존 TOMCAT_MIRROR=file://..., OLLAMA_INSTALL=offline 유지
[Chart.js 오프라인 폴백]
- index.html: CDN 실패 시 /static/chart.umd.min.js 로컬 폴백
- db_init.py: 오프라인 패키지에서 chart.umd.min.js 자동 복사
폐쇄망 설치 절차:
인터넷 서버: bash setup/download_packages.sh all
USB 복사: tar -czf offline.tar.gz setup/offline/
폐쇄망 설치: OFFLINE_PKG_DIR=./offline/ubuntu bash setup/setup_ubuntu.sh
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
[파일 목록]
- Dockerfile: GUARDiA ITSM Python 3.11-slim 이미지
- 비루트(guardia) 계정 실행
- 헬스체크 내장
- docker-compose.yml: 개발/테스트 풀스택
- guardia-itsm, nginx, postgres:15, redis:7, ollama/ollama, tomcat:9
- Ollama 모델은 볼륨 마운트 (이미지 외부)
- docker-compose.prod.yml: 운영 환경 오버라이드
- 외부 포트 차단, 호스트 경로 마운트
- docker-compose.gpu.yml: NVIDIA GPU 오버라이드
- docker-start.sh: dev|prod|gpu 모드 빠른 시작
- .dockerignore: 보안 파일(.env, *.db) 제외
- docker/nginx/guardia.conf: 리버스 프록시 설정
- docker/tomcat/tomcat-users.xml: opsagent 계정 설정
[폐쇄망 패키지]
- setup/docker_package.sh: 인터넷 서버에서 모든 이미지를 tar.gz로 패키징
- setup/docker_load.sh: 폐쇄망에서 tar.gz 로드 + 즉시 시작 옵션
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
[Ollama — 온프레미스 sLLM 서버]
- setup_ubuntu/centos/rhel/windows: Ollama 설치 단계 추가
- 환경변수 OLLAMA_INSTALL=online|offline|skip 지원 (망분리 환경)
- 환경변수 OLLAMA_MODELS 으로 초기 모델 설정 (기본: llama3.1:8b)
- 오프라인: OLLAMA_BIN_PATH로 바이너리 직접 지정
- SELinux 포트 허용 (RHEL), 방화벽 내부 전용 차단 (8080/11434)
[보안·운영 도구]
- Fail2ban: SSH 무차별 대입 방지 (5회 실패 시 1시간 차단)
- Chrony/NTP: 감사 로그 타임스탬프 정합성 확보
- JDK 8/11: 레거시 WAS(Tomcat 7/8) 지원을 위한 다중 JDK
- Logrotate: catalina.out 14일, *.log 8주 보관
[--test 검증 강화]
- Ollama 서비스 + API + 모델 존재 여부 검사
- Fail2ban/Chrony 실행 상태 검사
[단계 수 업데이트]
- Ubuntu: 10→13단계, CentOS: 10→13단계, RHEL: 11→13단계, Windows: 10단계
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- setup_ubuntu.sh: OpenJDK 17 + Tomcat 9 단계 추가 (10단계로 확장)
- setup_centos.sh: OpenJDK 17 + Tomcat 9 단계 추가 (10단계)
- setup_rhel.sh: OpenJDK 17 + Tomcat 9 + SELinux 포트 허용 (11단계)
- setup_windows.ps1: openjdk choco 설치 + Tomcat 9 NSSM 서비스 (10단계)
- setup_target_server.sh: 신규 — 관리 대상 WAS 서버 표준 구성
(OpenJDK 17 + Tomcat 9 + opsagent OS/Tomcat 계정 + SSH 보안 + GUARDiA 연결정보 출력)
- --test 검증: Java/Tomcat 항목 추가
- 공통: AJP 비활성화, shutdown 포트 -1 보안설정, opsagent Manager 계정 자동 추가
- 공통: TOMCAT_MIRROR 환경변수로 오프라인/내부망 설치 지원
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
[설치 스크립트 수정사항]
- PYTHONIOENCODING=utf-8 systemd/NSSM 서비스 환경변수 추가 (Windows cp949 오류 예방)
- db_init.py 헬퍼 추가: 스키마 불일치 자동 감지 → 백업 → 재초기화
- 포트 8001 충돌 감지 및 기존 프로세스 자동 종료 로직 추가
- --test 검증 항목 강화: HTTP 응답 + 로그인 API + UTF-8 인코딩 포함
- setup_ubuntu/centos/rhel: PYTHONUNBUFFERED=1 추가
[workspace 자동분석 워크플로우]
- workspace/ 디렉토리 생성 (소스코드 투입 위치)
- .claude/skills/workspace-analyzer/SKILL.md 스킬 생성
Phase 0~6: 탐색→스택탐지→심층분석→리포트→개발환경가이드→하네스생성→CLAUDE.md
- CLAUDE.md에 workspace 워크플로우 안내 등록
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
