DOCS/docs/troubleshooting/20250716_rb8001_deployment_issues.md

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 방식 적용):

# 변경 전 (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 모델 재다운로드

해결:

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 문법 차이

참고 명령어

# 로컬 테스트
cd rb8001
docker compose up -d --build

# 서버 확인
docker ps | grep robeing-8001
docker compose logs robeing-8001
curl http://localhost:8001/health