DOCS/02_Architecture/Infrastructure_Project_Structure.md

Infrastructure Project Structure

목적

이 문서는 인프라 프로젝트의 핵심 구성 요소를 무엇이 있는가와 왜 필요한가 기준으로 정리하는 기준 문서다.

1. 핵심 운영 자산

23 서버

• 무엇:
  • nginx
  • Gitea / CI
  • PostgreSQL
  • auth-server
  • robeing-gateway
  • 운영 보조 프론트/서비스
• 왜:
  • 외부 요청의 진입점과 운영 제어를 한곳에서 통합하기 위해
  • 인증, 라우팅, 배포 검증, 운영 판단의 기준면을 만들기 위해
  • 24 장애 시 임시 수용 지점을 확보하기 위해

24 서버

• 무엇:
  • rb8001 등 핵심 앱 런타임
  • 스킬 서비스들
  • 실행 중심 컨테이너
• 왜:
  • 사용자 가치가 생성되는 실행 부하를 23과 분리하기 위해
  • 앱 장애와 게이트웨이/DB 장애를 분리해 원인 판별 속도를 높이기 위해
  • 프로덕션 기준 서버를 명확히 하기 위해

내부 NAS

• 무엇:
  • 백업 저장소
  • 로그 아카이브
  • 릴리스/산출물 보관
  • 장기 보존 경로
• 왜:
  • 서버 자체와 분리된 기억 저장소가 있어야 복구 기준이 생기기 때문에
  • 장애 후에도 로그와 데이터가 남아야 원인을 설명할 수 있기 때문에

2. 보조 운영 자산

workspace-config

• 무엇: runtime.env, secrets.env
• 왜: 환경값의 기준점을 코드/개별 .env 밖으로 분리해 SSOT를 유지하기 위해

infra/nginx

• 무엇: nginx 배포 설정 저장소
• 왜: 진입 계층 설정을 애플리케이션 저장소와 분리해 추적성과 배포 일관성을 확보하기 위해

/mnt/hdd/logs

• 무엇: 서비스 로그 저장 경로
• 왜: 컨테이너/앱 수명주기와 분리된 관측 기록을 유지하기 위해

Gitea Actions / Runner

• 무엇: 23에서 운영되는 배포 자동화 경로
• 왜: 수동 서버 조작보다 재현 가능한 배포 절차를 만들기 위해

3. 구조적으로 중요한 관계

진입 경로

• 사용자/도메인 요청 -> 23의 nginx/gateway -> 필요한 서비스로 전달
• 의미: 외부 진입을 통제 가능한 한곳에서 먼저 본다.

실행 경로

• 실제 앱 처리와 스킬 실행은 24가 주도
• 의미: 사용자 가치 생성 부하를 제어/저장 계층과 분리한다.

보존 경로

• 백업, 로그, 장기 산출물은 NAS로 보낸다.
• 의미: 서버 장애가 곧 기록 손실이 되지 않게 한다.

4. 문서화 원칙

• 역할 정의는 이 문서 같은 구조 문서에 고정한다.
• 실제 IP/포트/마운트 값은 SSOT 문서 또는 workspace-config 기준으로 관리한다.
• 장애/변경/복구 과정은 journey/에서 사실 중심으로 기록한다.