cfe2901a55
- itsm/ -> workspace/guardia-itsm/ - manager/ -> workspace/guardia-manager/ - app/ -> workspace/guardia-messenger/ - manual/ -> workspace/guardia-docs/ workspace/zioinfo-web/ unchanged. git mv preserves full commit history. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
363 lines
16 KiB
Markdown
363 lines
16 KiB
Markdown
# 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. 오류 응답 형식
|
|
|
|
```json
|
|
{
|
|
"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 | 최초 작성 | 개발팀 |
|