ivada-infra/DOCS

happybell80 fcf43e2102 Document Company X external NAS sync flow

2026-03-11 19:11:25 +09:00

7.2 KiB

Raw Blame History

tags

tags

infra

nas

companyx

sync

plans

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

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

상위 원칙

관련 문서

문제 정의

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