Document SSOT env split and network migration

book/300_architecture/314_인프라_설정_SSOT_원칙.md

@@ -0,0 +1,43 @@
+# 314 인프라 설정 SSOT 원칙
+
+## 1. 목적
+- 인프라 핵심 설정(IP, 포트, 업스트림, 공통 URL, 환경별 엔드포인트)을 단일 출처(Single Source of Truth)로 관리한다.
+- 값 변경 1건이 다수 코드/설정/문서 수정을 유발하는 구조를 제거한다.
+
+## 2. 원칙
+### 2.1 단일 출처
+- 런타임 설정의 기준 파일은 `/home/admin/infra-config/runtime.env` 단일 파일로 한다.
+- 민감 정보의 기준 파일은 `/home/admin/infra-config/secrets.env` 단일 파일로 한다.
+
+### 2.2 분리 원칙
+- `runtime.env`: 비민감 운영값만 포함한다.
+  - 예: 내부 IP, 포트, 서비스 호스트, 모니터 URL, 기능 플래그
+- `secrets.env`: 인증/암호/키 등 민감값만 포함한다.
+  - 예: JWT secret, OAuth secret, DB password 포함 URL
+
+### 2.3 참조 원칙
+- 서비스 컨테이너는 `docker-compose.yml`의 `env_file`에서 위 2개 파일을 우선 참조한다.
+- 서비스별 `.env`는 “임시 로컬 오버라이드” 용도로만 사용한다.
+- 운영 기본값은 코드 하드코딩으로 두지 않는다.
+
+### 2.4 네트워크 표현 원칙
+- 컨테이너 간 통신은 서비스 DNS 이름을 우선 사용한다.
+- 호스트 접근이 필요한 경우에만 `host.docker.internal` 또는 운영 표준 호스트 값을 사용한다.
+- 고정 IP 직접 참조는 불가피한 경계 구간에서만 허용하고, 반드시 SSOT 변수로 선언한다.
+
+### 2.5 보안 원칙
+- `runtime.env`와 `secrets.env`는 git에 커밋하지 않는다.
+- 권한 최소화:
+  - `runtime.env` 640 이하
+  - `secrets.env` 600
+  - 디렉터리 권한 제한(예: 750)
+
+### 2.6 문서 원칙
+- 트러블슈팅 문서는 “사실/조치/검증”만 기록한다.
+- 영구 규칙 변경은 본 원칙 문서에만 반영한다.
+- 운영 주소 변경 시, 개별 문서에 직접 IP를 추가하지 말고 SSOT 변수명을 사용한다.
+
+## 3. 적용 기준
+- 신규 서비스: 최초 구성부터 본 원칙을 강제 적용한다.
+- 기존 서비스: 장애 영향도가 높은 서비스부터 단계적으로 이전한다.
+- 변경 검증: `docker compose config`, health check, 실제 API 경로 응답을 모두 통과해야 적용 완료로 본다.

journey/troubleshooting/260307_51123_성수이전_네트워크변경_운영기록.md

@@ -0,0 +1,18 @@
+# 260307 51123 서버 성수 이전 네트워크 변경 운영기록
+
+## 1. 배경
+- 51123 서버 운영 위치가 서울 양재에서 성수로 이전됨.
+- 이전 과정에서 공인 IP, 공유기, 내부 사설 IP 대역이 변경됨.
+- DNS 설정은 완료했고, 내부 사설 IP 정리 작업을 진행 중임.
+
+## 2. 현재 기준 주소(운영 사실)
+- 51123 임시 운용 서버 내부 사설 IP: `192.168.0.100`
+- NAS 내부 사설 IP: `192.168.0.101`
+
+## 3. 운영 반영 메모
+- 기존 `192.168.219.x` 기준 문서/환경변수/프록시/헬스체크 경로는 순차적으로 `192.168.0.x` 기준으로 정리 필요.
+- gateway 및 연계 서비스의 upstream 대상 주소는 실제 바인딩/노출 포트와 함께 재검증 필요.
+- NAS 마운트/백업 경로는 `192.168.0.101` 기준으로 재점검 필요.
+
+## 4. 기록 출처
+- 2026-03-07 사용자 전달 사실 기반 운영 기록.

journey/troubleshooting/260307_gateway_SSOT_runtime_secrets_분리_적용_및_검증.md

@@ -0,0 +1,76 @@
+# 260307 gateway SSOT(runtime/secrets) 분리 적용 및 검증
+
+## 1. 목적
+- 51123 임시 운용 환경에서 분산된 설정값을 1차 정리한다.
+- 우선순위가 높은 `robeing-gateway`부터 `runtime.env`(비민감)와 `secrets.env`(민감)로 분리 적용한다.
+
+## 2. 변경 사항
+### 2.1 SSOT 파일 신설
+- `/home/admin/infra-config/runtime.env` 생성
+  - 운영 비민감값(예: `HOST_51123`, `NAS_HOST`, `ROBEING_DEFAULT_HOST`, `MONITOR_URL`) 관리
+- `/home/admin/infra-config/secrets.env` 생성
+  - 민감값(예: `DATABASE_URL`, `JWT_SECRET_KEY`) 관리
+
+### 2.2 권한 적용
+- `runtime.env`: `640`
+- `secrets.env`: `600`
+- 디렉터리 `/home/admin/infra-config`: `750`
+
+### 2.3 게이트웨이 참조 경로 변경
+- 대상: `/home/admin/robeing-gateway/docker-compose.yml`
+- `env_file` 순서:
+  1. `/home/admin/infra-config/runtime.env`
+  2. `/home/admin/infra-config/secrets.env`
+  3. `.env` (임시 오버라이드 전용)
+
+### 2.4 기존 게이트웨이 `.env` 정리
+- 대상: `/home/admin/robeing-gateway/.env`
+- 실값 제거 후, “로컬 오버라이드 전용” 안내만 유지
+
+## 3. 검증 결과
+### 3.1 설정 파싱 검증
+- `docker compose -f /home/admin/robeing-gateway/docker-compose.yml config` 성공
+
+### 3.2 재가동 검증
+- 실행: `docker compose down && docker compose up -d --build`
+- 결과: `robeing-gateway` `Up (healthy)` 확인
+
+### 3.3 기능 검증
+- `GET http://127.0.0.1:8100/healthz` -> `200`
+- 도메인 경유 `/gateway/api/config` -> 미인증 요청 `401` (정상 인증 경계)
+- `gateway -> 192.168.0.100:8001/health` -> `200`
+- `gateway -> 192.168.0.100:9024/healthz` -> `200`
+
+## 4. 결론
+- 기존 무응답 핵심 원인이었던 연결 단절 상태는 해소됨.
+- 현재 `/api/message` 응답 경계는 연결 실패가 아니라 인증(`401`) 단계로 정상 전환됨.
+- SSOT 분리는 `robeing-gateway`에 1차 적용 완료, 나머지 서비스는 동일 패턴으로 순차 이전 필요.
+
+## 5. 후속 적용: robeing-monitor SSOT 분리 및 9024 복구
+### 5.1 변경 사항
+- 대상: `/home/admin/robeing/robeing-monitor`
+- `docker-compose.yml`이 `/home/admin/infra-config/runtime.env`, `/home/admin/infra-config/secrets.env`를 우선 참조하도록 변경
+- 기존 `.env`는 로컬 오버라이드 전용 안내만 유지
+- `app/core/config.py` 기본 DB 호스트를 현재 운영 기준 `192.168.0.100`으로 교정
+- `infra-config`에 아래 값을 추가
+  - `ROBEING_MONITOR_PORT`
+  - `ROBEING_MONITOR_LOG_LEVEL`
+  - `ROBEING_MONITOR_DATABASE_URL`
+  - `ROBEING_URLS`
+  - `SKILL_URLS`
+
+### 5.2 증상
+- 적용 전 `robeing_monitor` 컨테이너는 `unhealthy`
+- `curl http://127.0.0.1:9024/healthz` 타임아웃
+- Docker healthcheck도 동일하게 `Health check exceeded timeout (10s)` 반복
+
+### 5.3 검증 결과
+- `docker compose -f /home/admin/robeing/robeing-monitor/docker-compose.yml config` 성공
+- 실행: `docker compose down && docker compose up -d --build`
+- 결과: `robeing_monitor` `Up (healthy)` 확인
+- `GET http://127.0.0.1:9024/healthz` -> `200`
+
+### 5.4 결론
+- `robeing-monitor`도 SSOT 기반으로 1차 이전 완료
+- 9024 응답 정지 상태는 해소됐고, 현재 헬스체크 정상
+- 51123 임시 운용 핵심 경로는 `gateway`, `rb8001`, `robeing-monitor`까지 정상 응답 기준으로 복구됨