초기 홈 관리 시스템 API 구현
- Express.js 기반 백엔드 API 서버 - MariaDB, Redis, phpMyAdmin Docker 환경 - Device 관리 기본 CRUD 구현 - Mac Mini M4 Pro 전용 설정 및 배포 스크립트 - 자동화된 설치 및 배포 시스템 - 완전한 문서화 및 실행 가이드
This commit is contained in:
Hyungi Ahn
271
README.mac-mini.md
Normal file
271
README.mac-mini.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# Mac Mini 홈 관리 시스템 실행 가이드
|
||||
|
||||
Mac Mini M4 Pro에서 홈 관리 시스템을 운영하기 위한 상세 가이드입니다.
|
||||
|
||||
## 🖥️ Mac Mini 환경 요구사항
|
||||
|
||||
- **Mac Mini M4 Pro** (64GB RAM 권장)
|
||||
- **macOS Sonoma 14.5+**
|
||||
- **Docker Desktop for Mac**
|
||||
- **Git**
|
||||
- **최소 50GB 여유 공간**
|
||||
|
||||
## 🚀 초기 설정
|
||||
|
||||
### 1. Docker Desktop 설치
|
||||
|
||||
```bash
|
||||
# Homebrew로 설치 (권장)
|
||||
brew install --cask docker
|
||||
|
||||
# 또는 Docker 공식 사이트에서 다운로드
|
||||
# https://www.docker.com/products/docker-desktop/
|
||||
```
|
||||
|
||||
### 2. 프로젝트 클론
|
||||
|
||||
```bash
|
||||
cd /Users/hyungi
|
||||
git clone https://git.hyungi.net/hyungi/myhome-server.git
|
||||
cd myhome-server
|
||||
```
|
||||
|
||||
### 3. 자동 설정 실행
|
||||
|
||||
```bash
|
||||
# 실행 권한 부여
|
||||
chmod +x scripts/setup-mac-mini.sh
|
||||
|
||||
# 설정 실행
|
||||
./scripts/setup-mac-mini.sh
|
||||
```
|
||||
|
||||
## 📁 Mac Mini 데이터 구조
|
||||
|
||||
```
|
||||
/Users/hyungi/
|
||||
├── myhome-server/ # 프로젝트 소스
|
||||
├── home-management-db/ # MariaDB 데이터
|
||||
├── home-management-redis/ # Redis 데이터
|
||||
├── home-management-data/ # 업로드 파일
|
||||
└── home-management-logs/ # 로그 파일
|
||||
└── deploy.log
|
||||
```
|
||||
|
||||
## 🌐 네트워크 설정
|
||||
|
||||
### Mac Mini IP 확인
|
||||
|
||||
```bash
|
||||
# 현재 IP 주소 확인
|
||||
ifconfig | grep "inet " | grep -v 127.0.0.1
|
||||
|
||||
# 또는
|
||||
ipconfig getifaddr en0
|
||||
```
|
||||
|
||||
### 방화벽 설정 (필요시)
|
||||
|
||||
```bash
|
||||
# 포트 3000 허용
|
||||
sudo pfctl -f /etc/pf.conf
|
||||
|
||||
# 또는 시스템 환경설정 > 보안 및 개인정보보호 > 방화벽
|
||||
```
|
||||
|
||||
## 🔄 배포 및 업데이트
|
||||
|
||||
### 자동 배포
|
||||
|
||||
```bash
|
||||
# 최신 코드로 배포
|
||||
./scripts/deploy-mac-mini.sh
|
||||
|
||||
# 특정 커밋으로 배포
|
||||
./scripts/deploy-mac-mini.sh [commit-hash]
|
||||
```
|
||||
|
||||
### 수동 배포
|
||||
|
||||
```bash
|
||||
# 코드 업데이트
|
||||
git pull origin main
|
||||
|
||||
# 서비스 재시작
|
||||
docker-compose -f docker-compose.mac-mini.yml up -d --build
|
||||
```
|
||||
|
||||
## 📊 모니터링 및 관리
|
||||
|
||||
### 서비스 상태 확인
|
||||
|
||||
```bash
|
||||
# 컨테이너 상태
|
||||
docker-compose -f docker-compose.mac-mini.yml ps
|
||||
|
||||
# 시스템 리소스
|
||||
docker stats
|
||||
|
||||
# 로그 확인
|
||||
tail -f /Users/hyungi/home-management-logs/deploy.log
|
||||
```
|
||||
|
||||
### 데이터베이스 관리
|
||||
|
||||
```bash
|
||||
# phpMyAdmin 접속
|
||||
open http://localhost:8080
|
||||
|
||||
# 직접 MySQL 접속
|
||||
docker exec -it home_mariadb mysql -u homeuser -p
|
||||
```
|
||||
|
||||
### 백업 관리
|
||||
|
||||
```bash
|
||||
# 데이터베이스 백업
|
||||
docker exec home_mariadb mysqldump -u homeuser -pmac_mini_home_password home_management > backup_$(date +%Y%m%d).sql
|
||||
|
||||
# 데이터 디렉토리 백업
|
||||
tar -czf home_management_backup_$(date +%Y%m%d).tar.gz /Users/hyungi/home-management-*
|
||||
```
|
||||
|
||||
## 🔧 성능 최적화
|
||||
|
||||
### Docker 설정 최적화
|
||||
|
||||
Docker Desktop > Settings > Resources:
|
||||
- **CPU**: 6-8 cores
|
||||
- **Memory**: 16-24GB
|
||||
- **Disk**: 100GB+
|
||||
|
||||
### MariaDB 최적화 (이미 적용됨)
|
||||
|
||||
```ini
|
||||
# config/mariadb.cnf
|
||||
innodb_buffer_pool_size = 4G
|
||||
innodb_log_file_size = 512M
|
||||
max_connections = 200
|
||||
```
|
||||
|
||||
## 🔐 보안 설정
|
||||
|
||||
### SSH 키 설정 (CI/CD용)
|
||||
|
||||
```bash
|
||||
# SSH 키 생성
|
||||
ssh-keygen -t ed25519 -C "mac-mini-home-server"
|
||||
|
||||
# 공개키를 Gitea에 등록
|
||||
cat ~/.ssh/id_ed25519.pub
|
||||
```
|
||||
|
||||
### 환경별 비밀키 관리
|
||||
|
||||
```bash
|
||||
# 프로덕션 환경 변수 (docker-compose.mac-mini.yml에 설정됨)
|
||||
JWT_SECRET=mac-mini-production-jwt-secret-key-2025
|
||||
DB_PASSWORD=mac_mini_home_password
|
||||
```
|
||||
|
||||
## 🚨 트러블슈팅
|
||||
|
||||
### 메모리 부족
|
||||
|
||||
```bash
|
||||
# Docker 메모리 사용량 확인
|
||||
docker system df
|
||||
|
||||
# 불필요한 이미지 정리
|
||||
docker system prune -a
|
||||
```
|
||||
|
||||
### 디스크 공간 부족
|
||||
|
||||
```bash
|
||||
# 오래된 백업 이미지 정리
|
||||
docker images | grep "backup" | tail -n +8 | awk '{print $1":"$2}' | xargs docker rmi
|
||||
|
||||
# 로그 로테이션
|
||||
sudo log config --mode "rotate"
|
||||
```
|
||||
|
||||
### 네트워크 접근 문제
|
||||
|
||||
```bash
|
||||
# 포트 점유 확인
|
||||
lsof -i :3000
|
||||
|
||||
# Docker 네트워크 재설정
|
||||
docker network prune
|
||||
```
|
||||
|
||||
## 📱 외부 접근 설정
|
||||
|
||||
### 홈 네트워크에서 접근
|
||||
|
||||
다른 기기에서 접근하려면:
|
||||
- **URL**: `http://[Mac Mini IP]:3000`
|
||||
- **예시**: `http://192.168.1.100:3000`
|
||||
|
||||
### 포트 포워딩 (라우터 설정)
|
||||
|
||||
외부 인터넷에서 접근하려면 라우터에서:
|
||||
1. 포트 3000을 Mac Mini IP로 포워딩
|
||||
2. DDNS 설정 (선택사항)
|
||||
|
||||
## 📈 성능 모니터링
|
||||
|
||||
### 시스템 메트릭
|
||||
|
||||
```bash
|
||||
# CPU 사용률
|
||||
top -l 1 | grep "CPU usage"
|
||||
|
||||
# 메모리 사용률
|
||||
vm_stat
|
||||
|
||||
# 디스크 I/O
|
||||
iostat 1
|
||||
```
|
||||
|
||||
### 애플리케이션 메트릭
|
||||
|
||||
```bash
|
||||
# API 응답 시간
|
||||
time curl http://localhost:3000/api/devices
|
||||
|
||||
# 데이터베이스 성능
|
||||
docker exec home_mariadb mysql -u homeuser -pmac_mini_home_password -e "SHOW PROCESSLIST;"
|
||||
```
|
||||
|
||||
## 🔄 정기 유지보수
|
||||
|
||||
### 일일 작업
|
||||
|
||||
- [ ] 시스템 상태 확인
|
||||
- [ ] 로그 모니터링
|
||||
- [ ] 백업 상태 확인
|
||||
|
||||
### 주간 작업
|
||||
|
||||
- [ ] 코드 업데이트 (git pull)
|
||||
- [ ] Docker 이미지 정리
|
||||
- [ ] 데이터베이스 백업
|
||||
|
||||
### 월간 작업
|
||||
|
||||
- [ ] 전체 시스템 백업
|
||||
- [ ] 성능 리포트 생성
|
||||
- [ ] 보안 업데이트 적용
|
||||
|
||||
## 📞 지원
|
||||
|
||||
문제 발생시:
|
||||
1. `/Users/hyungi/home-management-logs/deploy.log` 확인
|
||||
2. Docker 로그 확인: `docker-compose -f docker-compose.mac-mini.yml logs`
|
||||
3. GitHub Issues에 로그와 함께 문의
|
||||
|
||||
---
|
||||
|
||||
**Mac Mini M4 Pro의 성능을 최대한 활용하여 안정적인 홈 관리 시스템을 운영하세요! 🏠💻**
|
||||
Reference in New Issue
Block a user