인프라 아키텍처

Akan 앱은 로컬, 클라우드 클러스터, 또는 사용자와 장비 가까이에 있는 엣지 서버에서 실행될 수 있습니다. 같은 애플리케이션 코드를 여러 환경에 맞게 패키징할 수 있고, 인프라는 트래픽이 어디로 들어오고 서비스가 어디서 실행되며 데이터와 배포 작업이 어떻게 관리되는지를 결정합니다.

Local: 빠르게 개발하고 확인하는 개발자 PC 환경입니다. MVP 화면, 기능 프로토타입, 로컬 디버깅에 적합합니다.

Cloud Cluster: 팀 공용 환경과 운영에 가까운 워크로드를 위한 Kubernetes 기반 실행 환경입니다.

Edge: 매장, 키오스크, 로봇, 공장, 건물, 로컬 장비망 가까이에서 실행되는 현장 서버입니다.

Master: CI/CD, 환경 파일, 비밀값, 릴리스 자동화를 관리하는 배포 제어 영역입니다.

Infrastructure shape

어떤 구성을 선택할까?

인프라 이름보다 제품 상황에서 먼저 출발하세요. 작은 내부 도구, 팀 QA 환경, 매장 키오스크, 운영 서비스는 서로 다른 수준의 인프라가 필요합니다.

MVP 또는 기능 프로토타입: 먼저 로컬 개발을 사용합니다. 제품에 공용 데이터, 팀 테스트, 배포 자동화가 필요해질 때까지 구성을 작게 유지합니다.

팀 QA 또는 스테이징: debug 또는 develop 환경의 클라우드 배포를 사용해 팀이 같은 서비스를 함께 검증할 수 있게 합니다.

물리 현장 또는 장비망: 서비스가 매장, 키오스크, 공장, 건물, 로봇, 사설 장비망 가까이에서 동작해야 한다면 edge를 사용합니다.

본사와 지점 구조: 하이브리드 구성을 사용합니다. 클라우드 클러스터를 메인 서비스로 두고, 엣지 서버는 현장 실행, 프록시, 캐시성 역할을 담당합니다.

트래픽 흐름

인프라는 앱 내부의 비즈니스 코드를 바꾸지 않습니다. 대신 요청이 어떤 경로로 Akan 런타임에 도착할지를 결정합니다. 내 PC에서는 경로가 단순하고, 클라우드 클러스터에서는 구조화된 계층을 거치며, 엣지 서버가 있으면 현장별 경로가 추가될 수 있습니다.

Request paths

로컬 경로: 개발자는 localhost로 접속하고 Akan 개발 런타임에 거의 직접 연결됩니다. 화면을 만들고 비즈니스 흐름을 확인하기에 가장 빠른 경로입니다.

클라우드 경로: 사용자는 공개 도메인으로 들어옵니다. Kubernetes Ingress가 요청을 받고, Service가 적절한 앱 pod를 찾은 뒤, Akan 런타임이 실제 페이지나 API 응답을 처리합니다.

엣지 경로: 매장, 키오스크, 로봇, 로컬 장비망은 먼저 엣지 프록시에 연결될 수 있습니다. 엣지 쪽은 가까운 런타임 작업을 처리하거나 클라우드 서비스로 트래픽을 전달할 수 있습니다.

요청이 Akan App Runtime에 도착하면 런타임은 어떤 종류의 작업인지 분류합니다. 페이지 요청은 웹 페이지를 렌더링하고, API 요청은 signal/service 로직을 실행하며, 웹소켓 요청은 실시간 채널을 유지하고, 정적 파일은 파일로 응답합니다.

Page: 브라우저 사용자를 위한 SSR 또는 CSR 페이지 응답입니다.

API: signal과 service 로직을 통한 비즈니스 작업입니다.

WebSocket: 실시간 업데이트와 오래 유지되는 클라이언트 연결입니다.

Asset: 정적 파일, 클라이언트 번들, 이미지, 생성 산출물입니다.

핵심은 이렇습니다. 인프라는 앱 안의 비즈니스 동작을 바꾸는 것이 아니라 앱으로 들어오는 경로를 선택합니다. 로컬, 클라우드, 엣지 경로는 서로 다르게 보일 수 있지만 결국 모두 Akan 런타임에 작업을 전달합니다.

데이터베이스 모드

처음에는 single 모드로 시작하세요. 대부분의 서비스는 첫날부터 별도 데이터베이스 클러스터가 필요하지 않습니다. 실제 성능 한계, 큐 처리, 다중 인스턴스 운영 요구가 생기면 앱의 비즈니스 구조를 바꾸지 않고 multiple 또는 cluster 모드로 올리면 됩니다.

single 모드의 기본 데이터베이스는 SQLite이지만, 그렇다고 장난감 서비스용이라는 뜻은 아닙니다. WAL 모드를 기본 지원하기 때문에 SQLite의 실제 성능은 상당히 좋습니다. DAU 1만 명 이하의 웬만한 일반 서비스는 실제 사용 데이터가 병목을 증명하기 전까지 single 모드로도 충분한 경우가 많습니다.

single

MVP, 초기 내부 도구, 관리자 화면, 콘텐츠 사이트, 많은 중소규모 서비스의 출발점으로 가장 적합합니다.

데이터베이스: SQLite

큐 / PubSub: SQLite기반, Bun IPC 가속 처리

캐시: SQLite 기반 키-값 캐시

성능: WAL 모드 기준으로 DAU 약 1만 명 이하의 웬만한 제품에는 충분한 성능을 기대할 수 있습니다.

multiple

제품에 분리된 캐시, pub/sub, 큐성 작업, 더 현실적인 로컬 서비스 경계가 필요해질 때 사용합니다.

데이터베이스: libsql

큐 / PubSub: Redis

캐시: Redis

성능: 전체 클러스터형 저장소보다 가볍게 유지하면서 캐시와 백그라운드 작업을 분리할 수 있습니다.

cluster

릴리스 전에 로컬 동작을 운영 클러스터와 비슷하게 맞추고 싶거나 더 무거운 관계형 영속성이 필요할 때 사용합니다.

데이터베이스: Postgres

큐 / PubSub: Redis

캐시: Redis

성능: 가장 운영 환경에 가까운 로컬 모드입니다. 더 무거운 동시 처리와 클러스터 지향 검증에 적합합니다.

akan.config.ts

Local database commands

실용적인 기준은 이렇습니다. 막연히 더 안전해 보인다는 이유로 데이터베이스 모드를 올리지 마세요. Redis 기반 pub/sub, 분리된 큐/캐시 동작, 더 무거운 동시 쓰기, 운영과 비슷한 배포 검증이 실제로 필요해질 때까지 single을 유지하면 됩니다.

성장 단계

인프라는 처음부터 크게 시작할 필요가 없습니다. 비즈니스는 서버 하나와 컨테이너 하나로 시작하고, 트래픽과 안정성 요구, 현장 운영 요구가 커질 때 단계적으로 확장하면 됩니다.

Infrastructure growth

1. 싱글 서버

작은 제품, MVP, 내부 도구, 초기 관리자 화면은 서버 하나와 Akan 컨테이너 하나로 충분히 운영할 수 있습니다. 데이터베이스도 보통 single 모드면 충분합니다.

single server / single container / single mode

Akan 런타임의 싱글 컨테이너는 부팅 시 0.05 cpu/200MB RAM 사용하며, 실사용 시 0.5 cpu/0.5GB RAM 정도를 사용합니다. 데이터베이스, api서버, 웹서버, CSR페이지, 이미지 최적화, 캐시, 큐, 멀티스레드, 로드밸런싱 등을 모두 처리하는데, 놀랍지 않나요?

1. 싱글 서버

2. 싱글 서버 다중 컨테이너

트래픽은 늘었지만 서버 한 대로 아직 충분하다면 같은 서버 안에서 여러 컨테이너를 실행합니다. 더 강한 서버, 더 많은 컨테이너, multiple 또는 cluster 데이터베이스 모드로 올리는 수직 확장 단계입니다.

single server / multiple containers / multiple or cluster mode

Akan Runtime은 AKAN_REPLICA 환경변수 설정에 따라 여러 child 서버를 실행해 로드밸런싱을 진행합니다. 로드밸런싱 목적으로는 여러 런타임을 실행할 필요가 없고, 안정성 향상이 필요하다면 여러 런타임을 실행하면 됩니다.

2. 싱글 서버 다중 컨테이너

3. 클라우드 클러스터 확장

서버 한 대로 부족해지면 클라우드 클러스터로 이동합니다. 여러 서버에서 여러 컨테이너가 실행되고, cluster 모드로 데이터베이스/캐시 계층도 운영에 가까운 형태가 됩니다.

multiple servers / multiple containers / cluster mode

3. 클라우드 클러스터 확장

4. 클라우드와 분산 엣지

초대형 서비스는 3번 단계의 클라우드 클러스터를 유지한 채 그 아래에 엣지 서버들을 추가할 수 있습니다. 각 엣지 서버는 자체 Akan 런타임과 로컬 데이터베이스를 가지므로 매장, 공장, 로봇, 로컬 네트워크가 가까운 곳에서 데이터를 계산하고 저장하는 분산 캐시 계층처럼 동작할 수 있습니다.

cloud cluster / edge runtime per site / database per edge

4. 클라우드와 분산 엣지

실용적인 기준은 비즈니스가 요구할 때만 확장하는 것입니다. 작게 시작하고 실제 사용량을 측정한 뒤, 싱글 서버에서 다중 컨테이너, 클라우드 클러스터, 마지막으로 클라우드와 엣지 조합으로 이동하면 됩니다.