KWON
f41599eef6
- WSL2 Ubuntu에서 'image already exists' 오류 해결 문서 추가 - Linux/macOS용 build.sh 스크립트 추가 (BuildKit 비활성화) - Windows PowerShell용 build.ps1 스크립트 추가 - 빌드 오류 트러블슈팅 가이드 추가 - docker-compose.yml에 빌드 오류 관련 주석 추가 - MODULES.md에 Docker 빌드 오류 해결 섹션 추가
263 lines
5.6 KiB
Markdown
263 lines
5.6 KiB
Markdown
# FGTools 모듈 테스트 가이드
|
|
|
|
프로젝트의 각 모듈을 개별적으로 테스트 실행할 수 있습니다.
|
|
|
|
## 준비 사항
|
|
|
|
```powershell
|
|
# 프로젝트 디렉토리로 이동
|
|
cd c:\DEV\python\fgtools
|
|
|
|
# PYTHONPATH 설정 (선택사항: 명시적 경로 설정)
|
|
$env:PYTHONPATH='c:\DEV\python\fgtools'
|
|
|
|
# 가상환경 활성화
|
|
.\venv\Scripts\Activate.ps1
|
|
```
|
|
|
|
## 서비스 모듈 테스트
|
|
|
|
### Weather (기상청) 서비스
|
|
|
|
#### ASOS 모듈 (종관기상 데이터)
|
|
```powershell
|
|
python services/weather/asos.py
|
|
```
|
|
**기능:**
|
|
- 기상청 ASOS 종관기상 데이터 조회
|
|
- 일별 기상 데이터 수집 (기온, 강수량, 습도 등)
|
|
- DB 저장 기능
|
|
|
|
#### Forecast 모듈 (기상청 예보)
|
|
```powershell
|
|
python services/weather/forecast.py
|
|
```
|
|
**기능:**
|
|
- 초단기 예보 (향후 6시간)
|
|
- 단기 예보 (향후 3일)
|
|
- 중기 예보 (3~10일 후)
|
|
|
|
#### Precipitation 모듈 (강수량)
|
|
```powershell
|
|
python services/weather/precipitation.py
|
|
```
|
|
**기능:**
|
|
- 시간별 강수량 예보
|
|
- HTML 테이블 생성
|
|
- 다양한 출력 형식 (JSON, HTML, 텍스트)
|
|
|
|
### Analytics (분석) 서비스
|
|
|
|
#### Air Quality 모듈 (대기질)
|
|
```powershell
|
|
python services/analytics/air_quality.py
|
|
```
|
|
**기능:**
|
|
- 한국환경공단 API를 통한 대기질 데이터 수집
|
|
- PM2.5, PM10, SO2, CO, NO2, O3 측정
|
|
- 측정소별 데이터 저장
|
|
|
|
#### GA4 모듈 (Google Analytics)
|
|
```powershell
|
|
python services/analytics/ga4.py
|
|
```
|
|
**기능:**
|
|
- GA4 API를 통한 웹사이트 분석 데이터 수집
|
|
- 일별 세션, 사용자, 이벤트 수 조회
|
|
- 병렬 처리를 통한 성능 최적화
|
|
|
|
#### Visitor Forecast 모듈 (방문객 예측)
|
|
```powershell
|
|
python services/analytics/visitor_forecast.py
|
|
```
|
|
**기능:**
|
|
- 날씨, 휴일, 과거 데이터를 기반한 방문객 예측
|
|
- 일별 및 주별 예측
|
|
- 날씨 영향도 분석
|
|
|
|
### Notification (알림) 서비스
|
|
|
|
#### Mattermost 모듈
|
|
```powershell
|
|
python services/notification/mattermost.py
|
|
```
|
|
**기능:**
|
|
- Mattermost로 알림 메시지 발송
|
|
- 웹훅 및 Bot API 방식 지원
|
|
- 다양한 메시지 타입 (날씨, 보고서 등)
|
|
|
|
#### Notion 모듈
|
|
```powershell
|
|
python services/notification/notion.py
|
|
```
|
|
**기능:**
|
|
- Notion 웹훅 이벤트 처리
|
|
- 페이지 생성/수정/삭제 감지
|
|
- 알림 메시지 생성 및 발송
|
|
|
|
## Flask 애플리케이션 테스트
|
|
|
|
### Dashboard (대시보드)
|
|
```powershell
|
|
# 서버 실행
|
|
python apps/dashboard/app.py
|
|
|
|
# 또는 직접 실행
|
|
$env:PYTHONPATH='c:\DEV\python\fgtools'
|
|
python -c "from apps.dashboard.app import create_app; app = create_app(); app.run()"
|
|
```
|
|
**포트:** 5000 (기본값)
|
|
**엔드포인트:**
|
|
- `GET /api/dashboard/health` - 헬스 체크
|
|
- `GET /api/dashboard/stats` - 통계 조회
|
|
|
|
### Weather API (날씨 API 서버)
|
|
```powershell
|
|
python apps/weather_api/app.py
|
|
```
|
|
**포트:** 5001
|
|
**엔드포인트:**
|
|
- `GET /api/weather/health` - 헬스 체크
|
|
- `GET /api/weather/precipitation` - 강수량 예보
|
|
|
|
### Webhook (웹훅 수신 서버)
|
|
```powershell
|
|
python apps/webhook/app.py
|
|
```
|
|
**포트:** 5002
|
|
**엔드포인트:**
|
|
- `GET /webhook/health` - 헬스 체크
|
|
- `POST /webhook/notion` - Notion 웹훅 수신
|
|
|
|
## 통합 테스트
|
|
|
|
### 모든 애플리케이션 동시 실행
|
|
```powershell
|
|
# Docker Compose 사용 (권장)
|
|
docker compose up -d
|
|
|
|
# 또는 개별 터미널에서 각각 실행
|
|
# 터미널 1
|
|
python apps/dashboard/app.py
|
|
|
|
# 터미널 2
|
|
python apps/weather_api/app.py
|
|
|
|
# 터미널 3
|
|
python apps/webhook/app.py
|
|
```
|
|
|
|
## 디버깅 및 로깅
|
|
|
|
### 디버그 모드 활성화
|
|
```powershell
|
|
$env:DEBUG='true'
|
|
$env:LOG_LEVEL='DEBUG'
|
|
python services/weather/asos.py
|
|
```
|
|
|
|
### 로그 레벨 설정
|
|
```powershell
|
|
$env:LOG_LEVEL='DEBUG' # 가장 상세
|
|
$env:LOG_LEVEL='INFO' # 일반 정보
|
|
$env:LOG_LEVEL='WARNING' # 경고
|
|
$env:LOG_LEVEL='ERROR' # 에러만
|
|
```
|
|
|
|
## 환경변수 설정
|
|
|
|
`.env` 파일에 다음 변수를 설정하세요:
|
|
|
|
```
|
|
# API 키
|
|
DATA_API_SERVICE_KEY=your_service_key
|
|
|
|
# 데이터베이스
|
|
DB_HOST=localhost
|
|
DB_USER=firstgarden
|
|
DB_PASSWORD=your_password
|
|
DB_NAME=firstgarden
|
|
|
|
# GA4
|
|
GA4_ENABLED=true
|
|
GA4_PROPERTY_ID=your_property_id
|
|
|
|
# Mattermost
|
|
MATTERMOST_ENABLED=true
|
|
MATTERMOST_WEBHOOK_URL=your_webhook_url
|
|
|
|
# Notion
|
|
NOTION_ENABLED=true
|
|
NOTION_API_SECRET=your_api_secret
|
|
|
|
# 로깅
|
|
LOG_LEVEL=INFO
|
|
DEBUG=false
|
|
```
|
|
|
|
## 성능 최적화 팁
|
|
|
|
### 병렬 처리
|
|
```powershell
|
|
# 최대 워커 수 설정 (기본: 4)
|
|
$env:MAX_WORKERS='8'
|
|
python services/analytics/ga4.py
|
|
```
|
|
|
|
### 타임아웃 설정
|
|
각 서비스는 적절한 타임아웃을 기본 설정으로 포함하고 있습니다.
|
|
|
|
## 트러블슈팅
|
|
|
|
### ModuleNotFoundError
|
|
```powershell
|
|
# PYTHONPATH 설정
|
|
$env:PYTHONPATH='c:\DEV\python\fgtools'
|
|
```
|
|
|
|
### 환경변수 누락
|
|
필요한 `.env` 파일이 있는지 확인하세요:
|
|
```powershell
|
|
# .env 파일 확인
|
|
Test-Path .env
|
|
```
|
|
|
|
### 데이터베이스 연결 오류
|
|
```powershell
|
|
# 데이터베이스 설정 확인
|
|
$env:DB_HOST
|
|
$env:DB_USER
|
|
$env:DB_NAME
|
|
```
|
|
|
|
### Docker 빌드 오류 ("image already exists")
|
|
```powershell
|
|
# WSL2 Ubuntu 환경에서 발생하는 오류 해결:
|
|
|
|
# 방법 1: BuildKit 비활성화 (권장)
|
|
$env:DOCKER_BUILDKIT=0
|
|
docker compose build
|
|
|
|
# 방법 2: 캐시 무시하고 빌드
|
|
docker compose build --no-cache
|
|
|
|
# 방법 3: 이전 이미지 삭제
|
|
docker rmi reg.firstgarden.co.kr/fgtools:latest
|
|
docker compose build
|
|
|
|
# 방법 4: BuildKit 캐시 정리
|
|
docker buildx prune -a
|
|
|
|
# 방법 5: 완전 초기화 후 빌드
|
|
docker compose down
|
|
docker rmi reg.firstgarden.co.kr/fgtools:latest
|
|
docker buildx prune -a
|
|
docker compose build
|
|
```
|
|
|
|
## 추가 정보
|
|
|
|
- [전체 프로젝트 구조](README.md)
|
|
- [설정 관리](core/config.py)
|
|
- [로깅 설정](core/logging_utils.py)
|