guardia-docs/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. 설치 전 요구사항 확인
2. 시스템 사전 준비
3. Python 환경 설정
4. GUARDiA ITSM 설치
5. GUARDiA Messenger 설치
6. 서비스 등록 (systemd)
7. SSL 점검 스크립트 배포
8. 방화벽 설정
9. Nginx 리버스 프록시 설정 (선택)
10. 설치 검증
11. 보안 강화 설정
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 요구사항 사전 확인

# 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)

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

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

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

2.3 전용 사용자 생성

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

# 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 디렉토리 구조 생성

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을 설치합니다.

# 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)

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

python3.11 --version

3.3 pip 업그레이드

python3.11 -m pip install --upgrade pip

---

4. GUARDiA ITSM 설치

4.1 소스 코드 배포

# 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 가상환경 생성 및 의존성 설치

# /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 환경 변수 설정

# .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는 반드시 강력한 랜덤 값으로 변경하세요!

랜덤 키 생성 방법:

# 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 업로드 디렉토리 생성

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 초기화

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 소스 코드 배포

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

5.2 의존성 설치

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

5.3 환경 변수 설정

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 서비스 파일 생성

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 서비스 파일 생성

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 서비스 등록 및 시작

# 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 로그 확인

# 실시간 로그 확인
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 점검 스크립트를 배포합니다.

# 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)

# 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)

# 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만 허용 (보안 강화)

# 내부 네트워크(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 설치

# Ubuntu
sudo apt install -y nginx

# CentOS/RHEL
sudo dnf install -y nginx

9.2 Nginx 설정

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 서비스 상태 확인

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

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

10.2 API 기능 테스트

# 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 스케줄러 동작 확인

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

10.4 설치 검증 스크립트

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 초기 관리자 비밀번호 변경

# 로그인 후 즉시 비밀번호 변경
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 문서 비활성화 (운영)

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

11.3 DB 파일 권한 설정

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

11.4 자동 백업 설정

# 백업 스크립트 생성
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 서비스 시작 실패

# 상세 에러 확인
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 포트 충돌

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

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

12.3 Python 패키지 설치 오류

# 개발 헤더 설치 (컴파일이 필요한 패키지)
# 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 권한 오류

# 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 데이터 미생성)

# 수동으로 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를 확인하거나 개발팀에 문의하세요.