---
title: "Windows 지원 기능"
description: "Windows에서 Alpamon이 지원하는 버전과 기능을 확인합니다. Websh, WebFTP, 명령 실행과 포트 포워딩의 조건을 살펴보고 SYSTEM 계정으로 작업이 실행되는 점을 이해하세요. 설치, 업그레이드, 제거 및 복구 절차를 시작하기 전에 플랫폼 차이를 확인할 수 있습니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# Windows 지원 기능

<span id="windows-서버" />

# Windows 지원 기능

Alpacon은 Alpamon 에이전트로 Windows 서버를 지원합니다. 터미널 접속(Websh), 파일 전송(WebFTP),
포트 포워딩, 시스템 정보 조회, 에이전트 재시작, 메트릭 수집을 사용할 수 있지만 Unix 전용 기능 중
일부는 사용할 수 없습니다. 포트 포워딩에는 Alpamon 2.5.1 이상이 필요합니다. 이 페이지에서는
Windows에만 해당하는 내용을 설명하며, 단계별 절차는 연결된 가이드에서 확인할 수 있습니다.

## 지원 버전 및 아키텍처

|  | 지원 대상 |
| --- | --- |
| Windows Server | 2019, 2022, 2025 |
| Windows 클라이언트 | Windows 10 (1803 이상), Windows 11 |
| 아키텍처 | amd64 (x64)만 지원 |

기본 지원 범위는 Windows Server 2019+ 및 Windows 10 1803+입니다. 브라우저 터미널인 **Websh**를
사용하려면 Windows의 가상 콘솔인 ConPTY가 추가로 필요하며, ConPTY는 Server 2019+ 및 Windows 10
1809+에서만 제공됩니다. 따라서 Windows 10 1803–1808에서는 Websh를 제외한 나머지 지원 기능을
모두 사용할 수 있습니다. **Windows Server 2016 및 이전 버전은 지원하지 않습니다.** 설치 프로그램에 필요한 기본 제공
`tar.exe`와 최신 PowerShell 기능이 없기 때문입니다. Windows용 ARM64 빌드는 없습니다.

## 설치

관리자 권한으로 실행한 PowerShell에서 설치하세요. cmd.exe는 지원하지 않습니다. 워크스페이스에서
생성한 명령어, `install.ps1`, 수동 `.zip` 설치, Ansible을 이용한 설치 방법은 모두
[설치 가이드](/use/servers/register/install/#windows)에 나와 있습니다.

## Windows에서 사용할 수 있는 기능

| 기능 | Windows |
| --- | --- |
| 터미널 세션(Websh) | ✅ |
| 명령 실행(`exec`, `shell`) | ✅ (PowerShell) |
| 파일 전송(WebFTP) | ✅ |
| 시스템 정보(사용자, 그룹, 인벤토리) | ✅ |
| 에이전트 재시작 | ✅ |
| 실시간 메트릭 | ✅ |
| 에이전트 자체 업그레이드 | ✅ (Alpamon 2.4.0 이상) |
| 사용자 및 그룹 관리 | ❌ |
| 권한 변경(`chmod` / `chown`) | ❌ |
| 포트 포워딩(터널) | ✅ (Alpamon 2.5.1 이상, IPv4 localhost `127.0.0.1`만) |
| 코드 에디터 | ❌ |
| ARM64 빌드 | ❌ |

Windows 서버에서도 **코드 에디터** 체크박스는 선택할 수 있지만, 에디터를 열면 시작되지 않고 `Connection timeout. The editor failed to start.` 오류로 끝납니다. 포트 포워딩은 IPv4 localhost(`127.0.0.1`)에서 대기하는 서비스에만 연결되고, `::1`에만 바인딩된 서비스에는 연결되지 않습니다.

## Windows의 권한과 사용자 식별

이 부분이 Linux 및 macOS와 가장 크게 다른 점입니다.

Windows에서 에이전트는 연결할 때 선택한 계정과 관계없이 모든 명령을 **SYSTEM (LocalSystem)**
권한으로 실행합니다. 세션에 표시되는 계정은 **감사 기록용 표시**일 뿐, 실행 권한을 제한하지
않습니다. Websh에서 `whoami`를 실행하면 `nt authority\system`이 반환됩니다.

서버에서 사용자별로 권한을 구분하지 않으므로, 접근은 Windows 파일 권한이 아니라 Alpacon에서
제어합니다.

- **Websh와 명령 실행**은 SYSTEM 권한으로 실행됨
- **WebFTP**는 SYSTEM 권한으로 실행되며, 에이전트가 접근할 수 있는 모든 경로에서 파일을 읽고 쓸 수
  있음. `C:\Windows\System32` 같은 시스템 디렉터리도 포함되며, 홈 디렉터리로 접근 범위를 제한하지
  않음
- **포트 포워딩**은 SYSTEM 권한으로 실행되는 에이전트가 연결을 열고 트래픽을 그대로 전달함.
  SQL Server나 WinRM처럼 로그인이 필요한 서비스는 SYSTEM이 아니라 클라이언트가 보낸 자격 증명으로
  인증함

실제 접근 범위는 **Alpacon 역할과 권한**, 그리고 **연결이 허용된 사용자 목록**으로 결정됩니다.
Websh, WebFTP, 포트 포워딩 접근 권한은 신중하게 부여하고, 역할을 사용해 민감한 서버와 경로에
접근할 수 있는 사용자를 제한하세요.

## 접속 가능 계정

Alpacon은 필요할 때 Windows 계정을 생성하지 않습니다. 시스템 계정으로 접속하려면 서버에 그 계정이
이미 있어야 합니다. 먼저 Windows 계정을 만들면 접속할 때 선택할 수 있습니다.

## 업그레이드

Alpamon 2.4.0 이상의 Windows 에이전트는 Linux 및 macOS 에이전트처럼 자동으로 업데이트하거나
`alpacon agent upgrade` 명령 또는 서버의 [에이전트 카드](/use/servers/manage/#에이전트-카드)에 있는
**에이전트 업그레이드** 버튼으로 직접 업데이트할 수 있습니다.
에이전트는 최신 릴리스를 다운로드하고 체크섬을 검증한 뒤 다시 시작합니다.
Alpamon 2.8.3 이상에서는 Windows의 각 명령이 에이전트와 함께 종료되는 작업 개체 안에서 실행됩니다.
에이전트가 다시 시작하면 작업 개체 안에 남아 있는 명령과 자식 프로세스가 종료됩니다. 예약 작업이나
Windows 서비스로 시작한 프로세스처럼 작업 개체를 벗어난 프로세스는 계속 실행됩니다.
자동 업그레이드나 예약된 다시 시작은 서버에 Websh 또는 WebFTP 세션이 열려 있거나 명령이 실행 중인
동안 기다립니다. 그 세션과 명령이 끝나거나 대기열에 등록된 지 48시간이 지나면, 둘 중 먼저 오는
시점에 진행됩니다. 수동 업그레이드나 다시 시작은 세션이 열려 있거나 명령이 실행 중이면
거부됩니다. 다만 강제로 실행하면 진행됩니다. 자세한 내용은
[`alpacon agent upgrade`](/reference/cli/agent/upgrade/)를 참고하세요.
업그레이드나 다시 시작이 진행될 때 작업 개체 안에서 명령이 계속 실행 중이라면 그 명령은 종료됩니다.
에이전트가 다시 시작한 뒤에도 계속 실행해야 하는 작업은 명령으로 시작하지 말고
예약 작업이나 Windows 서비스로 실행하세요.
2.4.0보다 오래된 에이전트는 스스로 업데이트하지 못하므로 바이너리를 한 번 직접 교체해야 합니다.
절차는 [에이전트 업그레이드](/use/servers/manage/#에이전트-카드)를 참고하세요.

## 제거 및 복구

에이전트를 제거하려면 `alpamon unregister`를 실행하고, 멈춘 호스트를 복구하려면
`alpamon register --force`를 실행하세요. alpamon v2.3.0 이상에서 Websh 대신 서버의 RDP 또는 직렬
콘솔로 접속해 실행하세요. 자세한 절차는 [제거](/use/servers/remove/)와
[재등록 및 복구](/use/servers/troubleshooting/#재등록-및-복구)를
참고하세요.

## 문제 해결

- **SmartScreen**: 바이너리에 서명이 없으므로 아카이브를 직접 다운로드했다면 등록 전에
  `Unblock-File`을 실행할 것
- **자동 로그 순환 없음**: `%ProgramData%\alpamon\log\alpamon.log`의 크기가 제한 없이 커지므로 예약
  작업으로 로그를 순환할 것
- **서비스 시작 실패(StartPending 포함)** 및 기타 에이전트 문제:
  [에이전트 문제 → Windows](/use/servers/troubleshooting/#windows-에이전트-문제) 참고

## 운영 참고 자료

서비스 복구 방식, PowerShell 및 TLS 요구 사항, 전체 설치 조합 등 자세한 운영 정보는 Alpamon Windows
운영 가이드
[alpamon/docs/windows.md](https://github.com/alpacax/alpamon/blob/main/docs/windows.md)를
참고하세요.

Source: https://docs.alpacax.com/ko/reference/platforms/windows/