Windows 로컬 서버 설정 가이드

Windows 데스크탑을 사용하여 GitHub Actions Self-hosted Runner와 Cloudflare Tunnel을 설정하는 완전한 가이드입니다.

사전 준비

필수 요구사항

Windows 10/11 Pro 이상 (Hyper-V 지원)
관리자 권한
GitHub 계정 및 레포지토리
Cloudflare 계정 (무료)
도메인 (Cloudflare에 등록된 상태)

Chocolatey 설치 (패키지 관리자)

PowerShell을 관리자 권한으로 실행:

Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

설치 확인:

choco --version

Docker Desktop 설치

1. Docker Desktop 다운로드 및 설치

choco install docker-desktop -y

또는 Docker 공식 사이트에서 다운로드

2. WSL2 설정 (필요시)

wsl --install
wsl --set-default-version 2

3. Docker Desktop 설정

Docker Desktop 실행
Settings → General → "Start Docker Desktop when you sign in" 체크
Settings → Resources → WSL Integration 활성화

4. Docker 동작 확인

docker --version
docker run hello-world

GitHub Actions Self-hosted Runner 설정

1. Runner 디렉토리 생성

mkdir C:\actions-runner
cd C:\actions-runner

2. Runner 다운로드

GitHub 레포지토리 → Settings → Actions → Runners → "New self-hosted runner" 클릭

표시되는 명령어를 따라 실행 (예시):

# 다운로드
Invoke-WebRequest -Uri https://github.com/actions/runner/releases/download/v2.XXX.X/actions-runner-win-x64-2.XXX.X.zip -OutFile actions-runner-win-x64.zip

# 압축 해제
Add-Type -AssemblyName System.IO.Compression.FileSystem
[System.IO.Compression.ZipFile]::ExtractToDirectory("$PWD\actions-runner-win-x64.zip", "$PWD")

3. Runner 등록 (서비스로 설치)

.\config.cmd --url https://github.com/<사용자명>/<레포지토리> --token <등록토큰>

설정 과정에서 물어보는 항목:

Runner group: Enter (기본값 Default)
Runner name: Enter (기본값 컴퓨터명) 또는 원하는 이름
Additional labels: 원하는 라벨 (예: home-server)
Work folder: Enter (기본값 _work)
Run as service?: Y (중요!)
User account: Enter (기본값 NT AUTHORITY\NETWORK SERVICE)

4. 서비스 계정을 LocalSystem으로 변경 (Docker 접근용)

# 서비스 이름 확인
Get-Service *actions*

# LocalSystem으로 변경 (서비스 이름은 실제 이름으로 교체)
sc config "actions.runner.<레포지토리명>.<러너명>" obj= LocalSystem

# 서비스 재시작
net stop "actions.runner.<레포지토리명>.<러너명>"
net start "actions.runner.<레포지토리명>.<러너명>"

5. 서비스 상태 확인

Get-Service *actions*

Running 상태여야 함

Cloudflare Tunnel 설정

1. 도메인 Cloudflare로 이전 (아직 안했다면)

Cloudflare Dashboard 로그인
"Add a Site" → 도메인 입력
무료 플랜 선택
기존 DNS 레코드 확인 후 Continue
표시된 네임서버를 도메인 등록 업체(가비아 등)에서 변경
Cloudflare에서 도메인 상태가 Active가 될 때까지 대기 (최대 24-48시간)

네임서버 전파 확인:

nslookup -type=NS <도메인>

Cloudflare 네임서버가 표시되면 완료

2. Cloudflared 설치

choco install cloudflared -y

또는:

winget install Cloudflare.cloudflared

3. Cloudflare 로그인

cloudflared tunnel login

브라우저가 열리면 로그인 후 도메인 선택

4. 터널 생성

cloudflared tunnel create <터널이름>

예: cloudflared tunnel create chagok

출력되는 터널 ID를 메모 (예: 4a623b71-56de-4b7a-8fc8-bfa097f16e5c)

5. 설정 파일 생성

notepad "$env:USERPROFILE\.cloudflared\config.yml"

다음 내용 입력 (터널 ID와 사용자명 수정):

tunnel: <터널ID>
credentials-file: C:\Users\<사용자명>\.cloudflared\<터널ID>.json

ingress:
  - hostname: <도메인>
    service: http://localhost:8080
  - hostname: www.<도메인>
    service: http://localhost:8080
  - service: http_status:404

주의: service: http://localhost:8080 끝에 /를 붙이지 마세요!

6. DNS 등록

cloudflared tunnel route dns <터널이름> <도메인>
cloudflared tunnel route dns <터널이름> www.<도메인>

7. 터널 테스트 (수동 실행)

cloudflared tunnel run <터널이름>

브라우저에서 https://<도메인> 접속 테스트

Ctrl+C로 중단

8. Windows 서비스로 등록

cloudflared service install

9. 서비스 시작 및 확인

# 서비스 이름 확인
Get-Service *cloud*

# 서비스 시작
net start Cloudflared

# 상태 확인
Get-Service Cloudflared

10. 서비스가 안 보일 경우 (Chocolatey 설치 시)

Chocolatey로 설치한 경우 서비스 경로 문제가 있을 수 있습니다.

설정 파일을 여러 위치에 복사:

# ProgramData 경로
New-Item -ItemType Directory -Path "C:\ProgramData\cloudflared" -Force
Copy-Item "$env:USERPROFILE\.cloudflared\config.yml" "C:\ProgramData\cloudflared\config.yml"
Copy-Item "$env:USERPROFILE\.cloudflared\<터널ID>.json" "C:\ProgramData\cloudflared\<터널ID>.json"

C:\ProgramData\cloudflared\config.yml의 credentials-file 경로도 수정:

credentials-file: C:\ProgramData\cloudflared\<터널ID>.json

서비스 재설치:

cloudflared service uninstall
cloudflared service install
net start Cloudflared

서비스 자동 시작 확인

재부팅 후 체크리스트

Docker Desktop: 자동 시작 (Settings에서 설정)
GitHub Actions Runner:
Get-Service *actions* # Status가 Running이어야 함
Cloudflared:
Get-Service *cloud* # Status가 Running이어야 함
웹사이트 접속: https://<도메인> 확인

서비스 시작 타입 확인

sc qc "actions.runner.<레포지토리명>.<러너명>"
sc qc Cloudflared

START_TYPE이 AUTO_START 또는 DELAYED_AUTO여야 함

시작 타입 변경 (필요시)

sc config "actions.runner.<레포지토리명>.<러너명>" start= delayed-auto
sc config Cloudflared start= auto

트러블슈팅

Runner가 Docker에 접근 못할 때

에러: Access is denied 또는 docker client must be run with elevated privileges

해결:

sc config "actions.runner.<레포지토리명>.<러너명>" obj= LocalSystem
net stop "actions.runner.<레포지토리명>.<러너명>"
net start "actions.runner.<레포지토리명>.<러너명>"

Cloudflared 터널 에러

수동 실행으로 테스트:
cloudflared tunnel run <터널이름>
config.yml 확인:
- service URL 끝에 / 없는지 확인
- credentials-file 경로가 올바른지 확인
- 터널 ID가 맞는지 확인
터널 상태 확인:
cloudflared tunnel info <터널이름>

서비스가 시작되지 않을 때

이벤트 로그 확인:
Get-WinEvent -LogName Application -FilterXPath "*[System[Provider[@Name='cloudflared']]]" -MaxEvents 20
Runner 로그 확인:
Get-Content C:\actions-runner\_diag\Runner_*.log -Tail 50

Runner 재설치

cd C:\actions-runner

# GitHub에서 제거 토큰 발급 후
.\config.cmd remove --token <제거토큰>

# 다시 등록
.\config.cmd --url https://github.com/<사용자명>/<레포지토리> --token <등록토큰>

Cloudflared 재설치

cloudflared service uninstall
choco uninstall cloudflared -y
choco install cloudflared -y
cloudflared tunnel login
cloudflared service install

유용한 명령어 모음

전체 서비스 상태 확인

Get-Service *actions*, *cloud* | Format-Table Name, Status, StartType

서비스 재시작

# Runner
net stop "actions.runner.<레포지토리명>.<러너명>"; net start "actions.runner.<레포지토리명>.<러너명>"

# Cloudflared
net stop Cloudflared; net start Cloudflared

Docker 컨테이너 상태 확인

docker ps -a

수동 데이터 수집 실행

docker exec chagok-app ./bin/collector daily --days 7
docker exec chagok-app ./bin/refinery all

Windows 데스크탑을 사용하여 GitHub Actions Self-hosted Runner와 Cloudflare Tunnel을 설정하는 가이드