IceWhaleTech/CasaOS 딥다이브
— 한 줄 설치로 내 집 서버를 개인 클라우드로 만드는 Go 마이크로서비스 OS

인터페이스 기반 서비스 레이어

service/service.go의 MyService는 모든 서비스 인터페이스를 담는 컨테이너다. SystemService, FileService 등을 인터페이스로 정의하고, 실제 구현체를 주입한다. 단위 테스트 시 mock 구현체로 교체할 수 있다.

// service/service.go 패턴
type Services interface {
    System()  SystemService
    File()    FileService
    Storage() StorageService
}

// 실제 사용: MyService.System().GetCpuPercent()

OpenAPI Code Generation (oapi-codegen)

YAML로 API를 먼저 설계하고, go generate로 서버 인터페이스를 자동 생성한다. 핸들러는 생성된 인터페이스를 구현하기만 하면 되므로, API 스펙과 구현이 언제나 일치한다.

// main.go 상단의 go:generate 지시자
//go:generate bash -c "mkdir -p codegen && go run github.com/deepmap/oapi-codegen/cmd/oapi-codegen \
  -generate types,server,spec -package codegen \
  api/casaos/openapi.yaml > codegen/casaos_api.go"

go:embed로 정적 파일 번들링

Swagger UI HTML과 설정 파일 샘플을 //go:embed로 바이너리에 포함시킨다. 배포 시 추가 파일 없이 단일 바이너리만 복사하면 된다.

// main.go
//go:embed api/index.html
_docHTML string

//go:embed api/casaos/openapi.yaml
_docYAML string

//go:embed build/sysroot/etc/casaos/casaos.conf.sample
_confSample string

systemd SD_NOTIFY 통합

go-systemd/daemon을 사용해 서비스 준비 완료를 systemd에 알린다. Type=notify로 설정된 systemd 유닛이 이 신호를 기다렸다가 "READY" 상태로 전환한다. 실제 서버 데몬 개발에 반드시 필요한 패턴이다.

gopsutil로 시스템 모니터링

shirou/gopsutil v3은 OS에 관계없이 CPU·메모리·디스크·네트워크 정보를 Go API로 읽는다. service/system.go에서 실전 사용법을 볼 수 있다.

// CPU 사용률, 메모리, 디스크, 네트워크 인터페이스 조회
cpu.Percent(0, false)
mem.VirtualMemory()
disk.Usage("/")
net.IOCounters(true)

Docker SDK (App-Management 서비스)

App-Management 서비스는 Go Docker SDK(docker/docker)를 사용해 컨테이너 이미지 풀, 컨테이너 생성·시작·중지·삭제를 프로그래밍 방식으로 제어한다. GUI 뒤에서 실제로는 Docker API 호출이 일어나는 구조다.

CasaOS 설치 후 앱 3개 띄우기 입문

Debian/Ubuntu VM이나 Raspberry Pi에 CasaOS를 설치하고, 앱스토어에서 Jellyfin(미디어 서버), Nextcloud(파일 동기화), AdGuard Home(광고 차단 DNS) 세 가지를 설치해 본다.

내장 Swagger UI로 API 직접 호출하기 초급

http://[기기IP]/doc/v2/casaos에 접속하면 Swagger UI가 뜬다. 헬스 체크 엔드포인트 GET /v2/casaos/health/services와 GET /v2/casaos/health/ports를 브라우저에서 직접 실행해 각 서비스의 상태를 확인한다.

gopsutil로 나만의 시스템 모니터 CLI 만들기 중급

CasaOS의 service/system.go를 참고해, Go로 CPU·RAM·디스크 사용량을 1초 간격으로 출력하는 CLI 도구를 작성한다. gopsutil v3 패키지를 직접 써 본다.

// 핵심 import
"github.com/shirou/gopsutil/v3/cpu"
"github.com/shirou/gopsutil/v3/mem"
"github.com/shirou/gopsutil/v3/disk"

Echo + OpenAPI로 나만의 미니 서비스 만들기 중상급

CasaOS 방식을 따라 openapi.yaml을 먼저 작성하고, oapi-codegen으로 Go 서버 코드를 생성한 뒤, Echo 프레임워크로 핸들러를 구현한다. 간단한 "메모장 API"(CRUD)를 만들고 SQLite + GORM으로 저장한다.

커스텀 CasaOS 앱 카드 만들기 고급

CasaOS 앱스토어에 없는 Docker 이미지를 CasaOS의 "커스텀 앱 설치" 기능으로 등록한다. docker-compose.yml을 작성하거나 UI의 커스텀 앱 양식을 채워 본인이 만든 LV.4 서비스를 컨테이너화해 CasaOS 대시보드에서 관리한다.