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 연결하도록 설정:

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 모드를 원격으로 전환:

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 사용

서비스 확인

systemctl status rdp-toggle-api

API 테스트

# 현재 상태 확인
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 모드 상태 확인

curl http://localhost:8090/status

응답 예시:

{
  "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 모드 전환

# 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 연결 설정 조회

curl http://localhost:8090/config

PUT /config

RDP 연결 설정 업데이트

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 예시

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 기반 컨트롤 패널도 제공됩니다:

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 원라이너 설치 (웹에서 바로 복사해서 실행)

---

🔧 서비스 관리

# 서비스 상태 확인
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을 허용하세요:

# UFW 사용 시
ufw allow 8090/tcp

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

---

📚 참고 문서

• RDP_TOGGLE_API.md - API 상세 문서
• proxmox_auto_rdp_setup_korean.md - RDP 초기 설정 가이드

---

🐛 문제 해결

API 서버가 시작되지 않는 경우

# 로그 확인
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 모드 전환이 작동하지 않는 경우

# RDP 초기 설정이 완료되었는지 확인
ls -la /home/rdpuser/.xinitrc
cat /etc/systemd/system/getty@tty1.service.d/override.conf

# FreeRDP3 설치 확인
which xfreerdp3

포트 8090이 이미 사용 중인 경우

# 포트 사용 확인
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