myhome-server/README.md

홈 관리 시스템 (Home Management API)

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

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

🎯 주요 기능

• 디바이스 관리: 홈 IoT 기기 등록 및 모니터링
• 전력 소비 추적: 실시간 전력 데이터 수집 및 분석
• 네트워크 트래픽 모니터링: 디바이스별 네트워크 사용량 추적
• 시스템 리소스 모니터링: 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

🚀 빠른 시작 (Mac Mini)

1. 저장소 클론

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

2. Mac Mini 자동 설정

# 실행 권한 부여
chmod +x scripts/setup-mac-mini.sh

# 자동 설정 실행
./scripts/setup-mac-mini.sh

3. 수동 설정 (선택사항)

# Mac Mini 전용 Docker Compose 사용
docker-compose -f docker-compose.mac-mini.yml up -d

4. 수동 배포

# 배포 스크립트 사용
chmod +x scripts/deploy-mac-mini.sh
./scripts/deploy-mac-mini.sh

# 또는 직접 배포
git pull origin main
docker-compose -f docker-compose.mac-mini.yml up -d --build

📊 서비스 확인 (Mac Mini)

• API 서버: http://localhost:3000 (Mac Mini 로컬)
• API 서버: http://mac-mini-m4.local:3000 (네트워크 접근)
• phpMyAdmin: http://localhost:8080
• API 문서: http://localhost:3000/api

헬스체크

# Mac Mini 로컬에서
curl http://localhost:3000/health

# 다른 기기에서 (IP 주소는 실제 Mac Mini IP로 변경)
curl http://192.168.1.100:3000/health

📚 API 엔드포인트

디바이스 관리

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

기본 사용 예제

# 디바이스 목록 조회
curl http://localhost:3000/api/devices

# 새 디바이스 생성
curl -X POST http://localhost:3000/api/devices \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "test_device",
    "name": "테스트 디바이스",
    "device_type": "server",
    "location": "테스트실"
  }'

🗄️ 데이터베이스

접속 정보 (Mac Mini)

• Host: localhost (Mac Mini 로컬) / mac-mini-m4.local (네트워크)
• Port: 3306
• Database: home_management
• Username: homeuser
• Password: mac_mini_home_password

기본 데이터

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

• 관리자 계정: admin / admin123
• 가족 계정: family / admin123
• 기본 디바이스: Mac Mini M4 Pro, Synology DS1525+, RT6600ax

🔧 개발 가이드

폴더 구조

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

스크립트

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

로그 확인

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

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

🐳 Docker 명령어 (Mac Mini)

# 모든 서비스 시작 (Mac Mini 전용)
docker-compose -f docker-compose.mac-mini.yml up -d

# 특정 서비스만 시작
docker-compose -f docker-compose.mac-mini.yml up -d mariadb redis

# 로그 확인
docker-compose -f docker-compose.mac-mini.yml logs -f

# 컨테이너 상태 확인
docker-compose -f docker-compose.mac-mini.yml ps

# 서비스 중지
docker-compose -f docker-compose.mac-mini.yml down

# 볼륨까지 삭제 (주의: 데이터 손실)
docker-compose -f docker-compose.mac-mini.yml down -v

🔍 문제 해결

데이터베이스 연결 오류

# MariaDB 컨테이너 상태 확인
docker-compose -f docker-compose.mac-mini.yml ps mariadb

# 데이터베이스 로그 확인
docker-compose -f docker-compose.mac-mini.yml logs mariadb

# 컨테이너 재시작
docker-compose -f docker-compose.mac-mini.yml restart mariadb

# Mac Mini 재배포
./scripts/deploy-mac-mini.sh

포트 충돌

기본 포트가 사용 중인 경우 docker-compose.mac-mini.yml에서 포트를 변경하세요:

ports:
  - "3001:3000"  # 3001로 변경

Mac Mini 네트워크 접근 문제

# 방화벽 확인
sudo pfctl -s all

# 포트 사용 확인
lsof -i :3000

# 네트워크 인터페이스 확인
ifconfig

📈 모니터링

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

1. http://localhost:8080 접속 (Mac Mini에서)
2. Server: mariadb
3. Username: homeuser
4. Password: mac_mini_home_password

API 성능 모니터링

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

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

🔐 보안

• 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에 등록해주세요.