maruadmin-agent 0.3.5

MaruAdmin Remote Server Management Agent

Raspberry Pi 설치 가이드

지원 모델 및 권장 사양

모델	RAM	OS	Python	Agent 용도	상태
Raspberry Pi 5	4GB/8GB	Bookworm	3.11	전체 기능	✅ 권장
Raspberry Pi 4	4GB/8GB	Bullseye/Bookworm	3.9/3.11	전체 기능	✅ 권장
Raspberry Pi 4	2GB	Bullseye	3.9	Agent 전용	⚠️ 제한적
Raspberry Pi 3	1GB	Bullseye+	3.9+	Agent 전용	⚠️ 제한적
Raspberry Pi 3	1GB	Stretch	3.5	-	❌ 미지원

빠른 시작

권장: OS 업그레이드 (Raspberry Pi 3/4)

# 현재 OS 버전 확인
cat /etc/os-release

# Raspbian 9 (Stretch) 이하는 업그레이드 필요
# Python 3.8+ 필요 (Bullseye 이상)

Raspberry Pi OS 업그레이드 방법:

1. 데이터 백업
2. Raspberry Pi Imager 다운로드
3. Raspberry Pi OS (64-bit) 선택 (Bookworm 권장)
4. SD 카드에 굽기
5. 재부팅 후 설치

옵션 1: PyPI 설치 (가장 간단)

# Python 3.8+ 필요 (Bullseye 이상)
sudo pip3 install maruadmin-agent

# 설정 파일 생성
sudo mkdir -p /etc/maruadmin
sudo nano /etc/maruadmin/agent.conf

# 서비스 설정 (install.sh 참고)

옵션 2: GitHub에서 로컬 설치 (권장)

# 1. Git으로 전체 저장소 클론
git clone https://github.com/dirmich/maruadmin.git
cd maruadmin/agent

# 2. 설치 스크립트 실행 (로컬 소스 자동 감지)
sudo ./install.sh

# 로컬 소스가 있으면 자동으로 PyPI 대신 로컬에서 설치됩니다

옵션 2: 원격 설치 (최신 OS만)

# Python 3.8+ 필요 (Bullseye 이상)
curl -fsSL https://raw.githubusercontent.com/dirmich/maruadmin/main/agent/install.sh | sudo bash

옵션 3: 수동 설치 (고급 사용자)

# 1. 저장소 클론
git clone https://github.com/dirmich/maruadmin.git
cd maruadmin/agent

# 2. 가상 환경 생성
sudo python3 -m venv /opt/maruadmin/venv

# 3. 의존성 설치
sudo /opt/maruadmin/venv/bin/pip install --upgrade pip
sudo /opt/maruadmin/venv/bin/pip install -r requirements.txt

# 4. Agent 설치
sudo /opt/maruadmin/venv/bin/pip install -e .

# 5. 설정 파일 복사
sudo mkdir -p /etc/maruadmin
sudo cp agent.conf.example /etc/maruadmin/agent.conf

# 6. Systemd 서비스 생성 (install.sh 참고)

Raspberry Pi 3 최적화

Swap 메모리 증설 (필수)

# 현재 Swap 확인
free -h

# Swap 크기 변경 (2GB 권장)
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile

# 다음 라인 수정:
# CONF_SWAPSIZE=2048

# 적용
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

# 확인
free -h

메모리 분할 조정

# GPU 메모리 최소화 (서버 전용)
sudo raspi-config
# Performance Options → GPU Memory → 16MB

# 또는 직접 수정
sudo nano /boot/config.txt
# gpu_mem=16

불필요한 서비스 비활성화

# Bluetooth 비활성화
sudo systemctl disable bluetooth
sudo systemctl stop bluetooth

# WiFi 비활성화 (유선 연결 사용 시)
sudo systemctl disable wpa_supplicant

# Desktop 환경 비활성화 (Lite 버전 권장)
sudo systemctl set-default multi-user.target

Docker 설치 (컨테이너 관리용)

# Docker 설치
curl -fsSL https://get.docker.com | sudo sh

# maruadmin 사용자를 docker 그룹에 추가
sudo usermod -aG docker maruadmin

# 재부팅 또는 재로그인
sudo reboot

# 확인
docker ps

문제 해결

Python 3.5 SSL 오류

SSLError: [SSL: SSLV3_ALERT_HANDSHAKE_FAILURE]

원인: Python 3.5는 최신 TLS를 지원하지 않음

해결: OS 업그레이드 (Bullseye 이상)

메모리 부족

MemoryError or system freezing

해결:

1. Swap 메모리 증설 (위 참고)
2. GPU 메모리 최소화
3. 불필요한 서비스 비활성화

성능 저하

Raspberry Pi 3 최적화:

• Agent만 실행 (Backend/Frontend는 다른 서버)
• Docker 컨테이너 수 제한 (2-3개)
• 모니터링 간격 증가 (60초 → 120초)

# /etc/maruadmin/agent.conf
monitor_interval = 120
heartbeat_interval = 60

네트워크 설정

고정 IP 설정 (권장)

# /etc/dhcpcd.conf 수정
sudo nano /etc/dhcpcd.conf

# 다음 추가 (예시):
interface eth0
static ip_address=192.168.1.100/24
static routers=192.168.1.1
static domain_name_servers=8.8.8.8 8.8.4.4

# 적용
sudo systemctl restart dhcpcd

SSH 활성화

# SSH 서비스 활성화
sudo systemctl enable ssh
sudo systemctl start ssh

# 공개키 추가 (Backend에서 생성된 키)
mkdir -p ~/.ssh
echo 'ssh-rsa AAAA...' >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
chmod 700 ~/.ssh

벤치마크 (참고)

작업	Pi 5 (8GB)	Pi 4 (4GB)	Pi 3 (1GB)
Agent 시작	~2초	~5초	~15초
하트비트	<1ms	~2ms	~5ms
컨테이너 목록	~50ms	~100ms	~200ms
메모리 사용	~50MB	~80MB	~120MB

FAQ

Q: Raspberry Pi 3에서 Backend도 실행 가능한가요? A: 가능하지만 권장하지 않습니다. Agent만 실행하세요.

Q: Docker 없이 사용 가능한가요? A: 가능합니다. 컨테이너 관리 기능만 비활성화됩니다.

Q: 여러 Raspberry Pi를 연결할 수 있나요? A: 가능합니다. 각 Pi에 Agent를 설치하고 다른 이름으로 등록하세요.

Q: 전력 소비는 어느 정도인가요? A: Pi 5 (5W), Pi 4 (3W), Pi 3 (2.5W) - Agent 실행 시

추가 리소스

• Raspberry Pi OS 다운로드
• Raspberry Pi 공식 문서
• Docker on Raspberry Pi
• MaruAdmin 메인 문서