ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

Record Company X sync recovery progress

Browse Source
This commit is contained in:
happybell80 2026-03-12 12:35:30 +09:00
parent 1e9757f4d2
commit 5114fa9e4b
5 changed files with 300 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
journey/plans/260311_external_nas_companyx_sync_운영계획.md
View File

@ -4,7 +4,7 @@ tags: [infra, nas, companyx, sync, plans]
# 260311 외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획
**상태**: 진행 중 (2026-03-11 대표 경로 검증 완료, 전체 트리 장기 실행 확인)
**상태**: 진행 중 (2026-03-12 상태 기록 강화 후 전체 트리 재개 실행 중)
## 상위 원칙
- [Infra Project Identity](../../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md)
@ -109,3 +109,9 @@ tags: [infra, nas, companyx, sync, plans]
- 실패 복구와 실행 요약이 남아 운영자가 같은 작업을 다시 이어갈 수 있다.
- 실패 로그, 상태 파일, 삭제 후보 로그 포맷이 실제 산출물로 확인된다.
- 이 이슈는 더 이상 `아이디어/리서치` 문제가 아니라, `실행 검증 완료 여부`만 남은 상태가 된다.
## 2026-03-12 현재 상태
- `companyx_external_nas_sync.py`는 장시간 실행 중에도 `/mnt/nas/workspace/.sync-logs/companyx_sync_state.json`을 갱신하도록 보강됐다.
- 전체 경로 재개 실행에서 `downloaded`, `skipped`, `directories_seen`, `files_seen`, `last_scanned_path`, `last_downloaded_path`가 실제 누적 기록되는 것을 확인했다.
- 따라서 현재 남은 일은 `상태 미기록 종료` 해결이 아니라, 전체 경로 완주 후 최종 `summary`와 최종 산출 수치를 남기는 실행 마감이다.

91
journey/plans/260312_companyx_sync_상태기록강화_및_재개실행_계획.md Normal file
View File

@ -0,0 +1,91 @@
---
tags: [infra, nas, companyx, sync, plans]
---
# 260312 Company X 상태 기록 강화 및 재개 실행 계획
**상태**: 대부분 완료 (2026-03-12 상태 기록 강화 구현, tmp 인벤토리 생성, 전체 재개 실행 중)
## 상위 원칙
- [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)
## 관련 문서
- [Company X 장시간 동기화 상태 미기록 종료 이슈](../troubleshooting/260312_companyx_sync_장시간동기화_상태미기록종료_이슈.md)
- [Company X 장시간 동기화 상태 미기록 종료 리서치](../research/260312_companyx_sync_장시간동기화_상태미기록종료_리서치.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획](./260311_external_nas_companyx_sync_운영계획.md)
## 문제 정의
- 현재 스크립트는 장시간 실행 중단 시 상태 파일과 실패 로그를 남기지 못해 전체 동기화 완료 여부를 닫지 못한다.
- 목표는 전체 동기화를 다시 시작하는 것이 아니라, `중간 상태가 남는 재개 가능 실행`으로 바꿔서 이 아이디어를 운영 기준으로 닫는 것이다.
## 구조 결정 고정
- 상태 파일은 마지막에만 쓰지 않고, 파일 다운로드 성공 시마다 갱신한다.
- 실패 로그도 예외 발생 시 즉시 append 한다.
- 임시 파일은 자동 삭제하지 않고, 재개 전 별도 목록으로 기록한다.
- 전체 재개 실행 전 기존 `tmp*` 파일 목록을 먼저 남긴다.
- 상태 파일 경로는 `/mnt/nas/workspace/.sync-logs/companyx_sync_state.json`로 고정한다.
- 실패 로그 경로는 `/mnt/nas/workspace/.sync-logs/companyx_sync_failures_YYYYMMDD.jsonl`로 고정한다.
- 임시 파일 진단 로그 경로는 `/mnt/nas/workspace/.sync-logs/companyx_tmp_inventory_YYYYMMDD.jsonl`로 고정한다.
- 실행 요약 파일 경로는 `/mnt/nas/workspace/.sync-logs/companyx_sync_summary_YYYYMMDD_HHMMSS.json`로 고정한다.
## 실행 순서
### 1. 스크립트 상태 기록을 강화한다
- `last_scanned_path`, `last_downloaded_path`, `updated_at`, `downloaded`, `skipped`, `failed` 누적치를 중간에도 기록하게 바꾼다.
- 종료 시점이 아니라 실행 중에도 상태 파일이 남게 만든다.
- 최소 기록 주기는 `파일 다운로드 성공 시마다 1회`로 둔다.
- 디렉터리 스캔만 진행되고 다운로드가 없을 때도 `last_scanned_path`, `updated_at`은 주기적으로 갱신하게 한다.
### 2. 임시 파일 진단 목록을 남긴다
- `/mnt/nas/workspace/6.Company X` 아래 `tmp*` 파일 경로, 크기, 수정시각을 별도 진단 로그로 기록한다.
- 이 단계에서는 삭제하지 않는다.
- 필드는 `path`, `size`, `mtime`, `captured_at`, `run_id`로 고정한다.
### 3. 전체 동기화를 다시 재개한다
- 같은 대상 `/6.Company X -> /mnt/nas/workspace/6.Company X`로 실행한다.
- 이미 받은 파일은 `수정시각 + 파일 크기` 기준으로 건너뛴다.
- 재개 실행 명령 기준:
- `/home/admin/infra/scripts/bin/companyx_external_nas_sync.py`
### 4. 종료 상태를 검증한다
- 완료 시 상태 파일, 실패 로그, 삭제 후보 로그, 최종 요약이 모두 남는지 확인한다.
- 재실행 시 `skipped` 증가와 불필요한 재다운로드 부재를 다시 확인한다.
- 완료 후 기본 검증 명령 기준:
- `pgrep -af 'companyx_external_nas_sync.py$'`
- `find '/mnt/nas/workspace/.sync-logs' -maxdepth 1 -type f | sort`
- `sed -n '1,120p' /mnt/nas/workspace/.sync-logs/companyx_sync_state.json`
## 체크리스트
- 상태 파일이 실행 중에도 갱신된다. 완료
- 실패 로그가 예외 시 즉시 append 된다.
- 재개 전 기존 `tmp*` 목록이 기록된다. 완료
- 재개 실행 후 최종 요약이 남는다. 대표 경로 완료, 전체 경로 진행 중
- 대표 경로와 전체 경로 모두에서 재실행 가능성이 확인된다. 진행 중
- 상태 파일, 실패 로그, 임시파일 진단 로그, 요약 파일의 경로와 필드가 고정값대로 생성된다. 대표 경로 완료, 전체 경로 진행 중
## 검증 기준
- `/mnt/nas/workspace/.sync-logs/companyx_sync_state.json`이 실행 중에도 최신 시각으로 갱신된다.
- 실패가 있으면 `companyx_sync_failures_YYYYMMDD.jsonl`에 즉시 남는다.
- 재개 실행 후 전체 요약에서 `downloaded/skipped/failed/delete_candidates`가 구분된다.
- 완료 후 임시 파일 잔존 여부와 최종 파일 상태를 비교 설명할 수 있다.
- 임시 파일 진단 로그와 최종 요약 파일이 실제로 생성된다.
## 완료 조건
- 전체 동기화가 중단돼도 현재 위치를 설명할 수 있는 상태 기록이 남는다.
- 재개 실행으로 `/6.Company X -> /mnt/nas/workspace/6.Company X`를 운영 기준으로 닫을 수 있다.
- 이 주제는 더 이상 `원인 불명 종료` 문제가 아니라 `완주 기록이 남는 운영 절차`로 전환된다.
## 2026-03-12 실행 결과
- `/home/admin/infra/scripts/bin/companyx_external_nas_sync.py`에 상태 파일 중간 기록, tmp 인벤토리, 요약 파일, 종료 신호 처리 로직을 반영했다.
- 대표 경로 재실행에서 `companyx_sync_state.json`, `companyx_sync_summary_20260312_121529.json`, `companyx_tmp_inventory_20260312.jsonl` 생성을 확인했다.
- 전체 경로 재개 실행에서는 `companyx_sync_state.json`이 장시간 실행 중에도 갱신되는 것을 확인했다.
- 따라서 이 계획의 핵심이었던 `상태 미기록` 복구는 달성됐고, 남은 것은 원래 동기화 계획의 완주 기록이다.

92
journey/research/260312_companyx_sync_장시간동기화_상태미기록종료_리서치.md Normal file
View File

@ -0,0 +1,92 @@
---
tags: [infra, nas, companyx, sync, research]
---
# 260312 Company X 장시간 동기화 상태 미기록 종료 리서치
**상태**: 해결 근거 확보 (2026-03-12 상태 기록 강화 적용 후 장시간 재개 실행에서 중간 상태 갱신 확인)
## 상위 원칙
- [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)
## 관련 문서
- [Company X 장시간 동기화 상태 미기록 종료 이슈](../troubleshooting/260312_companyx_sync_장시간동기화_상태미기록종료_이슈.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획](../plans/260311_external_nas_companyx_sync_운영계획.md)
## 목적
- 장시간 전체 동기화가 상태 파일과 실패 로그 없이 종료된 원인을 사실 기준으로 좁히고, 다음 복구 계획에서 무엇을 먼저 고쳐야 하는지 정리한다.
## Facts
1. 대표 경로 기준 스크립트 동작 자체는 정상이다.
- 대표 폴더 20개 파일 동기화와 재실행 `skipped=20`이 확인됐다.
2. 전체 트리 장시간 실행에서는 실제 데이터 누적이 있었다.
- 내부 경로 `/mnt/nas/workspace/6.Company X`가 `283G` 수준까지 증가했다.
- 즉 전체 실행이 시작 직후 실패한 것은 아니다.
3. 2026-03-12 보강 후에는 실행 메타데이터가 남는다.
- `/mnt/nas/workspace/.sync-logs/companyx_sync_state.json`
- `/mnt/nas/workspace/.sync-logs/companyx_tmp_inventory_20260312.jsonl`
- 대표 경로에서는 `companyx_sync_summary_20260312_121529.json`도 생성됐다.
4. 임시 파일은 남아 있다.
- 최신 흔적 예시는 `tmp3fe5jpym` `393,216,000B`, `tmpjrz40eiq` `0B`다.
- 임시 파일이 남았다는 것은 최소 일부 다운로드가 `os.replace` 이전에 끊겼다는 뜻이다.
5. 직접 실패 원인 로그는 없다.
- 현재 기준 `companyx_external_nas_sync.py` 프로세스는 없고, 상태 파일/실패 로그도 없어 내부 예외와 외부 종료를 구분할 직접 근거가 없다.
6. 코드 구조를 2026-03-12에 보강했다.
- 상태 파일은 시작 시, 다운로드 성공 시, 스캔 진행 중 주기적으로 기록된다.
- 임시 파일 목록은 실행 시작 전에 별도 JSONL로 남긴다.
- 요약 파일은 대표 경로 검증에서 실제 생성됐다.
- `SIGINT`, `SIGTERM`, `SIGHUP`에서도 상태와 요약을 남기도록 신호 처리를 추가했다.
7. 현재까지 가장 유력한 원인 후보는 `외부 중단 또는 세션 기반 종료`다.
- 직접 실패 로그가 없고, 상태 파일도 전혀 없으며, 장시간 데이터 누적 후 프로세스만 사라졌다.
- 이 패턴은 `초기 즉시 실패`보다 `장시간 실행 중 외부 종료` 쪽과 더 잘 맞는다.
- 다만 이것도 확정이 아니라 상대적으로 유력한 해석이다.
## Interpretation
1. 지금 닫힌 질문
- 아이디어 자체가 가능한가: 예
- 스크립트 기본 동작이 가능한가: 예
- 전체 트리 동기화가 장시간 실제 다운로드를 수행했는가: 예
2. 지금 안 닫힌 질문
- 왜 종료됐는가
- 다음 실행이 어디서부터 재개돼야 하는가
- 임시 파일을 어떻게 처리해야 운영적으로 안전한가
3. 가장 큰 구조 결함
- 스크립트가 `finished_at`과 상태 파일을 마지막에만 쓰는 구조라, 장시간 실행 중단 시 실행 흔적이 거의 남지 않는다.
- 즉 현재 문제의 핵심은 `동기화 알고리즘`보다 `중간 상태 기록 부재`다.
4. 지금 우선순위는 종료 원인 확정보다 재개 가능성 확보다.
- 종료 원인을 100% 확정하지 못해도, 상태 파일을 중간에 남기게 바꾸면 같은 종류의 불확실성을 크게 줄일 수 있다.
- 따라서 다음 단계는 포렌식보다 `상태 기록 강화 + 재개 실행 검증`이 맞다.
## Unresolved
1. 종료 원인 확정
- 외부 중단, 세션 중단, 네트워크 실패, 원격 응답 문제 중 무엇인지 미확정
2. 임시 파일 처리 기준
- 그대로 재시도할지, 먼저 분리 보관할지, 삭제 후보로 볼지 미확정
3. 상태 기록 주기
- 파일 단위, 디렉터리 단위, 주기적 flush 중 무엇이 적절한지 미확정
4. 실행 요약 파일 형식
- 콘솔 출력 외에 별도 `summary json` 파일을 남길지 아직 미확정
## 현재 결론
- 이 문제는 기존 아이디어의 반박 근거가 아니라, 실행 안정성 보강이 필요한 별도 주제였고 2026-03-12 기준 핵심 결함인 `상태 미기록`은 해결됐다.
- 현재 남은 것은 이 리서치 주제가 아니라, 원래 Company X 동기화 운영계획에서 전체 동기화 완주와 최종 요약 파일을 남기는 실행 마감이다.

73
journey/troubleshooting/260312_companyx_sync_장시간동기화_상태미기록종료_이슈.md Normal file
View File

@ -0,0 +1,73 @@
---
tags: [infra, nas, companyx, sync, troubleshooting]
---
# 260312 Company X 장시간 동기화 상태 미기록 종료 이슈
**상태**: 해결됨 (2026-03-12 상태 기록 강화 적용 후 장시간 재개 실행에서 `state.json` 실시간 갱신 확인)
## 상위 원칙
- [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/260307_external_nas_companyx_sync_아이디어.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 리서치](../research/260307_external_nas_companyx_sync_research.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획](../plans/260311_external_nas_companyx_sync_운영계획.md)
- [Company X 외부 NAS 동기화 스크립트 구현 및 대표 검증](../worklog/260311_companyx_external_nas_sync_스크립트구현_및_대표검증.md)
## 문제 정의
- `companyx_external_nas_sync.py`로 `/6.Company X -> /mnt/nas/workspace/6.Company X` 전체 동기화를 장시간 실행했지만, 프로세스 종료 후 상태 파일과 실패 로그가 남지 않았다.
- 따라서 전체 동기화가 어디까지 성공했고 어디에서 왜 끊겼는지 실행 결과만으로 닫을 수 없다.
- 이 문제는 아이디어 타당성 문제가 아니라, 장시간 실행을 운영 가능한 상태로 남기지 못한 실행 안정성 문제다.
## 재현 조건
- 대상: 외부 NAS `/6.Company X`
- 내부 경로: `/mnt/nas/workspace/6.Company X`
- 스크립트: `/home/admin/infra/scripts/bin/companyx_external_nas_sync.py`
- 대용량 디자인/영상 파일이 포함된 전체 트리 기준 장시간 실행
## 확인된 사실
1. 대표 경로 검증은 정상 동작했다.
- `/6.Company X/7. 사진/220308_X코스_5기 발표 사진` 기준 1회 동기화는 `downloaded=20`, 2회 재실행은 `skipped=20`, `failed=0`이었다.
2. 전체 트리 실행에서는 실제 데이터가 크게 누적됐다.
- 확인 시점 기준 `/mnt/nas/workspace/6.Company X`는 약 `283G`까지 증가했다.
3. 2026-03-12 보강 전 실행에서는 `companyx_external_nas_sync.py` 프로세스만 사라지고 실행 메타데이터가 남지 않았다.
- `pgrep -af 'companyx_external_nas_sync.py$'` 결과 없음
4. 2026-03-12 보강 후 실행에서는 `/mnt/nas/workspace/.sync-logs/`에 상태 파일과 임시파일 진단 로그가 생성됐다.
- `companyx_sync_state.json`
- `companyx_tmp_inventory_20260312.jsonl`
- 즉 장시간 실행 중 현재 위치를 설명할 최소 메타데이터는 남길 수 있게 됐다.
5. 임시 파일 흔적은 남아 있다.
- 예: `tmp3fe5jpym` `393,216,000B`
- 예: `tmpjrz40eiq` `0B`
- 즉 일부 다운로드는 완료 파일이 아니라 임시 파일 상태로 끊겼다.
6. 종료 직전 장시간 실행 흔적은 있었다.
- 이전 확인 기준 `companyx_external_nas_sync.py` 프로세스는 약 `2시간 46분` 이상 살아 있었다.
- 당시 CPU 사용률은 약 `16%`, 메모리 사용률은 약 `0.1%` 수준이었다.
- 내부 경로 용량은 장시간 실행 중 `11G -> 29G -> 143G -> 208G -> 283G`로 계속 증가했다.
7. 최신 임시 파일 시각은 2026-03-11 저녁 구간에 집중된다.
- 최신 예시: `2026-03-11 19:27:19 KST`, `tmp3fe5jpym`, `393,216,000B`
- 즉 오래된 원본 폴더 내부에 과거부터 있던 `tmp*`와, 이번 실행 중 새로 남은 `tmp*`를 구분해서 봐야 한다.
## 영향 범위
- 전체 동기화 완주 여부를 현재 결과만으로 단정할 수 없다.
- 재개 시 어떤 파일을 다시 받아야 하는지, 어떤 임시 파일을 어떻게 취급해야 하는지 운영 판단이 애매해진다.
- 아이디어 종료 기준인 `재현 가능한 동기화 운영 절차`가 아직 닫히지 않는다.
## 해결 후 남은 항목
- 최초 종료 원인은 여전히 확정되지 않았다.
- 다만 현재 주제의 핵심이었던 `상태 미기록`은 해결됐고, 남은 것은 전체 동기화 완주와 최종 요약 파일 확인이다.

37
journey/worklog/260312_companyx_sync_상태기록강화_및_재개실행.md Normal file
View File

@ -0,0 +1,37 @@
---
tags: [infra, nas, companyx, sync, worklog]
---
# 260312 Company X 상태기록 강화 및 재개 실행
## 관련 문서
- [Company X 장시간 동기화 상태 미기록 종료 이슈](../troubleshooting/260312_companyx_sync_장시간동기화_상태미기록종료_이슈.md)
- [Company X 장시간 동기화 상태 미기록 종료 리서치](../research/260312_companyx_sync_장시간동기화_상태미기록종료_리서치.md)
- [Company X 상태 기록 강화 및 재개 실행 계획](../plans/260312_companyx_sync_상태기록강화_및_재개실행_계획.md)
- [외부 NAS -> 내부 NAS 컴퍼니엑스 동기화 운영계획](../plans/260311_external_nas_companyx_sync_운영계획.md)
## 작업
- `/home/admin/infra/scripts/bin/companyx_external_nas_sync.py`에 중간 상태 기록, 임시 파일 인벤토리, 실행 요약 파일, 종료 신호 처리 로직을 추가했다.
- 상태 파일 경로는 `/mnt/nas/workspace/.sync-logs/companyx_sync_state.json`로 고정했고, 누적 `downloaded`, `skipped`, `failed`, `directories_seen`, `files_seen`, `downloaded_bytes`, `last_scanned_path`, `last_downloaded_path`를 실행 중에도 기록하게 맞췄다.
- 임시 파일 진단 로그 `/mnt/nas/workspace/.sync-logs/companyx_tmp_inventory_20260312.jsonl`를 생성해 기존 `tmp*` 9건을 기록했다.
- 전체 경로 `/6.Company X -> /mnt/nas/workspace/6.Company X` 재개 실행을 다시 시작했다.
## 검증
- 문법 검증: `python3 -m py_compile /home/admin/infra/scripts/bin/companyx_external_nas_sync.py`
- 대표 경로 재실행: `/6.Company X/7. 사진/220308_X코스_5기 발표 사진` 기준 `downloaded=0`, `skipped=20`, `failed=0`
- 대표 경로 로그 생성 확인:
- `companyx_sync_state.json`
- `companyx_sync_summary_20260312_121529.json`
- `companyx_tmp_inventory_20260312.jsonl`
- 전체 경로 재개 실행 중 상태 파일 갱신 확인:
- `2026-03-12 12:17:41+09:00`: `skipped=4733`, `failed=0`
- `2026-03-12 12:19:33+09:00`: `downloaded=6`, `skipped=11366`, `failed=0`
- `2026-03-12 12:26:22+09:00`: `downloaded=238`, `skipped=34352`, `failed=0`
- `2026-03-12 12:32:37+09:00`: `downloaded=1287`, `skipped=34352`, `failed=0`
- 즉 장시간 실행 중단 시 아무 흔적도 남지 않던 이전 문제와 달리, 현재는 실행 중에도 현재 위치와 누적치가 남는다.
## 한 줄 결론
- Company X 장시간 동기화의 핵심 운영 문제였던 `상태 미기록 종료`는 해결됐고, 현재 전체 동기화는 상태 기록이 남는 형태로 계속 진행 중이다.