4b77086bb2
- Express.js 기반 백엔드 API 서버 - MariaDB, Redis, phpMyAdmin Docker 환경 - Device 관리 기본 CRUD 구현 - Mac Mini M4 Pro 전용 설정 및 배포 스크립트 - 자동화된 설치 및 배포 시스템 - 완전한 문서화 및 실행 가이드
270 lines
6.2 KiB
Markdown
270 lines
6.2 KiB
Markdown
# 홈 관리 시스템 (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. 저장소 클론
|
|
|
|
```bash
|
|
git clone https://git.hyungi.net/hyungi/myhome-server.git
|
|
cd myhome-server
|
|
```
|
|
|
|
### 2. Mac Mini 자동 설정
|
|
|
|
```bash
|
|
# 실행 권한 부여
|
|
chmod +x scripts/setup-mac-mini.sh
|
|
|
|
# 자동 설정 실행
|
|
./scripts/setup-mac-mini.sh
|
|
```
|
|
|
|
### 3. 수동 설정 (선택사항)
|
|
|
|
```bash
|
|
# Mac Mini 전용 Docker Compose 사용
|
|
docker-compose -f docker-compose.mac-mini.yml up -d
|
|
```
|
|
|
|
### 4. 수동 배포
|
|
|
|
```bash
|
|
# 배포 스크립트 사용
|
|
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
|
|
|
|
### 헬스체크
|
|
|
|
```bash
|
|
# 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 # 디바이스 삭제
|
|
```
|
|
|
|
### 기본 사용 예제
|
|
|
|
```bash
|
|
# 디바이스 목록 조회
|
|
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 # 메인 애플리케이션
|
|
```
|
|
|
|
### 스크립트
|
|
|
|
```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 명령어 (Mac Mini)
|
|
|
|
```bash
|
|
# 모든 서비스 시작 (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
|
|
```
|
|
|
|
## 🔍 문제 해결
|
|
|
|
### 데이터베이스 연결 오류
|
|
|
|
```bash
|
|
# 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`에서 포트를 변경하세요:
|
|
|
|
```yaml
|
|
ports:
|
|
- "3001:3000" # 3001로 변경
|
|
```
|
|
|
|
### Mac Mini 네트워크 접근 문제
|
|
|
|
```bash
|
|
# 방화벽 확인
|
|
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 성능 모니터링
|
|
|
|
```bash
|
|
# 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](https://git.hyungi.net/hyungi/myhome-server/issues)에 등록해주세요. |