zioinfo-mail/manual/05_설치가이드_리눅스.md

# GUARDiA ITSM + Messenger — 설치 가이드 (Linux)

**문서 버전**: 1.0  
**작성일**: 2026-05-25  
**지원 OS**: Ubuntu 22.04 LTS, Ubuntu 20.04 LTS, CentOS 8+, RHEL 8+

---

## 목차

1. [설치 전 요구사항 확인](#1-설치-전-요구사항-확인)
2. [시스템 사전 준비](#2-시스템-사전-준비)
3. [Python 환경 설정](#3-python-환경-설정)
4. [GUARDiA ITSM 설치](#4-guardia-itsm-설치)
5. [GUARDiA Messenger 설치](#5-guardia-messenger-설치)
6. [서비스 등록 (systemd)](#6-서비스-등록-systemd)
7. [SSL 점검 스크립트 배포](#7-ssl-점검-스크립트-배포)
8. [방화벽 설정](#8-방화벽-설정)
9. [Nginx 리버스 프록시 설정 (선택)](#9-nginx-리버스-프록시-설정-선택)
10. [설치 검증](#10-설치-검증)
11. [보안 강화 설정](#11-보안-강화-설정)
12. [문제 해결](#12-문제-해결)

---

## 1. 설치 전 요구사항 확인

### 1.1 하드웨어 최소 요구사항

| 항목 | 최소 | 권장 |
|------|------|------|
| CPU | 2코어 | 4코어 이상 |
| RAM | 2GB | 4GB 이상 |
| 디스크 | 20GB | 50GB 이상 |
| 네트워크 | 100Mbps | 1Gbps |

### 1.2 소프트웨어 요구사항

```
OS: Ubuntu 22.04 LTS (권장)
Python: 3.11 이상
openssl: 1.1.1 이상 (SSL 점검에 필요)
sqlite3: 3.35 이상
```

### 1.3 요구사항 사전 확인

```bash
# OS 버전 확인
lsb_release -a
uname -r

# Python 버전 확인
python3 --version
# → Python 3.11.x 이상이어야 함

# openssl 버전 확인
openssl version
# → OpenSSL 1.1.1 이상

# SQLite 버전 확인
sqlite3 --version
# → 3.35.0 이상

# 디스크 여유 공간 확인
df -h /
# → Available 20GB 이상 확인

# 포트 사용 여부 확인 (8000, 8001이 비어 있어야 함)
ss -tlnp | grep -E ':8000|:8001'
# → 아무것도 출력되지 않아야 함
```

---

## 2. 시스템 사전 준비

### 2.1 시스템 업데이트 (Ubuntu)

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl wget vim unzip
```

### 2.2 시스템 업데이트 (CentOS/RHEL)

```bash
sudo dnf update -y
sudo dnf install -y git curl wget vim unzip
```

### 2.3 전용 사용자 생성

보안을 위해 root가 아닌 전용 사용자로 실행합니다.

```bash
# guardia 사용자 생성 (로그인 불가 설정)
sudo useradd -r -m -d /opt/guardia -s /bin/bash guardia
sudo passwd guardia   # 비밀번호 설정 (관리자만 알아야 함)

# 사용자 확인
id guardia
# → uid=998(guardia) gid=998(guardia) groups=998(guardia)
```

### 2.4 디렉토리 구조 생성

```bash
sudo mkdir -p /opt/guardia/{itsm,messenger}
sudo mkdir -p /opt/guardia/scripts/ssl
sudo mkdir -p /var/log/guardia
sudo mkdir -p /backup/guardia

sudo chown -R guardia:guardia /opt/guardia
sudo chown -R guardia:guardia /var/log/guardia
sudo chown -R guardia:guardia /backup/guardia

# 확인
ls -la /opt/guardia/
```

---

## 3. Python 환경 설정

### 3.1 Python 3.11 설치 (Ubuntu 22.04)

Ubuntu 22.04는 기본적으로 Python 3.10이 설치됩니다. 3.11을 설치합니다.

```bash
# deadsnakes PPA 추가
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update

# Python 3.11 설치
sudo apt install -y python3.11 python3.11-venv python3.11-dev

# 버전 확인
python3.11 --version
# → Python 3.11.x
```

### 3.2 Python 3.11 설치 (CentOS/RHEL 8)

```bash
# EPEL 및 개발 도구 설치
sudo dnf install -y epel-release
sudo dnf install -y python3.11 python3.11-pip

python3.11 --version
```

### 3.3 pip 업그레이드

```bash
python3.11 -m pip install --upgrade pip
```

---

## 4. GUARDiA ITSM 설치

### 4.1 소스 코드 배포

```bash
# guardia 사용자로 전환
sudo -u guardia bash

# 소스 코드 복사 (파일 서버에서 복사 또는 git clone)
# 방법 1: scp로 복사
# scp -r itsm/ guardia@서버IP:/opt/guardia/itsm/

# 방법 2: git clone (내부 Git 서버)
cd /opt/guardia
git clone http://내부git서버/guardia/itsm.git itsm

# 방법 3: 직접 파일 복사 (zip 사용)
# unzip guardia_itsm_v1.0.zip -d /opt/guardia/itsm/

# 설치 확인
ls /opt/guardia/itsm/
# → main.py database.py models.py schemas.py routers/ core/ utils/ static/ 등
```

### 4.2 가상환경 생성 및 의존성 설치

```bash
# /opt/guardia/itsm 디렉토리에서
cd /opt/guardia/itsm

# 가상환경 생성 (공유 위치)
python3.11 -m venv /opt/guardia/.venv

# 가상환경 활성화
source /opt/guardia/.venv/bin/activate

# pip 업그레이드
pip install --upgrade pip

# 의존성 설치
pip install -r requirements.txt

# 설치 확인
pip list | grep -E "fastapi|uvicorn|sqlalchemy|apscheduler"
# → 패키지 목록 출력 확인

# 가상환경 비활성화
deactivate
```

**requirements.txt 주요 패키지**:
```
fastapi>=0.110
uvicorn[standard]>=0.29
sqlalchemy>=2.0
aiosqlite>=0.20
python-jose[cryptography]>=3.3
passlib[bcrypt]>=1.7
python-multipart>=0.0.9
apscheduler>=3.10
asyncssh>=2.14
openpyxl>=3.1
httpx>=0.27
cryptography>=42.0
croniter>=2.0
```

### 4.3 환경 변수 설정

```bash
# .env 파일 생성
cat > /opt/guardia/itsm/.env << 'EOF'
SECRET_KEY=여기에_64자이상의_랜덤문자열_입력_반드시_변경하세요
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=480
DB_URL=sqlite+aiosqlite:////opt/guardia/itsm/guardia_itsm.db
ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
# 라이선스 마스터 키 (64자리 hex = 32바이트)
# 생성: python3 -c "import secrets; print(secrets.token_hex(32))"
# ⚠️ 분실 시 기발급 라이선스 전부 무효화 — 안전하게 별도 보관 필수
GUARDIA_LICENSE_KEY=0000000000000000000000000000000000000000000000000000000000000000
MESSENGER_BASE_URL=http://localhost:8001
MESSENGER_BOT_TOKEN=변경하세요
SSH_TIMEOUT=30
UPLOAD_ROOT=/opt/guardia/itsm/uploads
MAX_FILE_SIZE_MB=10
EOF

# 권한 설정 (소유자만 읽기/쓰기)
chmod 600 /opt/guardia/itsm/.env
chown guardia:guardia /opt/guardia/itsm/.env
```

> **중요**: `SECRET_KEY`, `ENCRYPTION_KEY`, `GUARDIA_LICENSE_KEY`는 반드시 강력한 랜덤 값으로 변경하세요!

**랜덤 키 생성 방법**:
```bash
# SECRET_KEY 생성 (64자)
python3 -c "import secrets; print(secrets.token_hex(32))"

# ENCRYPTION_KEY 생성 (64자 hex = AES-256)
python3 -c "import secrets; print(secrets.token_hex(32))"
```

### 4.4 업로드 디렉토리 생성

```bash
mkdir -p /opt/guardia/itsm/uploads/sr_files
mkdir -p /opt/guardia/itsm/uploads/workspaces
chown -R guardia:guardia /opt/guardia/itsm/uploads/
```

### 4.5 초기 실행 및 DB 초기화

```bash
cd /opt/guardia/itsm
source /opt/guardia/.venv/bin/activate

# 테스트 실행 (초기 DB 생성 및 시드 데이터 삽입)
python -m uvicorn main:app --host 127.0.0.1 --port 8000 &
sleep 5

# 정상 동작 확인
curl http://127.0.0.1:8000/
# → {"detail":"Not Found"} 또는 HTML 응답이면 정상

# 로그인 테스트
curl -X POST http://127.0.0.1:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin1234!"}'
# → {"access_token":"...","token_type":"bearer"} 출력 확인

# 프로세스 종료 (systemd 서비스로 실행 예정)
kill %1
deactivate
```

---

## 5. GUARDiA Messenger 설치

### 5.1 소스 코드 배포

```bash
sudo -u guardia bash
cd /opt/guardia
git clone http://내부git서버/guardia/messenger.git messenger
# 또는 파일 복사
```

### 5.2 의존성 설치

```bash
cd /opt/guardia/messenger
source /opt/guardia/.venv/bin/activate
pip install -r requirements.txt
deactivate
```

### 5.3 환경 변수 설정

```bash
cat > /opt/guardia/messenger/.env << 'EOF'
SECRET_KEY=ITSM과_동일한_키_또는_별도_키
ALGORITHM=HS256
DB_URL=sqlite+aiosqlite:////opt/guardia/messenger/guardia_messenger.db
ITSM_BASE_URL=http://localhost:8000
PORT=8001
EOF

chmod 600 /opt/guardia/messenger/.env
chown guardia:guardia /opt/guardia/messenger/.env
```

---

## 6. 서비스 등록 (systemd)

### 6.1 ITSM 서비스 파일 생성

```bash
sudo tee /etc/systemd/system/guardia-itsm.service > /dev/null << 'EOF'
[Unit]
Description=GUARDiA ITSM Service
Documentation=https://내부문서URL
After=network.target network-online.target
Wants=network-online.target

[Service]
Type=simple
User=guardia
Group=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 \
    --log-level info
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=5
StartLimitInterval=60
StartLimitBurst=3

# 보안 강화
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/opt/guardia/itsm/uploads /var/log/guardia

StandardOutput=append:/var/log/guardia/itsm.log
StandardError=append:/var/log/guardia/itsm.log

[Install]
WantedBy=multi-user.target
EOF
```

### 6.2 Messenger 서비스 파일 생성

```bash
sudo tee /etc/systemd/system/guardia-messenger.service > /dev/null << 'EOF'
[Unit]
Description=GUARDiA Messenger Service
After=network.target guardia-itsm.service

[Service]
Type=simple
User=guardia
Group=guardia
WorkingDirectory=/opt/guardia/messenger
EnvironmentFile=/opt/guardia/messenger/.env
ExecStart=/opt/guardia/.venv/bin/uvicorn main:app \
    --host 0.0.0.0 \
    --port 8001 \
    --workers 1 \
    --log-level info
Restart=always
RestartSec=5

NoNewPrivileges=true
PrivateTmp=true

StandardOutput=append:/var/log/guardia/messenger.log
StandardError=append:/var/log/guardia/messenger.log

[Install]
WantedBy=multi-user.target
EOF
```

### 6.3 서비스 등록 및 시작

```bash
# systemd 재로드
sudo systemctl daemon-reload

# 서비스 활성화 (부팅 시 자동 시작)
sudo systemctl enable guardia-itsm
sudo systemctl enable guardia-messenger

# 서비스 시작
sudo systemctl start guardia-itsm
sudo systemctl start guardia-messenger

# 상태 확인
sudo systemctl status guardia-itsm
sudo systemctl status guardia-messenger

# 기대 출력:
# ● guardia-itsm.service - GUARDiA ITSM Service
#    Active: active (running) since ...
```

### 6.4 로그 확인

```bash
# 실시간 로그 확인
sudo journalctl -u guardia-itsm -f

# 최근 50줄
sudo journalctl -u guardia-itsm -n 50

# 파일 직접 확인
tail -f /var/log/guardia/itsm.log
```

---

## 7. SSL 점검 스크립트 배포

GUARDiA ITSM이 관리하는 모든 서버에 SSL 점검 스크립트를 배포합니다.

```bash
# ITSM 서버에서 관리 대상 서버로 스크립트 복사
# (ITSM 서버에서 실행)

TARGET_SERVERS=("192.168.1.10" "192.168.1.11" "192.168.1.12")

for SERVER in "${TARGET_SERVERS[@]}"; do
    echo "배포 중: $SERVER"
    ssh guardia@${SERVER} "mkdir -p /opt/guardia/scripts/ssl"
    scp /opt/guardia/itsm/scripts/sm/ssl/ssl_expiry_check.sh \
        guardia@${SERVER}:/opt/guardia/scripts/ssl/
    ssh guardia@${SERVER} "chmod +x /opt/guardia/scripts/ssl/ssl_expiry_check.sh"
    
    # 동작 테스트
    ssh guardia@${SERVER} "bash /opt/guardia/scripts/ssl/ssl_expiry_check.sh google.com"
    echo "배포 완료: $SERVER"
done
```

---

## 8. 방화벽 설정

### 8.1 UFW (Ubuntu)

```bash
# UFW 활성화 (이미 활성화된 경우 skip)
sudo ufw enable

# GUARDiA 포트 허용
sudo ufw allow 8000/tcp comment "GUARDiA ITSM"
sudo ufw allow 8001/tcp comment "GUARDiA Messenger"

# SSH 허용 (원격 접속용, 이미 설정된 경우 skip)
sudo ufw allow 22/tcp

# 상태 확인
sudo ufw status verbose
```

### 8.2 firewalld (CentOS/RHEL)

```bash
# GUARDiA 포트 허용
sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --permanent --add-port=8001/tcp
sudo firewall-cmd --reload

# 확인
sudo firewall-cmd --list-ports
```

### 8.3 특정 IP만 허용 (보안 강화)

```bash
# 내부 네트워크(192.168.1.0/24)에서만 접근 허용
sudo ufw allow from 192.168.1.0/24 to any port 8000
sudo ufw allow from 192.168.1.0/24 to any port 8001
sudo ufw deny 8000
sudo ufw deny 8001
```

---

## 9. Nginx 리버스 프록시 설정 (선택)

HTTPS를 적용하거나 표준 포트(80/443)를 사용하려면 Nginx를 앞단에 배치합니다.

### 9.1 Nginx 설치

```bash
# Ubuntu
sudo apt install -y nginx

# CentOS/RHEL
sudo dnf install -y nginx
```

### 9.2 Nginx 설정

```bash
sudo tee /etc/nginx/conf.d/guardia.conf > /dev/null << 'EOF'
# HTTP → HTTPS 리다이렉트
server {
    listen 80;
    server_name itsm.example.com;
    return 301 https://$host$request_uri;
}

# ITSM HTTPS
server {
    listen 443 ssl http2;
    server_name itsm.example.com;

    ssl_certificate     /etc/ssl/certs/itsm.example.com.crt;
    ssl_certificate_key /etc/ssl/private/itsm.example.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # 업로드 용량 제한
    client_max_body_size 20M;

    # ITSM API/UI
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300;
        proxy_connect_timeout 10;
    }
}

# Messenger HTTPS
server {
    listen 443 ssl http2;
    server_name messenger.example.com;

    ssl_certificate     /etc/ssl/certs/messenger.example.com.crt;
    ssl_certificate_key /etc/ssl/private/messenger.example.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";  # WebSocket 지원
    }
}
EOF

# 설정 검증
sudo nginx -t
# → configuration file /etc/nginx/nginx.conf syntax is ok

# Nginx 재시작
sudo systemctl restart nginx
sudo systemctl enable nginx
```

---

## 10. 설치 검증

### 10.1 서비스 상태 확인

```bash
# 서비스 실행 상태
sudo systemctl is-active guardia-itsm guardia-messenger
# → active
# → active

# 포트 리스닝 확인
ss -tlnp | grep -E ':8000|:8001'
# → 8000, 8001 포트 출력 확인
```

### 10.2 API 기능 테스트

```bash
# 1. 홈페이지 응답 확인
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/
# → 200

# 2. 로그인 테스트
curl -s -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin1234!"}' | python3 -m json.tool
# → {"access_token": "eyJ...", "token_type": "bearer"} 출력 확인

# 3. 토큰으로 API 호출
TOKEN=$(curl -s -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin1234!"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

curl -s http://localhost:8000/dashboard/summary \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
# → 대시보드 통계 JSON 출력 확인

# 4. Messenger 확인
curl -s http://localhost:8001/
# → 200 응답 확인
```

### 10.3 스케줄러 동작 확인

```bash
# 로그에서 스케줄러 시작 메시지 확인
grep -i "scheduler" /var/log/guardia/itsm.log | tail -5
# → "scheduler started" 또는 "APScheduler started" 메시지 확인
```

### 10.4 설치 검증 스크립트

```bash
cat > /tmp/verify_install.sh << 'EOF'
#!/bin/bash
echo "=== GUARDiA 설치 검증 ==="

check() {
    if $1; then echo "  [ok] $2"; else echo "  [FAIL] $2"; fi
}

# 서비스 상태
systemctl is-active --quiet guardia-itsm
check "[ $? -eq 0 ]" "ITSM 서비스 실행 중"

systemctl is-active --quiet guardia-messenger
check "[ $? -eq 0 ]" "Messenger 서비스 실행 중"

# 포트 확인
ss -tlnp | grep -q ':8000'
check "[ $? -eq 0 ]" "ITSM 포트 8000 리스닝"

ss -tlnp | grep -q ':8001'
check "[ $? -eq 0 ]" "Messenger 포트 8001 리스닝"

# API 응답
CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/)
check "[ '$CODE' = '200' ]" "ITSM API 응답 (200)"

# DB 파일
[ -f /opt/guardia/itsm/guardia_itsm.db ]
check "[ $? -eq 0 ]" "ITSM DB 파일 존재"

echo "=== 검증 완료 ==="
EOF

chmod +x /tmp/verify_install.sh
bash /tmp/verify_install.sh
```

---

## 11. 보안 강화 설정

### 11.1 초기 관리자 비밀번호 변경

```bash
# 로그인 후 즉시 비밀번호 변경
TOKEN=$(curl -s -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin1234!"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

curl -X POST http://localhost:8000/auth/change-password \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"current_password":"admin1234!","new_password":"새로운강력한비밀번호!@#"}'
```

### 11.2 API 문서 비활성화 (운영)

```python
# main.py 수정
app = FastAPI(
    title="GUARDiA ITSM",
    version="1.0.0",
    lifespan=lifespan,
    docs_url=None,    # /docs 비활성화
    redoc_url=None,   # /redoc 비활성화
)
```

### 11.3 DB 파일 권한 설정

```bash
# DB 파일은 guardia 사용자만 접근 가능
chmod 600 /opt/guardia/itsm/guardia_itsm.db
chmod 600 /opt/guardia/messenger/guardia_messenger.db
```

### 11.4 자동 백업 설정

```bash
# 백업 스크립트 생성
cat > /opt/guardia/scripts/backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR=/backup/guardia
DATE=$(date +%Y%m%d_%H%M)
mkdir -p $BACKUP_DIR

cp /opt/guardia/itsm/guardia_itsm.db $BACKUP_DIR/itsm_$DATE.db
cp /opt/guardia/messenger/guardia_messenger.db $BACKUP_DIR/messenger_$DATE.db

# 30일 이전 백업 삭제
find $BACKUP_DIR -name "*.db" -mtime +30 -delete

echo "[$DATE] 백업 완료" >> /var/log/guardia/backup.log
EOF

chmod +x /opt/guardia/scripts/backup.sh

# cron 등록 (매일 오전 3시)
echo "0 3 * * * guardia /opt/guardia/scripts/backup.sh" | sudo tee -a /etc/cron.d/guardia
```

---

## 12. 문제 해결

### 12.1 서비스 시작 실패

```bash
# 상세 에러 확인
sudo journalctl -u guardia-itsm -n 50 --no-pager

# 가상환경 경로 확인
ls -la /opt/guardia/.venv/bin/uvicorn
# → 파일이 없으면: source /opt/guardia/.venv/bin/activate && pip install uvicorn

# .env 파일 권한 확인
ls -la /opt/guardia/itsm/.env
# → -rw------- 1 guardia guardia 이어야 함
```

### 12.2 포트 충돌

```bash
# 포트를 사용 중인 프로세스 확인
sudo lsof -i :8000
sudo lsof -i :8001

# 해당 프로세스 종료 후 재시작
sudo kill -9 <PID>
sudo systemctl start guardia-itsm
```

### 12.3 Python 패키지 설치 오류

```bash
# 개발 헤더 설치 (컴파일이 필요한 패키지)
# Ubuntu
sudo apt install -y python3.11-dev libssl-dev libffi-dev build-essential

# CentOS/RHEL
sudo dnf install -y python3.11-devel openssl-devel libffi-devel gcc

# 재설치
source /opt/guardia/.venv/bin/activate
pip install --upgrade pip
pip install -r /opt/guardia/itsm/requirements.txt
```

### 12.4 DB 권한 오류

```bash
# DB 파일 소유자 및 권한 확인
ls -la /opt/guardia/itsm/guardia_itsm.db

# 수정
sudo chown guardia:guardia /opt/guardia/itsm/guardia_itsm.db
sudo chmod 660 /opt/guardia/itsm/guardia_itsm.db
```

### 12.5 첫 로그인 실패 (seed 데이터 미생성)

```bash
# 수동으로 DB 초기화
sudo -u guardia bash -c "
  source /opt/guardia/.venv/bin/activate
  cd /opt/guardia/itsm
  python -c \"
import asyncio
from database import init_db, SessionLocal
from core.seed import seed_all

async def main():
    await init_db()
    async with SessionLocal() as db:
        await seed_all(db)
    print('DB 초기화 완료')

asyncio.run(main())
\"
"
```

---

*설치 중 문제가 발생하면 `/var/log/guardia/itsm.log`를 확인하거나 개발팀에 문의하세요.*