Skip to content

README-ko.md

Latest commit

 

History

History
246 lines (192 loc) · 10.9 KB

README-ko.md

File metadata and controls

246 lines (192 loc) · 10.9 KB
AIMeter logo

AIMeter

AIMeter는 AI provider 사용량, quota, 이력 추세를 추적하는 self-hosted 대시보드입니다.

React Express TypeScript Runtime Providers Deploy Deploy

AIMeter dashboard
AIMeter usage history AIMeter endpoint AIMeter settings

주요 기능

  • React 프론트엔드 대시보드
  • Express 백엔드 API
  • 다중 provider 어댑터 아키텍처
  • 런타임 모드: node, serverless
  • 데이터베이스 기반 저장소 및 bootstrap 흐름
  • 여러 AI provider를 위한 통합 대시보드
  • provider 자격 증명 관리 및 quota 표시
  • 사용량 이력 및 차트 페이지
  • endpoint/proxy 관련 API 페이지
  • bootstrap + admin 라우트 초기화 플로우
  • DB 엔진 지원: sqlite, d1, postgres, mysql

지원 Provider

Aliyun
Aliyun 		Antigravity
Antigravity 		Claude
Claude 		Codex
Codex 		Kimi
Kimi 		MiniMax
MiniMax
z.ai
z.ai 		Copilot
Copilot 		OpenRouter
OpenRouter 		Ollama
Ollama 		OpenCode
OpenCode 		Cursor
Cursor
provider별 예제 및 통합 노트: [docs/providers](../providers)

기술 스택

  • Frontend: React 18, TypeScript, Vite, Tailwind CSS
  • Backend: Node.js, Express, TypeScript
  • Storage: SQLite / Cloudflare D1 / PostgreSQL / MySQL

프로젝트 구조

.
├─ src/                  # 프론트엔드 앱
├─ server/               # 백엔드 API, 인증, 작업, 저장소
├─ deploy/               # 플랫폼별 배포 가이드
├─ docs/                  # API 문서, provider 예제, 번역, 설정 문서
├─ config.all.yaml       # 전체 구성 템플릿
├─ config.yaml           # 활성 로컬 구성(복사해서 생성)
└─ .env.all              # 전체 환경 변수 템플릿

빠른 시작

옵션 1: 컨테이너 (Docker)

nginx + Node.js 단일 컨테이너 배포. 데이터는 볼륨 마운트로 영속화됩니다.

mkdir -p ~/aimeter/db ~/aimeter/log
docker run -d --name aimeter \
  -p 3000:3000 \
  -e AIMETER_DATABASE_ENGINE=sqlite \
  -e AIMETER_DATABASE_CONNECTION=/aimeter/db/aimeter.db \
  -e AIMETER_SERVER_PORT=3000 \
  -e AIMETER_BACKEND_PORT=3001 \
  -e AIMETER_RUNTIME_MODE=node \
  -v ~/aimeter/db:/aimeter/db \
  -v ~/aimeter/log:/aimeter/log \
  bugwz/aimeter:latest

접속: http://localhost:3000

Docker Compose, HTTPS, MySQL/PostgreSQL, 멀티아키텍처 빌드: deploy/container/README.md

옵션 2: Vercel

Serverless 배포. 외부 MySQL 또는 PostgreSQL 데이터베이스가 필요합니다.

DB 배포
MySQL Deploy with Vercel
PostgreSQL Deploy with Vercel

환경 변수 설정 및 bootstrap 완료 후, 외부 cron 서비스를 구성하여 /api/system/jobs/refresh를 5분마다 호출하세요.

Cron 설정 및 전체 가이드: deploy/vercel/README.md

옵션 3: Cloudflare Workers

Serverless 배포. Cloudflare D1, MySQL, PostgreSQL을 지원합니다.

Deploy to Cloudflare Workers

배포 후 데이터베이스 모드에 따라 환경 변수를 설정하세요:

모드 필수 환경 변수
D1 AIMETER_RUNTIME_MODE=serverless
AIMETER_SERVER_PROTOCOL=https
AIMETER_DATABASE_ENGINE=d1
AIMETER_DATABASE_CONNECTION=DB
MySQL AIMETER_RUNTIME_MODE=serverless
AIMETER_SERVER_PROTOCOL=https
AIMETER_DATABASE_ENGINE=mysql
AIMETER_DATABASE_CONNECTION=mysql://USER:PASSWORD@HOST:3306/DATABASE
PostgreSQL AIMETER_RUNTIME_MODE=serverless
AIMETER_SERVER_PROTOCOL=https
AIMETER_DATABASE_ENGINE=postgres
AIMETER_DATABASE_CONNECTION=postgres://USER:PASSWORD@HOST:5432/DATABASE?sslmode=require

Cron Triggers가 내장되어 있으며, wrangler.jsonc가 기본으로 5분마다 자동 갱신을 예약합니다.

D1 바인딩, Hyperdrive, 전체 설정 단계: deploy/cloudflare/README.md

스크립트

npm run dev            # 프론트엔드만
npm run start:server   # 백엔드만
npm run dev:all        # 프론트엔드 + 백엔드
npm run dev:mock:all   # 프론트엔드 + 백엔드 (mock 모드)
npm run build          # 타입 검사 및 프론트엔드 빌드
npm run preview        # 프론트엔드 빌드 미리보기
npm run cf:dev         # Cloudflare Workers 로컬 개발
npm run cf:deploy      # Cloudflare Workers 배포

구성

현재 구현의 구성 소스 및 우선순위:

  1. config.yaml (AIMETER_CONFIG_FILE 경로 지정 가능)
  2. 환경 변수
  3. 내장 기본값

중요 사항:

  • database.engine / AIMETER_DATABASE_ENGINE 필수
  • database.connection / AIMETER_DATABASE_CONNECTION 필수
  • serverless 모드에서는 스케줄러 비활성화
  • node 모드에서는 프로세스 내 스케줄러 자동 시작

필드 매핑 및 상세 설명:

배포

지원 배포 모드 및 링크:

API 문서

보안 노트

  • 데이터베이스 모드에서 세션 시크릿 및 암호화 관련 설정은 bootstrap 과정에서 시스템 저장소에 초기화되어 영속화됩니다.
  • AIMETER_CRON_SECRET 및 AIMETER_ENDPOINT_SECRET는 선택적 통합 시크릿이며, 설정 시 32자 강랜덤 값을 사용하세요.
  • 운영 환경에서는 AIMETER_SERVER_PROTOCOL=https를 설정해 더 엄격한 전송 보안 헤더를 활성화하세요.