docs: record 51123 temp deploy failure root-cause fixes

journey/troubleshooting/260305_23임시배포_envdeploy_ssot_및_배포실패_근본원인_해결.md

@@ -0,0 +1,42 @@
+# 260305 23임시배포 env.deploy SSOT 및 배포실패 근본원인 해결
+
+**날짜**: 2026-03-05  
+**작성자**: Codex  
+**관련 파일**: `robeing/skill-rag-file/app/core/config.py`, `robeing/skill-rag-file/.gitea/workflows/deploy.yml`, `robeing/skill-embedding/config.py`, `robeing/robeing-monitor/.gitea/workflows/deploy.yml`
+
+---
+
+## 문제 상황
+- 51124 다운 상태에서 51123 임시운영 중, 일부 스킬 배포가 반복 실패했다.
+- `skill-rag-file`, `skill-embedding`은 컨테이너 기동 직후 `ValidationError`로 헬스체크 실패가 발생했다.
+- `robeing-monitor`는 배포 스크립트 단계에서 권한 오류로 중단됐다.
+
+## 확인된 근본 원인
+1. `skill-rag-file`/`skill-embedding` 설정 모델이 `.env`의 추가 키를 허용하지 않아 런타임 시작이 실패했다.
+2. 워크플로우의 배포 경로가 서비스별 하드코딩 경로를 사용해 SSOT(`DEPLOY_PROJECT_DIR`)가 깨져 있었다.
+3. `robeing-monitor` 배포 스크립트의 `chmod 777 logs`가 실제 권한 정책과 충돌해 즉시 실패했다.
+
+## 해결 방안
+1. 설정 파서 수정(원인 직접 수정)
+- `skill-rag-file/app/core/config.py`: `SettingsConfigDict(..., extra="ignore")` 적용.
+- `skill-embedding/config.py`: `SettingsConfigDict(..., extra="ignore")` 적용.
+
+2. 배포 경로 SSOT 정리
+- `skill-rag-file/.gitea/workflows/deploy.yml`: `cd /home/admin/...` 하드코딩 제거, `DEPLOY_PROJECT_DIR` 사용으로 통일.
+- `robeing-monitor/.gitea/workflows/deploy.yml`: 하드코딩 경로 제거, `DEPLOY_PROJECT_DIR` 기반으로 통일.
+
+3. 권한 충돌 제거
+- `robeing-monitor/.gitea/workflows/deploy.yml`: 실패 원인인 `chmod 777 logs` 제거.
+
+## 검증 결과
+- `skill-embedding` 최신 커밋 `f89109c` 실행: Gitea Actions `task 2106` `Job succeeded`.
+- `skill-rag-file` 최신 커밋 `ddc4693` 실행: Gitea Actions `task 2107` `Job succeeded`.
+- `robeing-monitor` 최신 커밋 `c62794c` 실행: Gitea Actions `task 2108` `Job succeeded`.
+
+## 운영 결론
+- 51123 임시운영 기준 배포 실패 이슈는 해결 완료 상태다.
+- 51124 복구 시 코드 수정 없이 각 레포 `.env.deploy`의 배포 대상 값만 24 서버 값으로 전환하면 된다.
+
+## 교훈
+- 배포 실패는 폴백 추가보다 실패 지점의 단일 원인(설정/권한/경로)을 직접 수정해야 재발이 줄어든다.
+- 배포 경로는 서비스별 하드코딩이 아니라 `DEPLOY_PROJECT_DIR` 단일 기준으로 유지해야 운영 전환(23↔24)이 단순해진다.