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

# 260311 외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획

**상태**: 진행 중 (2026-03-11 대표 경로 검증 완료, 전체 트리 장기 실행 확인)

## 상위 원칙
- [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/260307_external_nas_companyx_sync_아이디어.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 리서치](../research/260307_external_nas_companyx_sync_research.md)
- [외부 NAS -> 내부 NAS Sync Probe](../../260307_external_nas_to_internal_nas_sync_probe.md)
- [NAS(192.168.0.101) SSOT 전환 및 CIFS 실마운트 복구](../troubleshooting/260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md)

## 문제 정의

- 외부 NAS `sigongipc.synology.me`의 컴퍼니엑스 원본 폴더 `/6.Company X`를 내부 NAS `/mnt/nas/workspace/6.Company X`로 운영 가능하게 동기화해야 한다.
- 아이디어와 리서치 단계에서 `단일 파일`, `대표 하위 폴더`, `목표 경로 샘플 동기화`, `재실행 시 크기 기준 건너뛰기`까지는 검증됐지만, 전체 트리 기준 운영 절차는 아직 고정되지 않았다.
- 이번 계획의 목표는 `외부 NAS 직접 사용` 문제를 닫고, `내부 NAS만 사용하는 재현 가능한 동기화 운영 절차`를 실제 실행 가능한 수준으로 고정하는 것이다.

## 구조 결정 고정

- 원본 기준 경로는 외부 NAS `/6.Company X`다.
- 내부 기준 경로는 `/mnt/nas/workspace/6.Company X`다.
- 서버와 후속 처리 시스템은 외부 NAS를 직접 읽지 않고 내부 NAS만 읽는다.
- 증분 기준은 `수정시각 + 파일 크기`로 고정한다.
- SHA256은 초기 검증, 표본 검증, 의심 파일 확인에만 제한적으로 사용한다.
- 외부 삭제는 내부 NAS에 자동 전파하지 않는다.
- 외부에는 없고 내부에는 남아 있는 파일은 삭제 후보 로그로만 남긴다.

## 실행 순서

### 1. 전체 동기화 실행 스크립트를 고정한다

- 외부 DSM File Station API 기준으로 `/6.Company X`를 재귀 조회하는 실행 스크립트를 `infra/scripts` 기준으로 정리한다.
- 대상 루트, 내부 저장 루트, 증분 기준, 실패 로그 경로가 모두 한 군데에서 읽히게 맞춘다.
- 실행 중 생성되는 임시 테스트 경로나 실험용 루트 의존성은 제거한다.

### 2. 전체 트리 1회 기준 동기화를 수행한다

- `/6.Company X` 전체를 `/mnt/nas/workspace/6.Company X`로 1회 동기화한다.
- 총 파일 수, 총 용량, 총 소요 시간, 실패 파일 수를 기록한다.
- 중간 실패가 나면 실패 지점과 마지막 성공 지점을 남긴다.

### 3. 재실행 증분 동작을 검증한다

- 같은 작업을 다시 실행해 변경 없는 파일이 재다운로드되지 않는지 확인한다.
- 수정 파일 1건 또는 대표 샘플 변경 상황을 만들어 `수정시각 + 파일 크기` 기준 증분 반영이 동작하는지 확인한다.
- 해시 검증은 표본 파일만 수행해 과도한 전체 비용 없이 일관성을 확인한다.

### 4. 삭제 후보 기록 방식을 고정한다

- 외부에는 없고 내부에는 남아 있는 파일을 자동 삭제하지 않는다.
- 삭제 후보 목록을 날짜 기준 로그 파일로 남긴다.
- 운영자가 삭제 여부를 나중에 판단할 수 있게 경로, 파일 크기, 마지막 확인 시각을 함께 기록한다.

### 5. 실패 복구와 실행 기록을 고정한다

- 실패 파일 목록은 `/mnt/nas/workspace/.sync-logs/companyx_sync_failures_YYYYMMDD.jsonl`에 남긴다.
- 각 실패 기록은 `path`, `error`, `attempted_at`, `stage`를 포함한다.
- 마지막 성공 지점은 `/mnt/nas/workspace/.sync-logs/companyx_sync_state.json` 하나로 관리한다.
- 상태 파일은 `last_success_at`, `last_scanned_path`, `last_downloaded_path`, `run_id`를 포함한다.
- 다음 실행 시 전체 처음부터 다시 받지 않고 이어서 판단할 수 있는 최소 기록 구조를 이 파일들로 고정한다.
- 실행 결과는 `성공 수`, `건너뛴 수`, `실패 수`, `삭제 후보 수`로 요약할 수 있게 맞춘다.

### 6. 인증서 처리 방침을 분리한다

- 현재 운영은 `-k` 우회로 동작하지만, 이것을 장기 상시 기준으로 승격하지 않는다.
- 동기화 기능 검증과 인증서 정상화는 분리한다.
- 계획 범위에서는 `현재 우회 동작 유지 + 인증서 이슈 명시 기록`까지를 적용하고, 인증서 교정은 별도 후속 작업으로 분리한다.

### 7. 삭제 후보 로그 형식을 고정한다

- 삭제 후보 로그는 `/mnt/nas/workspace/.sync-logs/companyx_delete_candidates_YYYYMMDD.jsonl`에 남긴다.
- 각 삭제 후보 기록은 `path`, `size`, `last_seen_remote_at`, `detected_at`를 포함한다.
- 삭제 후보 로그는 운영 판단용 기록이며, 자동 삭제 트리거로 사용하지 않는다.

## 체크리스트

- 실행 스크립트가 `/6.Company X`와 `/mnt/nas/workspace/6.Company X`를 기준 경로로 사용한다.
- 전체 동기화 1회 결과에 총 파일 수, 총 용량, 총 시간, 실패 수가 남는다.
- 재실행 시 변경 없는 파일이 재다운로드되지 않는다.
- 수정 파일 반영 기준이 `수정시각 + 파일 크기`로 동작한다.
- 삭제 전파는 없고, 삭제 후보 로그만 남는다.
- 실패 파일과 마지막 성공 지점이 남는다.
- 실패 로그, 상태 파일, 삭제 후보 로그 위치와 필드가 문서 기준과 일치한다.
- 외부 NAS 직접 사용이 아닌 내부 NAS 기준 경로 사용 원칙이 문서와 실행 결과 모두에서 일치한다.

## 검증 기준

- `/mnt/nas/workspace/6.Company X` 아래에 전체 동기화 결과가 실제 생성된다.
- 실행 결과 로그에서 `downloaded`, `skipped`, `failed`, `delete_candidates`를 구분할 수 있다.
- 같은 입력으로 재실행했을 때 `skipped`가 증가하고 불필요한 재다운로드가 발생하지 않는다.
- 표본 파일 해시 검증에서 원본 다운로드와 내부 저장 결과가 일치한다.
- 삭제 후보 로그에 자동 삭제 없이 후보만 기록된다.
- 실패 로그와 상태 파일에 재시도 판단에 필요한 필드가 실제로 기록된다.

## 완료 조건

- `/6.Company X -> /mnt/nas/workspace/6.Company X` 전체 동기화 절차가 재현 가능하게 정리된다.
- 증분 기준과 삭제 비전파 원칙이 문서와 실행 결과에서 일치한다.
- 실패 복구와 실행 요약이 남아 운영자가 같은 작업을 다시 이어갈 수 있다.
- 실패 로그, 상태 파일, 삭제 후보 로그 포맷이 실제 산출물로 확인된다.
- 이 이슈는 더 이상 `아이디어/리서치` 문제가 아니라, `실행 검증 완료 여부`만 남은 상태가 된다.