Document NAS sync migration and verification runbook

2026-03-14 11:12:18 +09:00 · 2026-03-14 11:12:18 +09:00 · b9a1d2a9ad
commit b9a1d2a9ad
parent 3b20c0ef5f
5 changed files with 276 additions and 2 deletions
--- a/02_Architecture/51123_to_internal_nas_sync_verification_runbook.md
+++ b/02_Architecture/51123_to_internal_nas_sync_verification_runbook.md
@ -0,0 +1,209 @@
+---
+tags: [infra, nas, sync, runbook, 51123, companyx]
+---
+
+# 51123 -> 내부 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)
+
+## 관련 문서
+- [Infrastructure Project Structure](./Infrastructure_Project_Structure.md)
+- [260307 NAS(192.168.0.101) SSOT 전환 및 CIFS 실마운트 복구](../journey/troubleshooting/260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md)
+- [260313 내부 NAS -> 외부 NAS 경로 교정 및 Go 프로브 검증](../journey/troubleshooting/260313_internal_nas_external_nas_route_fix_and_go_probe_verification.md)
+- [260313 내부 NAS 직접 Go 동기화 가능성 리서치](../journey/research/260313_internal_nas_direct_go_sync_feasibility_research.md)
+
+## 목적
+
+- 51123 서버에서 내부 NAS `192.168.0.101`에 접속해 Company X 외부 NAS 동기화 상태를 같은 절차로 반복 점검한다.
+- 이 문서는 사건 기록이 아니라, 운영자가 다시 실행할 수 있는 고정 절차를 남기는 런북이다.
+
+## 적용 범위
+
+- 점검 주체: 51123 서버
+- 점검 대상: 내부 NAS `192.168.0.101`
+- 점검 주제:
+  - NAS SSH 접속 가능 여부
+  - NAS 라우팅이 외부 NAS 경로 기준으로 유지되는지
+  - Go 테스트 결과가 남아 있는지
+  - 현재 운영 중인 fullscan / hierarchical 동기화가 실패 없이 끝났는지
+
+## SSOT 기준값
+
+- 내부 NAS 호스트: `192.168.0.101`
+- NAS 공유 기준: `/mnt/nas`
+- 51123 런타임 기준 파일:
+  - `/home/admin/workspace-config/runtime.env`
+  - `/home/admin/workspace-config/secrets.env`
+- 23 서버 cron 기준:
+  - `*/30 * * * * /home/admin/infra/scripts/bin/companyx_external_nas_sync_hierarchical_cron.sh`
+  - `0 1 * * * /home/admin/infra/scripts/bin/companyx_external_nas_sync_fullscan_cron.sh`
+- NAS 로컬 동기화 로그 기준:
+  - `~/workspace/.sync-logs/`
+  - `~/workspace/.sync-logs-hierarchical/`
+- NAS 로컬 Go 테스트 흔적 기준:
+  - `~/workspace/.sync-logs-go/`
+  - `~/workspace/.sync-logs-go-real-20260313/`
+  - `~/workspace/.sync-logs-go-live/`
+
+## 사전 확인
+
+### 1. 51123 기준값 확인
+
+```bash
+grep -n '^NAS_' /home/admin/workspace-config/runtime.env /home/admin/workspace-config/secrets.env
+crontab -l
+ls -la /mnt/nas/workspace/.sync-logs /mnt/nas/workspace/.sync-logs-hierarchical
+```
+
+확인 기준:
+- `NAS_HOST=192.168.0.101`이어야 한다.
+- 30분 계층형과 1일 1회 전수조사 cron이 보여야 한다.
+- `/mnt/nas/workspace/.sync-logs*` 아래 최신 summary 파일이 있어야 한다.
+
+### 2. NAS SSH 포트 확인
+
+```bash
+nc -vz -w 3 192.168.0.101 22
+ssh-keygen -F 192.168.0.101
+```
+
+확인 기준:
+- `22/tcp` 접속 성공
+- known_hosts에 기존 호스트키가 있으면 재확인 없이 바로 접속 가능
+
+## 접속 절차
+
+### 1. 51123에서 내부 NAS SSH 접속
+
+```bash
+ssh -o StrictHostKeyChecking=no admin@192.168.0.101
+```
+
+설명:
+- 현재 운영 확인 기준 계정은 `admin`이다.
+- 비대화형 키 접속이 보장되지 않으므로, 필요 시 비밀번호 입력으로 접속한다.
+- 이 문서는 접속 방법을 남기는 문서이며, 비밀번호 값 자체는 문서에 적지 않는다.
+
+### 2. NAS 기본 상태 확인
+
+```bash
+date
+hostname
+whoami
+ip route
+```
+
+성공 기준:
+- `hostname`은 내부 NAS 장비명으로 응답해야 한다.
+- 라우팅에 `default via 192.168.0.1 dev eth1`가 있어야 한다.
+- 외부 NAS 호스트 라우트가 있으면 `112.218.113.4 via 192.168.0.1 dev eth1` 형태여야 한다.
+
+## 점검 절차
+
+### 1. NAS 내부에서 동기화 관련 경로 찾기
+
+```bash
+find ~ -maxdepth 3 \( -name '*companyx*' -o -name '*probe*' -o -name '*.log' -o -path '*/log/*' \) 2>/dev/null | sort | tail -n 200
+```
+
+목적:
+- Go 프로브/테스트 바이너리와 로컬 sync 로그 경로가 실제로 남아 있는지 본다.
+
+### 2. Go 테스트 결과 확인
+
+```bash
+for f in \
+  ~/workspace/.sync-logs-go/companyx_sync_summary_*.json \
+  ~/workspace/.sync-logs-go-real-20260313/companyx_sync_summary_*.json \
+  ~/workspace/.sync-logs-go-live/companyx_sync_summary_*.json
+do
+  [ -f "$f" ] && echo "FILE=$f" && cat "$f"
+done
+```
+
+판단 기준:
+- 샘플 다운로드 테스트는 `downloaded > 0`, `failed = 0`이면 1차 성공으로 본다.
+- 같은 경로 재실행 테스트는 `downloaded = 0`, `skipped > 0`, `failed = 0`이면 증분 판정이 동작한 것으로 본다.
+- 루트 기준 go-live 테스트는 `files_seen`과 `downloaded/skipped/failed`가 남아 있어야 한다.
+
+### 3. 현재 fullscan 운영 결과 확인
+
+```bash
+cat ~/workspace/.sync-logs/companyx_sync_state.json
+ls -1t ~/workspace/.sync-logs/companyx_sync_summary_*.json | head -n 3 | while read f; do
+  echo "FILE=$f"
+  cat "$f"
+done
+```
+
+판단 기준:
+- 최신 summary에 `finished_at`이 있어야 한다.
+- `failed = 0`이면 실패 없이 종료한 것이다.
+- `downloaded = 0`이어도 `skipped > 0`이면 정상 재검사일 수 있으므로 실패로 보지 않는다.
+- state 파일의 `updated_at`, `last_scanned_path`, `last_downloaded_path`가 있으면 상태 기록 기능은 정상으로 본다.
+
+### 4. 현재 hierarchical 운영 결과 확인
+
+```bash
+cat ~/workspace/.sync-logs-hierarchical/companyx_sync_state.json
+ls -1t ~/workspace/.sync-logs-hierarchical/companyx_sync_summary_*.json | head -n 3 | while read f; do
+  echo "FILE=$f"
+  cat "$f"
+done
+```
+
+판단 기준:
+- 최근 30분 실행 summary가 계속 생성돼야 한다.
+- `failed = 0`이면 정상 종료다.
+- `downloaded = 0`, `skipped > 0`은 캐시 기반 점검에서 흔한 정상 결과다.
+
+### 5. 필요 시 결과물 실체 확인
+
+```bash
+find ~/workspace/companyx_go_sample_real_20260313 -type f | wc -l
+stat -c '%n %s %y' ~/workspace/companyx_go_sample_real_20260313/Thumbs.db
+find ~/workspace/6.Company\ X -type f | wc -l
+stat -c '%n %s %y' ~/workspace/6.Company\ X/Thumbs.db
+```
+
+목적:
+- summary 숫자만이 아니라 실제 파일이 존재하는지 한 번 더 닫는다.
+
+## 성공 판정 규칙
+
+### A. NAS 접속 성공
+- 51123에서 NAS SSH 접속이 된다.
+- NAS 라우팅이 `eth1` 기준으로 유지된다.
+
+### B. Go 테스트 성공
+- 샘플 다운로드 summary에 `downloaded > 0`, `failed = 0`
+- 재실행 summary에 `downloaded = 0`, `skipped > 0`, `failed = 0`
+
+### C. 운영 동기화 정상
+- latest fullscan summary에 `finished_at` 존재, `failed = 0`
+- latest hierarchical summary가 최근 시각까지 누적되고 `failed = 0`
+
+### D. 주의
+- `downloaded = 0`만으로 실패라고 판단하지 않는다.
+- 반드시 `failed`, `finished_at`, `updated_at`, 실제 파일 존재 여부를 함께 본다.
+
+## 점검 결과를 어디에 남길지
+
+- 반복 절차 자체는 이 런북을 SSOT로 유지한다.
+- 특정 날짜의 실제 점검 결과는 아래 중 하나에 남긴다.
+  - 장애/이상 징후가 있으면 `journey/troubleshooting/`
+  - 문제 없이 끝난 점검이면 `journey/worklog/`
+
+## 이 런북이 다루지 않는 것
+
+- NAS 로컬에 Go 동기화 본체를 상시 배포하는 절차
+- DSM 작업 스케줄러 또는 NAS cron에 실제 운영 스케줄을 심는 절차
+- 외부 NAS 계정/비밀번호 같은 민감값 기록
+
+## 한 줄 결론
+
+- 이 런북은 `51123 -> 내부 NAS -> Go 테스트/운영 sync 상태 확인`을 같은 기준으로 반복하기 위한 고정 운영 절차다.
--- a/02_Architecture/Infrastructure_Project_Structure.md
+++ b/02_Architecture/Infrastructure_Project_Structure.md
@ -76,3 +76,8 @@
 - 역할 정의는 이 문서 같은 구조 문서에 고정한다.
 - 실제 IP/포트/마운트 값은 SSOT 문서 또는 `workspace-config` 기준으로 관리한다.
 - 장애/변경/복구 과정은 `journey/`에서 사실 중심으로 기록한다.
+
+## 관련 운영 런북
+
+- [51123 -> 내부 NAS 동기화 점검 런북](./51123_to_internal_nas_sync_verification_runbook.md)
+  - 51123에서 내부 NAS에 SSH 접속해 Company X sync 상태와 Go 테스트 결과를 반복 점검하는 절차
--- a/README.md
+++ b/README.md
@ -14,6 +14,7 @@
 - [00_Philosophy/](./00_Philosophy/)
 - [01_Terminology/](./01_Terminology/)
 - [02_Architecture/](./02_Architecture/)
+- [02_Architecture/51123_to_internal_nas_sync_verification_runbook.md](./02_Architecture/51123_to_internal_nas_sync_verification_runbook.md)
 - [journey/README.md](./journey/README.md)

 ## 먼저 보면 좋은 문서
@ -21,6 +22,7 @@
 - [01_Terminology/100_인프라_용어집.md](./01_Terminology/100_인프라_용어집.md)
 - [00_Philosophy/00_IDENTITY/Infra_Project_Identity.md](./00_Philosophy/00_IDENTITY/Infra_Project_Identity.md)
 - [02_Architecture/Infrastructure_Project_Structure.md](./02_Architecture/Infrastructure_Project_Structure.md)
+- [02_Architecture/51123_to_internal_nas_sync_verification_runbook.md](./02_Architecture/51123_to_internal_nas_sync_verification_runbook.md)

 ## 빠른 읽기 순서

@ -31,5 +33,6 @@
 5. [00_Philosophy/01_PRINCIPLES/Runtime_Principles.md](./00_Philosophy/01_PRINCIPLES/Runtime_Principles.md)
 6. [00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md](./00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md)
 7. [02_Architecture/Infrastructure_Project_Structure.md](./02_Architecture/Infrastructure_Project_Structure.md)
-8. [journey/research/260307_value_기준_인프라철학문서_구조초안.md](./journey/research/260307_value_기준_인프라철학문서_구조초안.md)
-9. [journey/README.md](./journey/README.md)
+8. [02_Architecture/51123_to_internal_nas_sync_verification_runbook.md](./02_Architecture/51123_to_internal_nas_sync_verification_runbook.md)
+9. [journey/research/260307_value_기준_인프라철학문서_구조초안.md](./journey/research/260307_value_기준_인프라철학문서_구조초안.md)
+10. [journey/README.md](./journey/README.md)
--- a/journey/README.md
+++ b/journey/README.md
@ -86,3 +86,4 @@
 - [24서버 NAS 마운트 복원 및 ONNX 백업 실행](./worklog/260309_24서버_nas마운트복원_onnx백업실행.md)
 - [Company X 외부 NAS 동기화 스크립트 구현 및 대표 검증](./worklog/260311_companyx_external_nas_sync_스크립트구현_및_대표검증.md)
 - [Company X 30분주기 cron 적용 및 예측 검증](./worklog/260312_companyx_sync_30분주기_cron적용_및_예측검증.md)
+- [Company X sync NAS 이관 및 23 cron 중지](./worklog/260314_companyx_sync_nas_이관_및_23cron_중지.md)
--- a/journey/worklog/260314_companyx_sync_nas_이관_및_23cron_중지.md
+++ b/journey/worklog/260314_companyx_sync_nas_이관_및_23cron_중지.md
@ -0,0 +1,56 @@
+---
+tags: [infra, nas, companyx, sync, worklog, migration]
+---
+
+# 260314 Company X sync NAS 이관 및 23 cron 중지
+
+## 관련 문서
+- [51123 -> 내부 NAS 동기화 점검 런북](../../02_Architecture/51123_to_internal_nas_sync_verification_runbook.md)
+- [260313 내부 NAS -> 외부 NAS 경로 교정 및 Go 프로브 검증](../troubleshooting/260313_internal_nas_external_nas_route_fix_and_go_probe_verification.md)
+- [260313 내부 NAS 직접 Go 동기화 가능성 리서치](../research/260313_internal_nas_direct_go_sync_feasibility_research.md)
+- [260313 내부 NAS 직접 Go 동기화 아이디어](../ideas/260313_internal_nas_direct_go_sync_아이디어.md)
+- [260312 Company X 상태기록 강화 및 재개 실행 계획](../plans/260312_companyx_sync_상태기록강화_및_재개실행_계획.md)
+
+## 작업
+
+- `infra/scripts` 저장소를 최신 `main`으로 맞춘 뒤 `go/companyx-sync`를 NAS 실행 기준으로 사용했다.
+- NAS 전용 래퍼를 추가했다.
+  - `companyx_sync_nas_hierarchical.sh`
+  - `companyx_sync_nas_fullscan.sh`
+- NAS 로컬 경로 기준값이 실제 경로와 맞도록 `/mnt/nas/workspace/workspace-config/runtime.env`의 `WORKSPACE_ROOT`, `NAS_MOUNT_PATH`, `NAS_WORKSPACE_PATH`, `NAS_BACKUP_ROOT`, `NAS_GITEA_LFS_PATH`를 `/var/services/homes/admin/workspace` 기준으로 교정했다.
+- 정적 Go 바이너리 `companyx-sync`와 NAS 전용 래퍼를 NAS 작업 경로 `/var/services/homes/admin/workspace/infra/infra/scripts/`에 배포했다.
+- NAS `/etc/crontab`에 아래 두 작업을 등록했다.
+  - `*/30 * * * * admin /var/services/homes/admin/workspace/infra/infra/scripts/bin/companyx_sync_nas_hierarchical.sh`
+  - `0 1 * * * admin /var/services/homes/admin/workspace/infra/infra/scripts/bin/companyx_sync_nas_fullscan.sh`
+- 23 서버 `crontab`에서는 기존 Company X 두 항목을 제거했다.
+  - `/home/admin/infra/scripts/bin/companyx_external_nas_sync_hierarchical_cron.sh`
+  - `/home/admin/infra/scripts/bin/companyx_external_nas_sync_fullscan_cron.sh`
+
+## 검증
+
+- NAS cron 자체 동작 검증:
+  - `/etc/crontab`에 1분 주기 임시 테스트 엔트리를 넣고
+  - `2026-03-14 11:07:01 KST`에 `/tmp/codex_cron_test_20260314.txt` 생성까지 확인한 뒤
+  - 테스트 엔트리와 임시 파일을 제거했다.
+- NAS 계층형 Go 수동 실행 검증:
+  - `2026-03-14 10:45:31~10:45:35 KST`
+  - `downloaded=0`, `skipped=38`, `failed=0`
+  - summary: `companyx_sync_summary_20260314_104531.json`
+- NAS 스케줄 등록 확인:
+  - `/etc/crontab`에 `COMPANYX_NAS_SYNC_20260314_HIER`, `COMPANYX_NAS_SYNC_20260314_FULL` 두 줄 존재 확인
+- 23 서버 중지 확인:
+  - `crontab -l`에서 Company X 동기화 두 줄이 제거된 상태 확인
+
+## 관찰
+
+- NAS fullscan Go 수동 실행은 장시간 작업으로 정상 진행 중이었으나, 대화형 세션 종료 시 `hangup signal received`로 중단됐다.
+- 종료 시점 요약:
+  - `run_id=20260314_104548`
+  - `finished_at=2026-03-14T11:01:58+09:00`
+  - `skipped=47001`
+  - `failed=1`
+- 이 실패는 세션 종료 신호에 의한 중단이므로, 스케줄러가 비대화형으로 실행할 때의 실패와는 구분해야 한다.
+
+## 한 줄 결론
+
+- Company X 외부 NAS 동기화의 정기 실행 주체는 23 서버에서 내부 NAS로 넘어갔고, 23 서버의 기존 cron 두 줄은 중지됐다.