DESKTOP-TKLFCPRython 938b25f286 feat(itsm): G-1~G-12 확장 기능 + 하네스/봇/설치스크립트 구현

G-1: 메신저 Webhook Relay + _send_to_room 실제 httpx 호출 구현
G-2: POST /api/tasks/bulk SR 대량작업 엔드포인트 (최대 100건)
G-3: 라이선스 만료 알림 스케줄러 (매일 09:00 KST)
G-4: 체험판 upgrade_banner 필드 + license.py 배너 로직
G-5: core/auto_rca.py + incidents/problem auto-rca 엔드포인트
G-6: core/deploy_impact.py + vibe impact-analysis 엔드포인트
G-7: core/ticket_classifier.py + SR 생성 시 AI 분류 + ai-suggestion API
G-8: VulnPatchRecord 모델 + vuln_scan 패치추적 4개 엔드포인트
G-9: core/jira_sync.py + gateway Jira/Confluence 연동 엔드포인트
G-10: core/push_notify.py + routers/push.py + PushSubscription 모델
G-11: approvals 다중승인 (위임/서명/기한초과/마감연장)
G-12: alembic.ini + migrations/ + cicd/migrate_to_postgres.sh

하네스: guardia-orchestrator 확장기능 Phase 반영
봇명령어: /sr /status /license /bulk 슬래시 명령어 추가
설치스크립트: setup/ (Ubuntu, CentOS, RHEL, Windows) --test 옵션 포함

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-29 18:18:52 +09:00

16 KiB

Raw Blame History

GUARDiA ITSM + Messenger — 분석 및 설계서

문서번호: GUARDIA-DS-001
버전: 1.0
작성일: 2026-05-25
작성자: GUARDiA 개발팀
보안등급: 내부용 (대외비)

1. 문서 목적

본 문서는 GUARDiA ITSM(IT Service Management) 플랫폼과 GUARDiA Messenger 시스템의 요구사항 분석, 시스템 설계, 데이터 설계, API 설계를 기술한다. 본 문서는 개발자, 운영자, 품질관리자가 시스템을 이해하고 유지보수하는 데 활용한다.

2. 시스템 개요

2-1. GUARDiA ITSM

GUARDiA ITSM은 공공기관 IT 운영을 위한 온프레미스 서비스관리 플랫폼이다.

항목	내용
목적	공공기관 IT 인프라 SR(Service Request) 접수·처리·이력 관리
운영 방식	온프레미스 (인터넷 완전 차단 환경 대응)
주요 사용자	운영 엔지니어, PM, 기관 담당자(고객)
기술 스택	FastAPI, SQLAlchemy (Async), SQLite, Python 3.11+
인증 방식	JWT (RS256), 역할 기반 접근 제어 (RBAC)

2-2. GUARDiA Messenger

GUARDiA Messenger는 ITSM과 연동되는 사내 메신저로, SR 알림, 봇 명령, 엔지니어 채팅을 지원한다.

항목	내용
목적	운영팀 실시간 소통 및 ITSM 이벤트 알림
연동 방식	GUARDiA ITSM Webhook API
주요 기능	채팅, 봇 명령, SR 알림, 공지

3. 요구사항 분석

3-1. 기능적 요구사항 (Functional Requirements)

ID	분류	요구사항	우선순위
FR-001	SR 관리	SR 접수·파싱·배정·승인·처리·완료 워크플로우	필수
FR-002	SR 관리	SR 상태 실시간 SSE 이벤트 브로드캐스트	필수
FR-003	인증	JWT 기반 역할별 로그인 (ADMIN/PM/ENGINEER/CUSTOMER)	필수
FR-004	CMDB	기관·서버 자산 등록 및 조회	필수
FR-005	SSH	서버 원격 명령 실행 (asyncssh)	필수
FR-006	SSL	SSL 인증서 만료 모니터링 및 갱신 이력 관리	필수
FR-007	PM	정기 PM 체크리스트 템플릿 및 반복 스케줄 관리	필수
FR-008	장애	P1~P4 장애 등록·상태 관리·RCA 기록	필수
FR-009	당직	온콜/당직 일정 관리	권장
FR-010	배치	배치 작업 등록·실행·이력 관리	권장
FR-011	CI/CD	Jenkins 파이프라인 연동 (빌드·배포·콜백)	선택
FR-012	알림	이메일(SMTP) + 메신저 Webhook 알림	필수
FR-013	보고서	작업이력·PM결과 Excel 다운로드	권장
FR-014	감사	해시 체인 기반 감사 로그	필수
FR-015	KB	장애 처리 지식 베이스 문서 관리	권장
FR-016	상용화	라이선스 키 기반 에디션 제어 (COMMUNITY / STANDARD / ENTERPRISE)	필수
FR-017	상용화	에디션별 기관·사용자·서버 수량 및 기능(LDAP/PAM/AI/CICD 등) 접근 제한	필수

3-2. 비기능적 요구사항 (Non-Functional Requirements)

ID	분류	요구사항
NFR-001	보안	AES-256-GCM 서버 자격증명 암호화
NFR-002	보안	API 응답에 IP·SSH계정·비밀번호 절대 미포함
NFR-003	보안	root SSH 직접 접속 차단
NFR-004	보안	명령어 안전성 검증 (위험 패턴 차단)
NFR-005	가용성	99% 이상 가용성 목표
NFR-006	성능	API 응답 시간 500ms 이하 (DB 조회 기준)
NFR-007	호환성	RHEL 8/9, CentOS 7/8, Ubuntu 20.04/22.04
NFR-008	호환성	Windows Server 2019/2022
NFR-009	격리	외부 인터넷 완전 차단 환경 동작 가능
NFR-010	감사	모든 SR 처리 이력 블록체인형 해시 체인 보존

4. 시스템 아키텍처

4-1. 전체 구성도

┌─────────────────────────────────────────────────────────────────┐
│                        클라이언트 레이어                           │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │  웹 브라우저  │  │  모바일 앱    │  │  GUARDiA Messenger     │ │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬─────────────┘ │
└─────────┼─────────────────┼─────────────────────┼───────────────┘
          │  HTTPS          │  HTTPS              │  WebSocket/HTTP
┌─────────▼─────────────────▼─────────────────────▼───────────────┐
│                        API 게이트웨이 레이어                        │
│                 Nginx (Reverse Proxy + TLS Termination)          │
└─────────────────────────────┬───────────────────────────────────┘
                              │ HTTP (내부)
┌─────────────────────────────▼───────────────────────────────────┐
│                        애플리케이션 레이어                          │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              GUARDiA ITSM (FastAPI)                     │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │  │
│  │  │ SR 관리   │ │ SSH 실행  │ │ SSL 감시  │ │ PM 관리   │  │  │
│  │  │ tasks    │ │ ssh_exec │ │ssl_mgr   │ │   pm     │  │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └───────────┘  │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │  │
│  │  │ 장애관리  │ │ 배치작업  │ │ CI/CD    │ │ Scheduler │  │  │
│  │  │incidents │ │  batch   │ │  cicd    │ │(APSchedul)│  │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └───────────┘  │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              GUARDiA Messenger (FastAPI)                 │  │
│  └──────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ SQLAlchemy (Async)
┌──────────────────────────────▼──────────────────────────────────┐
│                        데이터 레이어                               │
│  SQLite (개발/소규모)  →  PostgreSQL (운영 권장)                    │
└─────────────────────────────────────────────────────────────────┘
                               │ asyncssh
┌──────────────────────────────▼──────────────────────────────────┐
│                       대상 서버 레이어                              │
│  WEB (Nginx/Apache)  WAS (Tomcat/JBoss)  DB (PostgreSQL/Oracle) │
└─────────────────────────────────────────────────────────────────┘

4-2. GUARDiA ITSM 컴포넌트 설명

컴포넌트	파일	역할
진입점	`main.py`	FastAPI 앱, 라우터 등록, lifespan
ORM/스키마	`models.py`	SQLAlchemy 모델 + Pydantic 스키마
DB 세션	`database.py`	AsyncSession 팩토리
인증	`core/auth.py`	JWT 발급/검증
SSH 실행	`core/ssh_exec.py`	asyncssh 기반 원격 실행
알림	`core/notify.py`	SMTP + Messenger Webhook
스케줄러	`core/scheduler.py`	SSL/PM/계약 만료 자동 감시
Jenkins 클라이언트	`core/cicd.py`	Jenkins REST API
시드 데이터	`core/seed.py`	초기 데이터 자동 생성
라이선스 엔진	`core/license.py`	AES-256-GCM 라이선스 생성·검증·캐싱
라이선스 가드	`middleware/license_guard.py`	에디션별 기관·서버·기능 접근 제한 Dependency

4-3. GUARDiA Messenger 컴포넌트

C:\GUARDiA\messenger\
├── core/         실시간 채팅 엔진
├── models/       메시지·사용자·채널 ORM
└── main.py       WebSocket + REST API

5. 데이터 설계

5-1. 전체 테이블 목록 (27개)

번호	테이블명	설명	관련 기능
1	`tb_user`	시스템 사용자	인증
2	`tb_inst_meta`	기관 메타정보	CMDB
3	`tb_inst_contact`	기관 담당자 연락처	CMDB
4	`tb_server_info`	서버 자산 (암호화)	CMDB/SSH
5	`tb_sr_request`	SR 마스터	SR관리
6	`tb_sr_approval`	SR 승인 이력	승인
7	`tb_work_log`	작업 실행 로그	작업
8	`tb_audit_log`	감사 로그 (해시체인)	감사
9	`tb_rating`	만족도 평가	고객
10	`tb_shell_script`	SM 스크립트 메타	자동화
11	`tb_work_timetable`	작업 일정표	타임테이블
12	`tb_sr_attachment`	SR 첨부파일	첨부
13	`tb_notification_log`	알림 이력	알림
14	`tb_kb_document`	지식 베이스	KB
15	`tb_engineer_profile`	엔지니어 스킬	자동배정
16	`tb_project`	CI/CD 프로젝트	배포
17	`tb_vibe_session`	바이브 코딩 세션	CI/CD
18	`tb_ssl_history`	SSL 갱신 이력	SSL
19	`tb_pm_template`	PM 체크리스트 템플릿	PM
20	`tb_pm_schedule`	PM 반복 스케줄	PM
21	`tb_pm_result`	PM 점검 결과	PM
22	`tb_incident`	장애 마스터	장애관리
23	`tb_incident_sr`	장애↔SR 연결	장애관리
24	`tb_oncall_schedule`	온콜/당직 일정	당직
25	`tb_batch_job`	배치 작업	배치
26	`tb_batch_run`	배치 실행 이력	배치
27	`tb_license`	라이선스 등록 이력	상용화 라이선스 관리

5-2. 핵심 테이블 ERD (텍스트 형식)

tb_inst_meta (1) ──< (N) tb_server_info
                          │
tb_inst_meta (1) ──< (N) tb_sr_request ──< (N) tb_sr_approval
                                          ──< (N) tb_work_log
                                          ──< (N) tb_audit_log
                                          ──< (N) tb_sr_attachment
                                          ──< (N) tb_ops_task

tb_sr_request (N) >──< (N) tb_incident  (via tb_incident_sr)

tb_server_info (1) ──< (N) tb_ssl_history
tb_server_info (1) ──< (N) tb_batch_job

tb_pm_template (1) ──< (N) tb_pm_result
tb_work_timetable (1) ──< (N) tb_pm_result

5-3. SR 상태 머신

RECEIVED ──→ PARSED ──→ PENDING_APPROVAL ──→ APPROVED ──→ IN_PROGRESS
                                          └──→ REJECTED
                                                  ↓
IN_PROGRESS ──→ PENDING_PM_VALIDATION ──→ COMPLETED
                                      └──→ FAILED_ROLLBACK

6. API 설계

6-1. 인증 방식

POST /api/auth/login
요청: { "username": "admin", "password": "****" }
응답: { "access_token": "eyJ...", "token_type": "bearer" }

이후 모든 API 요청 헤더:
Authorization: Bearer eyJ...

6-2. 주요 API 목록

분류	메서드	경로	역할
인증	POST	`/api/auth/login`	로그인
SR	GET/POST	`/api/tasks`	SR 목록/생성
SR	PATCH	`/api/tasks/{id}/status`	상태 변경
SSL	GET	`/api/ssl/expiring`	만료 임박 목록
SSL	POST	`/api/ssl/check/{id}`	SSH 점검
SSL	POST	`/api/ssl/renew/{id}`	갱신 기록
PM	GET/POST	`/api/pm/templates`	체크리스트 템플릿
PM	POST	`/api/pm/schedules/{id}/trigger`	PM 실행
장애	GET/POST	`/api/incidents`	장애 관리
당직	GET	`/api/oncall/today`	오늘 당직자
배치	POST	`/api/batch/jobs/{id}/run`	배치 실행

6-3. 오류 응답 형식

{
  "detail": "오류 요약 메시지 (IP, 스택트레이스 미포함)"
}

7. 보안 설계

7-1. 자격증명 암호화

평문 비밀번호
    │
    ▼ AES-256-GCM (12바이트 nonce + 암호문)
    │
    ▼ Base64 인코딩
    │
tb_server_info.os_pw_enc 컬럼 저장

암호화 키: GUARDIA_ENC_KEY 환경변수 (32바이트)

7-2. JWT 보안

알고리즘: HS256
만료: 8시간 (기본값, 환경변수로 조정 가능)
저장: 클라이언트 메모리 (localStorage 사용 금지 권고)

7-3. SSH 보안

root 계정 직접 접속 금지 (ssh_user ≠ root 검증)
known_hosts 검증 (운영 환경 필수)
위험 명령어 패턴 차단:
- rm -rf /, mkfs, dd if=, shutdown, reboot 등

7-4. API 응답 보안

ServerOut 스키마에서 민감정보 제외:

ip_addr — 미포함
ssh_user — 미포함
os_pw_enc — 미포함

7-5. 감사 로그 무결성

각 감사 로그 항목은 이전 항목의 해시값을 포함하는 체인 구조:

log_hash = SHA256(prev_hash + actor + action + detail + timestamp)

8. 배포 구성

8-1. 운영 환경 권장 구성

인터넷
    │ (차단)
    ▼
[Nginx] :443 ──TLS──→ [GUARDiA ITSM] :8000
                  ──TLS──→ [GUARDiA Messenger] :8001

[GUARDiA ITSM] ──asyncssh──→ [관리 대상 서버들]
[GUARDiA ITSM] ──SMTP──→ [내부 메일 서버]

8-2. 최소 서버 사양

항목	최소	권장
CPU	2 코어	4 코어
메모리	4 GB	8 GB
디스크	50 GB	100 GB
OS	RHEL 8 이상 / Ubuntu 20.04 이상	RHEL 9 / Ubuntu 22.04
Python	3.10 이상	3.11

9. GUARDiA Messenger 설계

9-1. 주요 기능

기능	설명
채팅	1:1 및 그룹 채팅
봇 명령	`!vibe`, `!build`, `!deploy`, `!sr`, `!health` 등
SR 알림	ITSM SR 상태 변경 시 자동 알림
파일 전송	이미지·문서 공유

9-2. 봇 명령어 목록

명령어	설명	예시
`!sr <내용>`	SR 빠른 접수	`!sr WAS 응답 없음`
`!status <SR번호>`	SR 상태 조회	`!status SR-20260525-AA1234`
`!health <서버명>`	서버 헬스체크	`!health MOF-WAS-01`
`!oncall`	오늘 당직자 조회	`!oncall`
`!pm <스케줄명>`	PM 즉시 실행	`!pm 기재부 월간점검`
`!ssl <도메인>`	SSL 만료 확인	`!ssl csv.culture.go.kr`

10. 변경 이력

버전	날짜	내용	작성자
1.0	2026-05-25	최초 작성	개발팀

16 KiB Raw Blame History