pve9-repo-fix/RDP/README.md

# Proxmox RDP 자동화 시스템

Proxmox VE 호스트에서 **RDP 초기 설정** 및 **RDP/Shell 모드 API 전환**을 지원하는 통합 솔루션

## 개요

이 시스템은 두 가지 주요 기능을 제공합니다:

1. **Proxmox RDP 초기 설정** - 부팅 시 자동으로 원격 Windows PC에 RDP 연결
2. **RDP Toggle API** - 외부에서 API 호출로 RDP/Shell 모드 실시간 전환

프론트엔드 또는 curl 명령으로 Proxmox 물리 화면을 Shell ↔ RDP 모드로 즉시 전환 가능합니다.

---

## 🚀 빠른 설치

### 1️⃣ Proxmox RDP 초기 설정 (자동 부팅 연결)

Proxmox 호스트가 부팅 시 자동으로 RDP 연결하도록 설정:

```bash
curl -fsSL https://git.0bin.in/thug0bin/pve9-repo-fix/raw/branch/main/RDP/proxmox-auto-rdp-setup.sh | bash
```

**설치 내용:**
- ✅ X Window + Openbox 윈도우 매니저
- ✅ FreeRDP3 클라이언트 설치
- ✅ 자동 로그인 및 X 시작 설정
- ✅ RDP 서버 연결 정보 구성
- ✅ 풀스크린 RDP 자동 실행

### 2️⃣ RDP Toggle API 설치 (원격 제어)

API를 통해 RDP/Shell 모드를 원격으로 전환:

```bash
curl -fsSL https://git.0bin.in/thug0bin/pve9-repo-fix/raw/branch/main/RDP/install-rdp-api.sh | bash
```

**설치 내용:**
- ✅ FastAPI 기반 REST API 서버
- ✅ Python venv 환경 구성
- ✅ systemd 서비스 자동 시작
- ✅ 포트 8090에서 API 실행

---

## 📖 사용 방법

### RDP Toggle API 사용

#### 서비스 확인
```bash
systemctl status rdp-toggle-api
```

#### API 테스트
```bash
# 현재 상태 확인
curl http://localhost:8090/status

# RDP 모드로 전환
curl -X POST http://localhost:8090/toggle \
  -H 'Content-Type: application/json' \
  -d '{"mode":"rdp"}'

# Shell 모드로 전환
curl -X POST http://localhost:8090/toggle \
  -H 'Content-Type: application/json' \
  -d '{"mode":"shell"}'
```

---

## 📡 API 엔드포인트

### GET /status
현재 RDP/Shell 모드 상태 확인
```bash
curl http://localhost:8090/status
```

**응답 예시:**
```json
{
  "current_mode": "shell",
  "rdp_active": false,
  "last_changed": "2025-11-17T10:30:00",
  "config": {
    "rdp_server": "192.168.0.229",
    "rdp_username": "user",
    "local_user": "rdpuser"
  }
}
```

### POST /toggle
RDP/Shell 모드 전환
```bash
# RDP 모드 활성화
curl -X POST http://localhost:8090/toggle \
  -H 'Content-Type: application/json' \
  -d '{"mode":"rdp"}'

# Shell 모드로 전환
curl -X POST http://localhost:8090/toggle \
  -H 'Content-Type: application/json' \
  -d '{"mode":"shell"}'
```

### GET /config
현재 RDP 연결 설정 조회
```bash
curl http://localhost:8090/config
```

### PUT /config
RDP 연결 설정 업데이트
```bash
curl -X PUT http://localhost:8090/config \
  -H 'Content-Type: application/json' \
  -d '{
    "rdp_server": "new-server.example.com:3389",
    "rdp_username": "newuser",
    "rdp_password": "newpassword"
  }'
```

---

## 🔗 프론트엔드 연동

### React 예시

```jsx
import { useState, useEffect } from 'react';

const RDPToggle = () => {
  const [status, setStatus] = useState(null);
  const API_URL = 'http://your-proxmox-ip:8090';

  // 상태 확인
  const fetchStatus = async () => {
    const res = await fetch(`${API_URL}/status`);
    const data = await res.json();
    setStatus(data);
  };

  // 모드 전환
  const toggleMode = async (mode) => {
    await fetch(`${API_URL}/toggle`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ mode })
    });
    fetchStatus(); // 상태 갱신
  };

  useEffect(() => {
    fetchStatus();
  }, []);

  return (
    <div>
      <p>현재 모드: {status?.current_mode}</p>
      <button onClick={() => toggleMode('rdp')}>RDP 모드</button>
      <button onClick={() => toggleMode('shell')}>Shell 모드</button>
    </div>
  );
};
```

### 웹 기반 컨트롤 패널

간단한 HTML 기반 컨트롤 패널도 제공됩니다:
```bash
curl -fsSL https://git.0bin.in/thug0bin/pve9-repo-fix/raw/branch/main/RDP/rdp-toggle-web.html -o rdp-control.html
```

브라우저에서 `rdp-control.html` 파일을 열어 사용하세요.

---

## 📂 구성 파일

### 설치 위치
- **API 서버**: `/opt/rdp-toggle-api/`
- **Python 가상환경**: `/opt/rdp-toggle-api/venv/`
- **systemd 서비스**: `/etc/systemd/system/rdp-toggle-api.service`

### 구성 파일 목록
- `rdp-toggle-api.py` - FastAPI 기반 REST API 서버
- `install-rdp-api.sh` - 자동 설치 스크립트 (curl 실행 가능)
- `proxmox-auto-rdp-setup.sh` - Proxmox RDP 초기 설정 스크립트
- `rdp-toggle-web.html` - 웹 기반 컨트롤 패널
- `requirements.txt` - Python 패키지 의존성

---

## ✨ 주요 기능

- ✅ **RDP ↔ Shell 모드 즉시 전환**
- ✅ **실시간 상태 모니터링** (프로세스 확인)
- ✅ **CORS 지원** (외부 프론트엔드 접근 가능)
- ✅ **Python venv 환경** (시스템 패키지 충돌 방지)
- ✅ **systemd 서비스** (자동 시작, 재시작)
- ✅ **설정 동적 변경** (API로 RDP 서버 정보 변경)
- ✅ **curl 원라이너 설치** (웹에서 바로 복사해서 실행)

---

## 🔧 서비스 관리

```bash
# 서비스 상태 확인
systemctl status rdp-toggle-api

# 서비스 재시작
systemctl restart rdp-toggle-api

# 서비스 중지
systemctl stop rdp-toggle-api

# 서비스 시작
systemctl start rdp-toggle-api

# 로그 확인
journalctl -u rdp-toggle-api -f
```

---

## 🌐 네트워크 설정

- **기본 포트**: `8090`
- **바인드 주소**: `0.0.0.0` (모든 인터페이스)
- **CORS**: 모든 origin 허용 (`allow_origins=["*"]`)

외부에서 접근하려면 방화벽에서 포트 8090을 허용하세요:
```bash
# UFW 사용 시
ufw allow 8090/tcp

# iptables 사용 시
iptables -A INPUT -p tcp --dport 8090 -j ACCEPT
```

---

## 📚 참고 문서

- [RDP_TOGGLE_API.md](RDP_TOGGLE_API.md) - API 상세 문서
- [proxmox_auto_rdp_setup_korean.md](proxmox_auto_rdp_setup_korean.md) - RDP 초기 설정 가이드

---

## 🐛 문제 해결

### API 서버가 시작되지 않는 경우
```bash
# 로그 확인
journalctl -u rdp-toggle-api -n 50

# Python 가상환경 재설치
rm -rf /opt/rdp-toggle-api/venv
python3 -m venv /opt/rdp-toggle-api/venv
/opt/rdp-toggle-api/venv/bin/pip install fastapi uvicorn python-multipart pydantic
systemctl restart rdp-toggle-api
```

### RDP 모드 전환이 작동하지 않는 경우
```bash
# RDP 초기 설정이 완료되었는지 확인
ls -la /home/rdpuser/.xinitrc
cat /etc/systemd/system/getty@tty1.service.d/override.conf

# FreeRDP3 설치 확인
which xfreerdp3
```

### 포트 8090이 이미 사용 중인 경우
```bash
# 포트 사용 확인
ss -tulpn | grep 8090

# API 서비스 파일에서 포트 변경
nano /opt/rdp-toggle-api/rdp-toggle-api.py
# 마지막 줄: uvicorn.run(app, host="0.0.0.0", port=8090)
# 포트 번호를 원하는 값으로 변경 후 저장

systemctl restart rdp-toggle-api
```

---

## 📄 라이선스

MIT License

---

**작성자**: thug0bin
**리포지토리**: https://git.0bin.in/thug0bin/pve9-repo-fix