> Source: https://clickhouse.github.io/loom/ko/architecture/source-push/ (Markdown: https://clickhouse.github.io/loom/ko/architecture/source-push.md)

<!-- i18n: source=docs/architecture/source-push.md blob=3114dcae551415671efdfa6f880845f601eb7342 model=claude-sonnet-5-5 -->
> 이 페이지는 [영어 원문](https://clickhouse.github.io/loom/architecture/source-push/)을 기계 번역한 것이며, 영어 원문이 기준입니다.
> Machine-translated from the [English page](https://clickhouse.github.io/loom/architecture/source-push/), which is authoritative.

<a id="document-source-push-notifications"></a>

# 문서 소스 푸시 알림

제공자 알림으로 문서 소스 동기화를 요청하려면 `LOOM_KNOWLEDGE_SOURCE_PUSH_ENABLED=true`가 필요합니다. 알림은 문서 내용을 쓰거나 소스의 접근 정책을 변경하지 않습니다. 일반 15분 폴링은 계속 활성 상태로 유지되며, 누락된 전달을 복구하는 경로입니다. 푸시를 비활성화하면 설정, 전달, 갱신이 일시 중지되지만 시크릿 재봉인과 설정 폐기는 막지 않습니다.

<a id="source-entry-points"></a>

## 소스 진입점

- `server/knowledge/api/ops_source_push.py` (`OPERATIONS`)는 관리자용 설정, 확인, 상태 조회 작업을 선언합니다.
- `server/knowledge/app/source_push_routes.py` (`notification`)는 콜백 본문의 크기를 제한하고 제공자 전달을 분배합니다.
- `server/knowledge/app/source_push.py` (`receive`, `_fresh`, `_put`, `renew_drive`, `reseal_registry`)는 힌트를 인증하고 레지스트리 수명 주기 쓰기를 조율합니다.
- `server/knowledge/domain/source_push.py` (`fingerprint`, `verify_drive`, `verify_notion`, `verify_linear`)는 설정을 바인딩하고 제공자 증명을 검증합니다. `server/knowledge/store/source_push.py` (`get`, `put`)는 레지스트리 버전을 저장합니다.
- `server/knowledge/app/sources.py` (`sources_lease`, `deactivate_namespace_sources`)는 소스 수명 주기 변경을 조율합니다. `server/erasure/store/steps_ledgers.py` (`delete_source_push_by_namespace`)는 레지스트리 삭제를 확정합니다.

<a id="invariants"></a>

## 불변 조건

- 인증된 전달은 기존 소스 경로를 통해 동기화를 요청합니다. 제공자 페이로드는 내용을 쓰거나 소스 접근 범위를 넓힐 수 없습니다.
- 전달은 현재 소스 ID, 설정 세대와 자격 증명, 항목 및 구성 핑거프린트와 일치해야 합니다. 소스 리스와 순차 읽기가 소스 교체, 폐기, 늦게 도착한 제공자 응답을 차단합니다.
- 푸시 시크릿은 용도에 바인딩된 봉인을 사용합니다. 대기 중인 챌린지는 관리자만 확인할 수 있으며, 일반 읽기, 감사 대상, 멱등성 재생에서는 제외됩니다.
- 레지스트리 쓰기와 네임스페이스 삭제는 펜싱된 작성자 리스를 공유합니다. 삭제는 저장된 모든 버전을 제거하며, 설정을 게시하려면 해당 삭제 단계를 플릿 전체가 지원하는 것이 확인되어야 합니다.

<a id="registration-and-authentication"></a>

## 등록 및 인증

푸시 레지스트리는 소스 레지스트리 및 동기화 커서와 별개입니다. 행은 조직, 네임스페이스, 소스 ID, 제공자, 무작위 설정 세대를 소스의 자격 증명과 항목에 대한 핑거프린트에 바인딩합니다. 구성은 관리자 작업입니다. 명시적으로 구성된 HTTPS 공개 기본 URL이 필요합니다.

콜백 URL은 경로에 네임스페이스, 소스 ID, 설정 세대를 넣고 필수 `org` 쿼리 매개변수에 정확한 조직을 넣습니다. 쿼리 인코딩은 슬래시나 예약된 URL 문자가 포함된 조직 이름을 그대로 보존합니다. 콜백은 동기화 요청을 기록하기 전에 네임스페이스의 소스 리스 아래에서 레지스트리와 현재 소스를 다시 읽습니다. 소스가 제거되거나 교체된 경우, 자격 증명이 변경된 경우, 항목 집합이 변경된 경우, 네임스페이스가 비활성인 경우, 세대가 폐기된 경우에는 전달을 거부합니다. 콜백 페이로드와 헤더는 저장되거나 로그에 남지 않습니다.

- Drive 채널은 서로 독립적인 무작위 채널 ID와 봉인된 채널 토큰을 사용합니다. 전달은 만료 전에 활성 채널 ID, 토큰, 리소스 ID와 일치해야 합니다. 이는 채널 토큰 검증이며, Drive는 이러한 전달에 서명하지 않습니다. 이른 `sync` 알림은 작업을 요청하지 않고 확인 응답만 합니다. watch 응답은 설정 세대를 다시 확인한 후에만 활성화됩니다.
- Notion 설정은 새 세대마다 크기가 제한된 봉인된 검증 챌린지 하나를 가져옵니다. 설정이 대기 중일 때만 관리자가 이를 확인할 수 있습니다. 제공자 UI에서 구독을 확인한 후, 관리자는 해당 세대와 챌린지 핑거프린트를 정확히 지정해 확정합니다. 서명되지 않은 챌린지로는 구독을 활성화하거나 동기화를 요청할 수 없습니다. 활성 전달에는 원본 본문 HMAC과 구성된 워크스페이스 ID가 필요합니다.
- Linear 설정은 먼저 대기 중인 알림 주소를 노출합니다. 관리자는 그 주소로 웹훅을 만들고, 서명 시크릿과 함께 같은 세대를 확정합니다. 전달에는 원본 본문 HMAC, 서명된 본문의 밀리초 타임스탬프(1분 이내), 구성된 조직 ID가 필요합니다.

제공자 ID는 설정 중에 소스의 기존 자격 증명으로 읽습니다. 알림 본문에는 고정된 크기 제한이 있습니다. 유효한 중복 알림은 기존의 대기 중인 동기화 요청과 병합되며, 대기 중인 전체 동기화는 유지됩니다. 성공한 콜백은 4초의 핸들러 예산 안에 HTTP 200으로 응답합니다.

<a id="drive-coverage-and-renewal"></a>

## Drive 범위와 갱신

Drive 사용자 변경 채널은 모든 공유 드라이브 변경을 포괄하지 않습니다. 따라서 설정은 사용자 코퍼스와 계정이 속한 모든 공유 드라이브(최대 19개)에 대해 채널을 만듭니다. 완전하고 크기가 제한된 멤버십 목록을 사용하면 직접 공유된 파일의 드라이브 ID를 멤버십으로 오인하지 않습니다. 비멤버에게 직접 공유된 항목은 사용자 로그를 사용합니다. 설정은 푸시 범위가 완전하다고 주장하는 대신, 불완전하거나 한도를 초과한 코퍼스 집합을 거부합니다. 파일을 새 코퍼스로 옮기면 설정을 다시 해야 할 수 있으며, 폴링은 여전히 해당 변경을 발견합니다.

크기가 제한되고 기본적으로 꺼져 있는 워커가 만료 전에 채널을 갱신합니다. 워커는 새로운 고유 채널을 만들고, 응답과 소스 세대를 검증한 다음, 소스 리스 아래에서 교체합니다. 이전 채널은 최선의 노력으로 중지합니다. 갱신에 실패해도 폴링은 계속 사용할 수 있으며, 만료된 채널은 설정 상태에 표시됩니다.

구성 카탈로그는 제공자 작업, 채널별 중지, 전체 정리, 워커 패스의 제한 시간을 제어합니다. 기본값은 각각 40초, 2초, 5초, 120초입니다. 한 번의 패스는 제공자 시도 한 번과 정리 구간 두 번을 처리할 시간이 남아 있을 때까지만 갱신을 시작합니다. 구성은 120초 갱신 리스 안에서 48초의 작업 구간을 넘길 수 있는 제공자 작업과 정리의 조합, 또는 갱신을 시작할 시간이 남지 않는 패스 예산을 거부합니다. 채널 중지 제한 시간은 전체 정리 구간을 초과할 수 없습니다.

<a id="lifecycle-and-storage"></a>

## 수명 주기와 저장

레지스트리는 조직, 네임스페이스, 소스 ID 순으로 정렬되므로 네임스페이스 읽기는 물리적 키 범위를 가지치기합니다. 유지 관리 스캔도 같은 순서로 진행됩니다. 레지스트리는 전체 ID 튜플, 서버가 기록한 행위자, 파생된 출처 정보를 저장합니다. 시크릿은 용도에 바인딩된 봉인을 사용하며 재봉인에 참여합니다. 일반 소스 읽기와 감사 대상에는 토큰이나 챌린지가 포함되지 않습니다. 관리자 설정 읽기는 멱등성 재생 저장소를 거치지 않으므로, 공개된 대기 중 챌린지는 활성화 이후 일반 캐시에서 재생될 수 없습니다.

소스 제거, 자격 증명 교체, 항목 업데이트, 네임스페이스 폐기는 동일한 소스 리스 아래에서 푸시 설정을 폐기합니다. 늦게 도착한 외부 watch 응답은 폐기된 설정을 되살릴 수 없습니다. 네임스페이스 삭제는 기존의 확정형 삭제 메커니즘을 통해 모든 레지스트리 버전을 제거합니다. 구성 쓰기에는 레지스트리의 삭제 단계를 이해하는 플릿이 필요하며, 읽을 수 없는 플릿은 거부됩니다. 이 레지스트리가 없는 빌드로 롤백하기 전에 푸시를 비활성화하고, 현재 빌드로 레지스트리 행을 삭제한 다음, 네임스페이스 삭제가 완료되었는지 확인하세요. 중지할 수 없는 제공자 채널은 만료되며, 폐기된 콜백은 이를 거부합니다.

<a id="alternatives"></a>

## 대안

푸시 상태를 소스 행에 넣으면 모든 전달이 자격 증명 쓰기와 경합하고 이전 자격 증명이 그대로 이어질 위험이 있습니다. 동기화 상세 정보에 넣으면 봉인된 설정 시크릿이 일반 조회 출력과 섞입니다. 별도의 레지스트리를 사용하면 두 문제를 모두 피할 수 있습니다. 알림은 힌트일 뿐이므로 영속 이벤트 큐, 제공자 페이로드 보관소, 두 번째 수집 경로는 필요하지 않습니다.

<a id="provider-contracts"></a>

## 제공자 규약

- [Drive 푸시 알림](https://developers.google.com/workspace/drive/api/guides/push)
- [Drive 사용자 및 공유 드라이브 로그](https://developers.google.com/workspace/drive/api/guides/about-changes)
- [Notion 웹훅 검증](https://developers.notion.com/reference/webhooks)
- [Notion 이벤트 전달](https://developers.notion.com/reference/webhooks-events-delivery)
- [Linear 웹훅 검증](https://linear.app/developers/webhooks)
