시작하기

1.0 최신 릴리스 기준

현재 공개 제품 버전은 2.0.0입니다.
단일 노드 배포 뒤 purecvisorsd는 항상 active여야 하고, NGINX는 선택형 외부 TLS 종료 모드에서만 active 조건입니다.
선택한 모드의 /api/v1/health, /api/v1/version과 BPF 상태 검사가 통과해야 합니다.

2026-09-16 공개 현황: 공개 소스 5e84387에 VM 삭제 NVRAM 보존 수정, e028ef2에 선택형 LXC Btrfs·저장소 identity·영구 Job 결과와 LXC 7 CPU 가중치가 반영됐습니다.
초기 2.0.0 태그는 ZFS 전용 LXC이며 현재 main과 설치 commit으로 구분합니다.
버전·Single Edge 범위는 유지합니다.

지정 공개 소스 검증은 통과했지만 전체 소스 감사와 지원 환경 인증은 미완료이며, 전체 감사 판정은 FAIL(미완료)입니다.
회차별 결과와 GPU Passthrough 영상의 검증 범위는 품질 게이트의 공개 현황을 따릅니다.

검증 운영 문서: 개발 단계별 검증 기준은 DEVELOPMENT_VERIFICATION_POLICY.md를 참조하세요.
이 문서는 Level 1 로컬 코드 검증부터 Level 4 출시 게이트까지의 공식 규칙을 정의합니다.

1.1 PureCVisor란?

PureCVisor Single Edge는 C23 기반 KVM 하이퍼바이저 오케스트레이터입니다.
단일 프로세스 데몬 purecvisorsd가 fork 없이 GMainLoop 이벤트 루프로 동작하며, VM, 컨테이너, 스토리지, 네트워크를 통합 관리합니다.

핵심 특징:

특징	설명
단일 프로세스 아키텍처	fork 없이 GMainLoop + GTask 스레드 풀로 동작
클라이언트 인터페이스	CLI + Web UI
에디션 전용 RPC 집합	GHashTable O(1) 디스패치, 플러그인 동적 확장
REST API	JWT HS256 + RBAC + VM owner-scope + CORS + gzip 압축
Prometheus 메트릭	내장 exporter 기반 상태 노출
배포 형태	Single Edge (독립 노드)
C23 코드베이스	Single Edge 데몬, CLI, Web UI, 테스트, 운영 스크립트

1.2 아키텍처 개요

purecvisorsd는 API transport, dispatcher, 도메인 핸들러와 서비스 모듈을 한 프로세스에 두고 GMainLoop가 전체 수명주기를 소유합니다.
짧은 작업은 이벤트 루프에서 응답을 끝내고, 긴 작업만 제한된 GTask 워커 풀로 보냅니다.
아래 탭에서 실제 TLS 배포 모드를 선택하면 클라이언트와 부팅 입력부터 로컬 영속 상태와 Linux/KVM 호스트까지 이어지는 Single Edge 전체 구조를 해당 진입 경계로 확인할 수 있습니다.
기본 선택은 NGINX가 없는 purecvisorsd 직접 HTTPS 모드입니다.
마우스를 사용하는 환경에서는 SVG의 서비스 레이어 또는 컴포넌트에 포인터를 올려 직접 연결된 화살표의 흐름을 강조할 수 있습니다.

purecvisorsd 직접 HTTPS NGINX 외부 TLS 종료

Single Edge · purecvisorsd 직접 HTTPS

기본 · NGINX 없음 확대해서 보기 ↗

purecvisorsd가 외부 :443의 HTTPS와 WebSocket TLS를 직접 종료하는 기본 모드입니다.
별도 NGINX 프로세스가 없습니다.

Single Edge · NGINX 외부 TLS 종료

선택형 · host-loopback 확대해서 보기 ↗

NGINX가 외부 :443을 소유하고 purecvisorsd의 loopback REST·WebSocket으로 전달하는 선택형 모드입니다.
ADR-0029의 host-loopback 신뢰 경계가 성립하는 전용 호스트에서만 사용합니다.

1.2.1 런타임·접근 경계

• 사용자와 외부 소비자: Web UI, pcvctl, REST API client, 선택형 gRPC client와 Prometheus scraper가 단일 노드에 접근합니다.
• 기본 HTTPS 모드: purecvisorsd가 외부 :443의 REST·WebSocket TLS를 직접 종료합니다.
  HTTP listener는 loopback 복구 경로로 제한합니다.
• 선택형 NGINX 외부 종료 모드: NGINX가 외부 :443을 소유하고 127.0.0.1의 daemon REST·WebSocket으로 전달합니다.
  두 모드가 같은 주소의 :443을 동시에 소유하지 않습니다.
• 부팅 입력: daemon.conf, secret source와 Kernel LSM 목록이 bootstrap 정책, transport, BPF 준비 상태를 결정합니다.
• 프로세스 내부 transport: root 전용 UDS JSON-RPC, libsoup3 REST, 기본 비활성인 선택형 gRPC와 WebSocket event channel은 별도 서비스가 아니라 purecvisorsd 내부 진입점입니다.
  선택형 외부 종료 모드의 NGINX만 별도 프로세스입니다.

1.2.2 요청·권한·완료 흐름

1. pcvctl은 로컬 UDS로, Web UI와 REST client는 선택한 HTTPS 모드로 요청합니다.
   선택형 gRPC는 token과 고정 caller role을 검증한 뒤 같은 RPC 정책으로 수렴합니다.
2. transport가 인증 주체를 확정하면 dispatcher가 method policy, RBAC와 VM·컨테이너 owner-scope를 검사합니다.
3. dispatcher는 GHashTable에서 O(1)로 도메인 핸들러를 찾아 검증된 요청만 전달합니다.
4. 짧은 작업은 canonical JSON-RPC 응답으로 즉시 완료합니다.
5. 긴 작업은 Job ID가 포함된 accepted 응답을 먼저 보내고 제한된 GTask 워커에서 실행합니다.
   상태 registry를 사용하는 경로만 pcv_jobs.db 행을 생성하며, 일부 경로는 합성 Job ID를 사용합니다.
6. worker callback은 실제 결과를 경로별 상태 저장소, pcv_audit.db, daemon log와 WebSocket 완료 이벤트에 남깁니다.
   클라이언트는 WebSocket 또는 polling으로 최종 상태를 확인하며, accepted 응답은 실제 성공을 뜻하지 않습니다.

1.2.3 서비스 도메인

• Workload: VM, LXC 컨테이너와 ZFS/Btrfs 저장소 처리, template과 GPU 연결
• Network: Linux bridge, Local VPC, OVS·OVN, Security Group과 QoS
• Storage: ZFS, snapshot, backup·restore, iSCSI와 cloud job
• Security: JWT, TOTP, RBAC, audit, HIDS·HIPS와 BPF LSM audit
• Monitoring: host telemetry, process status와 Prometheus metrics
• Operations: telemetry, alert, Web Push, AI healing과 plugin

Monitoring 경로는 handler_monitor, telemetry, process monitor와 eBPF telemetry가 제공하는 host·process 관측값을 조회합니다.
공개 소스에는 systemd D-Bus availability writer나 별도 Monitoring SQLite DB가 없습니다.

1.2.4 영속 상태와 호스트 통합

PureCVisor는 외부 DBMS 없이 로컬 SQLite WAL 데이터베이스 9개와 파일 기반 desired state를 사용합니다.

• Core·identity·security·network DB 7개: vm_state.db, pcv_audit.db, pcv_jobs.db, rbac.db, pcv_security.db, security_groups.db, vpc.db
• Operations DB 2개: cloud_jobs.db, pcv_webpush.db
• Desired state: network, overlay, QoS, BPF와 backup 설정
• Virtualization: libvirt, QEMU, KVM과 LXC
• Storage: qcow2/raw, 선택형 ZFS, LXC Btrfs rootfs·snapshot, LIO와 open-iscsi
• Network host: Linux bridge, nftables, dnsmasq, WireGuard, tc, eBPF, OVS와 OVN
• Host security: Kernel LSM, bpffs, Suricata, systemd, journald, cgroups와 PSI
• Acceleration: GPU, SR-IOV와 선택형 DPDK

SQLite는 의도, 작업 상태와 증거를 보존하지만 libvirt domain, ZFS dataset, LXC Btrfs rootfs·identity·복원 journal, bridge, nftables, OVS·OVN과 bpffs의 actual state를 대신하지 않습니다.
DB 사이의 분산 트랜잭션이나 노드 간 복제도 제공하지 않으므로, 재시작과 복원 뒤에는 각 도메인의 reconcile과 실제 시스템 상태를 함께 확인해야 합니다.
DPDK는 선택형 가속 경로이며 현재 BPF LSM hook은 기존 LSM 결정을 바꾸지 않는 audit-only 경계입니다.

1.2.5 Single Edge 경계와 상세 문서

이 구조는 독립 Linux/KVM 노드 하나와 purecvisorsd 제어면 하나만 설명합니다.

• SQLite 파일별 책임, schema, 일관성·백업·복구 경계: 데이터베이스 아키텍처
• TLS 모드와 설치 절차: 설치 및 환경 구성
• REST 인증과 endpoint: REST API
• 현재 공개판 포함·제외 기준: PUBLIC_RELEASE_BOUNDARY.md

1.2.6 검증 문서 맵

문서 역할은 다음처럼 나눠서 봐야 합니다.

문서	역할
DEVELOPMENT_VERIFICATION_POLICY.md	개발 단계별 검증 규칙, Level 1~4 운영 기준
ADR_INDEX.md	ADR별 현재 Single Edge 적용 상태
docs/adr/	설계 결정과 예외 규칙의 단일 진실
DATABASE_STRUCTURE.md	SQLite DB 9개와 영구 테이블 26개의 책임, schema와 복구 경계
PUBLIC_SOURCE_POLICY.md	공개 소스 주석 제거와 소스맵 제외 정책

1.2.7 설계 결정 빠른 보기

운영 가이드 본문에서 ADR-0023처럼 표시되는 항목은 단순 참고 문구가 아니라 기능의 허용 조건과 예외 규칙이다.
통합 ui/docs.html reader는 같은 릴리스의 본문과 ADR 참조를 빠짐없이 표시하며, 설계 결정의 정본은 docs/ADR_INDEX.md와 docs/adr/에서 확인한다.

설계 결정	먼저 봐야 하는 상황	현재 Single Edge 결론
fork 금지 단일 데몬	프로세스, event loop, worker lifecycle 변경	purecvisorsd 단일 프로세스와 GMainLoop 소유권을 유지하고 긴 작업만 bounded worker로 보낸다
비동기 결과 채널	Job ID, polling, WebSocket 완료 경로 변경	accepted 응답과 실제 완료 상태를 분리하고 Job ID 기반 결과 채널을 유지한다
REST/WS TLS 기본 활성	daemon 직접 HTTPS, 선택형 NGINX 외부 종료 변경	기본은 daemon 자체 TLS이며 외부 종료는 host-loopback 신뢰 경계의 명시적 opt-in으로만 허용한다
VM clone 오픈 베타 안전장치	VM clone, Guest reset, Prepared template, power on 거부 조건	source VM은 shut off 상태여야 하며, prepared template 또는 libguestfs 기반 Guest reset 중 하나가 필요하다
VM 생성 저장 위치 계약	VM 생성 저장소, zvol/qcow2/raw 위치 정책 변경	storage_type과 storage_pool 또는 image_dir 조합을 명시 계약으로 유지한다
RBAC UDS 우회 정책	권한, operator owner-scope, UDS/REST 보안 변경	REST 인증과 dispatcher method policy를 모두 유지하고 make check-rbac로 검증한다
fire-and-forget audit 기록 정책	장시간 RPC, worker callback, audit/WS completion 변경	accepted 응답은 완료가 아니며 worker callback에서 실제 결과 audit를 남긴다
JWT Bearer 전용 인증	REST 인증, CSRF, 브라우저 호출 모델 설명	쿠키 세션 대신 Authorization: Bearer <JWT>를 사용하고 별도 CSRF 토큰을 운영하지 않는다
프론트엔드 IIFE 모듈 스코프	Web UI 모듈, endpoint registry, sanitizer 변경	Vanilla JS를 유지하고 PCV.* 네임스페이스와 EP 레지스트리를 사용한다

1.3 Single Edge 공개 리포지토리

📦 공개 배포 저장소 — LinkedIn/GitHub 공개 시에는 민감정보 정리가 끝난 HEAD를 git archive로 추출해 새 공개 저장소의 첫 커밋으로 올립니다.
기존 개발 저장소의 .git 이력은 공개 저장소에 가져가지 않습니다.
공개 URL은 생성 후 <public-repo-url>로 확정합니다.

• 공개 배포 기준 바이너리: bin/purecvisorsd
• systemd 서비스: purecvisorsd.service
• /api/v1/health 기준 런타임 모드: cluster=false, node_name=standalone

이 가이드는 싱글 노드 운영과 출시 범위만 다룹니다.

공개 범위 핵심

1. 독립 노드 운영: purecvisorsd 하나로 VM, 컨테이너, 스토리지, 네트워크를 통합 관리합니다.
2. 수동/로컬 네트워크: OVS 오버레이와 OVN 로컬 SDN 코어는 포함되지만, 클러스터 자동화는 포함되지 않습니다.
3. 출시 게이트 재인증 완료: VM lifecycle, Storage, Network, Backup/Restore, Auth/RBAC, Single Edge OVN/OVS, Longrun 축이 다시 통과한 상태를 기준으로 정리합니다.

1.4 5분 퀵스타트

# 1. 서비스 시작
sudo systemctl start purecvisorsd   # Single Edge

# 2. 상태 확인
curl -s http://127.0.0.1:8080/api/v1/health | python3 -m json.tool

정상 응답 예시:

{
    "capabilities": {
        "ovn": true,
        "dpdk": false,
        "cluster": false
    },
    "status": "ok",
    "service": "purecvisorsd",
    "version": "2.0.0",
    "node_name": "standalone"
}

제품 버전과 canonical Git/GitHub 릴리스 태그는 2.0.0이다.
소스 기준 단일 값은 include/purecvisor/version.h의 PCV_PRODUCT_VERSION이며, /api/v1/health, /api/v1/version, pcvctl --version, Prometheus purecvisor_info, Web UI config와 HTML 정적 자산 query string은 같은 릴리스 단위로 맞춘다.
/api/v1 같은 API path, OpenAPI spec version, Prometheus text format version, 라이브러리 ABI symbol은 제품 버전이 아니므로 별도 계약으로 유지한다.

# 3. bootstrap admin으로 첫 인증 토큰 발급
# 첫 설치에는 내장 기본 비밀번호가 없습니다.
# daemon.conf 또는 PURECVISOR_ADMIN_PASSWORD로 bootstrap 비밀번호를 먼저 설정합니다.
TOKEN=$(curl -s -X POST http://127.0.0.1:8080/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<configured-admin-password>"}' | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")

echo "Token: $TOKEN"

# 4. VM 생성
pcvctl vm create web-prod --vcpu 2 --memory_mb 2048 --disk_size_gb 20

# 5. VM 시작
pcvctl vm start web-prod

# 6. VM 목록 확인
pcvctl vm list

# 7. Web UI 접속
echo "http://127.0.0.1:8080/ui/ (admin / configured password)"

1.5 접속 정보 요약

인터페이스	주소	인증
UDS 소켓	/var/run/purecvisor/daemon.sock	없음 (로컬)
REST API	http://127.0.0.1:8080/api/v1/	JWT HS256
HTTPS	https://localhost:443/api/v1/	JWT HS256 + TLS
Web UI	http://127.0.0.1:8080/ui/	bootstrap admin admin / configured password
WebSocket (이벤트)	ws://127.0.0.1:8080/api/v1/ws/events	JWT
WebSocket (VNC)	ws://127.0.0.1:8080/api/v1/ws/vnc	JWT
Prometheus	http://127.0.0.1:8080/api/v1/metrics	없음
Health	http://127.0.0.1:8080/api/v1/health	없음

1.6 수동 RPC 테스트

UDS 소켓을 통해 직접 JSON-RPC 요청을 보낼 수 있습니다.

# VM 목록 조회
echo '{"jsonrpc":"2.0","method":"vm.list","params":{},"id":"1"}' \
  | nc -U /var/run/purecvisor/daemon.sock | python3 -m json.tool

# 호스트 메트릭 조회
echo '{"jsonrpc":"2.0","method":"telemetry.host","params":{},"id":"1"}' \
  | nc -U /var/run/purecvisor/daemon.sock | python3 -m json.tool

---