docs: add rb8001 deployment troubleshooting guide

- Document issues encountered during rb8001 deployment
- Record solutions for port configuration, env variables, Docker optimization
- Include lessons learned from rb10508_test integration

docs/troubleshooting/20250716_rb8001_deployment_issues.md

@@ -0,0 +1,117 @@
+# RB8001 배포 문제 해결 과정
+
+**날짜**: 2025-07-16  
+**작업자**: Claude & happybell
+
+## 개요
+
+rb8001 프로젝트에 rb10508_test의 기능을 통합한 후 Gitea Actions 배포 과정에서 발생한 문제들과 해결 과정 기록
+
+## 주요 문제 및 해결
+
+### 1. Gitea Actions 포트 설정 문제
+
+**문제**:
+- Health check가 10508 포트로 시도 (rb8001은 8001 사용)
+- 컨테이너 이름이 `test-api-container`로 표시
+
+**해결**:
+- `.gitea/workflows/cicd.yml`에서 모든 10508 → 8001 변경
+- 컨테이너 이름 및 경로 수정: `/home/admin/test_api` → `/home/admin/rb8001`
+
+### 2. 환경변수 로딩 실패
+
+**문제**:
+- Docker Compose에서 `~/.env` 경로 인식 실패
+- LOG_LEVEL 대소문자 충돌 (INFO vs info)
+
+**해결**:
+1. `~/.env` → `/home/admin/.env` (절대 경로로 변경)
+2. LOG_LEVEL 환경변수 제거
+3. 최종적으로 `.env`로 변경 (로컬 파일 사용)
+
+### 3. Gitea Actions 파일 복사 실패
+
+**문제**:
+- `${{ github.workspace }}` 변수가 Gitea Actions에서 작동하지 않음
+- find 명령어가 .env 파일도 삭제
+
+**해결**:
+- GitHub Actions 변수를 act 캐시 경로로 변경: `/home/admin/.cache/act/*/hostexecutor/*`
+- find 명령에 `! -name '.env'` 추가하여 .env 파일 보존
+
+### 4. Docker 빌드 최적화 문제
+
+**문제**:
+- 매번 torch (2GB+), sentence-transformers 등 거대한 패키지 재설치
+- 불필요한 패키지 설치 (gcc, postgresql-client)
+- ARG 변수 사용으로 Docker 캐싱 비효율
+
+**해결 (rb10508_test 방식 적용)**:
+```dockerfile
+# 변경 전 (rb8001 원본)
+FROM python:3.12.11-slim-bookworm
+ARG UID=1000
+ARG USR=api-user
+# ... ARG 변수들
+RUN apt-get install gcc postgresql-client
+RUN find ${BASE_PATH} -exec chmod 700 {} \;
+
+# 변경 후 (rb10508_test 방식)
+FROM python:3.13-slim
+RUN apt-get install curl  # 최소 패키지만
+RUN groupadd -r appuser && useradd -r -g appuser appuser  # 단순한 유저 생성
+RUN chmod -R 755 /code  # 표준 권한
+```
+
+### 5. 네트워크 모드와 포트 충돌
+
+**문제**:
+- `network_mode: host` + 포트 매핑 `8001:8000` 충돌
+- 내부/외부 포트 불일치
+
+**해결**:
+- `network_mode: host` 제거
+- 모든 포트를 8001로 통일 (PORT 환경변수, EXPOSE, docker-compose)
+
+### 6. 사전 다운로드된 모델 활용
+
+**문제**:
+- 매번 torch와 sentence-transformers 모델 재다운로드
+
+**해결**:
+```yaml
+volumes:
+  - /opt/models:/models:rw  # 서버의 사전 다운로드된 모델 마운트
+```
+
+## 최종 상태
+
+- 컨테이너는 정상 작동 중 (로그 확인)
+- Health check 200 OK 응답
+- 포트 8001에서 정상 실행
+
+## 남은 작업
+
+1. nginx 설정 적용 (PR 생성됨)
+2. 실제 서비스 테스트
+
+## 교훈
+
+1. **기존 작동하는 시스템 참조**: rb10508_test의 설정을 정확히 분석하고 적용
+2. **단순함이 최선**: ARG 변수, 복잡한 권한 설정보다 단순한 구조가 효율적
+3. **캐싱 고려**: Docker 레이어 순서와 변경 빈도 고려
+4. **환경 차이 인식**: GitHub Actions vs Gitea Actions 문법 차이
+
+## 참고 명령어
+
+```bash
+# 로컬 테스트
+cd rb8001
+docker compose up -d --build
+
+# 서버 확인
+docker ps | grep robeing-8001
+docker compose logs robeing-8001
+curl http://localhost:8001/health
+```