KevinLiss/ApeAdmin

Apeadmin 面向现代AI应用打造的Python后台管理框架，基于 FastAPI+Vue3 设计100%开源，内置 RBAC 权限管控、审计日志等企业级基础能力。框架集成 MCP‑SSE 网关，具备强大插件生态完整，帮助开发者快速搭建兼具业务管理与 AI 工具输出能力的应用。

ApeAdmin – 현대의 AI 애플리케이션을 위한 오픈소스 관리 플랫폼

무엇인가요 – ApeAdmin은 AI 기반 서비스를 호스팅하기 위해 설계된 풀스택 플러그인 지원 관리 프레임워크입니다. FastAPI 백엔드와 Vue 3 프론트엔드를 결합하고, MCP-SSE 게이트웨이를 추가하여 관리 기능(RBAC, 플러그인, 로그 등)을 AI 에이전트가 함수 호출로 사용할 수 있는 도구 로 노출합니다. 요약하면, 독립적인 Python 플러그인으로 확장 가능하고 인간 운영자와 LLM 에이전트 모두가 접근할 수 있는 "백엔드 as a service"를 제공합니다.

핵심 기능

카테고리	제공되는 기능
설치 워즈드	WordPress 스타일의 3단계 설정(DB 설정 → 사이트 및 관리자 → 완료). MySQL 데이터베이스 자동 생성, JWT 시크릿 생성, 재실행을 방지하기 위한 잠금 파일 작성.
RBAC	다섯 테이블 모델(사용자, 역할, 메뉴, 부서, 연결). 네 레이어 권한 검사(비로그인 → 인증 없음 → 규칙 → 데이터 범위) 및 버튼 수준 숨김을 위한 프론트엔드 `v-permission` 지시자.
플러그인 시스템	`importlib`를 통한 Python 패키지 플러그인 탐지. 핫로드/언로드, Docker 격리 배포, ZIP 업로드, 온라인 플러그인 마켓플레이스 지원. 플러그인은 라우트, MCP 도구, 이벤트 리스너 등록 가능.
MCP-SSE 게이트웨이	내부 관리 API를 도구/자원/프롬프트 템플릿으로 변환하여 LLM 에이전트가 호출할 수 있도록 합니다. JSON-Schema는 함수 시그니처에서 자동 생성되며, RBAC 필터링 및 일회성 티켓과 30초 타임아웃으로 보호됩니다. 모든 호출은 감사 기록됩니다.
AI 챗 어시스턴트	OpenAI, DeepSeek, Alibaba Tongyi, Zhipu GLM 또는 어떤 OpenAI 호환 엔드포인트도 지원. 스트리밍 SSE 출력, 마크다운 렌더링, 최대 5라운드의 도구 호출 루프 지원. 모델 키는 Fernet으로 암호화 저장.
감사 및 모니터링	Request-ID 미들웨어, 작업 로그, API별 지연 시간 추적, 검색 가능한 감사 로그.
데이터베이스 유연성	빠른 로컬 개발용 SQLite, 본격적인 생산 환경용 MySQL. `DB_TYPE`을 통해 자동 드라이버 전환. 선택적 Redis 캐시는 메모리 내 저장소로의 부드러운 팔백 지원.

아키텍처 개요

apeadmin/
  backend/          # FastAPI (async SQLAlchemy, Alembic 마이그레이션)
    src/
      api/          # REST 엔드포인트 (인증, 사용자, 역할, 플러그인, AI 챗…)
      core/         # 설정, 보안 (JWT + bcrypt), 미들웨어, 시드 데이터
      crud/         # RBAC 훅이 있는 일반적인 CRUD
      db/           # 엔진 및 세션 처리
      models/       # ORM 정의 (rbac, 플러그인, AI, MCP 로그)
      mcp/          # MCP 매니저, 라우트, 내장 도구
      plugins/      # 플러그인 인터페이스, 매니저, 내장 예제
      ai/           # 에이전트 오케스트레이션, 함수 호출 루프
      schemas/      # Pydantic 요청/응답 모델
      main.py       # 앱 진입점 (라이프사이클, 설정 모드)
  frontend/         # Vue 3 + Vite + TypeScript + Element Plus UI
    src/
      api/          # 모든 백엔드 라우트용 Axios 래퍼
      components/   # 헤더, 사이드바 등
      directives/   # `v-permission`
      router/       # 백엔드 메뉴 트리에서 동적으로 생성된 라우트
      stores/       # Pinia 스토어 (사용자, 메뉴, 권한)
      views/        # 페이지 (로그인, 시스템 관리, 플러그인 마켓, AI 챗…)

설계 원칙은 "설치하고 실행" 입니다. 구성되지 않은 인스턴스는 /setup로 리디렉션하고 .env 파일을 작성, 테이블을 생성한 후 일반적인 멀티테넌트 관리 시스템처럼 동작합니다.

누구에게 적합한가?

시나리오	ApeAdmin이 도움이 되는 이유
AI SaaS 플랫폼	데이터 조회, 사용자 관리, 사용자 정의 비즈니스 로직 등의 내부 도구를 별도 API를 작성하지 않고 LLM 에이전트에 공개할 수 있습니다.
기업 내부 도구	사용자, 부서, 사용자 정의 플러그인을 관리할 수 있는 권한 기반 UI를 빠르게 구축하면서도 단일 진실의 소스를 유지할 수 있습니다.
플러그인 생태계	팀은 독립적인 Python 플러그인(예: 데이터 커넥터, 모델 래퍼)을 개발할 수 있으며, 자동 탐지 및 핫로드가 가능해 핵심 시스템은 안정적으로 유지됩니다.
빠른 프로토타이핑	SQLite 개발 모드와 3단계 워즈드를 사용해 몇 분 안에 기능적인 관리 패널을 실행할 수 있습니다.

시작하기 (빠른 시작)

백엔드

cd backend
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

프론트엔드

cd frontend
npm install --legacy-peer-deps
npm run dev   # http://localhost:5173 에서 제공

URL을 열면 설정이 누락된 것을 감지하고 설치 워즈드를 시작합니다. SQLite(제로 설정)를 선택하거나 MySQL 인스턴스에 연결할 수 있습니다.
설치 후 정의한 관리자 자격 정보로 로그인한 후 다음을 탐색하세요:
- 시스템 → 사용자 / 역할 / 메뉴 / 부서
- 플러그인 → 마켓플레이스, ZIP 업로드, 활성/비활성
- MCP → 도구 / 자원 / 프롬프트 템플릿
- AI → 모델 API 키 추가 및 등록된 도구를 호출할 수 있는 채팅 세션 시작

본격적인 환경에서는 deploy/DEPLOY.md에 있는 Docker/Nginx 스크립트를 따르세요.

기술 스택

레이어	기술
백엔드	FastAPI, async SQLAlchemy 2.0, Alembic, Pydantic-Settings, JWT, bcrypt
프론트엔드	Vue 3.5, Vite 6, TypeScript 5.7, Element Plus 2.9, Pinia, ECharts
데이터베이스	MySQL (`aiomysql` 경유) 또는 SQLite (`aiosqlite`)
캐시	Redis (옵션)
AI 통합	Server-Sent Events 기반 MCP (Model Context Protocol), OpenAI 호환 엔드포인트 지원
패키징	MIT 라이선스, 백엔드는 pip 편집 가능 설치, 프론트엔드는 npm

라이선스 및 커뮤니티

라이선스: MIT – 상용 및 비상용 모두 자유롭게 사용 가능.
커뮤니티: 공식 웹사이트, 플러그인 마켓플레이스, 문서 포털, WeChat 사용자 그룹(리포지토리 내 QR 코드 참조). 기여는 표준적인 fork-branch-PR 워크플로우를 따르며 명확한 브랜치 명명 규칙이 있습니다.

TL;DR

ApeAdmin은 플러그인 우선, AI 인식 관리 프레임워크로, 사용자, 권한, 사용자 정의 비즈니스 로직을 관리하면서도 이를 LLM 에이전트가 호출할 수 있는 도구로 자동 노출합니다. 준비된 UI, 설치 워즈드, 완전한 플러그인 생태계를 제공하여 현대의 AI 중심 제품의 견고한 기반을 마련합니다.