초기 홈 관리 시스템 API 구현
- Express.js 기반 백엔드 API 서버 - MariaDB, Redis, phpMyAdmin Docker 환경 - Device 관리 기본 CRUD 구현 - Mac Mini M4 Pro 전용 설정 및 배포 스크립트 - 자동화된 설치 및 배포 시스템 - 완전한 문서화 및 실행 가이드
This commit is contained in:
Hyungi Ahn
270
README.md
Normal file
270
README.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# 홈 관리 시스템 (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)에 등록해주세요.
|
||||
Reference in New Issue
Block a user