Part.7 · PackrGUI·헤드리스 사용

용례 3: PackrGUI와 헤드리스 경로를 각각 검증하기

첫 연결 실습: 일반 사용자와 VM 관리자를 먼저 구분

목표: 이미 준비된 회사 VM에 내 클라이언트로 연결하고 같은 고객·설치 신원을 확인합니다. 이 실습은 Work를 자동 실행하지 않습니다. 회사에 VM이 아직 없다면 배포 담당자는 설치 안내 1–4절부터 진행하고, 일반 사용자는 설치 신원·준비 상태·접속 자료를 인계받습니다.

1. 관리자로부터 받아야 할 자료

호환 클라이언트의 실제 파일·지문·서명 상태, 고객·설치·릴리스 참조, 접속 endpoint와 TLS 서버명, 내 계정·기기 등록 방식, 허용 역할, 등록 만료/갱신 문의 경로를 받습니다. 릴리스가 기기별 프로필을 제공하면 조직의 안전한 전달 경로로 받습니다. 설명 페이지에 비밀키를 붙여넣거나 공통 설치 ZIP에 넣지 않습니다. 자동 등록 포털은 이 릴리스가 실제 제공할 때만 사용합니다.

2. OS별 설치와 실행 위치 확인

앱이 열리지 않으면 연결 실패가 아니라 앱 기동 단계로 기록합니다. OS의 정확한 경고, 앱 경로·버전·CPU와 동봉 파일을 확인하십시오. 운영체제 보안 설정 해제나 관리자 실행을 일반 해결책으로 사용하지 않습니다.

3. 연결·등록·신원 확인

1. 앱을 열고 해당 릴리스의 연결/프로필 선택 절차를 사용합니다. 새 서버를 추측하지 말고 관리자가 전달한 endpoint·TLS 서버명·프로필을 대조합니다.
2. 릴리스가 제공하는 사용자·기기 등록을 완료합니다. 단순 OS 로그인, 브라우저 복귀, 프로필 파일 선택만으로 등록 완료를 판단하지 않습니다. 만료 또는 미등록이면 관리자에게 그 상태를 전달합니다.
3. 제품이 표시한 고객·설치·릴리스와 관리자의 기대값을 대조합니다. 인증 상태와 서버 준비 상태를 따로 기록합니다. 다른 조직·설치가 보이면 접속을 중단합니다.
4. 처음에는 상태 조회만 확인합니다. 허용된 Work가 보이지 않으면 현재 역할·사용 권한을 관리자와 확인합니다. 일반 사용자에게 VM 관리자 로그인을 요구하지 않습니다.
5. 헤드리스도 사용할 사람만 해당 릴리스의 CLI·서비스 프로필로 별도 인증 상태를 조회합니다. GUI의 자격 증명을 임의 복사하거나 GUI 성공으로 헤드리스를 완료 처리하지 않습니다.

기대 결과: 실행한 클라이언트의 버전·경로, 같은 고객/설치 참조, 실제 인증 상태를 기록할 수 있습니다. 일반 사용자 등록이나 운영 연결이 해당 후보에서 아직 검증되지 않았다면 그 단계는 미확인으로 남습니다. 성공 화면을 가정해 채우지 않습니다.

막히면: 앱 기동 오류 → 패키지·OS 준비, 시간 초과/인증 거부 → 사례 C, 신원 변경 → 사례 B, 관리자 등록 문제 → 사례 D/E로 이동합니다. 실제 첫 Work는 별도의 첫 Work 용례를 따릅니다.

운영 목적

고객의 워크스테이션에서 GUI로 어플라이언스에 접속하고, 운영 자동화가 필요할 경우 릴리스가 제공한 별도의 헤드리스 경로를 확인합니다. 두 경로는 같은 고객 어플라이언스를 사용하더라도 설치 파일, 인증, 세션, 허용 기능과 결과 증거가 다를 수 있습니다.

예시 상황

운영자는 Mac의 PackrGUI에서 상태 화면을 볼 수 있습니다. 팀은 “그러면 Linux 서버의 헤드리스 작업도 준비됐다”고 말합니다. 이 결론은 검증되지 않았습니다. 각 클라이언트에서 직접 인증·설치 신원·기능을 확인해야 합니다.

경로별 확인표

실제 진행 순서

1. 각 플랫폼별 정확한 설치 파일을 릴리스 매니페스트와 대조합니다. Mac 패키지의 성공으로 Windows 패키지를 승인하지 않습니다.
2. GUI에서 서비스 응답, 인증 완료, 고객·설치 ID, 현재 허용 기능을 각각 확인합니다. 창이 열린 상태는 인증 완료가 아닙니다.
3. 헤드리스가 릴리스에 포함됐다면 별도의 공식 절차로 인증·연결·허용 범위를 확인합니다. GUI 자격 증명을 임의로 복사하지 않습니다.
4. 두 경로에서 같은 설치를 보는지 대조하되, 서로의 세션이나 권한을 자동으로 같다고 처리하지 않습니다.
5. 실제 Work를 수행할 때는 사용한 바로 그 경로의 최종 상태와 영수증을 확인합니다. 경로가 다르면 따로 기록합니다.

이번 릴리스가 packrctl을 제공할 때의 읽기 전용 확인

설치 담당자로부터 승인된 로컬 접근 경로를 받은 뒤, 설치 목록에 packrctl이 있는 경우 아래 명령으로 상태와 건강도를 읽으십시오. 권한 있는 어플라이언스 또는 관리 클라이언트에서만 실행합니다. 이 명령으로 GUI 세션을 인증하거나 Work를 승인할 수는 없습니다.

packrctl status --json > headless-status.json
packrctl health --json > headless-health.json

셸 종료 상태뿐 아니라 JSON의 준비 상태와 사유를 읽으십시오. UNKNOWN은 READY가 아닙니다. 정확한 전달 목록에 packrctl이 없으면 개발용 바이너리를 가져오지 말고 헤드리스 경로를 미제공으로 기록합니다.

실패 분기

한 경로만 실패하면 성공한 경로의 설정을 복제하기 전에 연결·인증 사례로 실패 지점을 분류합니다. 호스트 신원 경고는 신원 사례에서 즉시 중지합니다.

완료 기준

각 경로의 설치 파일·연결·인증·설치 ID·사용할 기능을 직접 확인한 뒤에만 해당 경로를 검증됨으로 기록하십시오.

제공된 구성요소 확인

플랫폼마다 전달 목록의 설치 파일 이름·서명·지원 버전·연결 방식을 확인하십시오. 설치 후에는 서버 신원, 인증 세션, 일치하는 고객·설치 ID를 기록합니다. 해당 플랫폼의 설치 파일이나 헤드리스 클라이언트가 목록에 없다면 다른 패키지를 사용하기 전에 공급자가 제공하는 지원 경로를 확인하십시오.

상세 시나리오: GUI만 연결되는 상황

Mac의 PackrGUI가 같은 설치 ID를 보여 주지만 서버 자동화 작업은 접속하지 못한다고 가정합니다. GUI의 인증 계정, 토큰 유효기간, 네트워크 경로는 자동화 서비스의 것과 다를 수 있습니다. GUI 화면을 캡처해 헤드리스 인증 성공으로 제출하지 마십시오. 헤드리스가 해당 릴리스의 제공 목록에 있는지부터 확인하고, 있다면 그 경로의 계정·주소·거부 사유를 별도로 기록합니다.

반대로 헤드리스 상태 조회가 성공해도 GUI 화면이 열리고 현재 세션에 같은 권한이 있는지 알 수 없습니다. 두 경로의 마지막 확인 단계가 다르면 가장 뒤처진 경로를 정확히 표시합니다. 예를 들어 GUI는 인증·신원 일치, 헤드리스는 네트워크 도달만 확인으로 적습니다.

플랫폼별 검증 기록 양식

실증 전에는 미확인으로 적습니다. 한 칸의 성공을 다른 운영체제나 경로에 복사하지 마십시오.

운영 중 사용할 구체적인 진행 예

예를 들어 데스크톱 GUI는 정상인데 예약 자동화가 거부됩니다. GUI 사용자 세션과 자동화 서비스의 실행 위치·사용 계정·네트워크 경로·설치 범위가 각각 같은지 확인합니다. GUI의 토큰이나 키를 자동화에 복사하지 말고 해당 릴리스가 제공하는 서비스 인증 절차를 사용합니다.

이 용례를 마칠 때 대조할 기록

GUI와 헤드리스의 설치 파일·버전·인증 결과·설치 ID·허용 기능·상태 조회 결과를 한 표의 별도 행으로 남깁니다. 어느 한 경로가 미제공이면 그대로 기록하고 실제 Work 영수증은 실행한 경로에 연결합니다.

계획한 절차, 실제 수행한 동작, 확인된 결과와 남은 단계를 구분해 기록하십시오. 위 상황은 이해를 위한 예시이며 이 문서 갱신에서 고객 환경의 실행이 이루어진 것은 아닙니다.

사용 용례 색인으로 돌아가기

용례 2: 로컬 런타임 변경 후 자동 재바인딩

운영 목적과 선행 조건

고객이 이미 승인한 설치·런타임 범위 안에서 로컬 모델의 별칭 또는 런타임 관찰값이 바뀌었을 때, Core가 새 관찰을 검증해 바인딩을 갱신하는 흐름입니다. 현재 설치 신원, 관리자 범위, 지원 모델과 변경 전 바인딩 상태를 먼저 확보합니다.

예시 상황

운영자가 로컬 모델의 별칭을 바꿉니다. 모델 서버는 실행 중이지만 PackrGUI는 과거 바인딩 시각을 보여 줍니다. 이 시점의 “모델이 응답한다”는 사실만으로 새 모델의 바인딩을 완료했다고 말할 수 없습니다.

변경 전·후 확인표

순서대로 진행

1. 변경 내용과 시각을 기록합니다. 기존 바인딩을 삭제하거나 내부 상태 저장소를 직접 고치지 않습니다.
2. 릴리스 위자드가 제공하는 감지·재관찰 경로에서 새 런타임이 발견되는지 확인합니다.
3. 현재 관리자가 승인한 고객·설치·런타임 범위 안인지 확인합니다. 범위 밖이면 자동 적용을 기대하지 않고 관리자 결정을 받습니다.
4. 제품의 감지 → 검증 → 바인딩 상태와 거부 사유를 순서대로 읽습니다. 여러 후보 모델 중 대상이 모호하면 임의 선택하지 않습니다.
5. 새 바인딩의 모델 참조, 설치 ID, 기록 시각이 변경 이후인지 확인합니다. 이때만 바인딩 갱신을 기록합니다.
6. 실제 Work와 영수증은 별도로 실행·검증합니다. 영수증 부재 사례를 참고하십시오.

실패 분기와 지원 자료

감지되지 않으면 런타임 실행·공식 연결 경로를 확인합니다. 검증이 거부되면 바인딩 사례에 따라 범위·신원·모호성을 분리합니다. 지원 요청에는 변경 전후 상태·시각·설치 ID·제품 거부 문구만 전달하고 내부 저장소나 고객 프롬프트는 보내지 않습니다.

완료 기준

현재 변경에 대한 새 관찰과 Core의 새 바인딩이 같은 설치 신원으로 기록돼야 합니다. 이것은 Work 결과 또는 macOS·Windows 자동 바인딩 검증을 뜻하지 않습니다.

상세 시나리오: 모델 별칭만 바뀐 경우

예를 들어 10:00에 로컬 런타임의 별칭을 모델-A에서 모델-B로 바꿨다고 가정합니다. 09:40의 바인딩됨 기록은 변경 전의 증거입니다. 운영자는 10:00의 변경 기록과 이후 새 감지 시각을 나란히 놓고, Core가 같은 설치 ID와 승인 범위로 새 모델 참조를 검증했는지 봅니다. 별칭만 변경돼도 여러 후보가 동시에 보이면 임의로 하나를 선택하지 않습니다.

새 바인딩이 나오지 않는다면 단계별로 분류합니다. 런타임 자체가 발견되지 않으면 서비스 준비와 공식 연결 경로를 확인합니다. 발견은 됐으나 범위 밖이면 승인 소유자에게 넘깁니다. 검증은 됐으나 모델 대상이 모호하면 정확한 모델 선택을 요구합니다. 이전 바인딩 화면의 시각만 갱신돼 보인다면 새 바인딩으로 선언하지 않습니다.

변경 기록 예시

시각과 모델명은 절차 설명용 가상 값입니다. 실제 Work는 해당 바인딩 이후의 별도 기록으로 확인하십시오.

운영 중 사용할 구체적인 진행 예

예를 들어 유지보수 창에서 모델 별칭과 런타임 주소 중 하나만 바꿉니다. 변경 전 지원 버전, 바인딩 참조와 마지막 상태를 보관하고 변경 후 새 관찰이 어느 값에 연결됐는지 대조합니다. 온라인 확인 성공이나 로컬 프로세스 재시작만으로 새 바인딩이 적용된 것으로 판단하지 않습니다.

이 용례를 마칠 때 대조할 기록

변경 전후 런타임·모델 참조, 관찰 시각, 검증 사유, 적용된 바인딩과 이후 별도로 수행한 승인 Work를 구분합니다. 되돌림도 제품이 다시 관찰·검증한 결과를 확인합니다.

계획한 절차, 실제 수행한 동작, 확인된 결과와 남은 단계를 구분해 기록하십시오. 위 상황은 이해를 위한 예시이며 이 문서 갱신에서 고객 환경의 실행이 이루어진 것은 아닙니다.

사용 용례 색인으로 돌아가기

용례 5: 첫 Work를 실행하고 결과·영수증을 검증하기

운영 목적과 시작 조건

고객이 지원되는 Pack 또는 릴리스가 지정한 시험 작업 한 건을 제품의 통제된 경로로 실행하고, 같은 설치·Work ID의 최종 결과와 영수증을 확인합니다. 서비스 준비, 인증된 연결, 관리자 범위, 현재 런타임 바인딩이 먼저 확인돼야 합니다.

예시 상황

운영자가 “Qwen이 바인딩됐으므로 첫 Work가 끝났습니다”라고 보고합니다. 검토자는 “Work ID, 실행 승인, 모델 호출, 결과 검증, 영수증이 같은 작업에 연결됐습니까?”라고 확인합니다. 아직 Work를 제출하지 않았다면 보고할 수 있는 상태는 런타임 준비까지입니다.

단계별 확인표

실제 진행 순서

1. 승인된 대상 한 건을 고르고 실행 계획·대상 환경을 확인합니다. Builder 후보를 승인 Pack으로 취급하지 않습니다.
2. 고객이 허용한 사용자 승인 경로를 완료합니다. passkey 등록·브라우저 복귀·실제 Work 승인은 서로 다른 단계입니다.
3. Work 제출 후 제품이 기록한 ID를 확보하고, 그 ID의 승인·시작·실행 상태를 순서대로 읽습니다.
4. 로컬 AI 모델을 사용한 경우, 일반적인 모델 응답이 아니라 그 Work에 연결된 호출을 확인합니다.
5. 결과 검증, 실패·롤백 여부, 최종 영수증을 같은 릴리스·설치·Work ID에 결합합니다. 실패·중단·롤백은 성공으로 바꾸어 쓰지 않습니다.
6. 영수증이 없으면 영수증 부재 사례의 마지막 확인 상태부터 조사합니다. 기록을 수동으로 생성하지 않습니다.

승인된 설치에서만 사용하는 조건부 CLI 예시

전달받은 릴리스가 packrctl과 CREATE_AUDIT_ARTIFACT 작업을 제공한다면, 이 Work 한 건의 승인과 어플라이언스의 권한·사전 조건을 확인한 뒤에만 아래 예시를 사용하십시오. 키는 승인받은 미사용 값으로 바꿉니다. 이 작업은 로컬 감사 산출물을 만들며 첨부 고객 문서를 감사하거나 Qwen 모델을 호출하지 않습니다.

packrctl work run CREATE_AUDIT_ARTIFACT "create audit artifact" \
  "REPLACE_WITH_ONE_UNUSED_APPROVED_KEY" --json > work-run.json
# 반환된 result.work.work_id를 복사합니다. Work ID를 만들지 마십시오.
packrctl work show "PASTE_RETURNED_WORK_ID" --json > work-show.json

반환 기록에서 타입 결과·최종 상태·검증·영수증 참조·사람의 최종 수락 상태를 따로 확인하십시오. 종료 코드나 JSON 파일 생성만으로 성공 영수증이 되지 않습니다. 결과가 불확실하면 work run을 다시 내지 말고 원래 요청을 제품이 지원하는 경로로 대조하십시오.

지원 요청과 완료 기준

지원 요청에는 릴리스·설치·Work ID, 사용 Pack/작업의 공개 가능한 이름, 마지막 확인 단계, 최초 오류, 영수증 상태만 적습니다. 프롬프트·고객 데이터·원시 결과는 일반 티켓에 넣지 않습니다. 완료: 승인된 같은 Work의 성공 최종 상태, 검증된 결과, 영수증이 함께 확인됩니다.

상세 시나리오: 모델은 응답하지만 Work 영수증이 없는 경우

운영자가 로컬 모델의 응답을 확인하고 “첫 Work 성공”이라고 보고하려 한다고 가정합니다. 먼저 Work ID가 있는지 확인합니다. ID가 없다면 제품에 Work가 접수됐다는 증거부터 없습니다. ID가 있어도 승인, 시작, 모델 호출, 결과 검증, 최종 상태가 각각 기록됐는지 읽습니다. 모델의 일반 응답은 특정 Work에 묶인 호출을 대신하지 않습니다.

예를 들어 로컬 모델 별칭을 바꾼 뒤 GUI에는 새 BOUND가 보이지만 Work 준비는 UNKNOWN일 수 있습니다. 현재 설치가 보여 주는 권한·런타임·Work 준비 상태와 정확한 사유 코드를 기록하십시오. 필요한 준비 상태가 확인될 때까지 Work를 제출하지 말고, UNKNOWN이 계속되면 그 값을 릴리스 지원 경로로 전달하십시오. 아래 표에는 자신의 첫 Work 기록을 채웁니다.

한 건의 Work 증거표

실패·중단·롤백 결과를 영수증 파일의 존재만으로 성공 처리하지 않습니다. 문제를 전달할 때는 처음 빠진 관문을 보고하고 원문 프롬프트와 결과물은 일반 지원 요청에 포함하지 마십시오.

운영 중 사용할 구체적인 진행 예

예를 들어 승인된 읽기 작업 한 건을 계획합니다. 실행 직전 동일 설치·Pack·입력·현재 권한과 계획을 확인하고 반환된 실제 Work ID를 보관합니다. 연결 문제로 결과가 늦게 보이더라도 같은 ID의 조회 경로를 사용하며, 결과를 얻기 위해 새 Work를 중복 실행하지 않습니다.

이 용례를 마칠 때 대조할 기록

최종 상태, 후조건 검증, 결과 지문, Work 기록과 영수증이 모두 같은 실행을 가리키는지 확인합니다. 실패·롤백·대기·미확인은 각각 기록하고 모델의 독립 응답을 제품 영수증으로 대체하지 않습니다.

계획한 절차, 실제 수행한 동작, 확인된 결과와 남은 단계를 구분해 기록하십시오. 위 상황은 이해를 위한 예시이며 이 문서 갱신에서 고객 환경의 실행이 이루어진 것은 아닙니다.

사용 용례 색인으로 돌아가기

사용 용례: 설치 이후 실제 운영 흐름

상황별 시작점

읽는 방법

각 용례는 상황 → 선행 조건 → 실제 진행 순서 → 실패 분기 → 완료 증거로 구성했습니다. 여러 증상이 동시에 보이면 마지막으로 확인된 상태부터 선택하십시오. 오류 해결은 사례 색인에서 증상별로 찾을 수 있습니다. 지원 요청에는 오류 원문과 릴리스·설치 신원처럼 최소 정보만 넣고 고객 데이터·비밀값은 제외하십시오.

담당자와 산출물로 용례를 선택하기

온라인 환경은 승인된 네트워크·제공자 경로를 사용하는 구성이고, 폐쇄형 온프렘은 필요한 설치 자산·모델·문서 등을 사전에 반입하는 구성입니다. 어느 쪽도 이 안내서가 제품의 기본값으로 고정하지 않습니다. SDK의 선택 Rust 의존성 세트는 SDK 어댑터 빌드의 Rust 범위를 준비하며 어플라이언스 이미지·모델 가중치·제공자 자격 증명·모든 OS 개발 도구를 대신하지 않습니다.

지원 인계 양식의 예: 릴리스·구성요소·OS, 시각과 시각대, 마지막 확인 단계, 최초 거부 원문, 수행한 변경, 현재 결과, 다음 담당자. 미확인·거부·대기·실패·완료를 같은 상태로 합치지 않습니다. 비밀값과 고객 내용은 첨부하지 않습니다.

설치·첫 사용 매뉴얼로 돌아가기