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

상태: 완료 (2026-03-12 30분 계층형 cron, 01:00 전수조사 cron, 수동 검증 완료)

상위 원칙

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

허용 지연은 30분 이내로 고정한다.
기본 실행 방식은 cron 기반 30분 주기 계층형 탐색 + 증분 pull로 고정한다.
30분 루프는 전체 파일 전수조사가 아니라 /6.Company X와 그 아래 1차 폴더들을 non-recursive로 조회해 2차 폴더까지 먼저 확인한다.
Search API는 전체 루트 대체재로 쓰지 않는다.
Search API는 변화가 잦고 범위가 좁은 일부 상위 폴더에서만 보조 후보로 제한 검토한다.
증분 기준은 기존과 동일하게 수정시각 + 파일 크기를 유지한다.
해시는 기본 증분 판정 기준으로 올리지 않는다.
내부 NAS DSM webhook/API 제어를 기본 전제로 두지 않는다.
외부 삭제는 내부 NAS에 자동 전파하지 않고, 삭제 후보 로그만 남긴다.
같은 주기의 중복 실행은 허용하지 않는다.
하루 1회는 파일 기준 전체 루트 전수조사를 수행해 누락과 정합성을 보정한다.
SHA256은 표본 무결성 검증과 의심 파일 확인에만 제한적으로 사용한다.

30분 주기 실행의 평균 소요 시간, 최장 소요 시간, 겹침 발생 여부를 기록한다.
1회 실행 시간이 30분을 반복 초과하면 주기를 더 늘리거나 상위 폴더 분할로 전환한다.
2차 폴더까지 확인 단계는 평균 1초 내외를 유지하는지 본다.
하강 대상 폴더 수가 급격히 늘어 30분 루프가 길어지면 상위 폴더 단위 분리 또는 주기 조정을 검토한다.
해시 재계산은 2026-03-12 실측에서 같은 표본 기준 stat 0.927ms 대비 sha256 617.713ms, 약 666.4배 느렸으므로 운영 기본 루프에 넣지 않는다.
전체 루트 1분 제한 실측에서는 directories_seen=436, files_seen=2276이었고, 기존 완주 총량 대비 단순 비례 예상 시간은 약 23.4분이었다.
따라서 현재 기본안은 30분 루프는 계층형 탐색, 하루 1회만 파일 전수조사다.

30분 주기 실행 3회 이상에서 failed=0 또는 원인 설명 가능한 실패 로그가 남는다.
각 실행 요약에서 started_at, finished_at, downloaded, skipped, failed를 확인할 수 있다.
같은 시간대 중복 프로세스가 생기지 않는다.
하루 1회 파일 전수조사 결과와 30분 루프 결과 사이에 설명되지 않는 누락이 없다.
30분 루프 로그에서 어떤 2차 폴더가 하강 대상으로 선택됐는지 확인할 수 있다.

현재 근거 기준 1순위는 cron 30분 주기 2차 폴더 메타 확인 + 바뀐 폴더만 하강 동기화 + 하루 1회 파일 전수조사다.
Search API는 작은 폴더에서는 빠르게 동작했지만 루트 전체에서는 신뢰 가능한 결과를 주지 못했으므로 기본 경로로 채택하지 않는다.
해시는 직접 실측에서 수정시각 + 파일 크기보다 현저히 느렸으므로, 운영 루프가 아니라 표본 검증에만 남긴다.
내부 NAS 관리자 계정으로 DSM API 로그인 자체는 가능했지만, 현재 확인된 API 목록에는 알림/webhook 제어 항목이 없었으므로 webhook 기반 설계는 채택하지 않는다.
루트 1회 조회는 약 60ms, 2차 폴더까지 확인은 약 1초, 전체 파일 전수조사는 약 23분대로 추정되므로, 현재 추천 점수는 95%다.

사용자 crontab에 */30 * * * * /home/admin/infra/scripts/bin/companyx_external_nas_sync_hierarchical_cron.sh를 적용했다.
사용자 crontab에 0 1 * * * /home/admin/infra/scripts/bin/companyx_external_nas_sync_fullscan_cron.sh를 적용했다.
계층형 스크립트 수동 검증 1회차는 root_scan_calls=15, first_level_dirs=14, second_level_dirs=110, primed_cache=true, downloaded=38, failed=0이었다.
계층형 스크립트 수동 검증 2회차는 candidate_dirs=0, downloaded=0, skipped=38, failed=0이었다.
전수조사 래퍼는 대표 폴더 기준 downloaded=20, failed=0, files_seen=20으로 정상 동작을 확인했다.