ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
DOCS/journey/plans/260312_external_nas_companyx_실시간동기화_계획.md

7.6 KiB
Raw Blame History

tags
tags
infra
nas
companyx
sync
realtime
plans

260312 외부 NAS -> 내부 NAS 컴퍼니엑스 실시간동기화 계획

상태: 완료 (2026-03-12 cron 적용, 중복 실행 방지 검증, 1분 제한 실측 기반 주기 30분으로 보정)

상위 원칙

관련 문서

문제 정의

  • 전체 트리 기준 재귀 조회는 이미 동작하지만, 현재 구조 그대로는 거의 즉시 반영을 말하기 어렵다.
  • 2026-03-12 실측에서 전체 트리 --dry-run은 3분 45초가 지나도 종료되지 않았고, 작은 폴더 Search API는 빠르지만 루트 전체 재귀 Search는 신뢰 가능한 결과를 주지 못했다.
  • 따라서 이번 계획의 목표는 실시간처럼 보이는 과장이 아니라, 현재 근거로 재현 가능한 짧은 지연 동기화 운영안을 고정하는 것이다.

구조 결정 고정

  • 허용 지연은 30분 이내로 고정한다.
  • 기본 실행 방식은 cron 기반 30분 주기 증분 pull로 고정한다.
  • 전체 루트 /6.Company X는 기존 List 기반 재귀 scan/pull을 유지한다.
  • Search API는 전체 루트 대체재로 쓰지 않는다.
  • Search API는 변화가 잦고 범위가 좁은 일부 상위 폴더에서만 보조 후보로 제한 검토한다.
  • 증분 기준은 기존과 동일하게 수정시각 + 파일 크기를 유지한다.
  • 해시는 기본 증분 판정 기준으로 올리지 않는다.
  • 내부 NAS DSM webhook/API 제어를 기본 전제로 두지 않는다.
  • 외부 삭제는 내부 NAS에 자동 전파하지 않고, 삭제 후보 로그만 남긴다.
  • 같은 주기의 중복 실행은 허용하지 않는다.
  • 하루 1회는 전체 루트 기준 검증 스캔을 수행해 Search API 누락 가능성과 누적 불일치를 점검한다.
  • SHA256은 표본 무결성 검증과 의심 파일 확인에만 제한적으로 사용한다.

실행 순서

1. 30분 주기 실행 엔트리를 고정한다

  • companyx_external_nas_sync.py를 30분마다 실행하는 cron 엔트리를 기준안으로 둔다.
  • 실행 겹침 방지를 위해 lock 파일 또는 flock 기반 단일 실행 제어를 같이 둔다.
  • 로그는 기존 .sync-logs 경로를 재사용한다.

2. 전체 루트 30분 주기 증분 실행을 먼저 기준안으로 채택한다

  • 최초 기준안은 /6.Company X -> /mnt/nas/workspace/6.Company X 전체 루트 재귀 조회다.
  • 이유는 현재 직접 검증된 방식 중 전체 범위를 안정적으로 설명 가능한 경로가 이것뿐이기 때문이다.
  • Search API를 먼저 중심 구조로 승격하지 않는다.
  • 내부 NAS나 외부 NAS의 파일 변경 webhook이 있다는 가정을 실행 기준에 넣지 않는다.

3. Search API는 일부 상위 폴더 후보에서만 별도 검증한다

  • /6.Company X/7. 사진처럼 범위가 제한된 상위 폴더를 후보로 둔다.
  • 작은 범위에서 pattern, mtime_from, mtime_to 기반 검색이 계속 일관되게 맞는지 확인한다.
  • 이 검증이 반복 통과되기 전까지 Search API는 보조 최적화 후보로만 취급한다.

4. 하루 1회 전체 검증 스캔을 추가한다

  • 10분 주기 실행과 별도로 하루 1회 전체 루트 기준 재귀 스캔을 수행한다.
  • 목적은 Search API 보조 최적화가 일부 폴더에서 쓰이더라도 누락 파일, 이동 파일, 시간 오차를 다시 맞추기 위함이다.
  • 이 검증 스캔도 같은 상태 파일과 요약 파일 체계를 사용한다.

5. 운영 임계치를 수치로 확인한다

  • 30분 주기 실행의 평균 소요 시간, 최장 소요 시간, 겹침 발생 여부를 기록한다.
  • 1회 실행 시간이 30분을 반복 초과하면 주기를 더 늘리거나 상위 폴더 분할로 전환한다.
  • Search API 후보 폴더는 동일 시점 List 결과와 표본 비교해 누락이 없을 때만 다음 단계로 올린다.
  • 해시 재계산은 2026-03-12 실측에서 같은 표본 기준 stat 0.927ms 대비 sha256 617.713ms, 약 666.4배 느렸으므로 운영 기본 루프에 넣지 않는다.
  • 전체 루트 1분 제한 실측에서는 directories_seen=436, files_seen=2276이었고, 기존 완주 총량 대비 단순 비례 예상 시간은 약 23.4분이었다.
  • 따라서 현재 기본안은 10분이 아니라 30분이 안전한 보수 주기다.

체크리스트

  • 허용 지연 30분이 문서와 실행 설정에서 일치한다.
  • cron 기준 실행이 중복 없이 유지된다.
  • 전체 루트 기준 30분 주기 실행에서 상태 파일과 요약 파일이 남는다.
  • 1회 실행 시간이 주기를 반복 초과하지 않는다.
  • Search API는 전체 루트 대체재가 아니라 일부 상위 폴더 후보로만 사용된다.
  • 해시는 기본 증분 판정이 아니라 표본 검증에만 남는다.
  • 하루 1회 전체 검증 스캔이 별도로 남는다.
  • 삭제 전파 없이 삭제 후보 로그만 남는다.

검증 기준

  • 30분 주기 실행 3회 이상에서 failed=0 또는 원인 설명 가능한 실패 로그가 남는다.
  • 각 실행 요약에서 started_at, finished_at, downloaded, skipped, failed를 확인할 수 있다.
  • 같은 시간대 중복 프로세스가 생기지 않는다.
  • 하루 1회 전체 검증 스캔 결과와 30분 주기 실행 결과 사이에 설명되지 않는 누락이 없다.
  • Search API 후보 폴더는 같은 표본에 대해 List와 결과가 일치한다.

완료 조건

  • 실시간 대신 30분 이내 반영이라는 운영 표현이 문서와 실행 결과에서 일치한다.
  • 30분 주기 증분 pull이 재현 가능하고, 중복 실행 없이 안정적으로 돈다.
  • Search API는 과장 없이 일부 상위 폴더 보조 최적화 후보로만 정리된다.
  • 이 주제는 더 이상 막연한 실시간 아이디어가 아니라, 측정값에 근거한 운영 기준으로 전환된다.

현재 추천 결론

  • 현재 근거 기준 1순위는 cron 30분 주기 + 전체 루트 증분 pull + 하루 1회 전체 검증 스캔이다.
  • Search API는 작은 폴더에서 빠르게 동작했지만 루트 전체에서는 신뢰 가능한 결과를 주지 못했으므로, 일부 상위 폴더에서만 제한 검토한다.
  • 해시는 직접 실측에서 수정시각 + 파일 크기보다 현저히 느렸으므로, 운영 루프가 아니라 표본 검증에만 남긴다.
  • 내부 NAS 관리자 계정으로 DSM API 로그인 자체는 가능했지만, 현재 확인된 API 목록에는 알림/webhook 제어 항목이 없었으므로 webhook 기반 설계는 채택하지 않는다.
  • 전체 루트 1분 제한 실측 기반 예상 시간이 약 23.4분이므로, 현재 추천 점수는 92%다.