NextPDF Connect 환경 진단 실행하기

한눈에 보기

실제 작업을 시작하기 전에 NextPDF Connect 서버가 정상이며 워크플로에 필요한 기능을 갖추고 있는지 확인합니다. 모든 에이전트 파이프라인에서 권장되는 첫 단계입니다. 서버 도구 레지스트리와 대조해 확인한 도구는 diagnostic.doctor, diagnostic.capabilities, diagnostic.verify입니다. 레지스트리는 이들을 점으로 구분된 프로토콜 이름으로 노출하며, 관련 도구인 diagnostic.inspect도 존재합니다. 모두 Core입니다.

설치

composer require nextpdf/server

트랜스포트를 바인딩합니다. veraPDF는 선택 사항인 규정 준수 검증 단계에서만 필요합니다. 구조 검증에는 외부 도구가 필요하지 않습니다.

개념 개요

• diagnostic.doctor는 기준 상태 보고서를 반환합니다. PHP 버전, 로드된 확장, 서버 버전, 활성 티어와 모든 경고가 포함됩니다. status를 게이트 기준으로 취급합니다. ok이면 진행하고, warning이면 warnings를 읽고, error이면 중단합니다.
• diagnostic.capabilities는 등록된 기능을 해당 티어 및 런타임 상태(available, unavailable, degraded)와 함께 나열합니다. 기능 수는 런타임 및 티어에 따라 달라지므로, 총개수를 하드코딩하지 마십시오. 워크플로가 의존하는 각 기능을 하나씩 확인합니다.
• diagnostic.verify는 구조적 무결성을 검사합니다. 검사 대상은 PDF 헤더, EOF 마커, 상호 참조 테이블입니다. 이는 페이지 트리를 통해 도달하는 문서 구조입니다(ISO 32000-2 §7.5). compliance_flavour를 지정하면 veraPDF도 호출합니다.

진단 결과는 모든 트랜스포트에서 통상적인 응답입니다(PSR-18 §p2).

API 표면

도구	역할	위험 티어
diagnostic.doctor	환경 상태 보고서	Safe
diagnostic.capabilities	상태가 포함된 기능 목록	Safe
diagnostic.verify	구조 / 규정 준수 검증	Safe
create_pdf, add_text, output_pdf	문서 스모크 테스트	다른 곳에 문서화된 대로

이 이름들은 레지스트리의 프로토콜 이름입니다. 도구 카탈로그가 기준이 되는 카탈로그입니다. 설치된 티어에 따라 존재하는 도구와 기능이 달라지므로, 도구나 기능의 개수가 고정되어 있다고 단언하지 마십시오.

코드 샘플 — 빠른 시작

1. diagnostic.doctor(인수 없음) → status를 읽습니다.
2. diagnostic.capabilities(인수 없음) → 필요한 각 기능이 available인지 확인합니다.
3. create_pdf 다음 add_text → 최소 스모크 문서를 만듭니다.
4. document_id를 사용한 diagnostic.verify → 구조 검사를 수행합니다.
5. 선택적으로 compliance_flavour: "4"를 사용한 diagnostic.verify → veraPDF를 실행합니다.
6. output_pdf(base64) → 스모크 세션을 폐기합니다.

코드 샘플 — 프로덕션

diagnostic.doctorstatus 값을 기준으로 파이프라인을 게이트합니다. 각 워크플로 의존성을 특정 기능 id에 매핑하고, 의존 단계에 들어가기 전에 available인지 확인합니다. degraded는 스폿 체크가 필요한 품질 위험으로 취급합니다. 구조 검사 diagnostic.verify는 항상 실행합니다. 규정 준수 변형은 적합성이 중요한 경우에만 실행하고, veraPDF가 없으면 서버 결함이 아니라 명확한 not-found 결과를 반환한다는 점을 받아들입니다.

엣지 케이스 및 주의 사항

• veraPDF 없음. 규정 준수 호출은 명시적인 not-found 결과를 반환합니다. 구조 검사는 계속 작동합니다. 규정 준수 검증이 필요하면 veraPDF를 설치하고 서버 프로세스의 PATH에 추가합니다.
• veraPDF 시간 초과. 큰 문서는 검증 시간 초과를 유발할 수 있습니다. 문서 크기를 줄이거나 서버 설정에서 시간 초과를 늘립니다.
• degraded 기능. 의존성이 부분적으로만 사용 가능하므로 출력 품질이 저하될 수 있습니다. 어떤 폴백이 사용 중인지 확인하려면 서버 로그를 확인합니다.
• Doctor error. 중요한 요구 사항이 충족되지 않았습니다. 진행하지 마십시오.

성능

구조 검증은 빠릅니다. 규정 준수 경로는 veraPDF를 실행하며 검증 시간 초과로 제한됩니다. 넉넉한 예산은 해당 하위 프로세스를 반영합니다.

보안 참고 사항

진단 출력은 환경 세부 정보를 드러냅니다. PHP 버전, 확장, 티어가 포함됩니다. 이를 운영자 전용으로 취급하고, 신뢰할 수 없는 호출자에게 노출하지 마십시오.

적합성

진술	사양	절	reference_id
진단 결과는 통상적인 트랜스포트 응답입니다.	PSR-18	§p2
구조적 무결성은 페이지 트리에 고정된 구조를 대상으로 합니다.	ISO 32000-2	§7.5

규정 준수 변형은 veraPDF를 실행하고 그 판정을 보고합니다. NextPDF는 적합성을 직접 단언하지 않습니다. 검증기가 판정합니다.

상업적 맥락

해당 없음 — 모든 진단 도구는 Core입니다.

트랜스포트 가용성

트랜스포트	가용	참고
MCP (stdio)	예	진단 결과는 도구 결과입니다.
REST	예	상태 엔드포인트가 이 도구들에 매핑됩니다.
gRPC	예	단항(Unary) 호출이며, 결과는 동일한 상태 필드를 전달합니다.

HITL 위험 티어

세 가지 진단 도구는 모두 Safe입니다. 읽기 전용이며 부작용이 없습니다. 이들은 확인 게이트를 트리거하지 않습니다. 스모크 테스트 output_pdf는 base64 모드입니다(Review, 게이트 없음).

확인 게이트 JSON 엔벨로프

진단에는 게이트가 적용되지 않습니다.

{ "allowed": true }

관련 항목

• Hello world
• 레이아웃 검사
• 도구 카탈로그