myhome-server/README.md

# 홈 관리 시스템 (Home Management API)

홈 IoT 기기 모니터링 및 관리를 위한 백엔드 API 시스템입니다.

> **Mac Mini M4 Pro 전용 버전** - 고성능 홈 서버 환경에 최적화

## 📋 **현재 개발 상태 (v1.0)**

✅ **백엔드 API 완성** - Tapo 스마트 플러그 관리, 디바이스 모니터링  
✅ **데이터베이스 구성 완료** - 5개 테이블, 기본 데이터 설정  
✅ **Docker 환경 구축** - MariaDB, Redis, API 서버 통합 운영  
🚧 **프론트엔드 웹 대시보드** - 개발 대기 중

## 🎯 주요 기능

### ✅ **구현 완료**
- **Tapo 스마트 플러그 관리**: 동적 기기 추가/제거/모니터링
- **전력 소비 추적**: Tapo P110 플러그를 통한 실시간 전력 데이터 수집
- **확장 가능한 아키텍처**: 설정 파일 기반 기기 관리
- **RESTful API**: Express.js 기반 완전한 백엔드 API
- **데이터베이스**: MariaDB를 통한 안정적인 데이터 저장 및 테이블 구성 완료
- **캐시 시스템**: Redis를 통한 고성능 데이터 처리
- **사용자 관리**: 관리자/가족 계정 및 역할 기반 시스템
- **디바이스 등록**: Mac Mini, NAS, 라우터 기본 디바이스 등록

### 🚧 **개발 예정**
- **웹 대시보드**: 실시간 모니터링 인터페이스
- **개인 문서관리**: Paperless 연동 문서 시스템
- **시스템 리소스 모니터링**: CPU, 메모리, 디스크 사용량 추적
- **네트워크 트래픽 모니터링**: 디바이스별 네트워크 사용량 추적
- **알림 시스템**: 임계값 기반 실시간 알림
- **사용자 관리**: 역할 기반 접근 제어

## 🛠 기술 스택

- **Backend**: Node.js, Express.js
- **Database**: MariaDB 11.x
- **ORM**: Sequelize
- **Cache**: Redis
- **Logging**: Winston
- **Container**: Docker & Docker Compose

## 📋 요구사항

- Node.js 18+
- Docker & Docker Compose
- Git

## 🚀 빠른 시작

### 1. 저장소 클론

```bash
git clone https://git.hyungi.net/hyungi/myhome-server.git
cd myhome-server
```

### 2. 필요한 디렉토리 생성

```bash
mkdir -p /Users/$(whoami)/home-management-db
mkdir -p /Users/$(whoami)/home-management-redis  
mkdir -p /Users/$(whoami)/home-management-data
mkdir -p /Users/$(whoami)/home-management-logs
```

### 3. Docker Compose 실행

```bash
# 모든 서비스 시작
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 서비스 상태 확인
docker-compose ps
```

### 4. Mac Mini SSH 연결 설정 (집에서)

```bash
# SSH 키 생성 (없는 경우)
ssh-keygen -t rsa

# Mac Mini에 공개키 복사
ssh-copy-id hyungiahn@192.168.1.122

# SSH 연결 테스트
ssh hyungiahn@192.168.1.122 "echo 'SSH 연결 성공!'"
```

### 5. Tapo 기기 설정

```bash
# Tapo 기기 설정 파일 편집
nano config/tapo-devices.json

# 실제 IP, 이메일, 패스워드 입력 후 저장
```

## 📊 서비스 확인

### 🌐 **서비스 접속 정보**
- **API 서버**: http://localhost:9306
- **phpMyAdmin**: http://localhost:9304
- **MariaDB**: localhost:9305
- **Redis**: localhost:9307

### 🏥 **헬스체크**

```bash
# API 서버 상태 확인
curl http://localhost:9306/health

# API 엔드포인트 목록 확인
curl http://localhost:9306/api

# Tapo 기기 목록 확인
curl http://localhost:9306/api/tapo/devices
```

## 📚 API 엔드포인트

### 🔌 Tapo 스마트 플러그 관리

```bash
# 기기 목록 조회
GET    /api/tapo/devices

# 새 기기 추가
POST   /api/tapo/devices

# 기기 설정 업데이트
PUT    /api/tapo/devices/:deviceId

# 기기 제거
DELETE /api/tapo/devices/:deviceId

# 실시간 전력 데이터 조회
GET    /api/tapo/devices/:deviceId/power

# 모든 기기 전력 데이터 조회
GET    /api/tapo/power

# 연결 테스트
POST   /api/tapo/test-connection

# 기기 설정 템플릿
GET    /api/tapo/template
```

### 📊 디바이스 관리

```bash
GET    /api/devices          # 모든 디바이스 조회
GET    /api/devices/:id      # 특정 디바이스 조회
POST   /api/devices          # 새 디바이스 생성
PUT    /api/devices/:id      # 디바이스 업데이트
DELETE /api/devices/:id      # 디바이스 삭제
```

### 🖥️ Mac Mini 시스템 모니터링

```bash
# 실시간 시스템 데이터 수집 (SSH 원격 실행)
GET    /api/mac-mini/collect

# 최근 데이터 조회
GET    /api/mac-mini/recent?limit=10

# 특정 기간 데이터 조회
GET    /api/mac-mini/history?startDate=2025-01-01&endDate=2025-01-02

# 시스템 상태 요약
GET    /api/mac-mini/summary

# SSH 연결 테스트
GET    /api/mac-mini/test
```

### 💡 기본 사용 예제

```bash
# Tapo 기기 목록 조회
curl http://localhost:9306/api/tapo/devices

# Tapo 기기 설정 템플릿 확인
curl http://localhost:9306/api/tapo/template

# 새 Tapo 기기 추가
curl -X POST http://localhost:9306/api/tapo/devices \
  -H "Content-Type: application/json" \
  -d '{
    "id": "living_room_plug",
    "name": "거실 스마트 플러그",
    "ip": "192.168.1.100",
    "email": "your-tapo-email@gmail.com",
    "password": "your-tapo-password",
    "location": "거실",
    "device_type": "smart_plug",
    "enabled": true
  }'

# 전력 소비 데이터 조회
curl http://localhost:9306/api/tapo/power

# Mac Mini 시스템 상태 확인
curl http://localhost:9306/api/mac-mini/summary

# Mac Mini 실시간 데이터 수집
curl http://localhost:9306/api/mac-mini/collect
```

## 🗄️ 데이터베이스

### 접속 정보

- **Host**: localhost
- **Port**: 9305
- **Database**: home_management
- **Username**: homeuser
- **Password**: mac_mini_home_password

### 테이블 구성

시스템에는 다음 테이블들이 구성되어 있습니다:

```yaml
✅ devices             # 디바이스 관리 (3개 기본 데이터)
✅ users               # 사용자 관리 (2개 기본 계정)
✅ mac_mini_data       # Mac Mini 시스템 데이터 (SSH 원격 수집)
✅ nas_data            # Synology NAS 데이터 (API 연동 예정)
✅ power_consumption   # 전력 소비 데이터 (기존)
✅ network_traffic     # 네트워크 트래픽 데이터 (기존)
✅ system_resources    # 시스템 리소스 데이터 (기존)
```

### 기본 데이터

시스템 초기화시 다음 데이터가 자동으로 생성됩니다:

**기본 계정:**
- **관리자 계정**: admin / admin123 (admin 권한)
- **가족 계정**: family / admin123 (family 권한)

**기본 디바이스:**
- **Mac Mini M4 Pro** (server, 서재)
- **Synology DS1525+** (nas, 서재)
- **Synology RT6600ax** (router, 거실)

## 🔧 개발 가이드

### 환경 변수 설정

`.env` 파일에 다음 설정을 추가하세요:

```bash
# Mac Mini SSH 설정 (집에서 설정)
MAC_MINI_HOST=192.168.1.122
MAC_MINI_USERNAME=hyungiahn
MAC_MINI_SSH_KEY=/Users/hyungiahn/.ssh/id_rsa
```

### 개발 환경별 작업

**외부에서 (VPN 환경):**
- ✅ 데이터베이스 구조 설계
- ✅ API 엔드포인트 개발
- ✅ SSH 수집기 코드 작성
- 🚧 프론트엔드 개발

**집에서 (로컬 네트워크):**
- SSH 키 설정 및 연결 테스트
- 실제 데이터 수집 테스트
- NAS API 연동
- 최종 통합 테스트

### 폴더 구조

```
src/
├── config/          # 설정 파일
├── controllers/     # 컨트롤러
├── collectors/      # 데이터 수집기 (SSH, API 연동)
├── middleware/      # 미들웨어
├── models/          # 데이터베이스 모델
├── routes/          # 라우터
├── services/        # 비즈니스 로직
├── utils/           # 유틸리티
└── app.js           # 메인 애플리케이션
```

### 스크립트

```bash
npm run dev          # 개발 서버 실행
npm run test         # 테스트 실행
npm run lint         # 코드 검사
npm run db:migrate   # 데이터베이스 마이그레이션
```

### 로그 확인

```bash
# Docker 컨테이너 로그
docker-compose logs -f api

# 로컬 로그 파일
tail -f logs/combined.log
```

## 🐳 Docker 관리

### 기본 명령어

```bash
# 모든 서비스 시작
docker-compose up -d

# 특정 서비스만 시작
docker-compose up -d mariadb redis

# 로그 확인
docker-compose logs -f

# 컨테이너 상태 확인
docker-compose ps

# 서비스 중지
docker-compose down

# 볼륨까지 삭제 (주의: 데이터 손실)
docker-compose down -v
```

### 개별 서비스 관리

```bash
# API 서버 재시작
docker-compose restart api

# 데이터베이스 백업
docker exec home_mariadb mysqldump -u homeuser -pmac_mini_home_password home_management > backup.sql

# 데이터베이스 복원
docker exec -i home_mariadb mariadb -u homeuser -pmac_mini_home_password home_management < backup.sql
```

## 🔍 문제 해결

### 데이터베이스 연결 오류

```bash
# MariaDB 컨테이너 상태 확인
docker-compose ps mariadb

# 데이터베이스 로그 확인
docker-compose logs mariadb

# 컨테이너 재시작
docker-compose restart mariadb

# 데이터베이스 연결 테스트
docker exec home_mariadb mariadb -u homeuser -pmac_mini_home_password home_management -e "SELECT 1"
```

### 포트 충돌

현재 사용 중인 포트들:
- **API**: 9306
- **MariaDB**: 9305  
- **phpMyAdmin**: 9304
- **Redis**: 9307

포트가 사용 중인 경우 확인:

```bash
# 포트 사용 확인
lsof -i :9306
lsof -i :9305

# 충돌하는 Docker 컨테이너 확인
docker ps --filter "publish=9306"
```

### API 서버 문제

```bash
# API 서버 로그 확인
docker-compose logs -f api

# API 헬스체크
curl -v http://localhost:9306/health

# Tapo 라이브러리 설치 확인
docker exec home_api npm list tp-link-tapo-connect
```

## 📈 모니터링

### phpMyAdmin으로 데이터베이스 모니터링

1. http://localhost:9304 접속
2. Server: `mariadb`
3. Username: `homeuser`
4. Password: `mac_mini_home_password`

### API 성능 모니터링

```bash
# API 응답 시간 테스트
time curl http://localhost:9306/api/devices

# 부하 테스트 (Apache Bench)
ab -n 1000 -c 10 http://localhost:9306/api/devices

# 데이터베이스 상태 확인
curl http://localhost:9306/api/devices | jq '.count'
```

## 🔐 보안

- JWT 기반 인증 (추후 구현)
- 비밀번호 bcrypt 해싱
- API 요청 제한 (Rate Limiting)
- 입력 데이터 검증

## 📝 라이센스

MIT License

## 🤝 기여하기

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📞 지원

문제가 있으시면 [Issues](https://git.hyungi.net/hyungi/myhome-server/issues)에 등록해주세요.