zioinfo-mail/workspace/guardia-docs/06_설치가이드_윈도우서버.md

GUARDiA ITSM + Messenger — 설치 가이드 (Windows Server)

문서 버전: 1.0
작성일: 2026-05-25
지원 OS: Windows Server 2019, Windows Server 2022

---

목차

1. 설치 전 요구사항 확인
2. 사전 소프트웨어 설치
3. GUARDiA ITSM 설치
4. GUARDiA Messenger 설치
5. Windows 서비스 등록 (NSSM)
6. 방화벽 설정
7. IIS 리버스 프록시 설정 (선택)
8. 설치 검증
9. 보안 강화 설정
10. 자동 백업 설정
11. 문제 해결

---

1. 설치 전 요구사항 확인

1.1 하드웨어 최소 요구사항

항목	최소	권장
CPU	2코어	4코어 이상
RAM	4GB	8GB 이상
디스크	30GB	60GB 이상
네트워크	100Mbps	1Gbps

1.2 소프트웨어 요구사항

OS: Windows Server 2022 (권장) 또는 Windows Server 2019
Python: 3.11 이상
OpenSSL: Win64 OpenSSL v3.x (SSL 점검 기능 사용 시)
NSSM: 서비스 등록 도구 (선택, Windows Service로 등록 시 필요)

1.3 설치 전 확인 (PowerShell)

PowerShell을 관리자 권한으로 실행하여 확인합니다.

# OS 버전 확인
[System.Environment]::OSVersion.Version
Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion

# PowerShell 버전 확인
$PSVersionTable.PSVersion
# → Major 5 이상

# 디스크 여유 공간 확인
Get-PSDrive C | Select-Object Used, Free
# → Free 30GB 이상 확인

# 포트 사용 여부 확인
netstat -an | findstr ":8000"
netstat -an | findstr ":8001"
# → 아무것도 출력되지 않아야 함

---

2. 사전 소프트웨어 설치

2.1 Python 3.11 설치

1. 웹브라우저에서 python.org/downloads 접속
2. Python 3.11.x (Windows installer 64-bit) 다운로드
3. 설치 시 반드시 체크: "Add Python to PATH"

# 설치 후 확인
python --version
# → Python 3.11.x

python -m pip --version
# → pip 24.x from ...

설치 후 PowerShell을 새로 열어야 PATH가 반영됩니다.

2.2 Git 설치 (선택)

내부 Git 서버에서 코드를 받는 경우 필요합니다.

1. git-scm.com/download/win 에서 설치 파일 다운로드
2. 기본 설정으로 설치
3. 확인: git --version

2.3 OpenSSL 설치 (SSL 점검 기능 사용 시)

1. 웹에서 "Win64 OpenSSL" 검색 → slproweb.com 또는 공식 배포처에서 다운로드
   (Win64 OpenSSL v3.x.x Light 권장)
2. 기본 경로 C:\Program Files\OpenSSL-Win64 에 설치
3. 시스템 환경변수 PATH에 추가: C:\Program Files\OpenSSL-Win64\bin

# 설치 확인
openssl version
# → OpenSSL 3.x.x

2.4 NSSM 설치 (서비스 등록용)

NSSM은 Python 앱을 Windows Service로 등록하는 도구입니다.

1. nssm.cc/download 에서 최신 버전 다운로드
2. 압축 해제 후 nssm.exe (win64 폴더)를 C:\Windows\System32\ 에 복사

# 확인
nssm version

---

3. GUARDiA ITSM 설치

3.1 설치 디렉토리 생성

PowerShell을 관리자 권한으로 실행합니다.

# 디렉토리 생성
New-Item -ItemType Directory -Force -Path "C:\GUARDiA\itsm"
New-Item -ItemType Directory -Force -Path "C:\GUARDiA\messenger"
New-Item -ItemType Directory -Force -Path "C:\GUARDiA\logs"
New-Item -ItemType Directory -Force -Path "C:\GUARDiA\backup"
New-Item -ItemType Directory -Force -Path "C:\GUARDiA\scripts\ssl"
New-Item -ItemType Directory -Force -Path "C:\GUARDiA\itsm\uploads\sr_files"
New-Item -ItemType Directory -Force -Path "C:\GUARDiA\itsm\uploads\workspaces"

Write-Host "디렉토리 생성 완료"

3.2 소스 코드 배포

# 방법 1: 파일 복사 (zip 파일로 배포 시)
Expand-Archive -Path "C:\temp\guardia_itsm_v1.0.zip" -DestinationPath "C:\GUARDiA\itsm" -Force

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

# 배포 확인
Get-ChildItem C:\GUARDiA\itsm\
# → main.py database.py models.py schemas.py 등 표시

3.3 가상환경 생성 및 의존성 설치

# C:\GUARDiA\itsm 으로 이동
cd C:\GUARDiA\itsm

# 가상환경 생성
python -m venv C:\GUARDiA\.venv

# 가상환경 활성화
C:\GUARDiA\.venv\Scripts\Activate.ps1

# 활성화 오류 시 실행 정책 변경
# Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

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

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

# 설치 확인
pip show fastapi uvicorn sqlalchemy apscheduler
# → Name, Version 정보 출력 확인

# 가상환경 비활성화
deactivate

설치 중 오류 발생 시:

# Visual C++ 빌드 도구가 필요한 패키지 오류 시
# Microsoft C++ Build Tools 설치 필요
# visualstudio.microsoft.com/visual-cpp-build-tools/ 에서 다운로드 후 설치

3.4 환경 변수 파일 (.env) 생성

메모장 또는 VS Code로 C:\GUARDiA\itsm\.env 파일을 생성합니다.

# PowerShell로 .env 파일 생성
$envContent = @"
SECRET_KEY=여기에_64자이상의_랜덤문자열_반드시_변경하세요
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=480
DB_URL=sqlite+aiosqlite:///C:/GUARDiA/itsm/guardia_itsm.db
ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
# 라이선스 마스터 키 (64자리 hex = 32바이트)
# 생성: python -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=C:/GUARDiA/itsm/uploads
MAX_FILE_SIZE_MB=10
"@
$envContent | Out-File -FilePath "C:\GUARDiA\itsm\.env" -Encoding utf8
Write-Host ".env 파일 생성 완료"

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

# GUARDIA_LICENSE_KEY 생성
python -c "import secrets; print(secrets.token_hex(32))"
# → 출력된 64자리 hex를 GUARDIA_LICENSE_KEY에 복사

# 랜덤 키 생성
python -c "import secrets; print(secrets.token_hex(32))"
# → 출력된 값을 SECRET_KEY에 복사

python -c "import secrets; print(secrets.token_hex(32))"
# → 출력된 값을 ENCRYPTION_KEY에 복사

3.5 초기 실행 및 DB 초기화 테스트

# 가상환경 활성화
C:\GUARDiA\.venv\Scripts\Activate.ps1

# 디렉토리 이동
cd C:\GUARDiA\itsm

# 임시 실행 (초기 DB 생성 확인)
$process = Start-Process -FilePath "C:\GUARDiA\.venv\Scripts\uvicorn.exe" `
    -ArgumentList "main:app --host 127.0.0.1 --port 8000" `
    -PassThru -NoNewWindow

Start-Sleep -Seconds 8

# 정상 동작 확인
$response = Invoke-WebRequest -Uri "http://127.0.0.1:8000/" -ErrorAction SilentlyContinue
Write-Host "HTTP 응답 코드: $($response.StatusCode)"
# → 200이면 정상

# 로그인 테스트
$body = '{"username":"admin","password":"admin1234!"}'
$result = Invoke-RestMethod -Uri "http://127.0.0.1:8000/auth/login" `
    -Method Post -Body $body -ContentType "application/json"
Write-Host "토큰: $($result.access_token.Substring(0,20))..."
# → 토큰 앞부분 출력 확인

# 프로세스 종료
Stop-Process -Id $process.Id

deactivate

---

4. GUARDiA Messenger 설치

4.1 소스 코드 배포

# 파일 복사
Expand-Archive -Path "C:\temp\guardia_messenger_v1.0.zip" `
    -DestinationPath "C:\GUARDiA\messenger" -Force

# 또는 git clone
cd C:\GUARDiA
git clone http://내부git서버/guardia/messenger.git messenger

4.2 의존성 설치

C:\GUARDiA\.venv\Scripts\Activate.ps1
cd C:\GUARDiA\messenger
pip install -r requirements.txt
deactivate

4.3 환경 변수 설정

$envContent = @"
SECRET_KEY=ITSM과_동일한_키_또는_별도_키
ALGORITHM=HS256
DB_URL=sqlite+aiosqlite:///C:/GUARDiA/messenger/guardia_messenger.db
ITSM_BASE_URL=http://localhost:8000
PORT=8001
"@
$envContent | Out-File -FilePath "C:\GUARDiA\messenger\.env" -Encoding utf8

---

5. Windows 서비스 등록 (NSSM)

NSSM을 사용하여 GUARDiA를 Windows Service로 등록합니다.

5.1 ITSM 서비스 등록

PowerShell을 관리자 권한으로 실행합니다.

# ITSM 서비스 등록
nssm install GUARDiA-ITSM C:\GUARDiA\.venv\Scripts\uvicorn.exe

# 서비스 파라미터 설정
nssm set GUARDiA-ITSM Application C:\GUARDiA\.venv\Scripts\uvicorn.exe
nssm set GUARDiA-ITSM AppParameters "main:app --host 0.0.0.0 --port 8000 --workers 2"
nssm set GUARDiA-ITSM AppDirectory "C:\GUARDiA\itsm"

# 로그 설정
nssm set GUARDiA-ITSM AppStdout "C:\GUARDiA\logs\itsm.log"
nssm set GUARDiA-ITSM AppStderr "C:\GUARDiA\logs\itsm_error.log"
nssm set GUARDiA-ITSM AppRotateFiles 1
nssm set GUARDiA-ITSM AppRotateBytes 10485760

# 서비스 설명
nssm set GUARDiA-ITSM Description "GUARDiA ITSM IT Service Management"
nssm set GUARDiA-ITSM DisplayName "GUARDiA ITSM"

# 환경 변수 설정 (경로 구분은 \t 탭 문자 사용)
nssm set GUARDiA-ITSM AppEnvironmentExtra "PYTHONDONTWRITEBYTECODE=1"

# 자동 시작 설정
nssm set GUARDiA-ITSM Start SERVICE_AUTO_START

5.2 Messenger 서비스 등록

nssm install GUARDiA-Messenger C:\GUARDiA\.venv\Scripts\uvicorn.exe

nssm set GUARDiA-Messenger Application C:\GUARDiA\.venv\Scripts\uvicorn.exe
nssm set GUARDiA-Messenger AppParameters "main:app --host 0.0.0.0 --port 8001 --workers 1"
nssm set GUARDiA-Messenger AppDirectory "C:\GUARDiA\messenger"
nssm set GUARDiA-Messenger AppStdout "C:\GUARDiA\logs\messenger.log"
nssm set GUARDiA-Messenger AppStderr "C:\GUARDiA\logs\messenger_error.log"
nssm set GUARDiA-Messenger AppRotateFiles 1
nssm set GUARDiA-Messenger Description "GUARDiA Messenger Service"
nssm set GUARDiA-Messenger Start SERVICE_AUTO_START

5.3 서비스 시작

# 서비스 시작
Start-Service GUARDiA-ITSM
Start-Service GUARDiA-Messenger

# 상태 확인
Get-Service GUARDiA-ITSM, GUARDiA-Messenger

# 기대 출력:
# Status   Name               DisplayName
# ------   ----               -----------
# Running  GUARDiA-ITSM       GUARDiA ITSM
# Running  GUARDiA-Messenger  GUARDiA Messenger

5.4 서비스 관리 명령어

# 시작
Start-Service GUARDiA-ITSM

# 중지
Stop-Service GUARDiA-ITSM

# 재시작
Restart-Service GUARDiA-ITSM

# 상태 확인
Get-Service GUARDiA-ITSM | Select-Object Name, Status, StartType

# 로그 확인 (최근 50줄)
Get-Content "C:\GUARDiA\logs\itsm.log" -Tail 50

# 실시간 로그 확인
Get-Content "C:\GUARDiA\logs\itsm.log" -Wait -Tail 20

5.5 서비스 제거 (재설치 시)

# 서비스 제거
nssm remove GUARDiA-ITSM confirm
nssm remove GUARDiA-Messenger confirm

---

6. 방화벽 설정

6.1 Windows Defender 방화벽 규칙 추가

# ITSM 포트 허용
New-NetFirewallRule `
    -DisplayName "GUARDiA ITSM" `
    -Direction Inbound `
    -Protocol TCP `
    -LocalPort 8000 `
    -Action Allow `
    -Profile Domain, Private

# Messenger 포트 허용
New-NetFirewallRule `
    -DisplayName "GUARDiA Messenger" `
    -Direction Inbound `
    -Protocol TCP `
    -LocalPort 8001 `
    -Action Allow `
    -Profile Domain, Private

# 규칙 확인
Get-NetFirewallRule -DisplayName "GUARDiA*" | Select-Object DisplayName, Enabled, Action

6.2 특정 IP 대역만 허용 (보안 강화)

# 내부 네트워크 192.168.1.0/24 에서만 접근 허용
New-NetFirewallRule `
    -DisplayName "GUARDiA ITSM (내부망)" `
    -Direction Inbound `
    -Protocol TCP `
    -LocalPort 8000 `
    -RemoteAddress "192.168.1.0/24" `
    -Action Allow

# 기존 전체 허용 규칙 비활성화
Disable-NetFirewallRule -DisplayName "GUARDiA ITSM"

---

7. IIS 리버스 프록시 설정 (선택)

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

7.1 IIS 및 ARR 설치

# IIS 설치
Enable-WindowsOptionalFeature -Online -FeatureName IIS-WebServerRole -All
Install-WindowsFeature -Name Web-Server -IncludeManagementTools

# ARR (Application Request Routing) 설치
# Web Platform Installer에서 "Application Request Routing 3.0" 설치
# 또는: https://www.iis.net/downloads/microsoft/application-request-routing

7.2 IIS 역방향 프록시 설정

IIS 관리자를 열어 다음을 설정합니다:

1. IIS 관리자 → 서버 노드 → Application Request Routing Cache
   → "Enable proxy" 체크

2. 웹사이트 → "URL 재작성" → 규칙 추가
   → 역방향 프록시 → 서버: localhost:8000

3. 바인딩 추가:
   - 포트 80 (HTTP)
   - 포트 443 (HTTPS, SSL 인증서 선택)

web.config 예시:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="GUARDiA ITSM" stopProcessing="true">
          <match url="(.*)" />
          <action type="Rewrite" url="http://localhost:8000/{R:1}" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

---

8. 설치 검증

8.1 서비스 상태 확인

# 서비스 상태
Get-Service GUARDiA-ITSM, GUARDiA-Messenger

# 포트 리스닝 확인
netstat -an | findstr ":8000"
netstat -an | findstr ":8001"
# → TCP  0.0.0.0:8000  ...  LISTENING

8.2 API 기능 테스트

# 1. 홈페이지 응답 확인
$response = Invoke-WebRequest -Uri "http://localhost:8000/"
Write-Host "HTTP 상태: $($response.StatusCode)"
# → 200

# 2. 로그인 테스트
$loginBody = '{"username":"admin","password":"admin1234!"}'
$loginResult = Invoke-RestMethod -Uri "http://localhost:8000/auth/login" `
    -Method Post -Body $loginBody -ContentType "application/json"
$token = $loginResult.access_token
Write-Host "로그인 성공: 토큰 앞 20자 = $($token.Substring(0,20))..."

# 3. 대시보드 API 호출
$headers = @{ Authorization = "Bearer $token" }
$dashboard = Invoke-RestMethod -Uri "http://localhost:8000/dashboard/summary" `
    -Headers $headers
Write-Host "대시보드 응답:"
$dashboard | ConvertTo-Json

# 4. Messenger 확인
$msgResponse = Invoke-WebRequest -Uri "http://localhost:8001/"
Write-Host "Messenger HTTP 상태: $($msgResponse.StatusCode)"

8.3 설치 검증 스크립트

# C:\GUARDiA\verify_install.ps1 생성
$script = @'
Write-Host "=== GUARDiA 설치 검증 ===" -ForegroundColor Cyan

function Check-Item($condition, $label) {
    if ($condition) {
        Write-Host "  [ok] $label" -ForegroundColor Green
    } else {
        Write-Host "  [FAIL] $label" -ForegroundColor Red
    }
}

# 서비스 상태
$itsmSvc = Get-Service GUARDiA-ITSM -ErrorAction SilentlyContinue
Check-Item ($itsmSvc -and $itsmSvc.Status -eq "Running") "ITSM 서비스 실행 중"

$msgSvc = Get-Service GUARDiA-Messenger -ErrorAction SilentlyContinue
Check-Item ($msgSvc -and $msgSvc.Status -eq "Running") "Messenger 서비스 실행 중"

# 포트 확인
$itsm8000 = netstat -an | findstr ":8000" | findstr "LISTENING"
Check-Item ($itsm8000 -ne $null) "ITSM 포트 8000 리스닝"

$msg8001 = netstat -an | findstr ":8001" | findstr "LISTENING"
Check-Item ($msg8001 -ne $null) "Messenger 포트 8001 리스닝"

# API 응답
try {
    $r = Invoke-WebRequest "http://localhost:8000/" -TimeoutSec 5
    Check-Item ($r.StatusCode -eq 200) "ITSM API 응답 (200)"
} catch {
    Check-Item $false "ITSM API 응답 (오류: $_)"
}

# DB 파일
Check-Item (Test-Path "C:\GUARDiA\itsm\guardia_itsm.db") "ITSM DB 파일 존재"

# 로그 파일
Check-Item (Test-Path "C:\GUARDiA\logs\itsm.log") "ITSM 로그 파일 존재"

Write-Host "=== 검증 완료 ===" -ForegroundColor Cyan
'@

$script | Out-File -FilePath "C:\GUARDiA\verify_install.ps1" -Encoding utf8

# 검증 실행
PowerShell -ExecutionPolicy Bypass -File "C:\GUARDiA\verify_install.ps1"

---

9. 보안 강화 설정

9.1 초기 관리자 비밀번호 변경

# 로그인
$loginBody = '{"username":"admin","password":"admin1234!"}'
$loginResult = Invoke-RestMethod -Uri "http://localhost:8000/auth/login" `
    -Method Post -Body $loginBody -ContentType "application/json"
$token = $loginResult.access_token

# 비밀번호 변경
$pwBody = @{
    current_password = "admin1234!"
    new_password = "새로운강력한비밀번호!@#456"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:8000/auth/change-password" `
    -Method Post -Body $pwBody -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $token" }
Write-Host "비밀번호 변경 완료"

9.2 .env 파일 접근 권한 제한

# .env 파일 소유자 확인
Get-Acl "C:\GUARDiA\itsm\.env"

# 서비스 계정(또는 시스템)만 읽기 가능하도록 권한 설정
$acl = Get-Acl "C:\GUARDiA\itsm\.env"
$acl.SetAccessRuleProtection($true, $false)  # 상속 차단

# 현재 사용자 전체 제어
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
    $env:USERNAME, "FullControl", "Allow"
)
$acl.AddAccessRule($rule)
Set-Acl "C:\GUARDiA\itsm\.env" $acl

Write-Host "파일 권한 설정 완료"

9.3 이벤트 로그 설정

# 이벤트 소스 등록 (최초 1회)
New-EventLog -LogName Application -Source "GUARDiA-ITSM" -ErrorAction SilentlyContinue

# 이벤트 로그 크기 설정
Limit-EventLog -LogName Application -MaximumSize 50MB

9.4 보안 정책 확인

# TLS 1.2 이상만 허용 (Windows Server 2019+는 기본 설정)
# 레지스트리 확인
Get-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.0\Server" -ErrorAction SilentlyContinue
# DisabledByDefault = 1 이면 비활성화

---

10. 자동 백업 설정

10.1 백업 스크립트 생성

# C:\GUARDiA\scripts\backup.ps1 생성
$backupScript = @'
$date = Get-Date -Format "yyyyMMdd_HHmm"
$backupDir = "C:\GUARDiA\backup"

# 백업 디렉토리 생성
if (-not (Test-Path $backupDir)) {
    New-Item -ItemType Directory -Path $backupDir -Force
}

# ITSM DB 백업
$itsmDb = "C:\GUARDiA\itsm\guardia_itsm.db"
if (Test-Path $itsmDb) {
    Copy-Item $itsmDb "$backupDir\itsm_$date.db"
    Write-Host "$date - ITSM DB 백업 완료"
}

# Messenger DB 백업
$msgDb = "C:\GUARDiA\messenger\guardia_messenger.db"
if (Test-Path $msgDb) {
    Copy-Item $msgDb "$backupDir\messenger_$date.db"
    Write-Host "$date - Messenger DB 백업 완료"
}

# 업로드 파일 백업 (선택)
# Compress-Archive -Path "C:\GUARDiA\itsm\uploads" -DestinationPath "$backupDir\uploads_$date.zip"

# 30일 이전 백업 삭제
Get-ChildItem $backupDir -Filter "*.db" | 
    Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
    Remove-Item -Force

Write-Host "$date - 백업 작업 완료"
"@

New-Item -ItemType Directory -Force -Path "C:\GUARDiA\scripts"
$backupScript | Out-File -FilePath "C:\GUARDiA\scripts\backup.ps1" -Encoding utf8

10.2 작업 스케줄러 등록

# 매일 새벽 3시 자동 실행
$action = New-ScheduledTaskAction `
    -Execute "PowerShell.exe" `
    -Argument "-NonInteractive -ExecutionPolicy Bypass -File C:\GUARDiA\scripts\backup.ps1 >> C:\GUARDiA\logs\backup.log 2>&1"

$trigger = New-ScheduledTaskTrigger -Daily -At "03:00"

$settings = New-ScheduledTaskSettingsSet `
    -ExecutionTimeLimit (New-TimeSpan -Hours 1) `
    -RunOnlyIfNetworkAvailable $false

Register-ScheduledTask `
    -TaskName "GUARDiA-Backup" `
    -Action $action `
    -Trigger $trigger `
    -Settings $settings `
    -RunLevel Highest `
    -Force

Write-Host "백업 작업 스케줄 등록 완료"

# 즉시 실행으로 테스트
Start-ScheduledTask -TaskName "GUARDiA-Backup"
Start-Sleep -Seconds 5
Get-ChildItem "C:\GUARDiA\backup\" | Sort-Object LastWriteTime -Descending | Select-Object -First 3

---

11. 문제 해결

11.1 서비스 시작 실패

# 1. 서비스 상태 확인
Get-Service GUARDiA-ITSM | Format-List *

# 2. 이벤트 로그 확인
Get-EventLog -LogName Application -Source "GUARDiA-ITSM" -Newest 10 | 
    Select-Object TimeGenerated, EntryType, Message

# 3. NSSM 로그 확인
Get-Content "C:\GUARDiA\logs\itsm_error.log" -Tail 30

# 4. 수동 실행으로 오류 확인
cd C:\GUARDiA\itsm
C:\GUARDiA\.venv\Scripts\uvicorn.exe main:app --host 127.0.0.1 --port 8000
# → 직접 오류 메시지 확인

11.2 Python 패키지 누락 오류

오류: ModuleNotFoundError: No module named 'xxx'

해결:
C:\GUARDiA\.venv\Scripts\Activate.ps1
pip install xxx
deactivate
Restart-Service GUARDiA-ITSM

11.3 포트 충돌

# 8000 포트 사용 프로세스 확인
netstat -ano | findstr ":8000"
# → 마지막 컬럼이 PID

# 프로세스 확인
Get-Process -Id <PID>

# 프로세스 종료 (필요 시)
Stop-Process -Id <PID> -Force

11.4 PowerShell 실행 정책 오류

오류: running scripts is disabled on this system

해결:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
# 또는 현재 사용자만:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

11.5 DB 파일 잠금 오류

오류: database is locked

해결:
1. 서비스 중지
   Stop-Service GUARDiA-ITSM

2. 잠금 파일 삭제
   Remove-Item "C:\GUARDiA\itsm\guardia_itsm.db-shm" -ErrorAction SilentlyContinue
   Remove-Item "C:\GUARDiA\itsm\guardia_itsm.db-wal" -ErrorAction SilentlyContinue

3. 서비스 재시작
   Start-Service GUARDiA-ITSM

11.6 인코딩 오류 (한글 깨짐)

# .env 파일을 UTF-8 without BOM으로 저장
[System.IO.File]::WriteAllText(
    "C:\GUARDiA\itsm\.env",
    (Get-Content "C:\GUARDiA\itsm\.env" -Raw),
    [System.Text.UTF8Encoding]::new($false)  # $false = no BOM
)

---

부록 A: Windows 서비스 빠른 참조

# 서비스 시작/중지/재시작
Start-Service GUARDiA-ITSM
Stop-Service GUARDiA-ITSM
Restart-Service GUARDiA-ITSM

Start-Service GUARDiA-Messenger
Stop-Service GUARDiA-Messenger
Restart-Service GUARDiA-Messenger

# 상태 확인
Get-Service GUARDiA-ITSM, GUARDiA-Messenger

# 로그 확인 (최근 50줄)
Get-Content "C:\GUARDiA\logs\itsm.log" -Tail 50
Get-Content "C:\GUARDiA\logs\itsm_error.log" -Tail 20

# 실시간 로그 모니터링
Get-Content "C:\GUARDiA\logs\itsm.log" -Wait -Tail 10

# 수동 백업
PowerShell -File "C:\GUARDiA\scripts\backup.ps1"

부록 B: 환경 변수 참조

변수명	설명	예시 값
SECRET_KEY	JWT 서명 키 (필수 변경)	랜덤 64자 이상 문자열
ENCRYPTION_KEY	AES-256 암호화 키 (필수 변경)	랜덤 64자 hex 문자열
ACCESS_TOKEN_EXPIRE_MINUTES	토큰 만료 시간(분)	480 (8시간)
DB_URL	SQLite DB 경로	sqlite+aiosqlite:///C:/...
MESSENGER_BASE_URL	Messenger 서버 URL	http://localhost:8001
SSH_TIMEOUT	SSH 실행 타임아웃(초)	30
UPLOAD_ROOT	파일 업로드 경로	C:/GUARDiA/itsm/uploads
MAX_FILE_SIZE_MB	최대 업로드 파일 크기(MB)	10

---

설치 중 문제가 발생하면 C:\GUARDiA\logs\itsm_error.log를 확인하거나 개발팀에 문의하세요.