---
tags: [infra, nas, companyx, sync, realtime, plans]
---

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

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

## 상위 원칙
- [Infra Project Identity](../../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md)
- [Core Infrastructure Principles](../../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md)
- [Operational Guardrails](../../00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md)
- 공통 작성 원칙: [0_VALUE Writing Principles](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/writing-principles.md)

## 관련 문서
- [Infra Journey](../README.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 실시간 동기화 아이디어](../ideas/260312_external_nas_companyx_실시간동기화_아이디어.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 실시간동기화 리서치](../research/260312_external_nas_companyx_실시간동기화_리서치.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획](./260311_external_nas_companyx_sync_운영계획.md)
- [Company X 상태기록 강화 및 재개 실행](../worklog/260312_companyx_sync_상태기록강화_및_재개실행.md)

## 문제 정의

- 전체 트리 기준 재귀 조회는 이미 동작하지만, 현재 구조 그대로는 `거의 즉시` 반영을 말하기 어렵다.
- 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은 표본 무결성 검증과 의심 파일 확인에만 제한적으로 사용한다.

## 실행 순서

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

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

### 2. 30분 루프는 2차 폴더까지 먼저 확인한다

- `/6.Company X` 루트와 그 아래 1차 폴더들을 non-recursive `List`로 먼저 확인한다.
- 이 단계의 목적은 전체 파일을 훑는 것이 아니라 `어느 2차 폴더가 바뀌었는지`를 빠르게 잡는 것이다.
- 2026-03-12 실측 기준 루트 1회 조회 평균은 `60.14ms`, 2차 폴더까지 확인하는 평균은 `983.861ms`였다.
- Search API를 먼저 중심 구조로 승격하지 않는다.
- 내부 NAS나 외부 NAS의 파일 변경 webhook이 있다는 가정을 실행 기준에 넣지 않는다.

### 3. 바뀐 폴더만 3차 이하로 하강한다

- 30분 루프에서 `mtime`이 바뀐 2차 폴더만 3차, 4차, 파일 레벨까지 내려간다.
- 하강한 경로에서는 파일 단위 `수정시각 + 파일 크기`로 실제 다운로드 여부를 판단한다.
- 바뀌지 않은 2차 폴더는 이번 30분 루프에서 더 내려가지 않는다.

### 4. 하루 1회 파일 전수조사로 최종 정합성을 맞춘다

- 30분 루프와 별도로 하루 1회 전체 루트 파일 전수조사를 수행한다.
- 목적은 `폴더 mtime`만으로는 놓칠 수 있는 `기존 파일 내용 수정`, 누락 파일, 시간 오차를 다시 맞추기 위함이다.
- 이 검증 스캔도 같은 상태 파일과 요약 파일 체계를 사용한다.

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

- 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분`이 문서와 실행 설정에서 일치한다.
- cron 기준 실행이 중복 없이 유지된다.
- 30분 루프가 `2차 폴더까지 확인 -> 바뀐 폴더만 하강`으로 동작한다.
- 1회 실행 시간이 주기를 반복 초과하지 않는다.
- 하루 1회 파일 전수조사가 별도로 남는다.
- 해시는 기본 증분 판정이 아니라 표본 검증에만 남는다.
- 삭제 전파 없이 삭제 후보 로그만 남는다.

## 검증 기준

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

## 완료 조건

- `실시간` 대신 `30분 이내 반영`이라는 운영 표현이 문서와 실행 결과에서 일치한다.
- 30분 주기 계층형 탐색이 재현 가능하고, 중복 실행 없이 안정적으로 돈다.
- 하루 1회 파일 전수조사와 역할이 겹치지 않는다.
- 이 주제는 더 이상 막연한 실시간 아이디어가 아니라, 측정값에 근거한 운영 기준으로 전환된다.

## 현재 추천 결론

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

## 2026-03-12 적용 상태

- 사용자 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`으로 정상 동작을 확인했다.