스크립트 상세 설명

모든 스크립트의 상세 설명 및 사용법
최종 업데이트: 2026-06-30

📁 스크립트 디렉터리 구조

~/scripts/
├── nas/                    # IoT·HA·ProPresenter·Postgres ensure
│   ├── bin/                # 진입점 (lib/ 로 분할)
│   └── iot/, pro-presenter/, nextcloud/, db/, dns/, net/
├── network/dns/            # Tailscale Split DNS (dnsmasq)
├── nextcloud-maint/        # 일일 헬스체크·orchestrate (lib/)
├── (adsp-quiz removed)     # 2026-08-04 폐기 → ~/backup/archives/adsp-quiz-decommission-*
├── utilities/          # 자주 사용하는 유틸리티 (52개)
│   ├── weekly-digest/      # 주간 합본 메일·SSL/DuckDNS
│   ├── audit/              # nas-audit
│   ├── maint/, ssl/, docker/, dns/, cleanup/, docs/, systemd/
├── cleanup/                # 정리 정책 (reports/ 에 역사 MD)
├── lib/mailfmt/            # 메일 포맷 모듈
└── archive/                # 한 번 사용한 스크립트

~/backup/
├── bin/                # 백업·복원·민감정보 백업 실행 스크립트 (정본)
├── logs/               # 백업 계열 로그
├── archives/           # 스크립트·보고서 아카이브
├── snapshots/          # 설정 스냅샷(.bak, crontab 덤프 등)
├── secrets/            # OAuth JSON·planning .env 등
└── README.md           # 레이아웃 설명

cron: 서버 crond=UTC — crontab 각 줄에 KST 의도 시각 주석. (crontab -l 참고)

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

시스템 점검

`audit/nas-audit.sh` (호환: `full-system-refactoring-check-v2.sh`)

용도: 시스템 전체 리팩토링 필요 사항 점검

점검 항목: - 보안 관련 (비밀번호 하드코딩, 환경 변수 파일, SSH 설정, UFW 방화벽) - 시스템 리소스 (디스크 사용량, Docker 리소스, 메모리 사용량) - 로그 관리 (Logrotate 설정, 로그 파일 크기) - 포트 노출 (외부 노출 포트, Docker 포트 매핑) - 백업 시스템 (백업 스크립트, 백업 디렉터리, Cron 백업 작업) - 스크립트 관리 (스크립트 구조, 홈 디렉터리 스크립트) - 시스템 업데이트 (업데이트 가능한 패키지, 보안 업데이트) - 서비스 상태 (Docker 컨테이너, CasaOS 서비스)

사용법:

~/scripts/utilities/audit/nas-audit.sh
# 또는 호환 진입점:
~/scripts/utilities/full-system-refactoring-check-v2.sh

출력: 콘솔에 점검 결과 출력

백업 관련

`backup-sensitive-files.sh`

용도: 민감 정보 파일 백업 (GPG 암호화 지원)

백업 대상: - ~/.env_secrets - ~/stacknori/.env - ~/stacknori/runner/.env - ~/.ssh/id_rsa - ~/.ssh/id_ed25519 - ~/.ssh/config

저장 위치: /mnt/HDD500GB/backups/env/

GPG 암호화: USE_GPG=1 및 GPG_PASSPHRASE 설정 시 암호화

보관 기간: 최신 30개만 유지

사용법:

# 환경 변수 설정 (선택사항)
export USE_GPG=1
export GPG_PASSPHRASE="your_passphrase"

# 스크립트 실행
~/backup/bin/backup-sensitive-files.sh

Cron: 수동 실행 (일일 cron은 backup-env-secrets.sh로 통합)

`backup-env-secrets.sh`

용도: 환경 변수 파일 (~/.env_secrets) 백업

저장 위치: /mnt/HDD500GB/backups/env/

GPG 암호화: USE_GPG=1 및 GPG_PASSPHRASE 설정 시 암호화

사용법:

~/backup/bin/backup-env-secrets.sh

Cron: 매일 03:45 자동 실행

정리 작업

`cleanup-pip-cache.sh`

용도: pip 캐시 정리

기능: - 정리 전/후 캐시 크기 확인 - pip cache purge 실행 - 회수된 용량 로그 기록

로그: ~/logs/automation/cleanup_pip_cache.log

사용법:

~/scripts/utilities/cleanup/cleanup-pip-cache.sh

Cron: 매주 일요일 07:00 자동 실행

`cleanup-cursor-cache.sh`

용도: Cursor IDE 캐시 정리

정리 대상: - ~/.cursor-server/ 디렉터리 - ~/.cursor/projects/terminals/ 임시 파일 - 7일 이상 된 임시 파일

사용법:

~/scripts/utilities/cleanup/cleanup-cursor-cache.sh

Cron: 매주 일요일 06:00 자동 실행

`cleanup-runner-cache.sh`

용도: GitHub Actions Runner 캐시 정리

정리 대상: - ~/stacknori/runner/_work/ 디렉터리 - ~/stacknori/runner/_diag/ 로그 파일 (7일 이상)

사용법:

~/scripts/utilities/cleanup/cleanup-runner-cache.sh

Cron: 매일 03:30 자동 실행

`cleanup-automation-logs.sh`

용도: 자동화 로그 정리

정리 대상: ~/logs/automation/ 디렉터리의 30일 이상 된 로그 파일

사용법:

~/scripts/utilities/cleanup/cleanup-automation-logs.sh

Cron: 매주 일요일 04:00 자동 실행

`cleanup-archive-backups.sh`

용도: Archive 백업 파일 정리

정리 대상: ~/scripts/archive/ 디렉터리의 *.sh.backup.* 파일 (30일 이상)

사용법:

~/backup/bin/cleanup-archive-backups.sh

Cron: 매주 일요일 05:00 자동 실행

기타

`archive-reports.sh`

용도: 오래된 보고서 압축 아카이브

대상: ~/reports/ 디렉터리의 .md 파일 (14일 이상)

저장 위치: ~/reports/archive/ (gzip 압축)

사용법:

~/scripts/utilities/maint/archive-reports.sh

Cron: 매주 일요일 03:15 자동 실행

`docker-cleanup-and-update.sh`

용도: Docker 리소스 정리 및 시스템 업데이트

기능: - 사용하지 않는 Docker 이미지 정리 - 사용하지 않는 Docker 컨테이너 정리 - 사용하지 않는 Docker 볼륨 정리 - 사용하지 않는 Docker 네트워크 정리 - 시스템 패키지 업데이트

사용법:

~/scripts/utilities/docker-cleanup-and-update.sh

`remove-password-hardcoding.sh`

용도: 스크립트에서 비밀번호 하드코딩 제거

기능: - ~/scripts/utilities/ 디렉터리의 스크립트 검사 - 비밀번호 하드코딩 발견 시 [REDACTED]로 변경 - ~/.env_secrets 파일 사용 권장

사용법:

~/scripts/utilities/maint/remove-password-hardcoding.sh

💾 백업 스크립트 (`~/backup/bin/` — 정본)

백업 실행 파일은 ~/backup/bin/ 만 사용한다. ~/scripts/ 아래에는 백업용 링크·폴더를 두지 않는다.

`backup-all.sh`

용도: 슬림 일일 백업 마스터 (2026-06 정책)

백업 대상: 1. PostgreSQL dump (Nextcloud, IoT, pro-presenter, ADsP Quiz) 2. Nginx 설정 3. SSL 인증서 (KST 월요일만)

비활성: Nextcloud data 풀 tar (backup-nextcloud.sh)

사용법:

~/backup/bin/backup-all.sh

Cron: 매일 02:00 KST 자동 실행(crond는 UTC → 0 17 * * *)

로그: /mnt/HDD500GB/backups/backup.log

`backup-nextcloud.sh`

상태: [비활성] 슬림 정책(2026-06) — data 풀 tar 미사용

파일 복구는 Nextcloud 휴지통·버전. DB는 backup-postgresql.sh.

사용법 (no-op):

~/backup/bin/backup-nextcloud.sh   # SKIP 메시지 후 exit 0

`backup-adsp-quiz-postgresql.sh` (DISABLED)

용도: ~~ADsP Quiz PostgreSQL dump~~ — 2026-08-04 decommissioned

저장 위치: /mnt/HDD500GB/backups/postgresql/adsp-quiz/

사용법:

~/backup/bin/backup-adsp-quiz-postgresql.sh

`backup-postgresql.sh`

용도: PostgreSQL 데이터베이스 백업

백업 대상: db-nextcloud 컨테이너의 모든 데이터베이스

저장 위치: /mnt/HDD500GB/backups/postgresql/

파일명 형식: 스크립트 내 규칙 따름

사용법:

~/backup/bin/backup-postgresql.sh

`backup-nginx.sh`

용도: Nginx 설정 백업

백업 대상: /etc/nginx/

저장 위치: /mnt/HDD500GB/backups/nginx/

파일명 형식: nginx_backup_YYYYMMDD_HHMMSS.tar.gz

사용법:

~/backup/bin/backup-nginx.sh

`backup-ssl.sh`

용도: SSL 인증서 백업

백업 대상: /etc/letsencrypt/

저장 위치: /mnt/HDD500GB/backups/ssl/

파일명 형식: ssl_backup_YYYYMMDD_HHMMSS.tar.gz

사용법:

~/backup/bin/backup-ssl.sh

🔄 복원 스크립트 (`~/backup/bin/`)

`restore-nextcloud.sh`

용도: Nextcloud 데이터 복원

사용법:

# 복원할 백업 파일 선택
~/backup/bin/restore-nextcloud.sh

주의사항: 복원 전에 현재 데이터를 백업하는 것을 권장합니다.

`restore-postgresql.sh`

용도: PostgreSQL 데이터베이스 복원

사용법:

# 복원할 백업 파일 선택
~/backup/bin/restore-postgresql.sh

주의사항: 복원 전에 현재 데이터베이스를 백업하는 것을 권장합니다.

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

Archive 디렉터리에는 한 번 사용한 스크립트들이 보관되어 있습니다. (32개)

주요 카테고리: - Nextcloud 설정 관련 - Portainer 설정 관련 - DNS/SSL 설정 관련 - 시스템 초기 설정 관련

이 스크립트들은 참고용으로 보관되며, 필요시 수정하여 재사용할 수 있습니다.

🔐 환경 변수

`~/.env_secrets`

용도: 비밀번호 등 환경 변수 저장

내용:

export SUDO_PASSWORD="your_password"

권한: 600 (소유자만 읽기/쓰기)

주의: 이 파일은 절대 Git에 커밋하지 마세요!

📝 로그 파일

백업 계열(전체 백업 마스터 로그는 /mnt/HDD500GB/backups/backup.log): 민감정보·archive 정리 등은 ~/backup/logs/ (backup_env.log, backup_sensitive_files.log, cleanup_archive_backups.log 등).
그 외 자동화 로그: ~/logs/automation/ (archive_reports.log, cleanup_runner_cache.log, cleanup_automation_logs.log, cleanup_cursor_cache.log, cleanup_pip_cache.log 등).

🚀 스크립트 작성 가이드

새로운 스크립트를 작성할 때 다음 사항을 준수하세요:

헤더 주석: 스크립트 용도 및 사용법 명시
에러 처리: set -e 또는 적절한 에러 처리
로그 기록: 백업·복원·민감정보 스크립트는 ~/backup/logs/, 그 외 자동화는 ~/logs/automation/
비밀번호 하드코딩 금지: ~/.env_secrets 파일 사용
권한 설정: 실행 권한 부여 (chmod +x)

템플릿:

#!/bin/bash
# 스크립트 설명

set -e

LOG_FILE="$HOME/logs/automation/script_name.log"
mkdir -p "$(dirname "$LOG_FILE")"

echo "[$(date '+%Y-%m-%d %H:%M:%S')] 스크립트 시작" | tee -a "$LOG_FILE"

# 스크립트 내용

echo "[$(date '+%Y-%m-%d %H:%M:%S')] 스크립트 완료" | tee -a "$LOG_FILE"

문서 자동 업데이트: ~/scripts/utilities/docs/update-documentation.sh
백업 정본: ~/backup/bin/, 레이아웃은 ~/backup/README.md

🏠 NAS 운영 (`~/scripts/nas/`)

스크립트	용도
`bin/iot-stack-verify.sh`	IoT PWA·API·Postgres·무드·DNS·HTTPS 종합 검증
`bin/ensure-broadlink-indoor-sensors.sh`	RM4 mini 실내 온습도 HA 엔티티 자동 복구
`bin/ensure-adguard-home.sh`	AdGuard Home CasaOS 컨테이너·웹 UI 보장
`bin/install-adguard-home-systemd.sh`	AdGuard ensure timer 설치 (KST 15분)
`bin/ensure-iot-postgres.sh`	iot-postgres compose ensure
`bin/ha-google-assistant-sdk-setup.sh`	Google Assistant SDK OAuth (`~/.local/venvs/google-oauth`)
`iot/`, `pro-presenter/`	각 스택 ensure·배포 보조

100줄 초과 로직은 nas/bin/lib/ 에 분할 (iot-stack-verify-*.sh, broadlink-indoor-*.py 등).

🌐 네트워크 (`~/scripts/network/dns/`)

Tailscale Split DNS — dnsmasq 설정·ensure timer.
상세: ~/docs/guides/DNS-ARCHITECTURE.md
systemd: tailscale-dns-ensure.service / .timer

☁️ Nextcloud 유지보수 (`~/scripts/nextcloud-maint/`)

스크립트	용도
`daily-healthcheck.sh`	cron: KST 08:00·20:00 stale mount 자동 복구
`orchestrate.sh`	수동·디버그용 전체 점검 (주간 메일은 weekly-digest)
`lib/orchestrate-core.sh`	에이전트 실행·복구·알림 (orchestrate 본문)

📦 ADsP Quiz (decommissioned 2026-08-04)

Scripts/runtime removed. Archive: ~/backup/archives/adsp-quiz-decommission-20260804-094131/.

lib/ 주제별: common/, kuma/, ssl/, fw/, mon/, rm8000/, nginx/, systemd/

스크립트 상세 설명

📁 스크립트 디렉터리 구조

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

시스템 점검

audit/nas-audit.sh (호환: full-system-refactoring-check-v2.sh)

백업 관련

backup-sensitive-files.sh

backup-env-secrets.sh

정리 작업

cleanup-pip-cache.sh

cleanup-cursor-cache.sh

cleanup-runner-cache.sh

cleanup-automation-logs.sh

cleanup-archive-backups.sh

기타

archive-reports.sh

docker-cleanup-and-update.sh

remove-password-hardcoding.sh

💾 백업 스크립트 (~/backup/bin/ — 정본)

backup-all.sh

backup-nextcloud.sh

backup-adsp-quiz-postgresql.sh (DISABLED)

backup-postgresql.sh

backup-nginx.sh

backup-ssl.sh

🔄 복원 스크립트 (~/backup/bin/)

restore-nextcloud.sh

restore-postgresql.sh

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

🔐 환경 변수

~/.env_secrets

📝 로그 파일

🚀 스크립트 작성 가이드

🏠 NAS 운영 (~/scripts/nas/)

🌐 네트워크 (~/scripts/network/dns/)

☁️ Nextcloud 유지보수 (~/scripts/nextcloud-maint/)

📦 ADsP Quiz (decommissioned 2026-08-04)

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

`audit/nas-audit.sh` (호환: `full-system-refactoring-check-v2.sh`)

`backup-sensitive-files.sh`

`backup-env-secrets.sh`

`cleanup-pip-cache.sh`

`cleanup-cursor-cache.sh`

`cleanup-runner-cache.sh`

`cleanup-automation-logs.sh`

`cleanup-archive-backups.sh`

`archive-reports.sh`

`docker-cleanup-and-update.sh`

`remove-password-hardcoding.sh`

💾 백업 스크립트 (`~/backup/bin/` — 정본)

`backup-all.sh`

`backup-nextcloud.sh`

`backup-adsp-quiz-postgresql.sh` (DISABLED)

`backup-postgresql.sh`

`backup-nginx.sh`

`backup-ssl.sh`

🔄 복원 스크립트 (`~/backup/bin/`)

`restore-nextcloud.sh`

`restore-postgresql.sh`

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

`~/.env_secrets`

🏠 NAS 운영 (`~/scripts/nas/`)

🌐 네트워크 (`~/scripts/network/dns/`)

☁️ Nextcloud 유지보수 (`~/scripts/nextcloud-maint/`)