우분투 NAS 서버 시스템 문서

개발자 및 신입 주니어 개발자를 위한 시스템 문서
최종 업데이트: 2025-11-28

📋 목차

시스템 개요
서비스 구조
디렉터리 구조
스크립트 설명
자동화 작업
백업 시스템
보안 설정
작업 내역

시스템 개요

하드웨어

CPU: N100/N150
OS: Ubuntu Server (Linux)
용도: NAS + 개발 서버

저장소 구조

/dev/nvme0n1p2  (233GB)  - 시스템 디스크 (7% 사용)
/dev/sda1        (458GB)  - /mnt/HDD500GB (백업용)
/dev/sdb1        (916GB)  - /mnt/HDD1TB (데이터용)
/DATA            (1.6TB)  - MergerFS 통합 볼륨 (HDD500GB + HDD1TB)

주요 서비스

CasaOS: 홈 클라우드 OS (앱 관리)
Docker: 컨테이너 오케스트레이션
Nginx: 리버스 프록시 및 웹 서버
Samba: 파일 공유 서비스

서비스 구조

CasaOS 서비스

casaos.service - 메인 서비스
casaos-gateway.service - 게이트웨이 (포트: 동적 할당)
casaos-app-management.service - 앱 관리
casaos-local-storage.service - 로컬 스토리지
casaos-message-bus.service - 메시지 버스
casaos-user-service.service - 사용자 서비스

Docker 컨테이너

컨테이너명	이미지	포트	용도
nextcloud	bigbeartechworld/big-bear-nextcloud-with-smbclient:0.0.12	127.0.0.1:7580→80	클라우드 스토리지
big-bear-nextcloud-cron-1	bigbeartechworld/big-bear-nextcloud-with-smbclient:0.0.12	-	Nextcloud 크론 작업
db-nextcloud	postgres:14.2	5432	Nextcloud 데이터베이스
redis-nextcloud	redis:6.2.20	6379	Nextcloud 캐시
big-bear-portainer	portainer/portainer-ce:2.35.0-alpine	127.0.0.1:9443→9443	Docker 관리 UI
uptime-kuma	louislam/uptime-kuma:2	127.0.0.1:3001→3001	서비스 모니터링
adguard-home	adguard/adguardhome:v0.107.69	127.0.0.1:3002→80	DNS 필터링
stacknori_api	stacknori_web	8000	자동 매매 시스템 API
stacknori_db	postgres:16-alpine	5432	자동 매매 시스템 DB

Nginx 설정

casaos → CasaOS 웹 인터페이스
nextcloud → nextcloud.livbee.co.kr
portainer → portainer.livbee.co.kr
adguard → adguard.livbee.co.kr
uptime-kuma → uptime-kuma.livbee.co.kr
stacknori-api → stacknori API 프록시

디렉터리 구조

/home/iwh/
├── scripts/                    # 스크립트 모음
│   ├── utilities/              # 자주 사용하는 유틸리티 (25개)
│   ├── archive/                # 한 번 사용한 스크립트 (32개)
│   ├── backup_*.sh            # 백업 스크립트
│   └── restore_*.sh           # 복원 스크립트
├── docs/                       # 시스템 문서
│   ├── README.md              # 이 문서
│   ├── CHANGELOG.md           # 작업 내역 로그
│   └── SCRIPTS.md             # 스크립트 상세 설명
├── reports/                    # 보고서 파일
│   └── archive/                # 오래된 보고서 (자동 압축)
├── logs/                       # 로그 파일
│   └── automation/             # 자동화 스크립트 로그
├── stacknori/                  # 자동 매매 시스템 프로젝트
│   ├── runner/                 # GitHub Actions Runner
│   └── ...
└── .env_secrets                # 환경 변수 (비밀번호 등)

/mnt/
├── HDD500GB/                   # 백업 디스크
│   └── backups/                # 백업 파일 저장소
└── HDD1TB/                     # 데이터 디스크

/DATA/                          # MergerFS 통합 볼륨
└── AppData/                    # CasaOS 앱 데이터
    ├── big-bear-nextcloud/     # Nextcloud 데이터
    └── ...

/etc/
├── nginx/
│   ├── sites-available/        # Nginx 설정 파일
│   └── sites-enabled/          # 활성화된 설정 (심볼릭 링크)
└── logrotate.d/                # 로그 로테이션 설정

스크립트 설명

유틸리티 스크립트 (`~/scripts/utilities/`)

시스템 점검

full_system_refactoring_check_v2.sh - 시스템 전체 리팩토링 필요 사항 점검
보안, 리소스, 로그, 포트, 백업, 스크립트 관리 등 종합 점검

백업 관련

backup_sensitive_files.sh - 민감 정보 파일 백업 (GPG 암호화)
.env_secrets, .ssh/*, stacknori/.env 등
backup_env_secrets.sh - 환경 변수 파일 백업

정리 작업

cleanup_pip_cache.sh - pip 캐시 정리
cleanup_cursor_cache.sh - Cursor IDE 캐시 정리
cleanup_runner_cache.sh - GitHub Actions Runner 캐시 정리
cleanup_automation_logs.sh - 자동화 로그 정리 (30일 이상)
cleanup_archive_backups.sh - Archive 백업 파일 정리

기타

archive_reports.sh - 오래된 보고서 압축 아카이브 (14일 이상)
docker_cleanup_and_update.sh - Docker 리소스 정리 및 시스템 업데이트
remove_password_hardcoding.sh - 비밀번호 하드코딩 제거

백업 스크립트 (`~/scripts/`)

backup_all.sh - 전체 백업 마스터 스크립트
Nextcloud, PostgreSQL, Nginx, SSL 인증서 백업
backup_nextcloud.sh - Nextcloud 데이터 백업
backup_postgresql.sh - PostgreSQL 데이터베이스 백업
backup_nginx.sh - Nginx 설정 백업
backup_ssl.sh - SSL 인증서 백업
restore_nextcloud.sh - Nextcloud 데이터 복원
restore_postgresql.sh - PostgreSQL 데이터베이스 복원

Archive 스크립트 (`~/scripts/archive/`)

한 번 사용한 스크립트들 (32개) - Nextcloud 설정 관련 - Portainer 설정 관련 - DNS/SSL 설정 관련 - 시스템 초기 설정 관련

자동화 작업

Cron 작업 목록 (10개) (10개) (9개)

시간	주기	스크립트	설명
02:00	매일	`backup_all.sh`	전체 백업
03:00	매일	`backup_sensitive_files.sh`	민감 정보 백업
03:30	매일	`cleanup_runner_cache.sh`	Runner 캐시 정리
03:45	매일	`backup_env_secrets.sh`	환경 변수 백업
03:15	매주 일	`archive_reports.sh`	보고서 아카이브
04:00	매주 일	`cleanup_automation_logs.sh`	자동화 로그 정리
05:00	매주 일	`cleanup_archive_backups.sh`	Archive 백업 정리
06:00	매주 일	`cleanup_cursor_cache.sh`	Cursor 캐시 정리
07:00	매주 일	`cleanup_pip_cache.sh`	pip 캐시 정리

로그 위치

모든 자동화 스크립트 로그는 ~/logs/automation/ 디렉터리에 저장됩니다.

백업 시스템

백업 대상

Nextcloud 데이터: /DATA/AppData/big-bear-nextcloud/
PostgreSQL 데이터베이스: db-nextcloud 컨테이너
Nginx 설정: /etc/nginx/
SSL 인증서: /etc/letsencrypt/
민감 정보 파일: .env_secrets, .ssh/*, stacknori/.env 등

백업 저장 위치

/mnt/HDD500GB/backups/
nextcloud/ - Nextcloud 백업
postgresql/ - PostgreSQL 백업
nginx/ - Nginx 설정 백업
ssl/ - SSL 인증서 백업
env/ - 환경 변수 및 민감 정보 백업

백업 주기

전체 백업: 매일 02:00
민감 정보 백업: 매일 03:00 (GPG 암호화)
환경 변수 백업: 매일 03:45

보안 설정

SSH 보안

Root 로그인 비활성화 (PermitRootLogin no)
인증 시도 제한 (MaxAuthTries 3)
X11 포워딩 비활성화
빈 비밀번호 비활성화

방화벽 (UFW)

SSH 포트 (22): 내부 네트워크만 허용
IPv4: 192.168.0.0/24, 100.64.0.0/10
IPv6: fd7a:115c:a1e0::/48
Samba 포트: 내부 네트워크만 허용
Docker 서비스 포트: 127.0.0.1에만 바인딩 (외부 노출 차단)

포트 노출 최소화

모든 Docker 컨테이너는 127.0.0.1에만 바인딩되어 있으며, 외부 접근은 Nginx를 통해서만 가능합니다.

작업 내역

자세한 작업 내역은 CHANGELOG.md를 참고하세요.

주요 작업 요약

✅ CasaOS 설치 및 설정
✅ Nextcloud 설치 및 도메인 연결 (nextcloud.livbee.co.kr)
✅ Portainer 설치 및 도메인 연결 (portainer.livbee.co.kr)
✅ SSL 인증서 설정 (Certbot)
✅ 백업 시스템 구축
✅ SSH 보안 강화
✅ 스크립트 정리 및 자동화
✅ 포트 노출 최소화
✅ 로그 관리 시스템 구축

빠른 참조

자주 사용하는 명령어

# 시스템 점검
~/scripts/utilities/full_system_refactoring_check_v2.sh

# 전체 백업
~/scripts/backup_all.sh

# Docker 컨테이너 확인
docker ps

# CasaOS 서비스 상태 확인
systemctl status casaos

# Nginx 설정 테스트
sudo nginx -t

# 로그 확인
tail -f ~/logs/automation/backup_all.log

환경 변수

~/.env_secrets - sudo 비밀번호 등 환경 변수 저장
권한: 600 (소유자만 읽기/쓰기)

문의 및 지원

시스템 관련 문의사항이나 문제 발생 시: 1. ~/scripts/utilities/full_system_refactoring_check_v2.sh 실행하여 시스템 점검 2. ~/logs/automation/ 디렉터리에서 관련 로그 확인 3. ~/docs/CHANGELOG.md에서 최근 작업 내역 확인

문서 자동 업데이트: 이 문서는 ~/scripts/utilities/update_documentation.sh 스크립트에 의해 자동으로 업데이트됩니다.