초기 홈 관리 시스템 API 구현

- Express.js 기반 백엔드 API 서버 - MariaDB, Redis, phpMyAdmin Docker 환경 - Device 관리 기본 CRUD 구현 - Mac Mini M4 Pro 전용 설정 및 배포 스크립트 - 자동화된 설치 및 배포 시스템 - 완전한 문서화 및 실행 가이드
2025-07-30 14:12:09 +09:00
commit 4b77086bb2
24 changed files with 3867 additions and 0 deletions
--- a/scripts/deploy-mac-mini.sh
+++ b/scripts/deploy-mac-mini.sh
@@ -0,0 +1,154 @@
+#!/bin/bash
+
+# Mac Mini 홈 관리 시스템 배포 스크립트
+
+set -e
+
+# 설정
+IMAGE_NAME="home-management-api"
+CONTAINER_NAME="home_api"
+BACKUP_DIR="/Users/hyungi/home-management-backups"
+LOG_FILE="/Users/hyungi/home-management-logs/deploy.log"
+COMMIT_HASH=${1:-"latest"}
+DEPLOYMENT_ID=${2:-$(date +%Y%m%d_%H%M%S)}
+
+# 로그 디렉토리 생성
+mkdir -p "$(dirname "$LOG_FILE")"
+mkdir -p "$BACKUP_DIR"
+
+echo "$(date): Mac Mini 배포 시작 - $DEPLOYMENT_ID (commit: $COMMIT_HASH)" | tee -a "$LOG_FILE"
+
+# 배포 상태 보고 함수
+function report_status() {
+    local status=$1
+    local message=$2
+    echo "$(date): [$status] $message" | tee -a "$LOG_FILE"
+    
+    # 향후 Gitea webhook으로 상태 보고 가능
+    # curl -s -X POST http://git.hyungi.net/api/deployments/update \
+    #      -H "Content-Type: application/json" \
+    #      -d "{\"deployment_id\": \"$DEPLOYMENT_ID\", \"status\": \"$status\", \"message\": \"$message\"}" || true
+}
+
+# 1. Git 최신 코드 가져오기
+report_status "pulling" "Git 최신 코드 가져오는 중"
+git fetch origin
+git reset --hard origin/main
+
+# 2. 현재 컨테이너 상태 확인 및 백업
+if docker ps -q -f name=$CONTAINER_NAME | grep -q .; then
+    echo "현재 실행 중인 컨테이너 백업 중..." | tee -a "$LOG_FILE"
+    BACKUP_TAG="backup-$(date +%Y%m%d-%H%M%S)"
+    docker commit $CONTAINER_NAME $IMAGE_NAME:$BACKUP_TAG
+    report_status "backing_up" "백업 생성: $BACKUP_TAG"
+    
+    # Graceful shutdown
+    echo "서비스 정리 중..." | tee -a "$LOG_FILE"
+    docker-compose -f docker-compose.mac-mini.yml down
+fi
+
+# 3. 새 이미지 빌드
+report_status "building" "Docker 이미지 빌드 중"
+docker-compose -f docker-compose.mac-mini.yml build --no-cache
+
+# 4. 데이터베이스 및 Redis 시작
+report_status "starting_db" "데이터베이스 서비스 시작 중"
+docker-compose -f docker-compose.mac-mini.yml up -d mariadb redis
+
+# 데이터베이스 연결 대기
+echo "데이터베이스 연결 대기 중..." | tee -a "$LOG_FILE"
+sleep 30
+
+# 5. 새 API 컨테이너 시작
+report_status "starting_api" "API 서버 시작 중"
+docker-compose -f docker-compose.mac-mini.yml up -d api phpmyadmin
+
+# 6. 헬스체크
+report_status "health_check" "헬스체크 수행 중"
+sleep 15
+
+HEALTH_CHECK_PASSED=false
+for i in {1..30}; do
+    if curl -f -s http://localhost:3000/health > /dev/null 2>&1; then
+        # API 기능 테스트
+        if curl -f -s http://localhost:3000/api/devices > /dev/null 2>&1; then
+            echo "$(date): 배포 성공!" | tee -a "$LOG_FILE"
+            report_status "success" "배포 완료"
+            HEALTH_CHECK_PASSED=true
+            
+            # 성공 시 시스템 정보 기록
+            echo "시스템 정보:" | tee -a "$LOG_FILE"
+            docker-compose -f docker-compose.mac-mini.yml ps | tee -a "$LOG_FILE"
+            
+            # 오래된 백업 이미지 정리 (7개 이상)
+            docker images | grep "$IMAGE_NAME:backup" | tail -n +8 | \
+                awk '{print $1":"$2}' | xargs -r docker rmi 2>/dev/null || true
+            
+            break
+        fi
+    fi
+    echo "서비스 시작 대기 중... ($i/30)" | tee -a "$LOG_FILE"
+    sleep 2
+done
+
+# 7. 실패시 롤백
+if [ "$HEALTH_CHECK_PASSED" = false ]; then
+    echo "$(date): 배포 실패! 롤백 진행 중..." | tee -a "$LOG_FILE"
+    report_status "rolling_back" "배포 실패, 롤백 중"
+    
+    docker-compose -f docker-compose.mac-mini.yml down
+    
+    # 최신 백업으로 롤백
+    LATEST_BACKUP=$(docker images | grep "$IMAGE_NAME:backup" | head -1 | awk '{print $2}')
+    if [ ! -z "$LATEST_BACKUP" ]; then
+        echo "백업 이미지로 롤백: $LATEST_BACKUP" | tee -a "$LOG_FILE"
+        
+        # 백업 이미지로 임시 컨테이너 실행
+        docker run -d \
+            --name $CONTAINER_NAME \
+            --network host \
+            --restart unless-stopped \
+            -v /Users/hyungi/home-management-logs:/app/logs \
+            -v /Users/hyungi/home-management-data:/app/data \
+            -e NODE_ENV=production \
+            -e DB_HOST=localhost \
+            -e REDIS_HOST=localhost \
+            $IMAGE_NAME:backup-$LATEST_BACKUP
+        
+        report_status "rolled_back" "롤백 완료: backup-$LATEST_BACKUP"
+    else
+        report_status "failed" "롤백 실패 - 백업 이미지 없음"
+    fi
+    
+    exit 1
+fi
+
+# 8. 배포 후 정리 작업
+echo "배포 후 정리 작업 중..." | tee -a "$LOG_FILE"
+
+# 시스템 상태 확인
+echo "=== 시스템 상태 ===" | tee -a "$LOG_FILE"
+docker-compose -f docker-compose.mac-mini.yml ps | tee -a "$LOG_FILE"
+
+echo "=== 디스크 사용량 ===" | tee -a "$LOG_FILE"
+df -h | tee -a "$LOG_FILE"
+
+echo "=== 메모리 사용량 ===" | tee -a "$LOG_FILE"
+docker stats --no-stream | tee -a "$LOG_FILE"
+
+# 네트워크 정보
+echo "=== 네트워크 정보 ===" | tee -a "$LOG_FILE"
+ifconfig | grep "inet " | grep -v 127.0.0.1 | tee -a "$LOG_FILE"
+
+echo "🎉 Mac Mini 배포 완료!"
+echo ""
+echo "📊 접속 정보:"
+echo "- API 서버: http://localhost:3000"
+echo "- phpMyAdmin: http://localhost:8080"
+echo ""
+echo "🔍 상태 확인:"
+echo "curl http://localhost:3000/health"
+echo ""
+echo "📝 로그 확인:"
+echo "tail -f $LOG_FILE"
+echo "docker-compose -f docker-compose.mac-mini.yml logs -f api" 
--- a/scripts/setup-db.sql
+++ b/scripts/setup-db.sql
@@ -0,0 +1,197 @@
+-- 홈 관리 시스템 데이터베이스 초기 설정
+
+-- 데이터베이스 생성 (Docker에서 자동 생성되므로 주석 처리)
+-- CREATE DATABASE home_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+-- USE home_management;
+
+-- 1. 디바이스 관리 테이블
+CREATE TABLE devices (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    device_id VARCHAR(50) UNIQUE NOT NULL,
+    name VARCHAR(100) NOT NULL,
+    device_type ENUM('server', 'nas', 'router', 'smart_plug', 'other') NOT NULL,
+    location VARCHAR(50),
+    ip_address VARCHAR(45),
+    mac_address VARCHAR(17),
+    power_rating_watts INT,
+    monitoring_enabled BOOLEAN DEFAULT TRUE,
+    metadata JSON,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    INDEX idx_device_id (device_id),
+    INDEX idx_type_enabled (device_type, monitoring_enabled)
+) ENGINE=InnoDB;
+
+-- 2. 전력 소비 데이터 테이블
+CREATE TABLE power_consumption (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    device_id VARCHAR(50) NOT NULL,
+    timestamp TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3),
+    watts DECIMAL(8,2) NOT NULL,
+    voltage DECIMAL(6,2),
+    current DECIMAL(6,3),
+    kwh_total DECIMAL(10,4),
+    metadata JSON,
+    INDEX idx_device_time (device_id, timestamp),
+    INDEX idx_timestamp (timestamp),
+    INDEX idx_watts (watts),
+    FOREIGN KEY (device_id) REFERENCES devices(device_id) ON DELETE CASCADE
+) ENGINE=InnoDB
+PARTITION BY RANGE (UNIX_TIMESTAMP(timestamp)) (
+    PARTITION p_2025_q1 VALUES LESS THAN (UNIX_TIMESTAMP('2025-04-01')),
+    PARTITION p_2025_q2 VALUES LESS THAN (UNIX_TIMESTAMP('2025-07-01')),
+    PARTITION p_2025_q3 VALUES LESS THAN (UNIX_TIMESTAMP('2025-10-01')),
+    PARTITION p_2025_q4 VALUES LESS THAN (UNIX_TIMESTAMP('2026-01-01')),
+    PARTITION p_future VALUES LESS THAN MAXVALUE
+);
+
+-- 3. 네트워크 트래픽 테이블
+CREATE TABLE network_traffic (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    device_mac VARCHAR(17) NOT NULL,
+    device_name VARCHAR(100),
+    timestamp TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3),
+    bytes_in BIGINT UNSIGNED NOT NULL,
+    bytes_out BIGINT UNSIGNED NOT NULL,
+    packets_in INT UNSIGNED,
+    packets_out INT UNSIGNED,
+    connection_count INT UNSIGNED,
+    metadata JSON,
+    INDEX idx_mac_time (device_mac, timestamp),
+    INDEX idx_timestamp (timestamp)
+) ENGINE=InnoDB;
+
+-- 4. 시스템 리소스 테이블
+CREATE TABLE system_resources (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    server_name VARCHAR(50) NOT NULL,
+    timestamp TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3),
+    cpu_percent DECIMAL(5,2),
+    memory_used_gb DECIMAL(6,2),
+    memory_total_gb DECIMAL(6,2),
+    disk_used_gb DECIMAL(8,2),
+    disk_total_gb DECIMAL(8,2),
+    network_io JSON,
+    temperature DECIMAL(4,1),
+    load_average JSON,
+    processes_count INT,
+    uptime_seconds BIGINT,
+    INDEX idx_server_time (server_name, timestamp)
+) ENGINE=InnoDB;
+
+-- 5. 서비스 상태 테이블
+CREATE TABLE service_status (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    service_name VARCHAR(50) NOT NULL,
+    server_name VARCHAR(50) NOT NULL,
+    timestamp TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3),
+    status ENUM('online', 'offline', 'degraded', 'maintenance') NOT NULL,
+    response_time_ms INT UNSIGNED,
+    cpu_usage DECIMAL(5,2),
+    memory_usage_mb INT,
+    error_message TEXT,
+    metadata JSON,
+    INDEX idx_service_time (service_name, timestamp),
+    INDEX idx_server_service (server_name, service_name),
+    INDEX idx_status (status, timestamp)
+) ENGINE=InnoDB;
+
+-- 6. 사용자 관리 테이블
+CREATE TABLE users (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    username VARCHAR(50) UNIQUE NOT NULL,
+    email VARCHAR(100) UNIQUE,
+    password_hash VARCHAR(255),
+    full_name VARCHAR(100),
+    role ENUM('admin', 'family', 'guest') DEFAULT 'family',
+    preferences JSON,
+    last_login TIMESTAMP NULL,
+    is_active BOOLEAN DEFAULT TRUE,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    INDEX idx_username (username),
+    INDEX idx_email (email),
+    INDEX idx_role (role)
+) ENGINE=InnoDB;
+
+-- 7. 알림 규칙 테이블
+CREATE TABLE alert_rules (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    name VARCHAR(100) NOT NULL,
+    description TEXT,
+    condition_type ENUM('threshold', 'change', 'pattern', 'custom') NOT NULL,
+    target_table VARCHAR(50) NOT NULL,
+    target_field VARCHAR(50) NOT NULL,
+    operator ENUM('>', '<', '>=', '<=', '=', '!=', 'contains') NOT NULL,
+    threshold_value DECIMAL(15,4),
+    time_window_minutes INT DEFAULT 5,
+    severity ENUM('info', 'warning', 'critical') DEFAULT 'warning',
+    notification_methods JSON,
+    is_active BOOLEAN DEFAULT TRUE,
+    cooldown_minutes INT DEFAULT 60,
+    last_triggered TIMESTAMP NULL,
+    created_by INT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (created_by) REFERENCES users(id),
+    INDEX idx_active (is_active),
+    INDEX idx_target (target_table, target_field)
+) ENGINE=InnoDB;
+
+-- 8. 알림 로그 테이블
+CREATE TABLE alert_logs (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    alert_rule_id INT NOT NULL,
+    triggered_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    trigger_value DECIMAL(15,4),
+    message TEXT,
+    severity ENUM('info', 'warning', 'critical') NOT NULL,
+    notification_sent BOOLEAN DEFAULT FALSE,
+    resolved_at TIMESTAMP NULL,
+    metadata JSON,
+    FOREIGN KEY (alert_rule_id) REFERENCES alert_rules(id) ON DELETE CASCADE,
+    INDEX idx_rule_time (alert_rule_id, triggered_at),
+    INDEX idx_severity (severity, triggered_at)
+) ENGINE=InnoDB;
+
+-- 기본 관리자 사용자 생성 (패스워드는 'admin123')
+INSERT INTO users (username, email, password_hash, full_name, role) VALUES
+('admin', 'admin@home.local', '$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewsF5ckPG6Y4TZsG', '시스템 관리자', 'admin'),
+('family', 'family@home.local', '$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewsF5ckPG6Y4TZsG', '가족 사용자', 'family');
+
+-- 기본 디바이스 등록
+INSERT INTO devices (device_id, name, device_type, location, monitoring_enabled) VALUES
+('mac_mini_m4', 'Mac Mini M4 Pro', 'server', '서재', TRUE),
+('ds1525plus', 'Synology DS1525+', 'nas', '서재', TRUE),
+('rt6600ax', 'Synology RT6600ax', 'router', '거실', TRUE);
+
+-- 기본 알림 규칙
+INSERT INTO alert_rules (name, description, condition_type, target_table, target_field, operator, threshold_value, severity, notification_methods, created_by) VALUES
+('높은 CPU 사용률', 'CPU 사용률이 80% 이상일 때 알림', 'threshold', 'system_resources', 'cpu_percent', '>', 80.0, 'warning', '["email"]', 1),
+('높은 전력 소비', '전력 소비가 평소보다 50% 이상 증가했을 때', 'change', 'power_consumption', 'watts', '>', 50.0, 'warning', '["email"]', 1),
+('서비스 다운', '서비스가 오프라인 상태일 때', 'threshold', 'service_status', 'status', '=', 'offline', 'critical', '["email", "push"]', 1);
+
+-- 성능 모니터링용 뷰
+CREATE VIEW device_power_summary AS
+SELECT 
+    d.device_id,
+    d.name,
+    d.device_type,
+    AVG(pc.watts) as avg_watts,
+    MAX(pc.watts) as max_watts,
+    COUNT(*) as reading_count,
+    MAX(pc.timestamp) as last_reading
+FROM devices d
+LEFT JOIN power_consumption pc ON d.device_id = pc.device_id
+WHERE d.monitoring_enabled = TRUE
+GROUP BY d.device_id, d.name, d.device_type;
+
+CREATE VIEW system_health_summary AS
+SELECT 
+    server_name,
+    AVG(cpu_percent) as avg_cpu,
+    AVG(memory_used_gb / memory_total_gb * 100) as avg_memory_pct,
+    AVG(disk_used_gb / disk_total_gb * 100) as avg_disk_pct,
+    MAX(timestamp) as last_update
+FROM system_resources
+WHERE timestamp >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
+GROUP BY server_name; 
--- a/scripts/setup-mac-mini.sh
+++ b/scripts/setup-mac-mini.sh
@@ -0,0 +1,99 @@
+#!/bin/bash
+
+# Mac Mini 홈 관리 시스템 설정 스크립트
+
+echo "🏠 Mac Mini 홈 관리 시스템 설정을 시작합니다..."
+
+# 필요한 디렉토리 생성
+echo "📁 데이터 디렉토리 생성 중..."
+mkdir -p /Users/hyungi/home-management-db
+mkdir -p /Users/hyungi/home-management-redis
+mkdir -p /Users/hyungi/home-management-data
+mkdir -p ./logs
+mkdir -p ./uploads
+
+# 권한 설정
+echo "🔐 권한 설정 중..."
+chmod 755 /Users/hyungi/home-management-db
+chmod 755 /Users/hyungi/home-management-redis
+chmod 755 /Users/hyungi/home-management-data
+chmod 755 ./logs
+chmod 755 ./uploads
+
+# Docker 이미지 빌드
+echo "🐳 Docker 이미지 빌드 중..."
+docker-compose -f docker-compose.mac-mini.yml build
+
+# 기존 컨테이너 정리
+echo "🧹 기존 컨테이너 정리 중..."
+docker-compose -f docker-compose.mac-mini.yml down -v
+
+# 데이터베이스와 Redis 먼저 시작
+echo "🗄️ 데이터베이스 서비스 시작 중..."
+docker-compose -f docker-compose.mac-mini.yml up -d mariadb redis
+
+# 데이터베이스 초기화 대기
+echo "⏳ 데이터베이스 초기화 대기 중 (60초)..."
+sleep 60
+
+# 데이터베이스 연결 테스트
+echo "🔍 데이터베이스 연결 테스트 중..."
+until docker exec home_mariadb mysql -u homeuser -pmac_mini_home_password -e "SELECT 1" > /dev/null 2>&1; do
+    echo "데이터베이스 연결 대기 중..."
+    sleep 5
+done
+
+echo "✅ 데이터베이스 연결 성공!"
+
+# phpMyAdmin 시작
+echo "🌐 phpMyAdmin 시작 중..."
+docker-compose -f docker-compose.mac-mini.yml up -d phpmyadmin
+
+# API 서버 시작
+echo "🚀 API 서버 시작 중..."
+docker-compose -f docker-compose.mac-mini.yml up -d api
+
+# 서비스 상태 확인
+echo "📊 서비스 상태 확인 중..."
+sleep 10
+
+# 헬스체크
+echo "🏥 헬스체크 수행 중..."
+for i in {1..30}; do
+    if curl -f http://localhost:3000/health > /dev/null 2>&1; then
+        echo "✅ API 서버가 정상적으로 시작되었습니다!"
+        break
+    fi
+    echo "API 서버 시작 대기 중... ($i/30)"
+    sleep 2
+done
+
+# 컨테이너 상태 출력
+echo "📋 컨테이너 상태:"
+docker-compose -f docker-compose.mac-mini.yml ps
+
+# 접속 정보 출력
+echo ""
+echo "🎉 Mac Mini 홈 관리 시스템 설정 완료!"
+echo ""
+echo "📊 접속 정보:"
+echo "- API 서버: http://localhost:3000"
+echo "- API 문서: http://localhost:3000/api"
+echo "- phpMyAdmin: http://localhost:8080"
+echo "  - 사용자: homeuser"
+echo "  - 비밀번호: mac_mini_home_password"
+echo ""
+echo "🔍 테스트 명령어:"
+echo "curl http://localhost:3000/health"
+echo "curl http://localhost:3000/api/devices"
+echo ""
+echo "📝 로그 확인:"
+echo "docker-compose -f docker-compose.mac-mini.yml logs -f api"
+echo ""
+
+# 네트워크 정보 확인
+echo "🌐 네트워크 정보:"
+ifconfig | grep "inet " | grep -v 127.0.0.1 | awk '{print "- " $2}'
+echo ""
+echo "💡 다른 기기에서 접속하려면 위 IP 주소를 사용하세요."
+echo "예: http://[IP]:3000"