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

# 260312 외부 NAS -> 내부 NAS 컴퍼니엑스 실시간동기화 리서치

## 상위 원칙
- [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)

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

## 목적

- `실시간에 가까운 동기화`가 현재 구조에서 왜 필요한지, 그리고 지금 근거로 어디까지 말할 수 있는지 좁힌다.
- 이 문서는 실시간 동기화 방식을 확정하는 문서가 아니라, `why`를 분리해 다음 `plans`가 무엇을 고정해야 하는지 정리하는 것을 목표로 한다.

## 리서치 질문

1. 이미 검증된 배치/재개 동기화 구조만으로도 운영 기준을 만족하는가
2. 실시간 또는 짧은 주기 동기화가 필요한 이유는 무엇인가
3. 현재 근거만으로 이벤트 기반 실시간 동기화를 말할 수 있는가
4. 지금 시점에서 닫을 수 있는 질문과 아직 닫을 수 없는 질문은 무엇인가

## Facts

### 1. 외부 NAS -> 내부 NAS 기본 동기화 구조는 이미 운영 가능 수준까지 검증됐다

- 외부 NAS `/6.Company X`를 내부 NAS `/mnt/nas/workspace/6.Company X`로 동기화하는 구조 자체는 이미 검증됐다.
- 2026-03-12 최종 실행 기준 `downloaded=18481`, `skipped=34352`, `failed=0`, `files_seen=52833`, `downloaded_bytes=83980539725`가 기록됐다.
- 즉 `실시간` 여부와 별개로, `외부 원본 -> 내부 기준 저장소 -> 서버는 내부 NAS만 사용` 구조는 이미 성립한다.

근거:
- [260307_external_nas_companyx_sync_research.md](./260307_external_nas_companyx_sync_research.md)
- [260311_external_nas_companyx_sync_운영계획.md](../plans/260311_external_nas_companyx_sync_운영계획.md)
- [260312_companyx_sync_상태기록강화_및_재개실행.md](../worklog/260312_companyx_sync_상태기록강화_및_재개실행.md)

### 2. 현재 검증된 접근 경로는 DSM API 기반 조회/다운로드다

- 외부 NAS 직접 SMB(Server Message Block) `139/445` 접근은 현재 직접 사용 경로가 아니다.
- 현재 검증된 외부 접근은 Synology DSM(DiskStation Manager) File Station API다.
- 따라서 지금 사실 기준에서 검증된 방식은 `외부 이벤트 push`가 아니라 `원격 조회 후 필요한 파일을 가져오는 pull` 구조다.

2026-03-12 21:01 KST 실측값:
- DSM 로그인: `4.124초`
- 루트 목록 조회 `/6.Company X`: `0.059초`, 응답 크기 `3401B`, 항목 `16개`
- 대표 사진 폴더 목록 조회 `/6.Company X/7. 사진/220308_X코스_5기 발표 사진`: `0.084초`, 응답 크기 `5559B`, 항목 `20개`
- 샘플 파일 다운로드 `Thumbs.db` `12,288B`: `0.175초`
- 샘플 파일 다운로드 엑셀 `151,832B`: `0.131초`
- 샘플 파일 다운로드 JPG `457,889B`: `0.233초`
- 샘플 파일 다운로드 PDF `20,147,273B`: `0.731초`, 약 `26.27 MiB/s`

근거:
- [260307_external_nas_to_internal_nas_sync_probe.md](./260307_external_nas_to_internal_nas_sync_probe.md)
- [260307_external_nas_companyx_sync_research.md](./260307_external_nas_companyx_sync_research.md)

### 3. 현재 구현 스크립트는 주기 실행/재개 실행에는 맞지만, 외부 변화 이벤트 수신 구조는 아니다

- 현재 스크립트 `/home/admin/infra/scripts/bin/companyx_external_nas_sync.py`는 DSM API로 폴더를 재귀 조회하고 파일을 내려받는다.
- 상태 파일, 실패 로그, 삭제 후보 로그, 요약 파일을 남기며 장시간 재개 실행도 가능하다.
- 하지만 코드와 현재 문서 기준으로는 외부 NAS 변화 이벤트를 받아 즉시 실행하는 webhook, queue, daemon 구조는 확인되지 않았다.

2026-03-12 21:01 KST 전체 트리 `--dry-run` 실측값:
- 실행 시작: `2026-03-12 21:01:21 KST`
- `3분 45초` 경과 시점에도 전체 스캔이 종료되지 않았다.
- 중단 직전 상태 파일 기준 `directories_seen=2744`, `files_seen=12913`, `failed=1`, `termination_signal=SIGTERM`이었다.
- 같은 시점 `downloaded=12912`, `downloaded_bytes=136,138,945,147`로 기록됐는데, 이는 `--dry-run`에서 실제 저장 대신 `내려받아야 할 파일`로 계산된 누적치다.
- 즉 `전체 트리 재조회 자체`가 분 단위 작업이며, 최소한 현재 구조를 그대로 두고는 `거의 즉시 반영`을 가정하기 어렵다.

근거:
- [/home/admin/infra/scripts/bin/companyx_external_nas_sync.py](/home/admin/infra/scripts/bin/companyx_external_nas_sync.py)
- [260311_companyx_external_nas_sync_스크립트구현_및_대표검증.md](../worklog/260311_companyx_external_nas_sync_스크립트구현_및_대표검증.md)
- [260312_companyx_sync_상태기록강화_및_재개실행.md](../worklog/260312_companyx_sync_상태기록강화_및_재개실행.md)

### 4. 실시간 동기화 필요성은 구조 성립 여부가 아니라 최신성 요구 수준에서 나온다

- 기존 아이디어 문서에서도 핵심 문제는 `내부 NAS 최신 반영 시점이 아직 실행 주기에 의존한다`는 점이었다.
- 즉 실시간 동기화의 질문은 `가능하냐`보다 `내부 NAS 반영 지연을 얼마나 줄여야 하느냐`에 가깝다.
- 현재까지는 전체 동기화 성공과 재개 가능성은 검증됐지만, `몇 분 이내`, `거의 즉시`, `일 단위` 중 어떤 최신성 목표가 필요한지는 아직 확정되지 않았다.

근거:
- [260312_external_nas_companyx_실시간동기화_아이디어.md](../ideas/260312_external_nas_companyx_실시간동기화_아이디어.md)

### 5. 현재 근거만으로는 이벤트 기반 실시간 동기화를 검증했다고 말할 수 없다

- 실동작으로 검증된 것은 `대표 경로 동기화`, `전체 트리 완주`, `재실행 건너뛰기`, `상태 기록`이다.
- 외부 NAS 변화 발생 직후 자동 감지, 즉시 실행, 중복 트리거 제어, 이동/삭제 이벤트 처리 같은 항목은 아직 직접 검증 기록이 없다.
- 따라서 `실시간 동기화 가능`보다는 `실시간에 가까운 주기 동기화 후보를 검토할 근거가 생겼다`가 현재 사실 범위에 더 맞다.

### 6. Search API는 부분적으로 동작하지만, 현재 NAS에서 전체 트리 증분 검색 대체재로 바로 쓰기는 어렵다

- 2026-03-12 21:07 KST 실측에서 `SYNO.FileStation.Search` 자체 호출은 성공했다.
- 작은 대표 폴더 `/6.Company X/7. 사진/220308_X코스_5기 발표 사진`에서는 정확 파일명 검색이 `start 0.060초 + list 0.078초`로 성공했고, `mtime_from/mtime_to` 조건도 정상 동작했다.
- 같은 대표 폴더에서 `mtime_window_hit`은 `total=19`, `mtime_window_miss`는 `0건`으로 나와 시간 조건 필터도 확인됐다.
- 하지만 루트 `/6.Company X` 전체 재귀 검색에서는 `Thumbs.db`, `창업기획자 등록절차 및 운영 안내(26.2월).hwp` 같은 실제 존재 파일명을 줘도 `finished=true`와 빈 결과만 반환됐다.
- 즉 현재 NAS에서는 `Search API = 사용 불가`는 아니지만, `전체 루트 증분 검색을 신뢰할 수 있는 상태`도 아니다.

2026-03-12 21:07~21:09 KST 실측값:
- 작은 폴더 정확 파일 검색: `start 0.060초`, `list 0.078초`, `total=1`
- 작은 폴더 `mtime` 적중 검색: `start 0.063초`, `list 0.072초`, `total=19`
- 작은 폴더 `mtime` 비적중 검색: `start 0.060초`, `list 0.074초`, `0건`
- 루트 전체 `Thumbs.db` 검색: `start 0.060초`, `list 0.073초`, `0건`
- 루트 전체 특정 HWP 검색: `start 0.058초`, `list 0.079초`, `finished=true`, 결과 없음

### 7. 해시 기반 판정은 `수정시각 + 파일 크기`보다 직접 측정 기준으로 훨씬 느리다

- 2026-03-12 21:19 KST 기준 `/mnt/nas/workspace/6.Company X`에서 대표 파일 4개와 임의 표본 20개, 총 `24개` 파일 `48,437,603B`를 대상으로 비교했다.
- 같은 파일 집합에서 `stat(파일 크기 + 수정시각)` 평균은 `0.927ms`였다.
- 같은 파일 집합에서 `sha256` 평균은 `617.713ms`였다.
- 즉 이 표본에서는 해시 계산이 `수정시각 + 파일 크기` 조회보다 약 `666.4배` 느렸다.
- 대표 파일별로도 `Thumbs.db 75.6배`, 엑셀 `149.5배`, JPG `286.8배`, 20MB PDF `518.8배`로 모두 해시 쪽이 현저히 느렸다.
- 따라서 현재 운영 질문이 `변경 여부 판정 속도`라면, 해시는 기본 증분 기준보다 표본 검증용으로 두는 것이 맞다.

2026-03-12 21:19 KST 실측값:
- 전체 표본 `24개`, `48,437,603B`
- `stat` 평균: `0.927ms`
- `sha256` 평균: `617.713ms`
- 비율: `sha256 / stat = 666.4배`
- `Thumbs.db` `12,288B`: `stat 0.015ms`, `sha256 1.137ms`, `75.6배`
- 엑셀 `151,832B`: `stat 0.018ms`, `sha256 2.750ms`, `149.5배`
- JPG `457,889B`: `stat 0.022ms`, `sha256 6.202ms`, `286.8배`
- PDF `20,147,273B`: `stat 0.351ms`, `sha256 181.927ms`, `518.8배`

### 8. 내부 NAS DSM API 로그인은 가능하지만, 알림/webhook 제어 API는 현재 노출되지 않았다

- 2026-03-12 21:49 KST 기준 내부 NAS `192.168.0.101:5001`은 DSM HTTPS로 응답했다.
- 같은 시각 내부 NAS 계정으로 DSM API 로그인도 성공했다.
- 다만 API 목록 조회 기준 `SYNO.Core.Notification`, `SYNO.Core.Notification.Advanced`는 현재 NAS에서 노출되지 않았다.
- 즉 `내부 NAS 관리자 계정으로 DSM API 로그인 가능`과 `파일 변경 webhook/API 제어 가능`은 같은 뜻이 아니다.
- 현재 확인 범위에서는 내부 NAS도 파일 접근 API(`SYNO.FileStation.List`)는 가능하지만, 알림/webhook 설정을 API로 제어할 직접 경로는 확인되지 않았다.

2026-03-12 21:49 KST 실측값:
- API 정보 조회: `SYNO.API.Auth`, `SYNO.Core.Desktop.Initdata`, `SYNO.Core.User`, `SYNO.FileStation.List` 노출 확인
- DSM API 로그인: `auth.cgi` 경유 `success=true`
- 파일 공유 조회: `docker`, `home`, `homes` 확인
- 알림 관련 API: `SYNO.Core.Notification*` 미노출

### 9. 전체 루트 1분 제한 실측 기준 현재 전수 조회는 약 23분대로 추정된다

- 2026-03-12 22:15 KST 기준 전체 루트 `/6.Company X`를 대상으로 `60초` 제한 실행을 했다.
- 이 실행은 `SIGTERM`으로 종료됐고, 그 시점 summary 기준 `directories_seen=436`, `files_seen=2276`, `skipped=2275`, `failed=1`이었다.
- 기존 전체 완주 기록의 총량 `directories_seen=10549`, `files_seen=52833`을 기준으로 단순 비례 추정하면 현재 전체 전수 조회 시간은 약 `23.4분`이다.
- 이 값은 엄밀한 완료 실측이 아니라 `1분 표본 기반 예측`이지만, 현재 구조에서 `10분 이내 전체 전수 조회`를 기본 가정으로 두기 어렵다는 근거로는 충분하다.

2026-03-12 22:15~22:16 KST 실측값:
- 제한 시간: `60초`
- `directories_seen=436`
- `files_seen=2276`
- `skipped=2275`
- `downloaded=0`
- `failed=1`
- `termination_signal=SIGTERM`
- 예상 전체 시간: `약 23.2~23.4분`

### 10. 1차 폴더와 2차 폴더 메타만 훑는 비용은 매우 낮다

- 2026-03-12 23:00 KST 기준 `/6.Company X` 루트 1회 조회만 `5회` 반복 측정한 결과 평균은 `60.14ms`였다.
- 같은 시각 `/6.Company X` 루트와 그 아래 1차 폴더 `14개`를 각각 non-recursive로 조회해 `2차 폴더까지` 확인한 결과 평균은 `983.861ms`였다.
- 즉 `전체 파일 전수조회 약 23분대`와 비교하면, `1차 폴더 메타 확인`과 `2차 폴더 메타 확인`은 운영 루프에 넣기 충분히 가볍다.
- 이 경로는 전체 파일을 매번 훑는 방식이 아니라, 상위 폴더 메타를 이용해 `어느 영역을 더 내려가야 할지` 후보를 좁히는 데 적합하다.

2026-03-12 23:00 KST 실측값:
- 루트 1회 조회 `5회` 평균: `60.14ms`
- 루트 엔트리: `16개`
- 1차 폴더 수: `14개`
- 루트 + 1차 폴더 `14개` 조회, 총 `15회 API 호출` 평균: `983.861ms`
- 2차 레벨 확인 결과: `2차 폴더 110개`, `2차 파일 36개`
- 응답 총량: `39,499B`

## Interpretation

### 1. 이 아이디어의 핵심 `why`는 구조 성립이 아니라 최신성 목표 정의다

- 기본 동기화 구조는 이미 검증됐기 때문에, 실시간 아이디어의 초점은 `무엇을 만들 수 있나`가 아니라 `왜 더 빠른 반영이 필요한가`다.
- 즉 다음 단계에서 먼저 닫아야 할 질문은 도구 선택보다 `허용 가능한 반영 지연`이다.

### 2. 현재 근거로 가장 보수적인 해석은 `계층형 탐색 + 짧은 주기 pull`이 1차 후보라는 것이다

- 현재 검증된 외부 접근이 DSM API pull 방식이고, 이벤트 수신 경로는 확인되지 않았다.
- 따라서 지금 근거만 놓고 보면 `외부 변화 감지 -> 즉시 push`보다 `짧은 주기 재조회 -> 증분 동기화`가 더 직접적인 운영 후보다.
- 이것은 권장안 확정이 아니라, 현재 검증 범위에 더 가까운 해석이다.
- 다만 2026-03-12 실측 기준 전체 트리 `dry-run`이 `3분 45초`를 넘어도 끝나지 않았으므로, 현재 구조 그대로는 `1분 미만` 같은 촘촘한 polling은 비현실적일 가능성이 높다.
- 반대로 단일 목록 조회가 `0.06~0.08초`, 20MB PDF 1건 다운로드가 `0.73초`였으므로, 범위를 더 좁히거나 상위 폴더를 분할하면 `짧은 주기 후보`를 다시 따져볼 여지는 있다.
- Search API는 작은 폴더에서는 매우 빠르지만, 루트 전체 재귀 검색에서는 실제 존재 파일도 놓쳤으므로 현재 단계에서 전체 스캔 대체재로 가정하면 안 된다.
- 따라서 지금 가장 보수적인 운영 해석은 `30분마다 2차 폴더까지 메타 확인 -> 바뀐 폴더만 3차 이하로 하강 -> 파일까지 내려가 증분 동기화`다.
- 같은 맥락에서 증분 기준도 해시보다 `수정시각 + 파일 크기`가 훨씬 빠르므로, 짧은 주기 운영에서는 해시를 기본 판정 기준으로 올리지 않는 것이 맞다.
- 내부 NAS도 현재 확인 기준으로는 `파일 변경 webhook`을 API로 바로 붙일 근거가 없으므로, 실시간 문제를 webhook 전제로 풀면 안 된다.
- 그리고 현재 1차 폴더 확인은 약 `60ms`, 2차 폴더 확인은 약 `1초`, 전체 파일 전수조회는 약 `23분대`로 추정되므로, `빠른 계층형 탐색 + 일일 전수보정`이 비용 대비 가장 현실적이다.

### 3. 실시간성 수준을 정하지 않으면 `plans`가 과도하게 넓어진다

- `1분 이내`, `10분 이내`, `업무시간대만 5분 주기`, `야간 1회`는 모두 다른 운영안이다.
- 최신성 목표가 없으면 polling 주기, 실패 복구, 동시 실행 방지, 삭제 정책, 경보 기준이 함께 흔들린다.
- 따라서 이 리서치의 결론은 `실시간 구현`이 아니라 `실시간 요구 수준을 먼저 고정해야 한다`는 데 있다.

## Unresolved

1. 최신성 목표
- 내부 NAS 반영 지연을 몇 분 이내로 요구하는지 아직 미확정

2. 외부 변화 감지 방식
- DSM API 폴링 외에 webhook 또는 이벤트 기반 경로가 실제로 가능한지 미검증
- DSM Search API를 루트 전체 증분 검색에 신뢰할 수 있는지 미확정
- 내부 NAS DSM에서 알림/webhook API를 별도 활성화하거나 제어할 수 있는지 미확정

3. 운영 비용
- 짧은 주기 재조회 시 DSM 세션, API 호출량, 장시간 중복 스캔 비용이 어느 정도인지 미확정
- 전체 해시 재계산 비용을 운영 주기에 포함할 수 있는지 미확정

4. 변경 유형별 정책
- 삭제, 이동, 부분 업로드, 파일 교체가 짧은 주기 동기화에서 어떻게 보일지 미확정

5. 실행 방식
- 2차 폴더 메타 확인 후 바뀐 폴더만 하강하는 계층형 탐색을 어떤 상태 파일 구조로 남길지 미확정

## 현재 결론

- `외부 NAS -> 내부 NAS` 동기화 자체는 이미 운영 가능 수준으로 검증됐으므로, 실시간 아이디어의 쟁점은 `가능성`이 아니라 `필요한 최신성 수준`이다.
- 현재 직접 검증된 경로는 DSM API 기반 pull이므로, 지금 사실 범위에서 말할 수 있는 가장 강한 결론은 `짧은 주기 증분 동기화 후보를 검토할 수 있다`까지다.
- 이벤트 기반 실시간 동기화는 아직 직접 검증되지 않았고, 전체 루트 전수 조회도 현재 예측상 `23분대`이므로, 다음 단계는 `30분마다 2차 폴더 메타 확인 -> 바뀐 폴더만 하강 동기화 -> 하루 1회 파일 전수조회`를 고정하는 `plans` 문서가 맞다.