> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/deployment-manager/services/event-store.md).

# Event Store

자동 보존, 저장 한도, 선택적 클라우드 백업과 함께 엣지 장치에 추론 이벤트를 저장합니다.

이벤트 스토어는 디바이스에서 추론 파이프라인이 생성한 이벤트를 기록하는 엣지 컨테이너 서비스입니다. 검사 결과, 품질 검사, 안전 경고 및 기타 워크플로 출력물을 로컬에 저장하고, REST API를 통해 다시 제공하며, 자체 디스크 사용량을 관리하므로 디바이스가 꽉 차지 않습니다.

이벤트 스토어에 기록된 이벤트는 다음 형식으로 Roboflow에 백업할 수도 있습니다 [비전 이벤트](/deployment/ko/monitoring-and-analytics/vision-events.md) 장기 저장 및 분석용으로.

{% hint style="info" %}
이벤트 스토어는 Enterprise 고객에게만 제공됩니다. [Roboflow 영업팀에 문의하여](https://roboflow.com/sales) 자세히 알아보세요.
{% endhint %}

## 연결 정보

다음을 `<device-ip>` Deployment Manager의 디바이스 페이지에 표시된 IP 주소로 바꾸세요.

<table data-search="false"><thead><tr><th>목적</th><th>주소</th></tr></thead><tbody><tr><td>REST API</td><td><code>http://&#x3C;device-ip>:8001</code></td></tr><tr><td>대화형 Swagger 문서</td><td><code>http://&#x3C;device-ip>:8001/docs</code></td></tr></tbody></table>

포트 8001은 HTTP를 통해 둘 다 제공합니다. 다음을 참조하세요. [이벤트 스토어 REST API](/deployment/ko/self-hosted/enterprise/deployment-manager/services/event-store/rest-api.md) 엔드포인트 참조를 위해.

API를 호출하지 않고도 디바이스의 실시간 용량 및 사용 내역을 보려면 다음을 사용하세요. [이벤트 스토어 상태 보기](/deployment/ko/self-hosted/enterprise/deployment-manager/monitoring/view-event-store-status.md).

## 저장소 설정

디바이스의 Configuration 탭에 있는 이벤트 스토어 카드에서 이 설정들을 구성하세요. 각 항목은 서비스의 환경 변수에 매핑됩니다.

<table data-search="false"><thead><tr><th>설정</th><th>변수</th><th>기본값</th><th>설명</th></tr></thead><tbody><tr><td>"보존 일수"</td><td><code>RETENTION_DAYS</code></td><td><code>1</code></td><td>이 일수보다 오래된 이벤트는 삭제됩니다.</td></tr><tr><td>"최대 레코드 수"</td><td><code>MAX_RECORDS</code></td><td><code>1000000</code></td><td>보관되는 이벤트의 최대 개수입니다. 이를 초과하면 가장 오래된 항목이 제거됩니다.</td></tr><tr><td>"최대 레코드 크기"</td><td><code>MAX_RECORD_SIZE_BYTES</code></td><td><code>524288</code> (512 KB)</td><td>단일 이벤트 레코드의 최대 크기입니다. 더 큰 이벤트는 거부됩니다.</td></tr><tr><td>"최대 저장 공간"</td><td><code>MAX_STORAGE_BYTES</code></td><td><code>5368709120</code> (5 GB)</td><td>저장된 파일에 대한 전체 디스크 한도입니다. 사용량이 이 한도에 가까워지면 정리 작업이 파일을 제거합니다.</td></tr><tr><td>"정리 간격"</td><td><code>CLEANUP_INTERVAL_SECONDS</code></td><td><code>300</code></td><td>자동 정리가 실행되는 빈도입니다.</td></tr></tbody></table>

추가 변수:

<table data-search="false"><thead><tr><th>변수</th><th>기본값</th><th>설명</th></tr></thead><tbody><tr><td><code>PORT</code></td><td><code>8001</code></td><td>API용 HTTP 포트입니다.</td></tr><tr><td><code>DATA_DIR</code></td><td><code>/data</code></td><td>디바이스의 데이터 저장 디렉터리입니다.</td></tr><tr><td><code>CONSISTENCY_CHECK_INTERVAL</code></td><td><code>12</code></td><td>N번의 정리마다 일관성 검사를 실행합니다(기본 정리 간격에서는 대략 매시간).</td></tr><tr><td><code>API_KEY</code></td><td>없음</td><td>선택적 API 키입니다. 다음을 참조하세요. <a href="#authentication">인증</a>.</td></tr></tbody></table>

## 자동 정리

정리는 전용 백그라운드 스레드에서 실행되므로 API 요청을 절대 차단하지 않습니다. 예약된 각 실행은 다음 세 단계를 순서대로 수행합니다.

1. 보존 기간. 다음보다 오래된 레코드를 삭제합니다. `RETENTION_DAYS`.
2. 레코드 제한. 레코드 수가 다음을 초과하면 `MAX_RECORDS`한도를 초과한 레코드를 삭제하며, 이미 업로드된 레코드를 먼저, 그다음 가장 오래된 레코드를 제거합니다.
3. 저장소 제한. 저장된 파일이 다음에 가까워지면 `MAX_STORAGE_BYTES`이미지 파일을 삭제하며, 이미 업로드된 파일을 먼저, 그다음 가장 오래된 파일을 제거합니다. 상위 레코드는 유지되고 그 레코드의 `current_file_count` 는 감소합니다.

매 `CONSISTENCY_CHECK_INTERVAL` 번의 정리마다 서비스는 데이터베이스와 파일 시스템도 대조합니다. 일치하는 데이터베이스 레코드가 없는 디스크의 고아 파일은 10분 유예 기간을 사용해 제거하므로 진행 중인 쓰기 작업은 건드리지 않으며, 파일이 이미 사라진 연결 끊긴 데이터베이스 레코드도 제거합니다.

다음을 사용해 즉시 실행을 트리거할 수도 있습니다. `POST /admin/cleanup`. 다음을 참조하세요. [관리](/deployment/ko/self-hosted/enterprise/deployment-manager/services/event-store/rest-api.md#administration).

### 이미지의 일시성

API가 반환하는 이미지 ID는 본질적으로 수명이 짧습니다. 1분 전에 확인되었던 ID도 정리 실행 후에는 404가 될 수 있으며, 이는 저장 공간이 제한된 엣지 하드웨어에서 의도된 동작입니다.

* 이미지를 가져올 때 `404` 응답을 처리하세요.
* 이미지 ID를 단일 세션 이상 캐시하지 마세요.
* 다음을 `current_file_count` 와 비교하세요. `original_file_count` 이벤트에서 해당 파일이 정리되었는지 확인합니다.

## 초안 이벤트 및 비디오

파이프라인은 이벤트를 즉시 저장하고, 인코딩이 끝나면 몇 초 뒤에 비디오를 첨부할 수 있습니다. 이벤트를 다음으로 생성하세요. `draft: true`, 비디오가 준비되면 업로드한 다음 이벤트를 최종 확정합니다. 다음 없이 생성된 이벤트는 `draft` 생성 시점에 최종 확정되므로 기존 파이프라인에는 영향이 없습니다.

이벤트가 최종 확정되기 전까지는 클라우드 업로드에서 건너뛰어집니다. 또한 클라우드 업로드가 서비스에서 활성화된 동안에만 정리로부터 보호됩니다. 클라우드 업로드가 꺼져 있으면 초안도 다른 레코드와 마찬가지로 삭제할 수 있습니다.

<table data-search="false"><thead><tr><th>설정</th><th>변수</th><th>기본값</th><th>설명</th></tr></thead><tbody><tr><td>"초안을 다음 뒤 자동 최종 확정"</td><td><code>DRAFT_AUTO_FINALIZE_SECONDS</code></td><td><code>3600</code></td><td>비디오가 끝내 도착하지 않는 초안은 이 초가 지나면 강제로 최종 확정되어 백업 및 정리가 가능해집니다.</td></tr><tr><td>"최대 비디오 업로드 크기(MB)"</td><td><code>MAX_VIDEO_UPLOAD_BYTES</code></td><td><code>1073741824</code> (1 GB, 앱에서는 다음으로 입력) <code>1024</code> in the app)</td><td>디바이스의 이벤트에 첨부할 수 있는 단일 비디오의 최대 크기입니다. 변수는 바이트 단위이고, 앱의 필드는 MB 단위입니다.</td></tr></tbody></table>

{% hint style="warning" %}
설정 `DRAFT_AUTO_FINALIZE_SECONDS` \~로 `0` 정리를 비활성화합니다. 그런 다음 최종 확정을 호출하지 않는 생산자의 초안이 누적되고, 클라우드 백업이 켜져 있으면 저장소를 가득 채워 새 쓰기를 HTTP 529로 차단할 수 있으며, 저장소가 재설정될 때까지 지속됩니다.
{% endhint %}

## 이미지별 메타데이터 및 로컬 전용 파일

파이프라인은 이벤트의 이미지와 예측 외에도 추가 데이터를 첨부할 수 있습니다.

이미지별 메타데이터는 개별 이미지에 첨부되는 키/값 데이터의 작은 단일 수준 객체로, 예를 들어 판정, 일련번호 또는 각도 레이블 등이 있습니다. 이는 레코드와 함께 저장되고 API에 의해 반환되지만, 쿼리는 불가능합니다. "레코드 및 파일" 백업에서는 각 이미지와 함께 업로드됩니다. `METADATA_MAX_VALUE_LENGTH` (기본값 `1000`)은 문자열 값의 길이를 제한합니다.

로컬 전용 파일은 검사 블롭, 썸네일 또는 JSON과 같이 이벤트에 첨부되는 임의의 파일입니다. 이 파일들은 디바이스에 남아 있으며 절대 업로드되지 않습니다. 콘텐츠 유형 제한은 없으며, `MAX_LOCAL_ONLY_FILE_UPLOAD_BYTES` (기본값 `104857600`(100 MB)는 각 업로드의 크기를 제한합니다. 파일은 이벤트가 아직 초안일 때만 첨부할 수 있으므로, 파이프라인은 다음으로 이벤트를 생성한 뒤 파일을 첨부하고 최종 확정해야 합니다. `draft: true`다음으로,

둘 다 자세한 내용은 [REST API 참조](/deployment/ko/self-hosted/enterprise/deployment-manager/services/event-store/rest-api.md).

## 클라우드 백업

디바이스에서 Vision Events 백업이 활성화되면 최종 확정된 이벤트가 Roboflow로 업로드됩니다. 다음 두 가지 모드를 사용할 수 있습니다.

* 레코드 및 파일은 관련 이미지 파일, 이미지별 메타데이터, 비디오 클립과 함께 이벤트 메타데이터를 업로드합니다.
* 레코드만은 이벤트 메타데이터만 업로드하고 이미지와 비디오는 디바이스에 남겨 두어 대역폭을 덜 사용합니다.

로컬 전용 파일은 어느 모드에서도 절대 업로드되지 않습니다.

레코드 및 파일 모드에서는 MP4 및 MOV 클립이 업로드되며, 이벤트당 최대 4개까지 Vision Events 대시보드에서 재생됩니다. 다른 형식의 클립(예: MKV, AVI), 네 번째 이후의 클립, 3 GB를 초과하는 클립(클라우드 한도)은 디바이스에 남습니다. 디바이스 한도("최대 비디오 업로드 크기(MB)")는 별도이며 기본값은 1 GB이므로, 디바이스에 보관할 클립에 대해서만 3 GB를 넘겨 올리세요.

실패한 클립 업로드는 다음 동안 전체 이벤트를 보류합니다. `UPLOAD_RETRY_DELAY_SECONDS` (기본값 `3600`(기본값 1시간) 후 다음 시도 전에. `VIDEO_UPLOAD_MAX_ATTEMPTS` 번 실패하면(기본값 `3`), 해당 클립은 건너뛰고 이벤트는 그것 없이 업로드되므로, 그 이벤트는 Roboflow에 약 3시간 늦게 도착할 수 있습니다.

다음을 참조하세요. [이벤트 전송](/deployment/ko/monitoring-and-analytics/vision-events/send-events.md) 백업 활성화 및 Roboflow에서 결과 쿼리에 대해.

### 업로드 신뢰성

실패한 업로드는 재시도됩니다. "업로드 포기 정책"은 서버가 계속 거부하는 레코드에 어떤 일이 일어나는지 제어합니다.

<table data-search="false"><thead><tr><th>정책</th><th>변수 값</th><th>동작</th></tr></thead><tbody><tr><td>절대 포기하지 않음</td><td><code>NEVER_ABANDON</code> (기본값)</td><td>레코드는 성공할 때까지 영원히 재시도됩니다. 데이터 보존에는 가장 안전하지만, 멈춘 레코드로 가득 찬 디바이스는 업로드되지 않은 항목을 버리기보다 새 쓰기를 HTTP 529로 거부하기 시작합니다.</td></tr><tr><td>최대 시도 후 포기</td><td><code>ABANDON_AFTER_MAX_ATTEMPTS</code></td><td>다음 후 <code>UPLOAD_MAX_ATTEMPTS</code> 번의 콘텐츠 오류 시도 후(기본값 <code>10</code>) 레코드는 포기됨으로 표시되고 저장소 정리의 우선 대상이 됩니다. 지속적으로 실패하는 레코드를 잃는 것이 새 쓰기를 차단하는 것보다 낫다면 이 옵션을 사용하세요.</td></tr></tbody></table>

서버의 콘텐츠 스타일 4xx 응답만(예: 400, 413, 422) 시도 횟수를 증가시킵니다. 모든 5xx 응답, 시간 초과, 네트워크 오류, 그리고 401, 403, 404, 408, 429는 일시적인 것으로 간주되어 정책과 관계없이 재시도됩니다.

`MIN_UPLOAD_IMAGE_BYTES` (기본값 `1`)는 업로드 전에 지정된 크기보다 작은 이미지를 건너뜁니다. 손상되었지만 비어 있지 않은 이미지는 현재 서버에서 5xx로 돌아오므로 어느 정책에서든 무한히 재시도됩니다. 이 값을 일반적인 손상 크기보다 크게 올리는 것이 해결책입니다.

## 인증

API 키 인증은 선택 사항이며 기본적으로 꺼져 있습니다. 다음을 서비스에 설정하여 활성화하세요. `API_KEY` 를 활성화하면 다음을 제외한 모든 엔드포인트가 `/health` 다음을 요구합니다. `X-API-Key` 헤더를.

```yaml
환경 변수:
  - API_KEY=your-secret-api-key-here
```

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  http://<device-ip>:8001/v2/events/latest/query
```

`/health` 는 인증 없이도 계속 접근 가능하므로 모니터링 시스템과 로드 밸런서가 이를 폴링할 수 있습니다.