운영자가 가장 자주 마주치는 문제에 대한 진단 노트입니다. 각 섹션은 증상, 원인, 수정 사항을 명시합니다. 전체 플래그 및 환경 변수 표면은 CLI 참조와 구성을 참조하세요.
엔진이 시작되지 않음
TLS 인증서 생성 실패
증상: 엔진이 데이터 디렉토리를 참조하는 쓰기 오류와 함께 부팅 시 종료됩니다.
--tls-cert/--tls-key가 제공되지 않으면 엔진은 리스너가 연결을 수락하기 전에 데이터 디렉토리에 자체 서명 인증서를 생성합니다. 데이터 디렉토리가 읽기 전용이거나 존재하지 않으면 쓰기가 실패하고 프로세스가 종료됩니다.
수정: --data-dir(또는 OLIVARES_DATA_DIR, ./olivares-data로 폴백)로 지정된 경로가 쓰기 가능하고 영구적인 디렉토리를 가리키는지 확인하세요. 또는 --tls-cert와 --tls-key로 자체 인증서를 제공하여 생성이 시도되지 않게 하세요.
Postgres 역할이 권한 있음
증상: 엔진이 슈퍼유저 또는 BYPASSRLS 역할에 대한 메시지와 함께 종료됩니다.
Postgres 스토어는 FORCE ROW LEVEL SECURITY로 테넌트 격리를 시행합니다. 슈퍼유저 또는 BYPASSRLS 역할은 모든 RLS 정책을 조용히 우회하므로, 엔진이 이에 대해 시작을 거부합니다.
수정: 자체 데이터베이스를 소유하는 전용 최소 권한 역할(NOSUPERUSER NOBYPASSRLS NOCREATEROLE NOCREATEDB)을 프로비저닝하세요. 단일 테넌트 또는 일회용 환경에서 가드를 진정으로 재정의해야 하면 --allow-privileged-db-role을 전달하세요. 전체 Postgres 설정은 자체 호스팅을 참조하세요.
비루프백 바인드에서 —seed-demo
증상: 엔진이 127.0.0.1에 바인딩하라는 오류와 함께 종료됩니다.
--seed-demo는 비밀번호가 공개(소스 트리에 있음)인 데모 관리자를 프로비저닝합니다. --listen 또는 --grpc-listen이 비루프백 주소에 바인딩되면 엔진이 시작을 거부합니다.
수정: 루프백(127.0.0.1)에 바인딩하거나 --seed-demo를 제거하세요. 데모 모드는 로컬 안내 전용입니다 — 빠른 시작을 참조하세요.
누락되거나 쓸 수 없는 데이터 디렉토리
증상: 엔진이 누락된 경로 또는 권한 오류를 참조하며 종료됩니다.
데이터 디렉토리에는 SQLite 스토어(기본 엔진 사용 시), 감사 서명 키, TLS 자료가 보관됩니다. 부팅 전에 존재하고 쓰기 가능해야 합니다.
수정: 제한적 권한으로 디렉토리를 생성하고 --data-dir 또는 OLIVARES_DATA_DIR을 가리키세요. 컨테이너화된 배포에서는 영구 볼륨을 마운트하세요.
소스가 에지를 생성하지 않음
OLIVARES_SOURCES_CONFIG가 설정되지 않음
증상: 엔진이 시작되고, 부팅 로그가 소스가 구성되지 않았다고 경고하며, 접근 맵이 비어 있습니다.
OLIVARES_SOURCES_CONFIG 없이 엔진은 소스 커넥터 없이 실행됩니다. 크래시하지 않습니다 — 정직하게 경고하고 계속합니다.
수정: OLIVARES_SOURCES_CONFIG를 소스 JSON 파일의 경로로 설정하세요. 소스 연결을 참조하세요.
구성 파일의 유효하지 않은 JSON
증상: 부팅 로그가 읽을 수 없거나 유효하지 않은 구성에 대해 경고합니다; 소스가 등록되지 않습니다.
엔진은 JSON 파싱 오류 시 빈 소스 목록으로 경고하고 계속합니다. 부팅을 중단하지 않습니다.
수정: jq . < "$OLIVARES_SOURCES_CONFIG"로 파일을 유효성 검사하고 구문 오류를 수정하세요. 엔진의 부팅 로그를 다시 읽으세요 — 경고에 파싱 오류가 포함됩니다.
잘못된 소스 종류 문자열
증상: 구성된 소스가 해결되지 않습니다; 부팅 로그가 알 수 없는 종류라고 경고합니다.
등록된 소스 종류는 정확한 문자열입니다: pgaudit, s3cloudtrail, ebpf, runtime, mcp, claude. 이전 문서에서 사용한 pg_audit 또는 cloudtrail은 잘못되었습니다 — 해당 문자열은 해결되지 않습니다.
수정: 위에 나열된 정확한 kind 값을 사용하세요. 예상하는 종류가 없으면 아직 기본 serve 바이너리에 배선되지 않았을 수 있습니다. 커넥터 자체의 디스크립터를 확인하세요.
로그 파일을 읽을 수 없음
증상: 소스가 등록되지만 관찰을 출력하지 않습니다; 로그가 권한 또는 파일 없음 오류를 보고합니다.
pgaudit 커넥터는 PostgreSQL 로그 파일을 읽습니다; s3cloudtrail 커넥터는 CloudTrail 로그 파일 또는 디렉토리를 읽습니다. 둘 다 엔진이나 수집기를 실행하는 프로세스에서 읽기 접근이 필요합니다.
수정: log_path (pgaudit) 또는 path (s3cloudtrail) 값의 권한을 확인하세요. 컨테이너화된 배포에서는 볼륨 마운트가 올바르고 컨테이너 내 예상 경로에 파일이 존재하는지 확인하세요.
csvlog 형식에서의 pgaudit follow
증상: "follow": "true"와 "format": "csvlog"인 pgaudit 소스가 연속 테일하지 않습니다 — 배치로 실행됩니다.
follow는 jsonlog에서만 작동합니다. csvlog 파일은 레코드가 줄바꿈을 넘을 수 있어 신뢰할 수 있는 테일 따르기가 안전하지 않으므로 항상 배치로 읽힙니다.
수정: 연속 테일이 필요하면 PostgreSQL 로그 형식을 jsonlog로 전환하세요. 그렇지 않으면 배치 동작을 수락하고 선택적으로 소스 항목에 poll_seconds를 설정하여 재읽기 빈도를 제어하세요.
Claude Code 후크가 발동하지 않음
관리형 설정이 배포되지 않음
증상: Claude Code가 후크 삽입 없이 실행됩니다; 도구 호출이 관찰되지 않고 거버넌스되지 않습니다.
시행 후크는 Claude Code의 엔터프라이즈 관리형 설정 계층에서 제공됩니다. 관리형 설정 파일이 호스트에 없으면 후크가 단순히 부재합니다.
수정: Claude Code가 실행되는 모든 호스트에 올바른 경로로 관리형 설정 파일이 배포되었는지 확인하세요. managed-hooks-only가 활성화되면 개발자가 낮은 우선순위 설정 파일에서 후크를 비활성화하거나 교체할 수 없습니다.
ANTHROPIC_BASE_URL 재정의
증상: 후크가 배포되었지만 Claude Code가 완전히 우회합니다.
맞춤 ANTHROPIC_BASE_URL은 서버 관리형 설정을 우회할 수 있어 관리형 후크가 로드되지 않습니다. 이것은 협력적 경로의 문서화된 정직한 주의사항입니다 — 커넥터는 설정 계층을 옵트아웃하는 클라이언트에 대해 시행할 수 없습니다.
수정: ANTHROPIC_BASE_URL이 설정되지 않았는지 또는 맞춤 엔드포인트가 여전히 관리형 설정을 따르는지 확인하세요. 비협력적 에이전트의 기반 진실은 후크가 아닌 커널/eBPF 백스톱입니다.
후크 PEP 도달 불가
증상: 모든 도구 호출이 거부됩니다; 후크가 모든 요청에 대해 깨끗한 deny를 반환합니다.
PEP는 기본 거부입니다: 시행 포인트에 도달할 수 없으면 — 네트워크 파티션, 잘못된 주소, 프로세스 다운 — 모든 도구 호출이 거부됩니다. 판정의 제로 값 자체가 deny입니다. 이것은 의도적인 비대칭 위험 설계입니다.
수정: PEP 주소에 대한 루프백 연결을 확인하세요. 엔진이 실행 중이고 HTTP 리스너가 정상인지 확인(/livez). PEP가 의도적으로 다운이면 제어 평면이 오프라인인 동안 개발자를 멈추지 않는 더 가벼운 로컬 시행 모드(엔진 왕복 없음)가 있지만 명시적으로 구성해야 합니다.
감사 체인 검증 실패
키 불일치
증상: olivares audit verify가 비제로로 종료; 보고서가 서명 검증 실패를 표시합니다.
--pubkey 또는 --event-pubkey 플래그가 체크포인트를 쓴 서명 키와 일치하지 않는 공개 키를 가리킵니다. 키 교체 후 또는 잘못된 오프박스 키 사본에 대해 검증할 때 흔합니다.
수정: 검증하는 기간 동안 활성이었던 서명 키에 해당하는 공개 키를 사용하세요. 엔진은 부팅 시 키 지문을 로깅합니다.
데이터 디렉토리 교체 후 체인 갭
증상: olivares audit verify가 체인 갭을 보고합니다 — 저장된 체인 팁이 원장 항목과 일치하지 않습니다.
데이터 디렉토리가 교체되었으면(예: olivares dr restore 대신 파일시스템 스냅샷에서 복원) 체인 팁이 원장과 정렬되지 않을 수 있습니다.
수정: 복원 후 원장 연속성을 확인하는 비파괴적 DR 훈련은 olivares dr verify를 사용하세요. olivares dr restore가 원장 연속성 안전 복원 경로입니다 — 복원 시 체인을 재검증하고 원장이 정상이 아니면 비제로 종료합니다.
서로 다른 서명 키를 가진 다중 노드
증상: 장애 조치 시 원장이 포크됩니다; 한 노드의 체크포인트에서는 검증이 통과하지만 다른 쪽에서는 실패합니다.
액티브-패시브 클러스터에서 공유되지 않으면 각 노드가 첫 부팅 시 자체 서명 키를 생성합니다. 장애 조치 후 새 리더가 다른 키로 서명하여 체인을 포크합니다.
수정: OLIVARES_AUDIT_SIGNING_KEY_FILE(마운트된 시크릿) 또는 OLIVARES_AUDIT_SIGNING_KEY(base64 인라인, 덜 선호)를 통해 복제본 간 서명 키를 공유하세요. 키 관리는 구성 참조를 참조하세요.
상태 프로브 문제
/readyz가 “store”:“down”으로 503 반환
증상: 준비 프로브가 실패합니다; 본문에 "store":"down"이 포함됩니다.
스토어 핑이 짧은 타임아웃으로 실행되어 실패했습니다. 인스턴스가 멈춘 백엔드에서 행하지 않고 드레인됩니다.
수정: 데이터베이스 연결을 확인하세요. Postgres의 경우 DSN, 네트워크 경로, 데이터베이스 프로세스가 실행 중인지 확인. SQLite의 경우 데이터 디렉토리의 스토어 파일이 잠기거나 손상되지 않았는지 확인.
/readyz가 “leader”:false로 503 반환
증상: 준비 프로브가 503을 반환합니다; 본문에 "leader":false가 포함됩니다.
이것은 액티브-패시브 클러스터에서 예상된 동작입니다. 스탠바이가 /readyz에서 503을 보고하여 로드 밸런서가 트래픽 라우팅을 중단하되, 재시작하지 않습니다. 리더가 죽으면 스탠바이가 리더십을 획득하고 /readyz가 200으로 전환됩니다.
수정: 수정 불필요 — 올바른 동작입니다. 로드 밸런서가 /readyz(준비)에서 라우팅하고 오케스트레이터가 /livez(생존)에서 재시작하는지 확인하세요. 두 가지를 혼동하면 정상 스탠바이에서 재시작 루프가 발생합니다.
/livez 실패
증상: 생존 프로브가 오류를 반환하거나 타임아웃됩니다.
/livez는 의존성 검사를 실행하지 않습니다. 실패하면 프로세스 자체가 비정상입니다 — 다운스트림 의존성이 아닙니다.
수정: 시스템 리소스(메모리, 디스크, 파일 디스크립터)와 엔진 로그를 확인하세요. /readyz 실패와 달리 여기서는 재시작이 적절합니다.
데모 모드 문제
데모 자격증명은 공개
데모 관리자 비밀번호는 소스 트리에 의도적으로 있습니다 — 시크릿이 아닙니다. --seed-demo에는 항상 일회용 데이터 디렉토리를 사용하고 데모를 네트워크에 노출하지 마세요.
데모에서 프로덕션으로 전환
데모 데이터 디렉토리를 재사용하지 마세요. 데모는 조작된 데이터와 공개 자격증명을 시딩합니다. 새로 시작하세요: --seed-demo 없이 olivares serve를 실행하고, 일회용 설정 토큰을 수령하고, 실제 관리자를 생성하세요. 자체 호스팅을 참조하세요.
PDP 구성 문제
유효하지 않은 Cedar 정책 파일
증상: 부팅 로그가 외부 PDP가 비활성화되었다고 경고합니다; 엔진은 네이티브 ABAC와 RBAC만으로 계속합니다.
OLIVARES_PDP_ENGINE=cedar이지만 OLIVARES_PDP_CEDAR_FILE이 읽을 수 없거나 잘못된 형식의 파일을 가리키면, 엔진이 외부 PDP를 비활성화합니다. 크래시하지 않고 요청을 거버넌스 없이 남기지 않습니다 — 네이티브 엔진이 계속 시행합니다.
수정: 파일 경로를 확인하고 Cedar 정책 구문을 유효성 검사하세요. 부팅 로그에 구체적인 오류가 포함됩니다.
OPA 엔드포인트 도달 불가
증상: 위와 동일 — 외부 PDP 비활성화, 네이티브 RBAC가 계속 거버넌스.
OLIVARES_PDP_ENGINE=opa이지만 OLIVARES_PDP_OPA_URL에 도달할 수 없거나 오류를 반환하면, 엔진이 네이티브 시행으로 폴백합니다. 깨진 외부 PDP가 게이트를 열지 않습니다.
수정: OPA URL, 네트워크 경로, bearer 토큰(OLIVARES_PDP_OPA_TOKEN)을 확인하세요. OPA 서비스가 실행 중이고 결정 경로(OLIVARES_PDP_OPA_PATH)가 올바른지 확인하세요.
두 PDP 엔진이 모두 구성됨
증상: 예상치 못한 정책 평가; 어떤 엔진이 활성인지 불명확.
OLIVARES_PDP_ENGINE은 정확히 하나의 엔진을 선택합니다: cedar 또는 opa. 모호하거나 누락된 엔진 선택기와 함께 두 엔진의 충돌하는 변수를 설정하면 예측 불가능한 PDP 상태가 됩니다.
수정: OLIVARES_PDP_ENGINE을 정확히 하나의 값으로 설정하고 해당 엔진의 변수만 구성하세요. 혼란을 피하기 위해 다른 엔진의 환경 변수를 제거하세요.