commit 1d53458143e6083e0bf9116154503ca18c3c822f Author: happybell80 Date: Sat Mar 7 15:37:11 2026 +0900 Initialize infra DOCS structure and philosophy diff --git a/00_Philosophy/00_IDENTITY/Infra_Project_Identity.md b/00_Philosophy/00_IDENTITY/Infra_Project_Identity.md new file mode 100644 index 0000000..6d8a90a --- /dev/null +++ b/00_Philosophy/00_IDENTITY/Infra_Project_Identity.md @@ -0,0 +1,47 @@ +# Infra Project Identity + +## 한 줄 정의 + +인프라 프로젝트는 `0_VALUE`의 가치를 실제 세계에서 끊기지 않게 구현하기 위해, **23 서버 / 24 서버 / 내부 NAS**를 하나의 운영 시스템으로 설계하고 유지하는 프로젝트다. + +## 이 프로젝트가 해결하는 문제 + +- 서비스가 돌아간다는 사실만으로는 가치가 보존되지 않는다. +- 기록, 인증, 배포, 백업, 복구, 로그, 네트워크가 흩어져 있으면 가치 판단 체계도 함께 무너진다. +- 사람 기억과 즉흥 조치에 의존하면, 실패 원인과 복구 기준이 사라진다. + +인프라 프로젝트는 이 문제를 해결하기 위해 다음을 담당한다. + +- 어떤 서버가 어떤 책임을 지는지 고정한다. +- 트래픽과 데이터가 어디를 통과하는지 추적 가능하게 만든다. +- 장애가 나도 기록과 복구 기준이 남도록 만든다. +- 문서와 설정을 분리하지 않고 운영 사실과 연결한다. + +## 핵심 운영 대상 + +### 23 서버 +- 역할: 게이트웨이, 프록시, Git/CI, DB, 운영 보조, 24 장애 시 임시 수용 +- 존재 이유: 전체 시스템의 진입점과 운영 제어면(control plane)을 맡기 위해 + +### 24 서버 +- 역할: 핵심 앱/에이전트/스킬 런타임 +- 존재 이유: 사용자 가치가 실제로 생성되는 실행면(runtime plane)을 안정적으로 분리하기 위해 + +### 내부 NAS +- 역할: 백업, 로그 아카이브, 산출물 보존, 복구 기준점 +- 존재 이유: 서버 장애나 배포 실패 후에도 상태를 되돌릴 수 있는 기억 저장소를 확보하기 위해 + +## 주변 환경의 위치 + +- 개발 노트북: 변경을 만들고 검증하는 작성 환경 +- 테스트 스마트폰: 실제 사용자 환경에서 화면/행동을 검증하는 장치 +- 외부 NAS/외부 시스템: 필요 시 연결되는 외부 자원 + +이들은 중요하지만, 인프라 프로젝트의 중심 SSOT는 아니다. + +## 인프라의 성공 기준 + +- 서비스가 단순히 뜨는가가 아니라, 왜 뜨고 왜 실패했는지 설명 가능한가 +- 변경 후 검증과 롤백 기준이 남는가 +- 사람이 바뀌어도 같은 절차로 운영 가능한가 +- 장애 시 가치 있는 기록과 데이터가 보존되는가 diff --git a/00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md b/00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md new file mode 100644 index 0000000..20db528 --- /dev/null +++ b/00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md @@ -0,0 +1,44 @@ +# Core Infrastructure Principles + +## 1. Value First +- 인프라는 비용 항목이 아니라 가치 보존 장치다. +- 23/24/NAS의 구조는 서비스 기능보다 먼저 `지속성`, `추적성`, `복구 가능성`을 보장해야 한다. + +## 2. Trust by Structure +- 신뢰는 설명이 아니라 구조에서 나온다. +- 권한, 경로, 로그, 백업, 검증, 복구 절차가 분리되어 있어야 운영 사실을 믿을 수 있다. + +## 3. Role Separation +- 23은 진입과 제어, 24는 실행, NAS는 보존과 복구를 담당한다. +- 한 자산에 모든 역할을 몰아넣지 않는다. +- 역할이 겹치더라도 기준 역할은 명확하게 남긴다. + +## 4. Single Source of Truth +- IP, 포트, 업스트림, 엔드포인트, 마운트 기준은 한 번만 정의한다. +- 비민감 운영값은 `runtime.env`, 민감값은 `secrets.env`로 분리한다. +- 여러 문서와 설정을 동시에 고쳐야 하면 구조가 잘못된 것으로 본다. + +## 5. Gateway First +- 외부 요청은 가능한 한 단일 진입점에서 통제한다. +- 인증, 라우팅, 관측, 장애 분리는 진입 계층에서 먼저 판별 가능해야 한다. +- 직접 포트 노출은 예외가 아니라 리스크로 본다. + +## 6. Continuity Over Convenience +- 빠른 임시 해결보다 재현 가능한 복구 구조를 우선한다. +- 배포는 성공보다 복구 가능성을 함께 증명해야 한다. +- 백업은 존재 여부가 아니라 실제 복구 가능성으로 평가한다. + +## 7. Verification Before Declaration +- 설정 변경만으로 완료를 선언하지 않는다. +- 로그, 헬스체크, 실제 도메인 응답, 저장 경로, 권한까지 대조해야 한다. +- `23 선검증 -> 24 반영`은 운영 리듬의 기본이다. + +## 8. Documented Operations +- 운영 문서는 회고가 아니라 실행 기준이다. +- 철학 문서는 왜를 정의하고, 구조 문서는 무엇을 고정하며, journey 문서는 실제 사실을 남긴다. +- 반복 검증된 운영 규칙만 철학/구조 계층으로 승격한다. + +## 9. Failure Must Stay Visible +- 실패는 숨기지 않고 분리 기록한다. +- 장애를 덮는 광범위 폴백, 상태코드 왜곡, 원인 은폐를 금지한다. +- 인프라는 실패를 없애는 시스템이 아니라, 실패를 빨리 분리하고 복구 가능하게 만드는 시스템이다. diff --git a/00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md b/00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md new file mode 100644 index 0000000..536121b --- /dev/null +++ b/00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md @@ -0,0 +1,22 @@ +# Operational Guardrails + +## 운영 경계 + +1. 23/24/NAS의 역할 문구는 문서와 설정에서 동일해야 한다. +2. 외부 공개 경로는 nginx/gateway 기준으로 먼저 설명 가능해야 한다. +3. 정적 자산, 로그, 백업은 실행 경로와 복구 경로를 분리한다. +4. 서버 이전, IP 변경, NAS 변경은 SSOT 변경으로 먼저 다룬다. + +## 금지사항 + +1. 한 서버에 진입, 실행, 저장, 복구 책임을 무비판적으로 중첩하는 것 +2. 설정 파일만 바꾸고 실응답/실마운트/실로그 검증 없이 완료로 판단하는 것 +3. 백업 존재를 복구 가능성으로 오인하는 것 +4. 문서 없이 임시 조치를 상시 운영 구조로 굳히는 것 +5. 로컬 성공을 운영 성공으로 오인하는 것 + +## 승격 규칙 + +- 한 번의 장애 대응 기록은 `journey`에 남긴다. +- 반복 재현된 운영 기준만 `00_Philosophy`나 `02_Architecture`로 승격한다. +- 예외는 예외로만 기록하고, 상시 구조로 승격할 때는 제거 조건과 이유를 함께 남긴다. diff --git a/02_Architecture/Infrastructure_Project_Structure.md b/02_Architecture/Infrastructure_Project_Structure.md new file mode 100644 index 0000000..e4a830e --- /dev/null +++ b/02_Architecture/Infrastructure_Project_Structure.md @@ -0,0 +1,78 @@ +# Infrastructure Project Structure + +## 목적 + +이 문서는 인프라 프로젝트의 핵심 구성 요소를 `무엇이 있는가`와 `왜 필요한가` 기준으로 정리하는 기준 문서다. + +## 1. 핵심 운영 자산 + +### 23 서버 +- 무엇: + - nginx + - Gitea / CI + - PostgreSQL + - auth-server + - robeing-gateway + - 운영 보조 프론트/서비스 +- 왜: + - 외부 요청의 진입점과 운영 제어를 한곳에서 통합하기 위해 + - 인증, 라우팅, 배포 검증, 운영 판단의 기준면을 만들기 위해 + - 24 장애 시 임시 수용 지점을 확보하기 위해 + +### 24 서버 +- 무엇: + - rb8001 등 핵심 앱 런타임 + - 스킬 서비스들 + - 실행 중심 컨테이너 +- 왜: + - 사용자 가치가 생성되는 실행 부하를 23과 분리하기 위해 + - 앱 장애와 게이트웨이/DB 장애를 분리해 원인 판별 속도를 높이기 위해 + - 프로덕션 기준 서버를 명확히 하기 위해 + +### 내부 NAS +- 무엇: + - 백업 저장소 + - 로그 아카이브 + - 릴리스/산출물 보관 + - 장기 보존 경로 +- 왜: + - 서버 자체와 분리된 기억 저장소가 있어야 복구 기준이 생기기 때문에 + - 장애 후에도 로그와 데이터가 남아야 원인을 설명할 수 있기 때문에 + +## 2. 보조 운영 자산 + +### `infra-config` +- 무엇: `runtime.env`, `secrets.env` +- 왜: 환경값의 기준점을 코드/개별 `.env` 밖으로 분리해 SSOT를 유지하기 위해 + +### `nginx-infra` +- 무엇: nginx 배포 설정 저장소 +- 왜: 진입 계층 설정을 애플리케이션 저장소와 분리해 추적성과 배포 일관성을 확보하기 위해 + +### `/mnt/hdd/logs` +- 무엇: 서비스 로그 저장 경로 +- 왜: 컨테이너/앱 수명주기와 분리된 관측 기록을 유지하기 위해 + +### Gitea Actions / Runner +- 무엇: 23에서 운영되는 배포 자동화 경로 +- 왜: 수동 서버 조작보다 재현 가능한 배포 절차를 만들기 위해 + +## 3. 구조적으로 중요한 관계 + +### 진입 경로 +- 사용자/도메인 요청 -> 23의 nginx/gateway -> 필요한 서비스로 전달 +- 의미: 외부 진입을 통제 가능한 한곳에서 먼저 본다. + +### 실행 경로 +- 실제 앱 처리와 스킬 실행은 24가 주도 +- 의미: 사용자 가치 생성 부하를 제어/저장 계층과 분리한다. + +### 보존 경로 +- 백업, 로그, 장기 산출물은 NAS로 보낸다. +- 의미: 서버 장애가 곧 기록 손실이 되지 않게 한다. + +## 4. 문서화 원칙 + +- 역할 정의는 이 문서 같은 구조 문서에 고정한다. +- 실제 IP/포트/마운트 값은 SSOT 문서 또는 `infra-config` 기준으로 관리한다. +- 장애/변경/복구 과정은 `journey/`에서 사실 중심으로 기록한다. diff --git a/260307_external_nas_to_internal_nas_sync_probe.md b/260307_external_nas_to_internal_nas_sync_probe.md new file mode 100644 index 0000000..dfc2528 --- /dev/null +++ b/260307_external_nas_to_internal_nas_sync_probe.md @@ -0,0 +1,52 @@ +# 260307 External NAS -> Internal NAS Sync Probe + +## 목적 +- 외부 NAS의 파일을 내부 NAS로 가져올 수 있는지 확인한다. +- 내부 NAS에 동일한 폴더 구조를 먼저 구성할 수 있는지 확인한다. + +## 기준 정보 +- 외부 NAS: `sigongipc.synology.me:5000` / DSM API `:5001` +- 내부 NAS: `192.168.0.101` +- 내부 마운트 경로: `/mnt/nas` + +## 확인 결과 +1. 외부 NAS 접근 +- `sigongipc.synology.me:5000` DSM 응답 확인 +- DSM Web API 로그인 성공 +- SMB(139/445)는 외부에서 타임아웃으로 직접 사용 불가 +- 따라서 현재 접근 경로는 `DSM File Station API`가 맞음 + +2. 파일 1건 전송 검증 +- 외부 NAS 경로: `/6.Company X/Thumbs.db` +- 내부 NAS 저장 경로: `/mnt/nas/backup/current/external-nas-test/Thumbs.db` +- SHA256 일치 확인 +- 결론: `외부 NAS -> API 다운로드 -> 내부 NAS 저장` 경로는 동작함 + +3. 폴더 구조 미러링 +- 내부 NAS에 `/mnt/nas/backup/current/external-nas-test/6.Company X` 생성 +- 외부 NAS 상위 폴더 구조를 동일하게 디렉터리만 생성 +- 생성 완료 폴더: + - `0. 엑셀러레이터 등록` + - `1. 행정` + - `2. 신규운영사 및 펀드 운용사, 용역 프로그램 제안 등` + - `3. 배치프로그램(X-COURSE, X-HISSTORY 등)` + - `4. TIPS, WINGS, LIPS 프로그램` + - `5. 멘토풀` + - `6. 투자` + - `7. 사진` + - `8. 교육` + - `9. 디자인` + - `10. MOU&인증` + - `11. Company X - logo & 디자인` + - `12. 컴퍼니엑스 소개자료` + - `SynologyDrive` + +## 현재 판단 +- 이중 NAS 구조는 가능하다. +- 지금 확인된 방식은 `외부 DSM API -> 내부 NAS 파일 저장`이다. +- 아직 자동 동기화는 없고, 수동/스크립트 기반 프로브만 완료된 상태다. + +## 다음 단계 후보 +1. 특정 폴더 단위 재귀 다운로드 스크립트 작성 +2. 외부 NAS -> 내부 NAS 단방향 동기화 정책 확정 +3. 내부 NAS의 에이전트 전용 경로(`/mnt/agent` 등) 분리 diff --git a/README.md b/README.md new file mode 100644 index 0000000..d961d44 --- /dev/null +++ b/README.md @@ -0,0 +1,46 @@ +# Infra DOCS + +이 디렉터리는 `0_VALUE`의 가치를 실제 운영 가능한 형태로 구현하는 **전체 인프라 프로젝트**의 공식 문서 허브입니다. + +여기서 인프라는 특정 서버 저장소가 아니라, 현재 우리가 직접 관리하는 핵심 물리 인프라를 뜻합니다. + +- `23 서버`: 게이트웨이, 프록시, Git/CI, DB, 운영 보조 +- `24 서버`: 앱 런타임, 핵심 서비스 실행 +- `내부 NAS`: 백업, 로그 아카이브, 산출물/복구 기준 저장 + +개발 노트북, 테스트 스마트폰, 외부 NAS 같은 자산은 필요할 때 연결되는 주변 실행 환경으로 다루며, 본 문서 체계의 중심 SSOT는 위 3개입니다. + +## 문서 구조 + +1. `00_Philosophy/` +- 인프라 프로젝트가 왜 존재하는지, 무엇을 지켜야 하는지, 무엇을 금지하는지 정의합니다. +- 반복 검증 후에도 바뀌기 어려운 기준만 둡니다. + +2. `02_Architecture/` +- 23/24/NAS를 중심으로 한 실제 구성 요소, 역할 분리, 트래픽/데이터/운영 구조를 정리합니다. +- 철학을 운영 가능한 구조로 번역한 계층입니다. + +3. `journey/` +- 리서치, 계획, 트러블슈팅, 워크로그를 기록합니다. +- 실행 중 사실, 조치, 검증 결과는 여기만 기록합니다. + +## 인프라 프로젝트에 맞춘 구조 선택 이유 + +- 일반 서비스 프로젝트처럼 `제품 기획`보다 `지속성 있는 운영 기반`이 중심입니다. +- 따라서 `철학 -> 구조 -> 실행 기록`의 3층이 가장 적합합니다. +- 전략/로드맵은 필요 시 `journey/plans`에서 운영 계획으로 다루고, 고정 철학은 `00_Philosophy`로 승격합니다. + +## 빠른 읽기 순서 + +1. `00_Philosophy/00_IDENTITY/Infra_Project_Identity.md` +2. `00_Philosophy/01_PRINCIPLES/Core_Infrastructure_Principles.md` +3. `00_Philosophy/02_GUARDRAILS/Operational_Guardrails.md` +4. `02_Architecture/Infrastructure_Project_Structure.md` +5. `journey/research/260307_value_기준_인프라철학문서_구조초안.md` +6. `journey/README.md` + +## 문서 운영 규칙 + +- `00_Philosophy/`는 고정 기준만 둡니다. +- 실제 장애, 변경, 점검, 복구 기록은 `journey/`에만 둡니다. +- `0_VALUE` 공통 원칙과 충돌하면 `0_VALUE`를 우선합니다. diff --git a/journey/README.md b/journey/README.md new file mode 100644 index 0000000..1ba515c --- /dev/null +++ b/journey/README.md @@ -0,0 +1,22 @@ +# Infra Journey + +이 폴더는 인프라 이슈와 실행 흐름을 기록하는 공간입니다. + +## 구조 +- [ideas](./ideas/) : 있으면 좋은 구조나 운영 아이디어 +- [scenarios](./scenarios/) : 운영자/사용자가 기대하는 상태와 흐름 +- [troubleshooting](./troubleshooting/) : 현재 문제, 이슈, 장애, 구조 어긋남 +- [research](./research/) : 원인 분석과 사실 수집 +- [plans](./plans/) : 실행 결정과 전환 계획 +- [worklog](./worklog/) : 문제 없이 끝난 실행의 가벼운 기록 + +## 기준 +- 출발점은 하나가 아니라 다릅니다. +- `좋겠다`는 `ideas`에서 시작합니다. +- `기대한다`는 `scenarios`에서 시작합니다. +- `문제다`는 `troubleshooting`에서 시작합니다. +- 그다음 필요에 따라 `research -> plans -> worklog`로 이어집니다. +- 실행 중 문제가 생기면 `worklog`가 아니라 `troubleshooting`으로 기록합니다. + +## 현재 문서 +- [23서버 워크스페이스 인프라 구조정리 이슈](./troubleshooting/260307_23서버_워크스페이스_인프라_구조정리_이슈.md) diff --git a/journey/research/260307_value_기준_인프라철학문서_구조초안.md b/journey/research/260307_value_기준_인프라철학문서_구조초안.md new file mode 100644 index 0000000..c6e8941 --- /dev/null +++ b/journey/research/260307_value_기준_인프라철학문서_구조초안.md @@ -0,0 +1,84 @@ +# 260307 value 기준 인프라철학문서 구조초안 + +## 목적 +- `infra 프로젝트`의 철학 문서를 쓰기 전에, 어떤 상위 원칙과 타 프로젝트 문서 패턴을 가져와야 하는지 정리한다. +- 인프라 프로젝트에 맞는 `DOCS` 상위 구조를 초안 수준으로 고정한다. + +## 이번에 참고한 기준 문서 + +### 0_VALUE +- `/home/admin/0_VALUE/00_Principles/global-principles.md` +- `/home/admin/0_VALUE/00_Principles/vision.md` +- `/home/admin/0_VALUE/02_Governance/system-and-infrastructure-overview.md` +- `/home/admin/0_VALUE/02_Governance/infrastructure-ssot-principle.md` + +### robeing +- `/home/admin/robeing/DOCS/book/300_architecture/310_전체_시스템_구조_컨테이너와_마이크로서비스.md` +- `/home/admin/robeing/DOCS/book/300_architecture/314_infrastructure-ssot-principle.md` +- `/home/admin/robeing/DOCS/journey/plans/260303_23테스트보조_24프로덕션_운영전환_계획.md` +- `/home/admin/robeing/DOCS/journey/troubleshooting/260307_NAS_192_168_0_101_SSOT_전환_및_CIFS_실마운트_복구.md` +- `/home/admin/robeing/DOCS/journey/troubleshooting/260226_NAS_192_168_219_51_접속불가_임시백업복구.md` +- `/home/admin/robeing/DOCS/journey/troubleshooting/260303_51123_gateway_rb8001_연결점검_23서버_전달사항.md` + +### projectStarsAndI +- `/home/admin/projectStarsAndI/DOCS/journey/research/260221_23_24_NAS_게이트웨이_운영구성_정리.md` + +### 구조 참고용 프로젝트 +- `/home/admin/TheGooseCouncil/DOCS/README.md` +- `/home/admin/goosefarminvesting/DOCS/README.md` +- `/home/admin/robeing/DOCS/README.md` + +## 공통으로 추출된 인프라 철학 키워드 + +1. 역할 분리 +- 23은 진입/제어, 24는 실행, NAS는 보존/복구 + +2. 지속성 +- 가치 있는 상태는 서버 메모리나 사람 기억에만 남아 있으면 안 된다. + +3. SSOT +- IP, 포트, 업스트림, 마운트, 비밀값은 한 번만 정의해야 한다. + +4. 검증 우선 +- 설정 변경이 아니라 실응답, 실마운트, 실로그로 판단한다. + +5. 게이트웨이 중심 +- 외부 요청은 단일 진입점에서 먼저 인증/라우팅/관측 가능해야 한다. + +6. 실패의 가시성 +- 장애를 덮지 않고, 원인 분리와 복구 가능성을 남겨야 한다. + +## 인프라 프로젝트에 맞는 문서 구조 판단 + +다른 제품 프로젝트의 `전략/제품` 중심 구조를 그대로 가져오는 것은 맞지 않았다. + +인프라는 제품 개념보다 운영 지속성이 본질이므로, 아래 구조가 가장 적합하다고 판단했다. + +1. `00_Philosophy` +- 왜 이 인프라를 운영하는가 +- 무엇을 지켜야 하는가 +- 무엇을 금지하는가 + +2. `02_Architecture` +- 23/24/NAS와 보조 자산이 어떻게 나뉘는가 +- 무엇이 핵심 자산이고 무엇이 보조 자산인가 + +3. `journey` +- 실제 변경, 장애, 점검, 복구 기록 + +## 이번 초안에서 보류한 항목 + +1. 개발 노트북/테스트 스마트폰/외부 NAS의 상세 운영 원칙 +- 이유: 현재 철학 문서의 중심축은 23/24/내부 NAS이기 때문 + +2. 세부 인벤토리 표 +- 이유: 철학 문서보다 구조 문서에서 관리하는 편이 맞기 때문 + +3. 장기 로드맵 폴더 +- 이유: 현재 단계에서는 `journey/plans`로 충분하고, 고정 계층으로 분리할 정도로 안정화되지 않았기 때문 + +## 이번 작업의 결론 + +- `infra 프로젝트`의 본문은 `23/24/NAS` 중심으로 쓴다. +- 주변 자산은 보조 실행 환경으로 분리한다. +- 문서 구조는 `철학 -> 구조 -> journey` 삼층으로 유지한다. diff --git a/journey/troubleshooting/260307_23서버_워크스페이스_인프라_구조정리_이슈.md b/journey/troubleshooting/260307_23서버_워크스페이스_인프라_구조정리_이슈.md new file mode 100644 index 0000000..efb3ad0 --- /dev/null +++ b/journey/troubleshooting/260307_23서버_워크스페이스_인프라_구조정리_이슈.md @@ -0,0 +1,80 @@ +--- +tags: [infra, workspace, ssot, structure, issue] +--- + +# 23서버 워크스페이스-인프라 구조정리 이슈 + +## 상위 원칙 +- `/home/admin/0_VALUE/02_Governance/writing-principles.md` +- `/home/admin/0_VALUE/02_Governance/infrastructure-ssot-principle.md` + +## 관련 문서 +- 이전 탐침: `/home/admin/infra/DOCS/260307_external_nas_to_internal_nas_sync_probe.md` +- 운영 원칙: `/home/admin/robeing/DOCS/book/300_architecture/314_infrastructure-ssot-principle.md` + +## 문제 정의 +- 23 서버의 실제 워크스페이스 루트는 `/home/admin`이지만, 구조 해석은 아직 프로젝트 단위보다 절대경로 단위에 묶여 있다. +- 인프라 관련 경로가 `infra`, `infra-config`, `nginx-infra`로 분산되어 있어, 인프라 프로젝트 경계가 명확하지 않다. +- 여러 문서와 스크립트가 `/home/admin/infra-config`, `/home/admin/robeing/DOCS`, 과거 `/home/admin/DOCS`를 직접 참조하고 있어 구조 변경 시 수정 범위가 커진다. +- `TheGooseCouncil`와 `thegoosecouncil`, `external_nas_test`, `tmp_lfs_branch_test`처럼 경계가 불명확하거나 임시 성격이 남은 디렉터리가 루트 신호를 흐린다. + +## 왜 문제인가 +- 23 서버만의 임시 구조가 굳어지면 24 서버 복구나 신규 서버 이식 시 경로 재작성 비용이 급격히 커진다. +- 인프라 작업이 로빙 문서, 서버 공용 규칙, 런타임 설정에 흩어져 있으면 책임 경계가 약해지고 추적성이 떨어진다. +- SSOT가 값(IP, secret)에는 일부 적용됐지만, 경로와 프로젝트 경계에는 아직 적용되지 않아 구조 변경 내성이 낮다. + +## 해결 목표 +- `/home/admin`을 23 서버의 `WORKSPACE_ROOT`로 명시한다. +- `infra`를 인프라 프로젝트 경계로 명확히 정의한다. +- 인프라 설정은 현재 `infra-config`를 유지하되, 의미상 `workspace-config` 성격임을 문서로 먼저 고정한다. +- 이후 구조 변경이 필요해도 루트 기준 해석으로 이동하도록 준비한다. + +## 권장 구조 +```text +WORKSPACE_ROOT=/home/admin +├── 0_VALUE +├── infra +│ └── DOCS +├── infra-config +├── nginx-infra +├── robeing +├── TheGooseCouncil +├── vMIR +├── shopify0207 +└── keyfrees +``` + +## 단계별 전환 방안 +### 1. 해석 기준 먼저 고정 +- `WORKSPACE_ROOT=/home/admin`를 공용 런타임 SSOT에 추가한다. +- 문서와 운영 규칙에서 23 서버의 워크스페이스 기준점을 `/home/admin`으로 통일한다. + +### 2. 참조 경로 정리 +- `/home/admin/DOCS` 같은 과거 경로를 전수 점검해 현재 프로젝트 경계로 교체한다. +- `infra-config`와 `robeing/DOCS`를 직접 박아 넣은 절대경로는 우선순위 높은 것부터 줄인다. + +### 3. 인프라 프로젝트 경계 고정 +- 인프라 이슈, 시나리오, 탐침 문서는 `infra/DOCS/journey/*`로 모은다. +- 로빙 문서에는 인프라 자체를 복제 기록하지 않고 필요한 참조 링크만 남긴다. + +### 4. 마지막에 이름/물리구조 재편 검토 +- `infra-config`는 바로 옮기지 않는다. +- 참조가 충분히 줄어든 뒤 `workspace-config` 리네임 또는 `infra/config` 재배치 여부를 검토한다. + +## 하지 말아야 할 방식 +- `infra`, `infra-config`, `nginx-infra`를 바로 한 폴더로 몰아넣는 방식 +- 절대경로 하드코딩을 유지한 채 물리 이동부터 하는 방식 +- 로빙 문서와 인프라 문서에 같은 운영 사실을 중복 기록하는 방식 + +## 현재 판단 +- 지금 단계에서는 `구조 이동`보다 `구조 해석의 SSOT화`가 우선이다. +- 즉 먼저 워크스페이스 개념을 도입하고, 그 다음 경로 참조를 줄이고, 마지막에 물리 리네임을 하는 순서가 맞다. + +## 다음 작업 +- `runtime.env`에 `WORKSPACE_ROOT=/home/admin` 추가 +- `/home/admin/DOCS` 잔존 참조 전수 정리 +- `infra` 프로젝트용 `AGENTS.md` 초안 작성 검토 + +## 문서 관계 +- 이 문서는 23 서버 워크스페이스/인프라 경계 문제를 다루는 트러블슈팅 문서다. +- 외부 NAS와 내부 NAS 동기화 탐침은 별도 실행 기록으로 `/home/admin/infra/DOCS/260307_external_nas_to_internal_nas_sync_probe.md`를 따른다. diff --git a/journey/worklog/260307_23서버_기본점검_및_ro-being_홈_500_조치.md b/journey/worklog/260307_23서버_기본점검_및_ro-being_홈_500_조치.md new file mode 100644 index 0000000..f516363 --- /dev/null +++ b/journey/worklog/260307_23서버_기본점검_및_ro-being_홈_500_조치.md @@ -0,0 +1,75 @@ +# 260307 23서버 기본점검 및 ro-being 홈 500 조치 + +## 목적 +- 23 서버(51123)의 기본 운영 상태를 점검한다. +- 로그인 MOTD 기준으로 보안 업데이트, 핵심 서비스, 도메인 응답 상태를 확인한다. +- `ro-being.com` 홈 `500`의 로그 기준 원인을 확인하고 복구한다. + +## 사실 +### 서버 기본 상태 +- 점검 시각: `2026-03-07 15:22~15:24 KST` +- OS: `Ubuntu 22.04.5 LTS` +- 커널: `6.8.0-101-generic` +- 업타임: 약 `20시간 17분` + +### 패키지/보안 상태 +- `apt list --upgradable` 기준 일반 업그레이드 가능 패키지는 `2건` + - `network-manager-openvpn` + - `network-manager-openvpn-gnome` +- `pro status --format json` 기준 이 서버는 Ubuntu Pro에 attach되지 않았다. +- MOTD의 `24 additional security updates can be applied with ESM Apps`는 Pro 미연결 상태 안내다. + +### 리소스 상태 +- 루트 디스크 `/dev/sda2`: `228G` 중 `85G` 사용, `40%` +- HDD `/mnt/hdd`: `916G` 중 `169G` 사용, `20%` +- NAS `/mnt/nas`: `5.3T` 중 `6.2G` 사용, 마운트 정상 +- 메모리: `29Gi` 중 `6.7Gi` 사용, 가용 `21Gi` +- 스왑: `2.0Gi` 중 사용 `0` + +### 핵심 서비스 상태 +- `systemctl is-active` 기준 `nginx`, `docker`, `postgresql`, `gitea` 모두 `active` +- `docker ps` 기준 주요 컨테이너 `healthy` + - `robeing-gateway` + - `robeing_monitor` + - `auth-server` + - `rb8001` + - `goosefarm-app` + +### 도메인 응답 상태 +- `https://goosefarminvesting.com` → `HTTP/2 200` +- `https://git.ro-being.com` → `HTTP/2 200` +- `https://ro-being.com` → 점검 시작 시 `HTTP/2 500` +- `https://www.ro-being.com` → 인증서 SAN 불일치 + - 현재 인증서 SAN: `ro-being.com`, `git.ro-being.com` + +### ro-being.com 홈 500 원인 +- 점검 시작 시 `https://ro-being.com`은 `HTTP/2 500`을 반환했다. +- 같은 시각대 `robeing-gateway` 로그에서는 `/api/stats/rb8001` 요청이 `200 OK`로 처리되었다. +- 같은 시각대 nginx `error.log`에는 아래 오류가 기록되었다. + - `stat() "/home/admin/robeing/frontend-customer/dist/index.html" failed (13: Permission denied)` + - `rewrite or internal redirection cycle while internally redirecting to "/index.html"` +- 즉, 홈 `500`은 gateway 장애가 아니라 nginx 정적 서빙 경로 설계 문제였다. +- 세부적으로는 다음 두 문제가 겹쳐 있었다. + - nginx가 프로젝트 작업 디렉터리(`/home/admin/robeing/...`) 아래 정적 파일을 직접 읽도록 구성되어 있었다. + - `location /`의 SPA fallback이 `try_files $uri $uri/ /index.html;`로 되어 있어 `/` 요청에서 내부 리다이렉트 사이클이 발생했다. + +## 조치 +- `/home/admin/robeing/frontend-customer/dist/` 내용을 `/var/www/html/robeing/`으로 동기화했다. +- `/var/www/html/robeing` 소유권을 `www-data:www-data`로 정리했다. +- `/etc/nginx/sites-available/default` +- `/etc/nginx/sites-enabled/default` +- 위 두 파일에서 `ro-being.com` 정적 루트를 `root /var/www/html/robeing;`로 변경했다. +- 위 두 파일에서 홈 SPA fallback을 `try_files $uri /index.html;`로 변경했다. + +## 검증 +- `sudo nginx -t` 통과 +- `sudo systemctl reload nginx` 수행 +- 조치 후 `https://ro-being.com` 재확인 결과 `HTTP/2 200` +- 조치 후 `https://ro-being.com/index.html` 재확인 결과 `HTTP/2 200` +- `https://git.ro-being.com`은 계속 `HTTP/2 200` +- `https://goosefarminvesting.com`은 계속 `HTTP/2 200` + +## 남은 이슈 +- `www.ro-being.com`은 현재 인증서 SAN에 포함되지 않아 TLS 검증 실패 상태다. +- 일반 패키지 업그레이드 가능 항목 `2건`은 남아 있다. +- Ubuntu Pro/ESM Apps는 미연결 상태다.