> 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).

## 저장 설정

디바이스의 구성 탭에 있는 이벤트 저장소 카드에서 이 항목들을 구성합니다. 각 항목은 서비스의 환경 변수에 매핑됩니다.

<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> (512KB)</td><td>단일 이벤트 레코드의 최대 크기입니다. 더 큰 이벤트는 거부됩니다.</td></tr><tr><td>"최대 저장 공간"</td><td><code>MAX_STORAGE_BYTES</code></td><td><code>5368709120</code> (5GB)</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>"최대 비디오 업로드 크기"</td><td><code>MAX_VIDEO_UPLOAD_BYTES</code></td><td><code>1073741824</code> (1GB)</td><td>이벤트에 첨부할 수 있는 단일 비디오의 최대 크기입니다.</td></tr></tbody></table>

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

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

파이프라인은 디바이스에 남아 클라우드로는 절대 업로드되지 않는 추가 데이터를 이벤트에 첨부할 수 있습니다.

이미지별 메타데이터는 판정, 일련번호 또는 각도 레이블과 같이 개별 이미지에 첨부되는 키/값 데이터로 이루어진 작은 단일 수준 객체입니다. 이는 레코드와 함께 저장되고 API를 통해 반환되지만, 쿼리할 수 없으며 백업에서 제외됩니다. `METADATA_MAX_VALUE_LENGTH` (기본값 `1000`) 문자열 값의 길이를 제한합니다.

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

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

## 클라우드 백업

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

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

이미지별 메타데이터와 로컬 전용 파일은 두 모드 모두에서 절대 업로드되지 않습니다.

참조: [이벤트 전송](/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` 는 인증 없이도 접근 가능하므로 모니터링 시스템과 로드 밸런서가 이를 폴링할 수 있습니다.