From 818497af08c1df9d9ee7178c42a77a73ea304369 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Sun, 15 Mar 2026 23:45:12 +0900 Subject: [PATCH] Add workflow operations docs --- README.md | 13 +- .../51123_nas_remote_operations_workflow.md | 189 ++++++++++++++++++ workflow/README.md | 28 +++ 3 files changed, 226 insertions(+), 4 deletions(-) create mode 100644 workflow/51123_nas_remote_operations_workflow.md create mode 100644 workflow/README.md diff --git a/README.md b/README.md index 8d00160..d8d8ce2 100644 --- 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) diff --git a/workflow/51123_nas_remote_operations_workflow.md b/workflow/51123_nas_remote_operations_workflow.md new file mode 100644 index 0000000..ff44f8c --- /dev/null +++ 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 접속 -> 작업 유형별 절차 -> 변경 후 검증` 순서로 같은 절차를 반복합니다. diff --git a/workflow/README.md b/workflow/README.md new file mode 100644 index 0000000..36ace9b --- /dev/null +++ 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)