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

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

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

---

## 목차

1. [설치 전 요구사항 확인](#1-설치-전-요구사항-확인)
2. [사전 소프트웨어 설치](#2-사전-소프트웨어-설치)
3. [GUARDiA ITSM 설치](#3-guardia-itsm-설치)
4. [GUARDiA Messenger 설치](#4-guardia-messenger-설치)
5. [Windows 서비스 등록 (NSSM)](#5-windows-서비스-등록-nssm)
6. [방화벽 설정](#6-방화벽-설정)
7. [IIS 리버스 프록시 설정 (선택)](#7-iis-리버스-프록시-설정-선택)
8. [설치 검증](#8-설치-검증)
9. [보안 강화 설정](#9-보안-강화-설정)
10. [자동 백업 설정](#10-자동-백업-설정)
11. [문제 해결](#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을 **관리자 권한**으로 실행하여 확인합니다.

```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"**

```powershell
# 설치 후 확인
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
```

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

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

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

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

```powershell
# 확인
nssm version
```

---

## 3. GUARDiA ITSM 설치

### 3.1 설치 디렉토리 생성

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

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

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

```powershell
# 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
```

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

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

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

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

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

```powershell
# 랜덤 키 생성
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 초기화 테스트

```powershell
# 가상환경 활성화
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 소스 코드 배포

```powershell
# 파일 복사
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 의존성 설치

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

### 4.3 환경 변수 설정

```powershell
$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을 **관리자 권한**으로 실행합니다.

```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 서비스 등록

```powershell
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 서비스 시작

```powershell
# 서비스 시작
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 서비스 관리 명령어

```powershell
# 시작
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 서비스 제거 (재설치 시)

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

---

## 6. 방화벽 설정

### 6.1 Windows Defender 방화벽 규칙 추가

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

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

```powershell
# 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
<?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 서비스 상태 확인

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

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

### 8.2 API 기능 테스트

```powershell
# 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 설치 검증 스크립트

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

```powershell
# 로그인
$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 파일 접근 권한 제한

```powershell
# .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 이벤트 로그 설정

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

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

### 9.4 보안 정책 확인

```powershell
# 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 백업 스크립트 생성

```powershell
# 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 작업 스케줄러 등록

```powershell
# 매일 새벽 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 서비스 시작 실패

```powershell
# 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 포트 충돌

```powershell
# 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 인코딩 오류 (한글 깨짐)

```powershell
# .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 서비스 빠른 참조

```powershell
# 서비스 시작/중지/재시작
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`를 확인하거나 개발팀에 문의하세요.*