967 lines
23 KiB
Markdown
967 lines
23 KiB
Markdown
# GUARDiA ITSM + Messenger — 운영자 지침서
|
|
|
|
**문서 버전**: 1.0
|
|
**작성일**: 2026-05-25
|
|
**대상**: 시스템 운영자, IT 관리자
|
|
|
|
---
|
|
|
|
## 목차
|
|
|
|
1. [시스템 개요](#1-시스템-개요)
|
|
2. [일상 운영 절차](#2-일상-운영-절차)
|
|
3. [사용자 계정 관리](#3-사용자-계정-관리)
|
|
4. [SR(서비스요청) 관리](#4-sr서비스요청-관리)
|
|
5. [SSL 인증서 관리](#5-ssl-인증서-관리)
|
|
6. [정기점검(PM) 관리](#6-정기점검pm-관리)
|
|
7. [장애 관리](#7-장애-관리)
|
|
8. [온콜/당직 관리](#8-온콜당직-관리)
|
|
9. [배치 작업 관리](#9-배치-작업-관리)
|
|
10. [백업 및 복구](#10-백업-및-복구)
|
|
11. [모니터링 및 알림](#11-모니터링-및-알림)
|
|
12. [보안 운영 지침](#12-보안-운영-지침)
|
|
13. [장애 대응 절차](#13-장애-대응-절차)
|
|
14. [로그 관리](#14-로그-관리)
|
|
15. [주요 설정 파일](#15-주요-설정-파일)
|
|
16. [라이선스 관리](#16-라이선스-관리)
|
|
|
|
---
|
|
|
|
## 1. 시스템 개요
|
|
|
|
### 1.1 구성 요소
|
|
|
|
| 구성요소 | 역할 | 기본 포트 |
|
|
|----------|------|-----------|
|
|
| GUARDiA ITSM | IT 서비스 관리 플랫폼 | 8000 |
|
|
| GUARDiA Messenger | 내부 메신저 + 봇 | 8001 |
|
|
| SQLite DB | 데이터 저장소 | — |
|
|
| APScheduler | 백그라운드 작업 (SSL 점검, PM) | — |
|
|
|
|
### 1.2 서비스 URL
|
|
|
|
```
|
|
운영자/엔지니어 화면: http://<서버IP>:8000/
|
|
고객 화면: http://<서버IP>:8000/customer
|
|
로그인: http://<서버IP>:8000/login
|
|
API 문서: http://<서버IP>:8000/docs (운영: 비활성화 권장)
|
|
Messenger: http://<서버IP>:8001/
|
|
```
|
|
|
|
### 1.3 프로세스 구성
|
|
|
|
```
|
|
systemd (Linux):
|
|
guardia-itsm.service — ITSM 메인 서버
|
|
guardia-messenger.service — Messenger 서버
|
|
|
|
Windows Service:
|
|
GUARDiA-ITSM — ITSM 메인 서버
|
|
GUARDiA-Messenger — Messenger 서버
|
|
```
|
|
|
|
---
|
|
|
|
## 2. 일상 운영 절차
|
|
|
|
### 2.1 매일 아침 점검 체크리스트
|
|
|
|
```
|
|
시간: 매일 09:00
|
|
|
|
□ 1. 서비스 상태 확인
|
|
→ curl http://localhost:8000/ (200 응답 확인)
|
|
|
|
□ 2. 야간 스케줄러 실행 결과 확인
|
|
→ /var/log/guardia/scheduler.log 최신 항목 확인
|
|
→ SSL 점검 결과 확인 (00:10 실행)
|
|
→ 계약 만료 점검 결과 확인 (01:00 실행)
|
|
→ PM 자동 생성 결과 확인 (06:00 실행)
|
|
|
|
□ 3. 신규 SR 확인
|
|
→ ITSM 로그인 → 대시보드 → 미배정 SR 확인
|
|
→ P1/P2 긴급 건 우선 배정
|
|
|
|
□ 4. SSL 만료 임박 도메인 확인
|
|
→ ITSM → SSL 관리 → CRITICAL/URGENT 상태 도메인 갱신 조치
|
|
|
|
□ 5. 오늘 PM 일정 확인
|
|
→ ITSM → 정기점검 → 오늘 예정 작업 확인
|
|
|
|
□ 6. 라이선스 상태 확인
|
|
→ ITSM → 사이드바 🔏 라이선스 관리 → 상태 배너 확인
|
|
→ 노랑 배너(만료 30일 이내): 갱신 준비 시작
|
|
→ 빨강 배너(만료): 즉시 갱신 키 적용
|
|
```
|
|
|
|
### 2.2 매주 점검 체크리스트
|
|
|
|
```
|
|
시간: 매주 월요일 10:00
|
|
|
|
□ DB 파일 크기 확인 (100MB 이상 시 정리 검토)
|
|
□ 로그 파일 로테이션 확인
|
|
□ 업로드 파일 디렉토리 크기 확인
|
|
□ 미해결 SR 현황 검토 (7일 이상 미처리 건)
|
|
□ 만족도 낮은 SR 원인 분석
|
|
□ 이번 주 당직 배정 확인 및 알림
|
|
□ 만료 예정 SSL 인증서 30일 이내 갱신 계획 수립
|
|
```
|
|
|
|
### 2.3 매월 점검 체크리스트
|
|
|
|
```
|
|
시간: 매월 1일 11:00
|
|
|
|
□ 월간 SR 통계 보고서 작성
|
|
□ PM 점검 완료율 확인 및 미완료 건 추적
|
|
□ 보안 패치 현황 확인
|
|
□ 사용자 계정 감사 (퇴직자 계정 비활성화 확인)
|
|
□ DB 백업 파일 무결성 확인
|
|
□ 장애 발생 현황 분석 및 재발 방지 대책 검토
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 사용자 계정 관리
|
|
|
|
### 3.1 계정 역할(Role) 정의
|
|
|
|
| 역할 | 권한 | 사용 대상 |
|
|
|------|------|-----------|
|
|
| ADMIN | 전체 관리 | 시스템 관리자 |
|
|
| PM | SR 배정, 결재, PM 관리 | 프로젝트/서비스 매니저 |
|
|
| ENGINEER | SR 처리, 작업 등록 | IT 엔지니어 |
|
|
| CUSTOMER | 자신의 SR 조회/생성 | 고객/사용자 |
|
|
|
|
### 3.2 신규 사용자 등록
|
|
|
|
**방법 1: API 직접 등록 (ADMIN)**
|
|
```
|
|
POST /auth/register
|
|
{
|
|
"username": "user001",
|
|
"password": "초기비밀번호!123",
|
|
"full_name": "홍길동",
|
|
"email": "hong@example.com",
|
|
"role": "ENGINEER"
|
|
}
|
|
```
|
|
|
|
**방법 2: seed.py 수정 (초기 구성 시)**
|
|
```python
|
|
# core/seed.py — _seed_users() 함수에 추가
|
|
{"username": "new_user", "password": "초기PW!", "role": Role.ENGINEER}
|
|
```
|
|
|
|
### 3.3 비밀번호 정책
|
|
|
|
```
|
|
최소 길이: 8자
|
|
필수 조합: 영문 + 숫자 + 특수문자
|
|
금지 비밀번호: admin1234, password, 12345678 등
|
|
변경 주기: 90일마다 강제 변경 (구현 예정)
|
|
초기 비밀번호: 등록 후 첫 로그인 시 변경 강제
|
|
```
|
|
|
|
### 3.4 계정 잠금 및 비활성화
|
|
|
|
```
|
|
# 퇴직자/이탈자 계정 비활성화
|
|
PATCH /auth/users/{id}
|
|
{"is_active": false}
|
|
|
|
# 계정 삭제 (데이터 보존 위해 비활성화 권장, 삭제 비권장)
|
|
DELETE /auth/users/{id}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. SR(서비스요청) 관리
|
|
|
|
### 4.1 SR 유형 및 처리 기한
|
|
|
|
| SR 유형 | 설명 | 목표 처리 시간 |
|
|
|---------|------|----------------|
|
|
| INCIDENT | 긴급 장애, 서비스 중단 | P1: 1시간, P2: 4시간 |
|
|
| SERVICE | 일반 서비스 요청 | 2 영업일 |
|
|
| CHANGE | 변경 요청 (결재 필요) | 5 영업일 |
|
|
| LOG | 작업 기록, 배치 결과 | 정보성 (SLA 없음) |
|
|
|
|
### 4.2 SR 상태 흐름
|
|
|
|
```
|
|
OPEN → IN_PROGRESS → RESOLVED → CLOSED
|
|
↓ ↑
|
|
REJECTED ← (결재 거부) REOPENED (재오픈)
|
|
```
|
|
|
|
### 4.3 담당자 배정 방법
|
|
|
|
```
|
|
자동 배정:
|
|
PATCH /assign/{sr_id}
|
|
{"assignee_id": null} → 시스템이 자동 배정
|
|
|
|
수동 배정:
|
|
PATCH /assign/{sr_id}
|
|
{"assignee_id": 5} → 특정 엔지니어(ID:5)에게 배정
|
|
```
|
|
|
|
### 4.4 SLA 위반 모니터링
|
|
|
|
```
|
|
SLA 위반 기준:
|
|
P1 INCIDENT: 1시간 이내 미처리
|
|
P2 INCIDENT: 4시간 이내 미처리
|
|
|
|
점검 방법:
|
|
GET /dashboard/sla-violations
|
|
|
|
Messenger 알림: 위반 30분 전 자동 알림 (스케줄러)
|
|
```
|
|
|
|
---
|
|
|
|
## 5. SSL 인증서 관리
|
|
|
|
### 5.1 SSL 도메인 등록
|
|
|
|
```
|
|
새 도메인 등록:
|
|
POST /ssl-manager/domains
|
|
{
|
|
"domain": "www.example.com",
|
|
"port": 443,
|
|
"server_id": 1,
|
|
"memo": "메인 홈페이지"
|
|
}
|
|
```
|
|
|
|
### 5.2 자동 점검 일정
|
|
|
|
```
|
|
매일 00:10 — 모든 등록 도메인 SSL 점검 자동 실행
|
|
점검 방법: 관리 서버의 ssl_expiry_check.sh 스크립트 실행
|
|
|
|
알림 발송 조건:
|
|
EXPIRED (만료됨) → 즉시 Critical 알림
|
|
URGENT (7일 이내) → 매일 알림
|
|
WARN (30일 이내) → 최초 발견 시 알림
|
|
OK (30일 초과) → 알림 없음
|
|
```
|
|
|
|
### 5.3 SSL 갱신 처리 절차
|
|
|
|
```
|
|
1단계: 만료 임박 도메인 확인
|
|
GET /ssl-manager/domains?level=CRITICAL
|
|
GET /ssl-manager/domains?level=URGENT
|
|
|
|
2단계: 인증서 갱신 (외부 CA에서 수행)
|
|
- Let's Encrypt: certbot renew
|
|
- 상용 CA: CA 포털에서 갱신 신청
|
|
|
|
3단계: 서버에 인증서 적용
|
|
- Nginx/Apache 인증서 파일 교체
|
|
- 웹서버 재시작
|
|
|
|
4단계: GUARDiA ITSM에 갱신 완료 기록
|
|
POST /ssl-manager/domains/{id}/renew
|
|
{
|
|
"renewed_at": "2026-05-25T10:00:00",
|
|
"new_expiry": "2027-05-25T10:00:00",
|
|
"memo": "Let's Encrypt 자동 갱신"
|
|
}
|
|
|
|
5단계: 즉시 재점검으로 확인
|
|
POST /ssl-manager/domains/{id}/check
|
|
```
|
|
|
|
### 5.4 SSL 스크립트 배포
|
|
|
|
서버에 점검 스크립트를 배포해야 SSH 점검이 가능합니다:
|
|
|
|
```bash
|
|
# 관리 대상 서버에 스크립트 배포
|
|
scp scripts/sm/ssl/ssl_expiry_check.sh user@서버IP:/opt/guardia/scripts/ssl/
|
|
ssh user@서버IP "chmod +x /opt/guardia/scripts/ssl/ssl_expiry_check.sh"
|
|
|
|
# 테스트
|
|
ssh user@서버IP "bash /opt/guardia/scripts/ssl/ssl_expiry_check.sh www.example.com"
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 정기점검(PM) 관리
|
|
|
|
### 6.1 PM 스케줄 설정
|
|
|
|
```
|
|
PM 주기 옵션:
|
|
WEEKLY — 매주
|
|
BIWEEKLY — 격주
|
|
MONTHLY — 매월
|
|
QUARTERLY — 분기별 (3개월)
|
|
SEMIANNUAL — 반기별 (6개월)
|
|
ANNUAL — 연간
|
|
CUSTOM — 커스텀 cron 식
|
|
|
|
스케줄 등록:
|
|
POST /pm/schedules/
|
|
{
|
|
"name": "운영 서버 월간 점검",
|
|
"server_id": 1,
|
|
"template_ids": [1, 2, 3],
|
|
"frequency": "MONTHLY",
|
|
"day_of_month": 15,
|
|
"assigned_to": 5
|
|
}
|
|
```
|
|
|
|
### 6.2 PM 작업 자동 생성
|
|
|
|
```
|
|
매일 06:00 — 스케줄러가 당일 PM 작업 자동 생성
|
|
자동 생성된 작업: GET /pm/works/
|
|
|
|
수동 생성:
|
|
POST /pm/works/
|
|
{
|
|
"schedule_id": 1,
|
|
"planned_date": "2026-06-01",
|
|
"notes": "6월 월간 점검"
|
|
}
|
|
```
|
|
|
|
### 6.3 PM 결과 입력
|
|
|
|
```
|
|
각 체크리스트 항목 결과 입력:
|
|
PATCH /pm/works/{work_id}/results/{result_id}
|
|
{
|
|
"result": "PASS", // PASS / FAIL / WARNING / NA
|
|
"value": "85%", // 측정값
|
|
"note": "" // FAIL인 경우 조치 내역 필수
|
|
}
|
|
|
|
PM 완료 처리:
|
|
PATCH /pm/works/{work_id}/complete
|
|
```
|
|
|
|
### 6.4 PM 보고서 출력
|
|
|
|
```
|
|
Excel 보고서 다운로드:
|
|
GET /pm/works/{work_id}/report
|
|
→ Excel 파일 다운로드 (PASS: 녹색, FAIL: 빨간색, WARNING: 노란색)
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 장애 관리
|
|
|
|
### 7.1 장애 등급 정의
|
|
|
|
| 등급 | 영향 | 대응 시간 | 예시 |
|
|
|------|------|-----------|------|
|
|
| P1 | 전체 서비스 중단 | 1시간 | 운영 DB Down |
|
|
| P2 | 주요 기능 장애 | 4시간 | 로그인 불가 |
|
|
| P3 | 부분 기능 장애 | 8시간 | 특정 기능 오류 |
|
|
| P4 | 경미한 장애 | 2영업일 | UI 오류 |
|
|
|
|
### 7.2 P1/P2 장애 대응 절차
|
|
|
|
```
|
|
즉시 조치 (15분 이내):
|
|
1. ITSM에 장애 등록 (POST /incidents/)
|
|
→ Messenger 긴급 알림 자동 발송
|
|
2. 온콜 담당자에게 연락
|
|
3. 장애 타임라인 기록 시작
|
|
|
|
초기 조사 (30분 이내):
|
|
4. PATCH /incidents/{id}/status — INVESTIGATING
|
|
5. 원인 파악 시작
|
|
6. 임시 우회 방안 검토
|
|
|
|
조치 및 복구:
|
|
7. PATCH /incidents/{id}/status — MITIGATED (임시 조치 완료)
|
|
8. 근본 원인 해결
|
|
9. PATCH /incidents/{id}/status — RESOLVED
|
|
|
|
사후 처리:
|
|
10. RCA(근본원인분석) 작성
|
|
11. POST /incidents/{id}/close (RCA 포함 필수)
|
|
12. 재발 방지 대책 SR 등록
|
|
```
|
|
|
|
### 7.3 장애 타임라인 기록
|
|
|
|
```
|
|
장애 진행 중 모든 주요 활동 기록:
|
|
POST /incidents/{id}/timeline
|
|
{
|
|
"event_type": "INVESTIGATION",
|
|
"description": "DB 서버 CPU 100% 확인, 쿼리 분석 중"
|
|
}
|
|
|
|
event_type 옵션:
|
|
DETECTION — 최초 감지
|
|
INVESTIGATION — 조사 활동
|
|
ACTION — 조치 수행
|
|
UPDATE — 현황 업데이트
|
|
RECOVERY — 복구 완료
|
|
POSTMORTEM — 사후 분석
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 온콜/당직 관리
|
|
|
|
### 8.1 당직 배정
|
|
|
|
```
|
|
단건 배정:
|
|
POST /oncall/duties
|
|
{
|
|
"duty_date": "2026-06-01",
|
|
"shift": "ALL_DAY", // ALL_DAY / DAYTIME / NIGHTTIME
|
|
"user_id": 5,
|
|
"note": "야간 비상 연락"
|
|
}
|
|
|
|
월간 일괄 배정:
|
|
POST /oncall/duties/bulk
|
|
{
|
|
"duties": [
|
|
{"duty_date": "2026-06-01", "shift": "ALL_DAY", "user_id": 5},
|
|
{"duty_date": "2026-06-02", "shift": "ALL_DAY", "user_id": 6}
|
|
],
|
|
"overwrite": false // true: 중복 시 덮어쓰기
|
|
}
|
|
```
|
|
|
|
### 8.2 오늘 당직 확인
|
|
|
|
```
|
|
GET /oncall/today
|
|
→ 오늘 날짜의 당직자 목록 (교대별)
|
|
|
|
응답 예시:
|
|
{
|
|
"date": "2026-06-01",
|
|
"duties": {
|
|
"ALL_DAY": [{"user": "홍길동", "phone": "010-XXXX-XXXX"}],
|
|
"NIGHTTIME": [{"user": "김철수", "phone": "010-XXXX-XXXX"}]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 8.3 월간 당직 조회
|
|
|
|
```
|
|
GET /oncall/calendar?year=2026&month=6
|
|
→ 해당 월 전체 당직 일정
|
|
```
|
|
|
|
---
|
|
|
|
## 9. 배치 작업 관리
|
|
|
|
### 9.1 배치 작업 등록
|
|
|
|
```
|
|
POST /batch/jobs
|
|
{
|
|
"name": "일일 DB 백업",
|
|
"server_id": 1,
|
|
"command": "bash /opt/scripts/backup.sh",
|
|
"cron_expr": "0 2 * * *", // 매일 오전 2시
|
|
"timeout_sec": 3600,
|
|
"alert_on_fail": true,
|
|
"is_active": true
|
|
}
|
|
```
|
|
|
|
> **주의**: 다음 명령어 패턴은 등록 자체가 거부됩니다:
|
|
> `rm -rf /`, `shutdown`, `reboot`, `mkfs`, `dd if=`, Fork Bomb 등
|
|
|
|
### 9.2 배치 작업 모니터링
|
|
|
|
```
|
|
최근 실행 이력:
|
|
GET /batch/jobs/{id}/runs?limit=20
|
|
|
|
실행 상태:
|
|
RUNNING — 실행 중
|
|
SUCCESS — 성공
|
|
FAILED — 실패 (alert_on_fail=true 시 SR 자동 생성)
|
|
TIMEOUT — 타임아웃 초과
|
|
|
|
실패 시 자동 SR: GET /tasks/?sr_type=LOG&priority=HIGH
|
|
```
|
|
|
|
### 9.3 수동 실행
|
|
|
|
```
|
|
POST /batch/jobs/{id}/run
|
|
→ 202 Accepted (백그라운드 실행 시작)
|
|
|
|
실행 결과 확인:
|
|
GET /batch/jobs/{id}/runs?limit=1 (최신 1건)
|
|
```
|
|
|
|
---
|
|
|
|
## 10. 백업 및 복구
|
|
|
|
### 10.1 DB 백업 절차
|
|
|
|
```bash
|
|
# Linux — 수동 백업
|
|
cp /opt/guardia/itsm/guardia_itsm.db /backup/guardia_itsm_$(date +%Y%m%d).db
|
|
cp /opt/guardia/messenger/guardia_messenger.db /backup/guardia_messenger_$(date +%Y%m%d).db
|
|
|
|
# 자동 백업 스크립트 (cron 등록 권장)
|
|
# crontab -e
|
|
0 3 * * * /opt/guardia/scripts/backup.sh >> /var/log/guardia/backup.log 2>&1
|
|
|
|
# Windows — PowerShell
|
|
$date = Get-Date -Format "yyyyMMdd"
|
|
Copy-Item "C:\GUARDiA\itsm\guardia_itsm.db" "D:\Backup\guardia_itsm_$date.db"
|
|
```
|
|
|
|
### 10.2 업로드 파일 백업
|
|
|
|
```bash
|
|
# 업로드 파일 디렉토리 전체 백업
|
|
tar -czf /backup/uploads_$(date +%Y%m%d).tar.gz /opt/guardia/itsm/uploads/
|
|
```
|
|
|
|
### 10.3 복구 절차
|
|
|
|
```bash
|
|
# 1. 서비스 중지
|
|
systemctl stop guardia-itsm
|
|
systemctl stop guardia-messenger
|
|
|
|
# 2. 현재 DB 보존
|
|
mv guardia_itsm.db guardia_itsm.db.broken
|
|
|
|
# 3. 백업 복원
|
|
cp /backup/guardia_itsm_20260525.db guardia_itsm.db
|
|
|
|
# 4. 서비스 재시작
|
|
systemctl start guardia-itsm
|
|
systemctl start guardia-messenger
|
|
|
|
# 5. 서비스 상태 확인
|
|
curl http://localhost:8000/
|
|
```
|
|
|
|
### 10.4 백업 보관 정책
|
|
|
|
```
|
|
일간 백업: 30일 보관
|
|
주간 백업: 12주 보관
|
|
월간 백업: 12개월 보관
|
|
```
|
|
|
|
---
|
|
|
|
## 11. 모니터링 및 알림
|
|
|
|
### 11.1 시스템 모니터링 지점
|
|
|
|
| 모니터링 항목 | 임계값 | 조치 |
|
|
|--------------|--------|------|
|
|
| ITSM 서비스 응답 | 5초 이상 → 경고 | 서비스 재시작 |
|
|
| DB 파일 크기 | 500MB 이상 → 경고 | 정리/이관 검토 |
|
|
| 디스크 사용률 | 80% 이상 → 경고 | 파일 정리 |
|
|
| 업로드 디렉토리 | 10GB 이상 → 경고 | 오래된 파일 정리 |
|
|
| 스케줄러 실행 | 오전 06:30까지 미실행 → 경고 | 재시작 |
|
|
|
|
### 11.2 Messenger 알림 채널
|
|
|
|
```
|
|
장애 알림: #guardia-incidents
|
|
SSL 만료 알림: #guardia-ssl
|
|
PM 일정 알림: #guardia-pm
|
|
배치 실패: #guardia-ops
|
|
```
|
|
|
|
### 11.3 서비스 상태 확인
|
|
|
|
```bash
|
|
# Linux
|
|
systemctl status guardia-itsm
|
|
systemctl status guardia-messenger
|
|
|
|
# 로그 실시간 확인
|
|
journalctl -u guardia-itsm -f
|
|
|
|
# Windows
|
|
Get-Service -Name "GUARDiA-ITSM"
|
|
```
|
|
|
|
---
|
|
|
|
## 12. 보안 운영 지침
|
|
|
|
### 12.1 계정 보안
|
|
|
|
```
|
|
□ 기본 admin 비밀번호 즉시 변경 (초기 설치 후)
|
|
□ 퇴직자 계정 당일 비활성화
|
|
□ 공용 계정 사용 금지 (1인 1계정 원칙)
|
|
□ 분기마다 불필요 계정 감사
|
|
□ CUSTOMER 역할 계정은 자신의 SR만 조회 가능 확인
|
|
```
|
|
|
|
### 12.2 API 접근 제어
|
|
|
|
```
|
|
□ 운영 환경에서 /docs 페이지 비활성화 권장
|
|
main.py: app = FastAPI(docs_url=None, redoc_url=None)
|
|
|
|
□ CORS 설정 확인 (운영 환경)
|
|
allow_origins: 실제 도메인만 허가 (localhost 제거)
|
|
|
|
□ 로그인 실패 횟수 모니터링
|
|
GET /audit/logs?action=LOGIN_FAIL
|
|
```
|
|
|
|
### 12.3 서버 자격증명 관리
|
|
|
|
```
|
|
□ SSH 비밀번호는 AES-256-GCM 암호화 저장 확인
|
|
□ 평문 비밀번호 어디에도 저장 금지
|
|
□ ENCRYPTION_KEY는 .env에만 저장, Git 제외
|
|
□ API 응답에 IP/PW 포함 여부 정기 검사
|
|
□ root SSH 직접 접속 금지 설정 확인
|
|
```
|
|
|
|
### 12.4 감사 로그 관리
|
|
|
|
```
|
|
감사 로그 확인:
|
|
GET /audit/logs?start=2026-05-01&end=2026-05-31
|
|
|
|
무결성 검증:
|
|
GET /audit/verify
|
|
→ "integrity": true 확인
|
|
|
|
의심 활동 모니터링:
|
|
- 새벽 시간대 로그인
|
|
- 다수 SR 한 번에 변경
|
|
- 서버 자격증명 접근
|
|
```
|
|
|
|
---
|
|
|
|
## 13. 장애 대응 절차
|
|
|
|
### 13.1 ITSM 서비스 응답 없음
|
|
|
|
```
|
|
증상: curl http://localhost:8000/ 타임아웃
|
|
|
|
1단계 — 프로세스 확인
|
|
Linux: ps aux | grep uvicorn
|
|
Windows: Get-Process -Name python
|
|
|
|
2단계 — 로그 확인
|
|
Linux: journalctl -u guardia-itsm --since "10 min ago"
|
|
Linux: cat /var/log/guardia/itsm.log | tail -100
|
|
|
|
3단계 — 서비스 재시작
|
|
Linux: systemctl restart guardia-itsm
|
|
Windows: Restart-Service "GUARDiA-ITSM"
|
|
|
|
4단계 — 재시작 후 확인
|
|
curl http://localhost:8000/
|
|
→ 200 응답 확인
|
|
```
|
|
|
|
### 13.2 DB 잠금(Lock) 오류
|
|
|
|
```
|
|
증상: "database is locked" 에러 로그 발생
|
|
|
|
1단계 — 연결 프로세스 확인
|
|
Linux: fuser guardia_itsm.db
|
|
|
|
2단계 — 임시 잠금 파일 삭제 (서비스 중지 후)
|
|
rm guardia_itsm.db-shm guardia_itsm.db-wal
|
|
|
|
3단계 — 서비스 재시작
|
|
systemctl restart guardia-itsm
|
|
```
|
|
|
|
### 13.3 스케줄러 미동작
|
|
|
|
```
|
|
증상: SSL 점검, PM 자동 생성이 실행되지 않음
|
|
|
|
1단계 — 로그 확인
|
|
grep "scheduler" /var/log/guardia/itsm.log
|
|
|
|
2단계 — APScheduler 설치 확인
|
|
pip show apscheduler
|
|
|
|
3단계 — 서비스 재시작
|
|
systemctl restart guardia-itsm
|
|
|
|
4단계 — 수동 실행으로 대체
|
|
ITSM → SSL 관리 → "전체 점검" 버튼
|
|
ITSM → 정기점검 → 수동 작업 생성
|
|
```
|
|
|
|
### 13.4 Messenger 연결 실패
|
|
|
|
```
|
|
증상: ITSM 알림이 Messenger에 미전달
|
|
|
|
1단계 — Messenger 서비스 상태 확인
|
|
systemctl status guardia-messenger
|
|
|
|
2단계 — 연결 설정 확인
|
|
.env 파일의 MESSENGER_BASE_URL, MESSENGER_BOT_TOKEN 확인
|
|
|
|
3단계 — 연결 테스트
|
|
curl http://localhost:8001/api/health
|
|
|
|
4단계 — Messenger 재시작
|
|
systemctl restart guardia-messenger
|
|
|
|
주의: Messenger 알림 실패는 ITSM 기능에 영향 없음 (알림만 안 됨)
|
|
```
|
|
|
|
---
|
|
|
|
## 14. 로그 관리
|
|
|
|
### 14.1 로그 파일 위치
|
|
|
|
```
|
|
Linux:
|
|
/var/log/guardia/itsm.log — ITSM 애플리케이션 로그
|
|
/var/log/guardia/scheduler.log — 스케줄러 실행 로그
|
|
/var/log/guardia/messenger.log — Messenger 로그
|
|
/var/log/guardia/backup.log — 백업 실행 로그
|
|
|
|
Windows:
|
|
C:\GUARDiA\logs\itsm.log
|
|
C:\GUARDiA\logs\scheduler.log
|
|
C:\GUARDiA\logs\messenger.log
|
|
```
|
|
|
|
### 14.2 로그 로테이션 설정 (Linux)
|
|
|
|
```
|
|
# /etc/logrotate.d/guardia
|
|
/var/log/guardia/*.log {
|
|
daily
|
|
missingok
|
|
rotate 30
|
|
compress
|
|
delaycompress
|
|
notifempty
|
|
create 640 guardia guardia
|
|
postrotate
|
|
systemctl reload guardia-itsm
|
|
endscript
|
|
}
|
|
```
|
|
|
|
### 14.3 감사 로그 (DB 내 저장)
|
|
|
|
```
|
|
ITSM 내 모든 주요 활동은 tb_audit_log 테이블에 저장됩니다.
|
|
해시 체인으로 무결성 보호.
|
|
|
|
조회:
|
|
GET /audit/logs?limit=100
|
|
GET /audit/logs?user_id=5&start=2026-05-01
|
|
|
|
무결성 검증:
|
|
GET /audit/verify
|
|
```
|
|
|
|
---
|
|
|
|
## 15. 주요 설정 파일
|
|
|
|
### 15.1 .env 운영 설정
|
|
|
|
```ini
|
|
# 운영 환경 .env
|
|
SECRET_KEY=<64자 이상 랜덤 문자열>
|
|
ALGORITHM=HS256
|
|
ACCESS_TOKEN_EXPIRE_MINUTES=480
|
|
DB_URL=sqlite+aiosqlite:///./guardia_itsm.db
|
|
ENCRYPTION_KEY=<64자리 hex 문자열>
|
|
|
|
MESSENGER_BASE_URL=http://localhost:8001
|
|
MESSENGER_BOT_TOKEN=<봇 토큰>
|
|
|
|
SSH_TIMEOUT=30
|
|
UPLOAD_ROOT=./uploads
|
|
MAX_FILE_SIZE_MB=10
|
|
|
|
# 운영: API 문서 비활성화
|
|
DOCS_DISABLED=true
|
|
```
|
|
|
|
### 15.2 서비스 파일 (Linux systemd)
|
|
|
|
```ini
|
|
# /etc/systemd/system/guardia-itsm.service
|
|
[Unit]
|
|
Description=GUARDiA ITSM Service
|
|
After=network.target
|
|
|
|
[Service]
|
|
User=guardia
|
|
WorkingDirectory=/opt/guardia/itsm
|
|
EnvironmentFile=/opt/guardia/itsm/.env
|
|
ExecStart=/opt/guardia/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --workers 2
|
|
Restart=always
|
|
RestartSec=5
|
|
StandardOutput=append:/var/log/guardia/itsm.log
|
|
StandardError=append:/var/log/guardia/itsm.log
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
### 15.3 방화벽 설정
|
|
|
|
```bash
|
|
# Linux (firewalld)
|
|
firewall-cmd --permanent --add-port=8000/tcp # ITSM
|
|
firewall-cmd --permanent --add-port=8001/tcp # Messenger
|
|
firewall-cmd --reload
|
|
|
|
# Windows (PowerShell)
|
|
New-NetFirewallRule -DisplayName "GUARDiA ITSM" -Direction Inbound -Protocol TCP -LocalPort 8000 -Action Allow
|
|
New-NetFirewallRule -DisplayName "GUARDiA Messenger" -Direction Inbound -Protocol TCP -LocalPort 8001 -Action Allow
|
|
```
|
|
|
|
---
|
|
|
|
## 부록 A: 운영 명령어 빠른 참조
|
|
|
|
```bash
|
|
# 서비스 시작/중지/재시작
|
|
systemctl start|stop|restart guardia-itsm
|
|
systemctl start|stop|restart guardia-messenger
|
|
|
|
# 상태 확인
|
|
systemctl status guardia-itsm
|
|
curl http://localhost:8000/
|
|
|
|
# 로그 확인
|
|
journalctl -u guardia-itsm -f --since "1 hour ago"
|
|
|
|
# DB 백업
|
|
cp guardia_itsm.db guardia_itsm_$(date +%Y%m%d%H%M).db
|
|
|
|
# 업로드 용량 확인
|
|
du -sh uploads/
|
|
|
|
# 활성 연결 확인
|
|
ss -tlnp | grep :8000
|
|
```
|
|
|
|
## 부록 B: 비상 연락망
|
|
|
|
```
|
|
ITSM 운영팀: ...
|
|
보안팀: ...
|
|
인프라팀: ...
|
|
```
|
|
|
|
---
|
|
|
|
---
|
|
|
|
## 16. 라이선스 관리
|
|
|
|
### 16.1 라이선스 등록 절차
|
|
|
|
1. ITSM 관리자 계정으로 로그인
|
|
2. 사이드바 하단 **🔏 라이선스 관리** 클릭 (`/license` 페이지)
|
|
3. **라이선스 키 등록/갱신** 섹션에 `GRD-...` 형식의 키 붙여넣기
|
|
4. **라이선스 등록** 버튼 클릭
|
|
5. 상단 배너에서 에디션·만료일 확인
|
|
|
|
**API로 등록 (자동화)**:
|
|
```bash
|
|
curl -X POST http://localhost:8001/api/license/activate \
|
|
-H "Authorization: Bearer <ADMIN_TOKEN>" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"license_key": "GRD-..."}'
|
|
```
|
|
|
|
### 16.2 라이선스 상태 배너 의미
|
|
|
|
| 배너 색상 | 상태 | 조치 |
|
|
|---------|------|------|
|
|
| ✅ 초록 | 정상 활성 | — |
|
|
| ⚠️ 노랑 | 만료 30일 이내 경고 | 갱신 라이선스 요청 |
|
|
| ❌ 빨강 | 만료됨 | 즉시 갱신 키 적용 필요 |
|
|
| ⬜ 회색 | 라이선스 미등록 | Community 제한 모드로 동작 |
|
|
|
|
### 16.3 에디션별 자원 제한
|
|
|
|
| 에디션 | 기관 수 | 사용자 수 | 서버 수 | 주요 기능 |
|
|
|--------|--------|---------|--------|---------|
|
|
| COMMUNITY | 1 | 10 | 20 | MFA |
|
|
| STANDARD | 50 | 200 | 500 | MFA, LDAP, PAM, AI 에이전트 |
|
|
| ENTERPRISE | 무제한 | 무제한 | 무제한 | 전체 기능 |
|
|
|
|
> **주의**: 한도 초과 시 신규 등록 API가 HTTP 403을 반환한다.
|
|
> 기존 등록 데이터는 만료·초과 후에도 삭제되지 않는다.
|
|
|
|
### 16.4 라이선스 갱신
|
|
|
|
갱신 라이선스 키를 받은 후 16.1과 동일하게 등록하면 기존 라이선스가 자동으로 비활성화되고 새 라이선스로 교체된다.
|
|
|
|
자세한 발급·갱신 절차는 **`manual/14_라이선스_키_발급_가이드.md`** 참조.
|
|
|
|
---
|
|
|
|
## 17. 신규 기능 (v2.0 — 2026-06-02)
|
|
|
|
| 기능 | 위치 | 상세 가이드 |
|
|
|------|------|------------|
|
|
| 📱 모바일 앱 QR 직접 배포 | Manager → 앱 배포 | `44_신규기능_운영가이드.md` §1 |
|
|
| ⚡ 배치 SSH 일괄 실행 | ITSM → 배치 SSH 실행 | `44_신규기능_운영가이드.md` §2 |
|
|
| 🏷️ 자산 QR 태그 관리 | ITSM → 자산 QR 태그 | `44_신규기능_운영가이드.md` §3 |
|
|
| 🔔 스마트 알림 규칙 편집기 | ITSM/Manager → 알림 규칙 | `44_신규기능_운영가이드.md` §4 |
|
|
| 📧 웹메일 주소록·서명 | Webmail → 주소록/서명 탭 | `44_신규기능_운영가이드.md` §5 |
|
|
|
|
### 17.1 빠른 시작 — APK QR 배포
|
|
|
|
```
|
|
1. Manager(https://zioinfo.co.kr:8090) 로그인
|
|
2. 사이드바 → 📱 앱 배포
|
|
3. APK 파일 선택 + 버전 입력 → 🚀 배포 + QR 생성
|
|
4. 생성된 QR 이미지를 사용자에게 공유
|
|
5. 사용자: QR 스캔 → APK 다운로드 → 설치 완료
|
|
```
|
|
|
|
### 17.2 빠른 시작 — 배치 SSH
|
|
|
|
```
|
|
1. ITSM(https://zioinfo.co.kr:8443) 로그인
|
|
2. 사이드바 → ⚡ 배치 SSH 실행
|
|
3. 명령어 + 서버 ID 목록 입력 → 실행
|
|
4. 서버별 결과(성공/실패·stdout) 즉시 확인
|
|
```
|
|
|
|
---
|
|
|
|
*본 운영자 지침서는 GUARDiA ITSM v2.0 기준으로 작성되었습니다.*
|