⚡ create-alloy-app 사용 가이드

설치 및 실행

# npx 캐시 제거 (항상 최신 버전 사용)
npx clear-npx-cache

# 프로젝트 생성
npx create-alloy-app my-project

또는 프로젝트 이름 없이 실행하면 대화형으로 물어봅니다:

npx create-alloy-app

질문 흐름 안내

1. 프로젝트 이름

? 프로젝트 이름 (my-alloy-app):

• 생성할 프로젝트 폴더 이름입니다.
• 명령어에 이름을 이미 입력했으면 건너뜁니다 (npx create-alloy-app my-project).
• 기본값: my-alloy-app

2. 프로젝트 타입

? 프로젝트 타입을 선택하세요
❯ Tera SSR — Bootstrap 5 서버 사이드 렌더링
  Vue3 SPA — Vue3 + Vite + Bootstrap 5 + vue-router
  API Only — REST API 전용 (뷰 없음)

| 타입 | 설명 | 적합한 경우 | |---|---|---| | Tera SSR | Rust 기반 서버 사이드 렌더링 (Jinja2 호환 문법) | 전통적 웹사이트, SEO 중요한 페이지 | | Vue3 SPA | Vue3 + Vite 프론트엔드 + Alloy 백엔드 | SPA 대시보드, 관리 패널 | | API Only | HTML 뷰 없음, REST API만 제공 | 모바일 앱 백엔드, 마이크로서비스 |

↑↓ 방향키로 선택, Enter로 확정. 기본값: Tera SSR

3. 서버 포트

? 서버 포트 (3000):

• Alloy 서버가 수신할 포트 번호
• 기본값: 3000
• 여러 프로젝트를 동시에 실행하려면 각각 다른 포트를 지정하세요 (예: 3001, 3002)

4. 트래픽 암호화

? 트래픽 암호화 사용 (Y/n):

• ON: 클라이언트-서버 간 데이터를 AES-256으로 암호화합니다.
  • WASM 클라이언트(AlloyClient)가 모든 API 요청/응답을 자동 암호화
  • WebSocket(AlloySocket)도 메시지 자동 암호화
• OFF: 평문 HTTP 통신 (개발/테스트용)
• 기본값: Tera/API → No, Vue3 → Yes

4-1. Master Secret (암호화 ON 시)

? Master Secret (32자) (자동 생성된 키):

• AES-256 암호화에 사용되는 비밀 키 (32바이트)
• Enter를 누르면 랜덤으로 자동 생성됩니다 (권장)
• ⚠️ 프로덕션에서는 반드시 고유한 키를 사용하세요

5. WebSocket

? WebSocket 사용 (Y/n):

• ON: 실시간 양방향 통신 활성화 (채팅, 알림, 라이브 대시보드 등)
• OFF: WebSocket 관련 코드가 프로젝트에서 제거됩니다
• 기본값: Yes

5-1. WebSocket 경로 (ON 시)

? WebSocket 경로 (/ws):

• 클라이언트가 WebSocket에 접속할 URL 경로
• 기본값: /ws → ws://localhost:3000/ws
• nginx 리버스 프록시 시 이 경로에 대해 WebSocket 업그레이드를 설정해야 합니다

6. 보안 설정

CORS

? CORS 활성화 (Y/n):

• ON: 다른 도메인에서의 API 요청을 허용합니다
• 프론트엔드와 백엔드가 다른 도메인인 경우 필수
• 기본값: Yes

XSS 방지

? 입력값 자동 이스케이프 (XSS 방지) (Y/n):

• ON: 모든 입력값에서 <script> 등 위험한 HTML 태그를 자동 이스케이프
• SQL Injection, XSS 공격 방어
• 기본값: Yes

Rate Limiting

? Rate Limiting (DDoS 방지) (y/N):

• ON: IP 기반으로 초당 요청 수를 제한합니다 (기본 100 RPS, 버스트 200)
• DDoS 방어 및 API 남용 방지
• 기본값: No (필요 시 alloy.conf에서 나중에 설정 가능)

7. 확인 및 생성

─── 프로젝트 설정 확인 ───
  이름:       my-project
  타입:       tera
  포트:       3000
  암호화:     ON
  WebSocket:  /ws
  CORS:       ON
  XSS 방지:   ON
  Rate Limit: OFF

? 이 설정으로 프로젝트를 생성하시겠습니까? (Y/n):

• Yes → 프로젝트 생성 시작
• No → 취소

생성 후 실행

개발 모드

cd my-project
npm run dev          # 서버 시작 (nodemon 자동 재시작)

Vue3의 경우 npm run dev가 Vite HMR + 서버를 동시에 시작합니다.

프로덕션 모드

npm start            # NODE_ENV=production으로 실행
# 또는
npm run pm2          # PM2로 백그라운드 실행
npm run pm2:stop     # 중지
npm run pm2:logs     # 로그 확인

Vue3 빌드 (프로덕션 배포 시)

npm run build:vue    # Vite 프로덕션 빌드
npm start            # 빌드된 에셋으로 서비스

주요 설정 파일

| 파일 | 설명 | |---|---| | src/alloy.conf | 서버/보안/DB/WS 등 전체 설정 | | src/app.js | 앱 진입점 (WebSocket 핸들러 포함) | | src/controllers/ | API 라우트 컨트롤러 | | ecosystem.config.cjs | PM2 설정 |

nginx 리버스 프록시 설정 (프로덕션)

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /ws {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

⚠️ WebSocket 경로를 /ws가 아닌 다른 경로로 변경한 경우, nginx의 location 블록도 해당 경로로 변경하세요.