Add workflow operations docs

2026-03-15 23:45:12 +09:00 · 2026-03-15 23:45:12 +09:00 · 818497af08
commit 818497af08
parent 563a2308f1
3 changed files with 226 additions and 4 deletions
--- a/README.md
+++ b/README.md
@ -14,6 +14,7 @@
 - [00_Philosophy/](./00_Philosophy/)
 - [01_Terminology/](./01_Terminology/)
 - [02_Architecture/](./02_Architecture/)
+- [workflow/README.md](./workflow/README.md)
 - [02_Architecture/51123_to_internal_nas_sync_verification_runbook.md](./02_Architecture/51123_to_internal_nas_sync_verification_runbook.md)
 - [02_Architecture/51123_github_org_repo_bootstrap_runbook.md](./02_Architecture/51123_github_org_repo_bootstrap_runbook.md)
 - [journey/README.md](./journey/README.md)
@ -23,6 +24,8 @@
 - [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)
+- [workflow/README.md](./workflow/README.md)
+- [workflow/51123_nas_remote_operations_workflow.md](./workflow/51123_nas_remote_operations_workflow.md)
 - [02_Architecture/51123_to_internal_nas_sync_verification_runbook.md](./02_Architecture/51123_to_internal_nas_sync_verification_runbook.md)
 - [02_Architecture/51123_github_org_repo_bootstrap_runbook.md](./02_Architecture/51123_github_org_repo_bootstrap_runbook.md)

@ -35,7 +38,9 @@
 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. [02_Architecture/51123_to_internal_nas_sync_verification_runbook.md](./02_Architecture/51123_to_internal_nas_sync_verification_runbook.md)
-9. [02_Architecture/51123_github_org_repo_bootstrap_runbook.md](./02_Architecture/51123_github_org_repo_bootstrap_runbook.md)
-10. [journey/research/260307_value_기준_인프라철학문서_구조초안.md](./journey/research/260307_value_기준_인프라철학문서_구조초안.md)
-11. [journey/README.md](./journey/README.md)
+8. [workflow/README.md](./workflow/README.md)
+9. [workflow/51123_nas_remote_operations_workflow.md](./workflow/51123_nas_remote_operations_workflow.md)
+10. [02_Architecture/51123_to_internal_nas_sync_verification_runbook.md](./02_Architecture/51123_to_internal_nas_sync_verification_runbook.md)
+11. [02_Architecture/51123_github_org_repo_bootstrap_runbook.md](./02_Architecture/51123_github_org_repo_bootstrap_runbook.md)
+12. [journey/research/260307_value_기준_인프라철학문서_구조초안.md](./journey/research/260307_value_기준_인프라철학문서_구조초안.md)
+13. [journey/README.md](./journey/README.md)
--- a/workflow/51123_nas_remote_operations_workflow.md
+++ b/workflow/51123_nas_remote_operations_workflow.md
@ -0,0 +1,189 @@
+---
+tags: [infra, workflow, nas, 51123, remote-operations]
+---
+
+# 51123 NAS Remote Operations Workflow
+
+## 상위 원칙
+- [../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md](../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md)
+- [../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md](../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md)
+- [../00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md](../00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md)
+
+## 관련 문서
+- [../02_Architecture/51123_to_internal_nas_sync_verification_runbook.md](../02_Architecture/51123_to_internal_nas_sync_verification_runbook.md)
+- [../journey/troubleshooting/260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md](../journey/troubleshooting/260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md)
+- [../journey/troubleshooting/260313_internal_nas_external_nas_route_fix_and_go_probe_verification.md](../journey/troubleshooting/260313_internal_nas_external_nas_route_fix_and_go_probe_verification.md)
+- [../journey/research/260313_internal_nas_direct_go_sync_feasibility_research.md](../journey/research/260313_internal_nas_direct_go_sync_feasibility_research.md)
+
+## 목적
+
+- 51123 서버에서 내부 NAS `192.168.0.101`를 원격 점검·수정·검증할 때 같은 순서로 작업합니다.
+- 사람과 에이전트가 같은 문서를 읽고 같은 기준으로 NAS 원격 작업을 수행합니다.
+
+## 적용 범위
+
+- NAS 점검
+- NAS SSH 접속
+- NAS 라우팅 확인
+- NAS 동기화 로그 확인
+- NAS cron 수정
+- NAS 실행 스크립트 확인
+
+## 기본 원칙
+
+- 먼저 51123 기준값과 로그를 확인한 뒤 NAS에 들어갑니다.
+- NAS 원격 변경 전에는 현재 상태와 백업 경로를 먼저 확보합니다.
+- 점검과 수정은 분리해서 기록합니다.
+- `정상으로 보인다`가 아니라 로그, state, summary, 실제 스케줄 값을 같이 확인합니다.
+- `downloaded = 0`만으로 실패 판단을 하지 않습니다.
+- cron, lock, run log, summary를 같은 시각대로 교차 확인합니다.
+
+## 표준 흐름
+
+### 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`
+- `/mnt/nas` 마운트 정상
+- 최근 summary 파일 존재
+
+### 2. NAS 접속 가능 여부 확인
+
+```bash
+nc -vz -w 3 192.168.0.101 22
+ssh-keygen -F 192.168.0.101
+```
+
+판단 기준:
+- `22/tcp` 접속 성공
+- known_hosts 엔트리 존재 또는 신규 확인 가능
+
+### 3. NAS 기본 상태 확인
+
+```bash
+ssh -o StrictHostKeyChecking=no admin@192.168.0.101
+date
+hostname
+whoami
+ip route
+```
+
+판단 기준:
+- `hostname`은 `companyx`
+- `default via 192.168.0.1 dev eth1`
+- 외부 NAS 호스트 라우트가 있으면 `112.218.113.4 via 192.168.0.1 dev eth1`
+
+### 4. 작업 유형별 분기
+
+#### A. 점검만 할 때
+- [51123_to_internal_nas_sync_verification_runbook.md](../02_Architecture/51123_to_internal_nas_sync_verification_runbook.md) 절차를 그대로 따릅니다.
+
+#### B. NAS cron을 수정할 때
+
+1. 현재 값 확인
+
+```bash
+cat /etc/crontab
+```
+
+2. 백업 생성
+
+```bash
+sudo cp /etc/crontab /etc/crontab.bak_YYYYMMDD_HHMMSS
+```
+
+3. 필요한 한 줄만 수정
+
+4. 수정 직후 다시 확인
+
+```bash
+grep 'COMPANYX_NAS_SYNC_' /etc/crontab
+```
+
+5. 수정 이유와 기대 동작을 같이 기록
+
+#### C. NAS 동기화 실패를 볼 때
+
+아래 순서로 같이 봅니다.
+
+```bash
+cat ~/workspace/.sync-logs/companyx_sync_state.json
+ls -1t ~/workspace/.sync-logs/companyx_sync_summary_*.json | head -n 3
+tail -n 100 ~/workspace/.run-logs/companyx/companyx_sync_fullscan.log
+
+cat ~/workspace/.sync-logs-hierarchical/companyx_sync_state.json
+ls -1t ~/workspace/.sync-logs-hierarchical/companyx_sync_summary_*.json | head -n 3
+tail -n 100 ~/workspace/.run-logs/companyx/companyx_sync_hierarchical.log
+```
+
+판단 기준:
+- `summary.finished_at` 존재 여부
+- `state.failed` 값
+- 같은 시각대에 lock 충돌, skip, hangup 같은 메시지 존재 여부
+
+#### D. lock 충돌을 볼 때
+
+먼저 두 스크립트의 lock 경로를 확인합니다.
+
+```bash
+sed -n '1,220p' ~/workspace/infra/infra/scripts/bin/companyx_sync_nas_hierarchical.sh
+sed -n '1,220p' ~/workspace/infra/infra/scripts/bin/companyx_sync_nas_fullscan.sh
+```
+
+판단 기준:
+- 같은 lock 파일이면 스케줄 충돌 가능성을 먼저 의심합니다.
+- 같은 분에 배치된 작업이면 cron 시각 충돌을 먼저 봅니다.
+
+## 자주 쓰는 작업 패턴
+
+### 패턴 1. NAS가 오늘 새벽 1시에 무엇을 했는지 확인
+
+```bash
+grep 'COMPANYX_NAS_SYNC_' /etc/crontab
+ls -1t ~/workspace/.sync-logs/companyx_sync_summary_*.json | head -n 3
+ls -1t ~/workspace/.sync-logs-hierarchical/companyx_sync_summary_*.json | head -n 6
+tail -n 50 ~/workspace/.run-logs/companyx/companyx_sync_fullscan.log
+tail -n 50 ~/workspace/.run-logs/companyx/companyx_sync_hierarchical.log
+```
+
+### 패턴 2. cron 시간만 빠르게 조정
+
+```bash
+sudo cp /etc/crontab /etc/crontab.bak_YYYYMMDD_HHMMSS
+sudo vi /etc/crontab
+grep 'COMPANYX_NAS_SYNC_' /etc/crontab
+```
+
+검증:
+- 변경된 시각이 실제 줄에 반영됐는지 확인
+- 다음 실행 시각 이후 summary 생성 여부 확인
+
+## 변경 후 검증
+
+- 수정한 파일 내용이 기대값과 일치하는지 확인합니다.
+- 다음 실행 시각 이후 summary와 run log가 실제로 생기는지 확인합니다.
+- lock 충돌 수정이면 `skip: previous sync still running` 메시지가 사라졌는지 확인합니다.
+
+## 금지선
+
+- 점검 없이 바로 cron부터 바꾸지 않습니다.
+- 백업 없이 `/etc/crontab`를 직접 덮어쓰지 않습니다.
+- state 하나만 보고 성공/실패를 단정하지 않습니다.
+- 51123 기준과 NAS 기준 경로를 섞어 쓰지 않습니다.
+
+## 기록 원칙
+
+- 문제 없이 끝난 반복 점검은 `journey/worklog/`
+- 이상 징후, 스케줄 충돌, 실패 원인 분석은 `journey/troubleshooting/`
+
+## 한 줄 결론
+
+- 51123에서 NAS를 원격 조정할 때는 `51123 기준 확인 -> NAS 접속 -> 작업 유형별 절차 -> 변경 후 검증` 순서로 같은 절차를 반복합니다.
--- a/workflow/README.md
+++ b/workflow/README.md
@ -0,0 +1,28 @@
+---
+tags: [infra, workflow, docs, operations]
+---
+
+# workflow
+
+반복 실행하는 운영 절차를 관리합니다.
+
+이 폴더는 사람과 에이전트가 같은 실행 기준을 읽도록 유지하는 실행 SSOT 레이어입니다.
+`00_Philosophy`가 원칙, `02_Architecture`가 구조, `workflow`가 반복 실행 절차, `journey`가 실제 사건 기록을 맡습니다.
+
+## 상위 원칙
+- [../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md](../00_Philosophy/00_IDENTITY/Infra_Project_Identity.md)
+- [../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md](../00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md)
+- [../00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md](../00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md)
+
+## 문서 범위
+- 같은 작업을 여러 번 반복할 때 읽는 표준 절차
+- 변경 전 확인, 실행 순서, 검증 기준, 롤백 기준
+- 사람과 에이전트가 공통으로 따라야 하는 운영 워크플로우
+
+## 현재 문서
+- [51123_nas_remote_operations_workflow.md](./51123_nas_remote_operations_workflow.md)
+
+## 관련 문서
+- [../README.md](../README.md)
+- [../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)