diff --git a/book/300_architecture/314_인프라_설정_SSOT_원칙.md b/book/300_architecture/314_인프라_설정_SSOT_원칙.md new file mode 100644 index 0000000..23ae988 --- /dev/null +++ b/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 경로 응답을 모두 통과해야 적용 완료로 본다. diff --git a/journey/troubleshooting/260307_51123_성수이전_네트워크변경_운영기록.md b/journey/troubleshooting/260307_51123_성수이전_네트워크변경_운영기록.md new file mode 100644 index 0000000..d4d4b32 --- /dev/null +++ b/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 사용자 전달 사실 기반 운영 기록. diff --git a/journey/troubleshooting/260307_gateway_SSOT_runtime_secrets_분리_적용_및_검증.md b/journey/troubleshooting/260307_gateway_SSOT_runtime_secrets_분리_적용_및_검증.md new file mode 100644 index 0000000..ebad0b2 --- /dev/null +++ b/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`까지 정상 응답 기준으로 복구됨