Proxmox P3 Portal 설치 및 활용 가이드 - 통합 관리·Ansible 자동화와 실제 구축 이슈

Proxmox VE는 기본 웹 관리 화면만으로도 VM 생성과 설정, 스토리지와 네트워크 운영이 가능합니다. 다만 Ansible 기반 반복 작업, 템플릿 자동 빌드, 사용자별 접근 제어, 작업 이력까지 한 화면에서 관리하고 싶다면 별도의 운영 포털을 고민하게 됩니다.

이번에 살펴볼 P3 Portal은 그런 목적을 겨냥한 셀프 호스팅 관리 플랫폼입니다. GitHub에서 공개한 Core Edition의 설치 문서와 실행 구성을 바탕으로, 실제 사용자 이슈까지 함께 살펴보겠습니다.

이 글은 공개된 소스·개발자 설명·사용자 이슈를 바탕으로 작성한 설치 가이드입니다. 별도 테스트 서버에 직접 설치하고 운영 검증한 결과는 아닙니다. 특히 2026년 11월 기준으로 저장소가 스스로 'early beta'라고 안내하므로, 운영 도입 전에 격리된 Lab 환경에서 충분히 검증하는 편이 좋습니다.

1. P3 Portal은 어떤 도구일까?

P3 Portal은 Proxmox VE REST API와 연동해 클러스터 상태를 조회하고 VM/LXC 관리, 자동화 작업을 실행하는 웹 포털입니다. Docker 또는 Podman 컨테이너로 배포하며, 포털 내부 사용자 계정과 Proxmox API 서비스 계정을 구분해서 관리합니다.

노드와 VM/LXC 및 CPU·메모리·스토리지 현황을 보여주는 P3 Portal 대시보드 — 출처: P3Portal-org/p3portal GitHub 공식 스크린샷

주요 기능은 다음과 같습니다.

• 리소스 대시보드: 노드, VM, LXC, CPU, RAM, Storage 상태를 한눈에 확인

• VM/LXC 수명주기 관리: 전원, 스냅샷, 복제, 마이그레이션, 디스크 관리 및 템플릿 전환

• 네트워크·방화벽 관리: Linux Bridge, VLAN, Proxmox SDN 및 방화벽 정책

• 자동화: Ansible 플레이북 실행과 로그, Packer 기반 이미지·템플릿 빌드

• 운영 권한: 로컬 사용자, TOTP, 역할별 접근 제어와 작업 이력

• HA 설정: Proxmox 자체 HA 리소스 및 관련 규칙 관리

다만 포털이 하이퍼바이저 자체의 기능을 새로 만드는 것은 아닙니다. 실제 VM 동작과 HA, SDN 등은 Proxmox의 지원 기능과 권한·구성에 의존합니다.

2. Core와 Plus는 무엇이 다를까?

저장소 README를 보면 무료 Core 이미지와 별도 Plus 이미지가 구분되어 있습니다. Core는 AGPLv3 라이선스이고, Plus는 별도의 Source-Available 조건을 따릅니다.

Core에도 사용자 수와 역할 프리셋 등의 일부 제한이 있으므로, 단순히 '완전 무료 vCenter 대체제'로 이해하기보다는 기능별 라이선스 범위를 확인하는 것이 맞습니다. Plus 이미지의 무료 체험 기능 및 상용 판매 상태는 바뀔 수 있으므로 프로젝트 안내를 참고하세요.

여러 독립 Proxmox 클러스터를 하나의 대시보드로 관리하려는 목적이라면 Core/Plus 구분을 먼저 확인하세요. 반대로 단일 클러스터의 리소스 모니터링과 Ansible 자동화를 경험할 때는 Core부터 시작하는 편이 간단합니다.

3. 설치 환경과 사전 확인

README에 명시된 요구사항은 Docker 24 이상 또는 Podman 4.4 이상, 그리고 네트워크로 연결 가능한 Proxmox VE 7.x 이상입니다. Portal 서버는 반드시 Proxmox 호스트 자체일 필요가 없고, 관리망에서 API에 접근할 수 있는 별도 Linux VM으로 운영할 수 있습니다.

예시로 다음과 같은 Lab 구성을 가정할 수 있습니다. 이는 설명을 위한 구성 예시이며, P3 Portal이 요구하는 고정 IP 또는 공식 최소 사양은 아닙니다.

• Portal 서버: Debian/Ubuntu 기반 Linux VM, Docker Compose 실행

• Portal 웹 접속: TCP 8443

• Proxmox API: Portal → Proxmox TCP 8006

• Packer HTTP 부트스트랩: 필요할 때 TCP 8103 및 게스트 VM의 네트워크 도달성 확인

• 운영 접근: 인터넷 공개 대신 내부망 또는 VPN 사용

Proxmox API는 TLS 인증서 검증과 방화벽 정책도 함께 확인하는 것이 좋습니다.

4. Docker Compose로 P3 Portal 설치하기

4-1. 저장소 다운로드

먼저 Docker와 Compose가 준비된 Linux 서버에 접속합니다.

docker --version
docker compose version

git clone https://github.com/P3Portal-org/p3portal.git
cd p3portal

4-2. 환경 파일 준비

저장소에 포함된 예제 파일을 복사합니다.

cp .env.example .env
openssl rand -hex 32

마지막 명령어로 나온 임의 문자열을 SECRET_KEY에 입력합니다.

SECRET_KEY=여기에_생성한_64자리_16진수_비밀키_입력
TZ=Asia/Seoul

SECRET_KEY를 GitHub에 커밋하거나 외부에 공유하면 안 됩니다. Proxmox API 토큰은 최신 안내 기준으로 환경 변수에 직접 넣는 대신 초기 Setup Wizard에서 등록합니다. .env.example에 남아 있는 과거 PROXMOX_*_TOKEN_* 항목은 주석 또는 구버전 참고용이므로 그대로 사용하면 안 됩니다.

4-3. 이미지를 내려받고 실행

기본 docker-compose.yml은 Core 이미지를 사용합니다.

docker compose pull
docker compose up -d
docker compose ps

기본 구성에는 portal, celery-worker, valkey 서비스가 포함되어 있습니다. Docker Compose 파일에서 Portal의 8443 포트와 Packer 용도 8103 포트를 노출합니다.

docker compose logs --tail=100 portal
docker compose logs --tail=100 celery-worker

포트가 열려 있는지 서버에서 확인할 수 있습니다.

ss -lnt | grep -E ':(8443|8103)\b'

접속 주소는 다음과 같습니다.

https://<Portal-서버-IP>:8443

첫 실행 시 자체 서명된 HTTPS 인증서가 생성될 수 있습니다. Lab에서는 브라우저 경고의 인증서 정보를 확인해 접근할 수 있지만, 실제 운영 환경에서는 조직의 신뢰할 수 있는 인증서를 사용하는 것이 좋습니다.

5. 초기 Setup Wizard 진행하기

브라우저에서 처음 접속하면 초기 설정 마법사가 실행됩니다.

라이선스, 데이터베이스, 관리자 계정, Proxmox 연결 등을 설정하는 초기 마법사 — 출처: P3Portal-org/p3portal GitHub 공식 스크린샷

README의 진행 순서는 라이선스 → DB 선택 → 관리자 계정 → Proxmox 노드 연결 → API 토큰 → Packer 토큰(선택) → 완료입니다.

처음에는 SQLite로도 시작할 수 있지만, 여러 작업이 동시에 실행되는 운영 환경이라면 PostgreSQL 도입을 검토할 수 있습니다. 저장소 문서는 PostgreSQL 14 이상 지원을 안내합니다. 실제 배포 파일과 DB 백업 구성이 현재 버전에서 유효한지 별도로 확인해야 합니다.

6. Proxmox API 계정과 토큰 구성하기

여기서 가장 중요한 부분은 Proxmox 권한입니다. 포털 접속용 로컬 계정을 만드는 것과, 포털이 Proxmox API를 호출할 때 사용할 서비스 계정 및 토큰을 만드는 것은 서로 다른 작업입니다.

최신 Proxmox 계정 설정 가이드에서는 Viewer, Operator, Admin 세 계정을 기본으로 사용합니다. Packer는 필요할 때 추가합니다.

문서의 실제 명령어를 기준으로 Proxmox 노드에서 사용자와 역할을 생성할 수 있습니다. 아래 명령어는 새 Lab 환경용 예시입니다. 기존 계정이나 역할이 있다면 생성하지 말고 권한을 먼저 점검하세요.

# Proxmox 호스트에서 실행
pveum user add portal-viewer@pve --comment "P3 Portal Viewer"
pveum user add portal-operator@pve --comment "P3 Portal Operator"
pveum user add portal-admin@pve --comment "P3 Portal Admin"

pveum role add PortalViewer --privs "VM.Audit,VM.GuestAgent.Audit,Pool.Audit,Sys.Audit,Datastore.Audit"

pveum role add PortalOperator --privs "VM.Audit,VM.GuestAgent.Audit,VM.PowerMgmt,VM.Snapshot,VM.Config.CPU,VM.Config.Memory,VM.Config.Disk,VM.Config.Network,Datastore.Allocate,Datastore.AllocateSpace,Pool.Audit,Datastore.Audit"

pveum role add PortalAdmin --privs "VM.Audit,VM.GuestAgent.Audit,VM.PowerMgmt,VM.Snapshot,VM.Allocate,VM.Clone,VM.Migrate,VM.Backup,VM.Config.CPU,VM.Config.Memory,VM.Config.Disk,VM.Config.Network,VM.Config.HWType,VM.Config.Options,VM.Config.Cloudinit,VM.Config.CDROM,Datastore.Allocate,Datastore.AllocateSpace,Datastore.AllocateTemplate,Datastore.Audit,SDN.Use,SDN.Allocate,Pool.Audit,Sys.Audit,Sys.Modify,Sys.AccessNetwork"

역할을 각 사용자에 할당합니다.

pveum acl modify / --user portal-viewer@pve --role PortalViewer --propagate 1
pveum acl modify / --user portal-operator@pve --role PortalOperator --propagate 1
pveum acl modify / --user portal-admin@pve --role PortalAdmin --propagate 1

이 예시의 경로 /와 --propagate 1은 하위 리소스에도 권한이 전달될 수 있으므로, 운영 환경에서는 적용 범위를 충분히 검토해야 합니다.

API 토큰을 생성합니다.

pveum user token add portal-viewer@pve portal-viewer --privsep 0
pveum user token add portal-operator@pve portal-operator --privsep 0
pveum user token add portal-admin@pve portal-admin --privsep 0

토큰 Secret은 생성 시 표시되는 값을 안전하게 보관하세요. --privsep 0은 서비스 계정의 권한을 토큰이 그대로 상속하게 하는 설정입니다. 반드시 각각의 서비스 계정에 필요한 최소 권한만 부여했는지 확인해야 합니다.

만들어진 Token ID와 Secret은 Portal 초기 마법사의 Proxmox Tokens 단계에 입력합니다. 기존 설치라면 System Settings → Nodes → Edit node에서도 수정할 수 있습니다.

참고로 저장소 README의 간략한 권한 표에는 PVEAuditor나 Administrator 같은 이름이 남아 있지만, 상세 docs/proxmox-setup.md의 현행 설치 절차에서는 PortalViewer, PortalOperator, PortalAdmin을 사용합니다. 설치할 때는 같은 버전의 상세 가이드를 일관되게 따르는 편이 좋습니다.

7. 실제로 어떻게 활용할 수 있을까?

사례 A. VM과 노드를 한 화면에서 조회

처음 연결한 뒤 노드와 VM/LXC 목록이 나타나는지 확인합니다. VM별 CPU·메모리·스토리지 사용량, 전원 상태, 접근 가능한 관리 작업을 점검하는 용도입니다.

특히 대시보드의 VM IP가 비어 있다면 QEMU Guest Agent 설치 상태 및 VM.GuestAgent.Audit 권한을 확인하세요. 이 권한이 없으면 포털이 VM IP 정보를 제대로 조회하지 못할 수 있다는 내용이 공식 설정 문서에 나와 있습니다.

사례 B. Ansible로 VM 배포 작업 실행

입력 파라미터와 실행 로그를 활용하는 Ansible 자동화 화면 — 출처: P3Portal-org/p3portal GitHub 공식 스크린샷

P3 Portal에는 meta.yaml 기반의 파라미터형 Ansible 플레이북 실행 기능이 있습니다. 예를 들어 클라우드 초기화(Cloud-Init) 템플릿을 복제하고, VM 설정을 입력받는 업무를 GUI 형태로 구성할 수 있습니다.

저장소에는 다음과 같은 학습용 Starter Pack이 포함되어 있습니다.

# P3 Portal 저장소 루트에서 실행
cp -r examples/starter-pack/ansible/vm-clone-basic ansible/
cp -r examples/starter-pack/packer/debian-13-minimal packer/
docker compose restart portal

이 예제는 각각 기본 VM 템플릿 복제와 Debian 13 템플릿 빌드 흐름을 보여줍니다. 다만 개발자는 이를 운영용으로 강화된 배포 템플릿이 아닌 학습 예제라고 명시합니다. SSH 키, 비밀번호, 네트워크 구성과 권한을 운영 기준으로 바꾼 뒤 사용해야 합니다.

사례 C. Packer로 템플릿 자동 생성

Packer 빌드 작업과 진행 상태를 확인할 수 있는 화면 — 출처: P3Portal-org/p3portal GitHub 공식 스크린샷

반복적으로 VM을 만들 때는 OS 설치부터 템플릿화까지 자동화하고 싶을 수 있습니다. P3 Portal은 .pkr.hcl 정의를 사용한 Packer 빌드를 지원합니다.

이 기능을 사용하려면 일반 Portal 사용자 권한 외에 Packer 전용 Proxmox 토큰, ISO·스토리지 접근 권한, 게스트 설치용 HTTP/SSH 연결 등을 준비해야 합니다. 특히 Proxmox VE 8 이상에서는 ISO URL 다운로드에 Sys.AccessNetwork 권한이 필요할 수 있습니다.

Packer HTTP 서버가 VM에서 도달할 수 있어야 하므로, 네트워크 분리나 NAT 환경이라면 포트 8103 및 Portal 호스트 IP 구성을 먼저 확인해야 합니다.

8. 공개된 사용·설치 사례에서 참고할 문제

P3 Portal에 대한 장기 운영 후기나 독립적인 성능 벤치마크는 공개 자료에서 충분히 확인되지 않았습니다. 대신 실제 설치·사용 중 GitHub에 등록된 이슈를 보면 초기 도입 시 주의할 부분을 파악할 수 있습니다.

사례 1. Docker Compose 기본 구성에서 SQLite 잠금 발생

GitHub Issue #3에 한 사용자가 기본 Docker Compose 구성으로 운영하면서 다음 오류가 발생했다고 보고했습니다.

sqlite3.OperationalError: database is locked

보고자는 Portal API 프로세스와 Celery Worker가 동일 SQLite DB에 접근하는 구조를 원인 후보로 분석하고, WAL과 Busy Timeout을 사용하는 해결 방향을 제안했습니다. 해당 이슈는 완료 상태로 종료됐으며 이후 버전에서 수정 내용에 대한 개발자 설명이 남아 있습니다.

여기서 얻을 수 있는 운영상의 교훈은 DB를 단순 파일 하나로만 보고 방치하지 않는 것입니다. 다수 사용자·작업이 함께 실행되는 환경에서는 PostgreSQL 사용과 백업 정책을 고려하는 것이 좋습니다. 현재 배포 이미지에 이 문제가 남아 있다고 단정할 필요는 없습니다.

사례 2. 백업 스토리지가 없다고 표시되는 문제

GitHub Issue #2에는 VM의 백업 생성 대화상자에서 다음 메시지가 발생한다는 보고가 있습니다.

No backup storages configured on this node

개발자의 종료 코멘트에 따르면 실제 원인은 스토리지 부재가 아니라 Viewer 토큰에 Datastore.Audit 권한이 없었던 것입니다. Proxmox가 해당 API 호출에 빈 목록을 반환해 구분이 어려웠다고 설명합니다.

개발자는 v1.105.4-beta에서 수정했다고 안내했으며, 구버전에서 생성한 Viewer 역할은 다음 명령어로 권한을 갱신하도록 설명합니다.

pveum role modify PortalViewer --privs "VM.Audit,VM.GuestAgent.Audit,Pool.Audit,Sys.Audit,Datastore.Audit"

이처럼 빈 목록이 표시되더라도 실제 자원이 없다고 바로 판단하기보다는 API 서비스 계정의 권한부터 확인하는 것이 좋습니다.

사례 3. ZIP 플레이북 업로드 경로 검증 취약점

GitHub Issue #4에서는 압축 파일 내부의 절대 경로를 처리하는 과정에서 잘못된 위치로 파일을 쓸 가능성이 보고됐습니다. 개발자는 v1.74.6-beta에서 경로 검증과 역할 검사 문제를 수정했다고 밝혔고, 이후 v1.74.8-beta에서 관련 코드를 별도로 재구현했다고 설명했습니다.

이 이슈도 종료 처리됐습니다. 다만 업로드 기능처럼 서버 파일을 다루는 부분은 신뢰할 수 있는 관리자만 사용하도록 제한하고, 현재 실행 이미지의 버전과 코드가 수정 이후인지 확인하는 것이 안전합니다.

9. 운영 환경에 적용하기 전 체크할 부분

버전 고정과 업데이트

README의 기본 명령은 latest 이미지를 사용합니다. 이는 시작이 편리하지만 시간이 지나면 이미지 내용이 달라질 수 있습니다. 실제 운영에서는 사용한 이미지 태그나 이미지 digest를 기록해 두는 편이 좋습니다.

docker compose images
docker image inspect ghcr.io/p3portal-org/p3portal:latest --format '{{.Id}}'

업데이트 전에는 ./data와 설정, 직접 작성한 플레이북 및 템플릿을 백업합니다. GitHub 저장소의 릴리스 설명과 변경 사항도 확인하세요.

네트워크 접근 범위

프로젝트는 내부망 또는 VPN 사용을 전제로 합니다. 관리 권한을 가진 포털을 별도 접근 통제 없이 인터넷에 직접 공개하지 않는 편이 좋습니다. 관리용 TCP 8443, Proxmox API TCP 8006, 필요시 Packer TCP 8103의 통신 방향을 명확히 구분합니다.

자격 증명과 운영 권한

SECRET_KEY와 Proxmox API 토큰은 유출 시 영향이 큽니다. 별도 서비스 계정, 역할별 최소 권한, 토큰 교체 절차, 포털 관리자 2단계 인증을 운영 정책에 반영해야 합니다.

데이터 백업

기본 Compose는 ./data, ./ansible, ./packer를 사용합니다. Portal 데이터베이스·로그와 사용자 정의 자동화 파일이 손실되면 재구성에 시간이 걸립니다. DB 일관성을 보장하는 백업 방법으로 정기 백업하고, 복구 테스트도 진행해야 합니다.

10. P3 Portal은 누구에게 적합할까?

추천하는 경우

• Proxmox VM/LXC 운영과 반복적인 배포 작업을 한 곳에서 처리하고 싶은 환경

• CLI로 실행하던 Ansible과 Packer 작업을 웹 UI로 제공하고 싶은 환경

• 일반 관리자와 운영자의 권한을 분리하고 작업 이력을 남기려는 환경

• 오픈소스 기반 도구를 Lab에서 평가할 수 있는 팀

도입 전 추가 검토가 필요한 경우

• 여러 독립 클러스터를 통합 관리하려는 환경: Plus 라이선스 필요

• 상용 vCenter와 동등한 수준의 자동 DRS 기능을 기대하는 환경: P3 Portal의 HA 관리가 곧 DRS 제공을 의미하지는 않음

• 검증된 SLA·상용 기술 지원이 필요한 환경: Early Beta 상태와 지원 정책 확인 필요

• 외부 인터넷에서 직접 접근해야 하는 환경: 프로젝트가 안내하는 LAN/VPN 운영 범위를 벗어남

11. 정리

P3 Portal은 Proxmox에 없는 하이퍼바이저 기능을 마법처럼 추가하는 솔루션은 아닙니다. 대신 이미 있는 Proxmox API와 Ansible·Packer 도구를 운영자가 활용하기 쉬운 형태로 묶어주는 포털입니다.

처음 도입한다면 Core 설치 → Viewer/Operator/Admin 토큰 생성 → VM 상태 조회 → Starter Pack 자동화 → 권한·로그 점검 순서로 확인하는 것을 추천합니다.

네트워크와 스토리지 관리, VM 배포까지 실제로 변경하는 기능은 반드시 실서비스와 분리된 Lab에서 먼저 검증해야 합니다. 다중 클러스터와 선언적 인프라 배포를 원한다면 Core와 Plus 간 기능·라이선스 차이를 먼저 살펴보는 것이 좋겠습니다.

참고자료

• P3Portal-org/p3portal — 공식 GitHub 저장소

• P3 Portal 설치 및 기능 안내 — README

• Proxmox API 계정 및 권한 설정

• Starter Pack 사용 예제

• Core/Plus 라이선스 안내

• 실제 사용 사례: SQLite 잠금 이슈 #3

• 실제 사용 사례: 백업 스토리지 권한 이슈 #2

• 보안 이슈 및 수정 내역 #4

※ 스크린샷 4장은 프로젝트 공식 저장소에서 가져온 자료입니다. 직접 설치·운영한 결과 화면이 아닙니다. 작성 기준: 2026년 11월 8일.