Claude-51124 22557e7132 docs: 오래된 트러블슈팅 아카이브 및 구조 정리

- 7-8월 초기 구축 문서 12개를 _archive/troubleshooting/2025_07-08_initial_setup/로 이동
- book/300_architecture/390_human_in_the_loop_intent_learning.md를 journey/research/intent_classification/로 이동 (개발 여정 문서)
- 빈 폴더 제거 (journey/assets/*)

2025-11-17 14:06:05 +09:00

4.2 KiB

Raw Permalink Blame History

함수형 프로그래밍 전환 및 skill-embedding 포트 변경

날짜: 2025-08-12
작업자: happybell80 & Claude (로컬 개발자)
작업 범위: rb10508_micro, skill-embedding

오후 2시 30분

rb10508_micro 함수형 프로그래밍 전환

배경

os.getenv() 호출이 여러 파일에 산재
환경변수 기본값 하드코딩 문제
함수형 프로그래밍 원칙 위반

작업 내용

1. config.py 환경변수 중앙화

모든 환경변수를 config.py로 통합
Skill URLs, 감정 시스템, 프라이버시, 스케일링, 모니터링 설정 추가
SKILL_EMBEDDING_URL 포트 8015 → 8515 변경

2. 감정 모듈 수정

# 변경 전
BASIC_EMOTIONS = os.getenv('BASIC_EMOTIONS', 'joy,sadness').split(',')

# 변경 후  
BASIC_EMOTIONS = settings.BASIC_EMOTIONS.split(',')

3. growth.py 완전 함수형 전환

NamedTuple 사용 (Stats)
순수 함수로 변경 (get_default_stats, gain_experience)
레거시 클래스는 래퍼로 유지 (호환성)

4. 위험한 부분 제외

SlackService: Slack SDK 요구사항으로 클래스 유지
HTTPEmbeddingFunction: ChromaDB 인터페이스 요구사항

결과

✅ 환경변수 중앙 관리
✅ 함수형 원칙 준수
✅ 테스트 용이성 향상

오후 2시 45분

skill-embedding 서비스 포트 변경 (8015 → 8515)

변경 파일

config.py: 기본 포트 8515
docker-compose.yml: 포트 매핑, 환경변수, 헬스체크
.gitea/workflows/deploy.yml: 헬스체크 URL
test_api.py: 모든 테스트 URL
README.md: 문서 업데이트
http_embedding_function.py: 기본 URL

헬스체크 구현

단순 헬스체크: /healthz (서비스 생존 확인)
상세 헬스체크: /health (모델 정보 포함)

오후 2시 50분

배포 시 문제 발생

문제 1: docker-compose.yml version 속성

# 문제
version: '3.8'  # deprecated 경고

# 해결
# version 라인 제거

문제 2: 컨테이너 이름 충돌

기존 8015 포트 서비스가 실행 중
같은 이름(skill-embedding)으로 새 컨테이너 생성 실패
24서버팀이 docker rm -f skill-embedding 실행 후 해결

교훈

로컬 개발자는 서버 작업 안내만 제공
서버 작업은 24서버팀에게 요청
테스트 시 실제 런타임 환경 확인 필요

오후 3시 00분

테스트 부족 문제

로컬 테스트의 한계

Python 문법 검사(AST)만 수행
Docker 실행 환경 테스트 안함
포트 충돌 확인 안함

필요했던 테스트

# 포트 사용 확인
ss -tulpn | grep 8515

# Docker compose 검증
docker compose config

# 실제 헬스체크
curl http://localhost:8515/healthz

오후 3시 15분

최종 정리

성공한 작업

rb10508_micro 함수형 전환
- config.py 중앙화 완료
- growth.py 순수 함수형
- 위험 부분 제외 (SlackService, HTTPEmbeddingFunction)
skill-embedding 포트 변경
- 8015 → 8515 완료
- /healthz 엔드포인트 추가
- docker-compose.yml 개선

실수와 교훈

테스트 부족
- 문법 검사만으로 부족
- 런타임 테스트 필요
역할 혼동
- 로컬 개발자가 서버 작업 시도 (❌)
- 24서버팀에게 요청해야 함 (✅)
배포 준비 미흡
- 기존 서비스 확인 필요
- 컨테이너 충돌 예상 필요

개선 사항

배포 전 체크리스트 작성
24서버팀과 사전 협의
실제 환경 테스트 강화

교훈

함수형 프로그래밍 원칙
- 환경변수는 중앙에서 관리
- 순수 함수 우선
- 외부 라이브러리 요구사항은 예외
포트 변경 시 주의사항
- 기존 서비스 확인
- 모든 관련 파일 동기화
- Gitea Actions 파일 누락 주의
로컬/서버 역할 분리
- 로컬 개발자: 코드 작성, 테스트, 푸시
- 24서버팀: 서버 작업, 컨테이너 관리, 배포
테스트 중요성
- 문법 검사 < 단위 테스트 < 통합 테스트 < 런타임 테스트
- 실제 환경과 유사한 테스트 환경 필요

작성: 2025-08-12 15:15

4.2 KiB Raw Permalink Blame History