KevinLiss/ApeAdmin

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

ApeAdmin는 무엇인가요?

ApeAdmin은 현대적인 AI 애플리케이션을 위한 목적에 맞춰 설계된 오픈소스 FastAPI + Vue 3 기반의 관리자 패널 프레임워크입니다. 일반적인 백오피스 기능—사용자/역할 관리, 메뉴, 감사 로그, RBAC 등—을 제공하지만, 플러그인 아키텍처와 MCP‑SSE 게이트웨이를 추가하여 AI 에이전트가 시스템 기능을 "도구"처럼 호출할 수 있도록 합니다. 간단히 말해, 몇 분 안에 설치할 수 있는 "백엔드로서의 서비스"이며, Python 플러그인을 통해 인간 사용자와 대규모 언어 모델 에이전트 모두에게 비즈니스 로직을 노출할 수 있습니다.

핵심 기능

카테고리	기능 설명
설치 마법사	WordPress 스타일의 3단계 설정 (DB 설정 → 사이트 및 관리자 → 완료). 자동으로 데이터베이스를 생성하고, JWT 시크릿을 생성하며, 첫 실행 후 설치 마법사를 잠급니다.
RBAC	다섯 테이블 모델 (사용자, 역할, 메뉴, 부서, 관계). 네 레이어 권한 검사 (로그인 없음 → 인증 없음 → 규칙 → 데이터 범위) 및 버튼 수준 숨김을 위한 프론트엔드 `v‑permission` 지시자.
플러그인 시스템	`importlib`를 통해 Python 패키지 탐지. 런타임 중 로드/해제 가능하며, 전체 수명 주기 (`load → install → register → uninstall`)를 갖습니다. ZIP 파일로 배포하거나 온라인 플러그인 마켓에서 설치할 수 있습니다.
MCP‑SSE 게이트웨이	등록된 플러그인 함수를 도구, 자원, 또는 프롬프트로 노출하여 AI 에이전트가 Server-Sent Events를 통해 호출할 수 있도록 합니다. 스키마는 함수 서명에서 자동 생성되며, 호출은 RBAC로 필터링되며, 각 호출은 요청/응답 및 시간 정보와 함께 로깅됩니다.
AI 채팅	통합 다중 모델 채팅 (DeepSeek, Qwen, GLM, OpenAI 또는 OpenAI 호환 엔드포인트). 스트리밍 SSE 출력, 마크다운 렌더링, 최대 5라운드의 도구 호출 루프를 지원합니다. 모델 키는 Fernet으로 암호화하여 저장됩니다.
감사 및 모니터링	글로벌 요청 ID, 작업 로그, API별 지연 시간 추적, ECharts 시각화를 포함한 내장 대시보드.
데이터베이스 유연성	SQLite (설정 없이 바로 사용 가능) 또는 MySQL을 생산 환경에 사용할 수 있으며, 드라이버는 `DB_TYPE`로 전환됩니다. 선택적 Redis 캐시는 사용 불가 시 메모리 내 캐시로 대체됩니다.

누구에게 적합한가요?

사용 사례	왜 ApeAdmin이 적합한가요
AI SaaS 플랫폼 – 사용자, 역할, 사용자 정의 AI 도구를 관리하기 위한 보안적인 관리자 UI가 필요할 때.
기업 – LLM 에이전트에게 내부 서비스를 제공하되, 맞춤형 API를 작성하지 않아도 되는 경우—단지 서비스를 MCP 도구로 등록하기만 하면 됩니다.
개발자 – 문서 검색, 워크플로우 자동화와 같은 AI 증강 내부 도구를 개발하고, 핵심 코드를 깨끗하게 유지하기 위해 플러그인 모델을 선호할 때.
스타트업 – 처음부터 구조를 만들지 않고도 빠르게 "관리자 패널 + AI 게이트웨이"를 구축하고 싶을 때.

기술 스택 요약

계층	기술
백엔드	FastAPI, SQLAlchemy 2.0 (비동기), Alembic 마이그레이션
프론트엔드	Vue 3.5, Vite 6, TypeScript 5.7, Element Plus, Pinia, ECharts
데이터베이스	MySQL (via `aiomysql`) 또는 SQLite (`aiosqlite`)
캐시	Redis (선택 사항)
인증	JWT + bcrypt 암호 해싱
AI 통합	MCP (Model Context Protocol) over SSE, DeepSeek, Qwen, GLM, OpenAI 또는 사용자 정의 OpenAI 호환 엔드포인트 지원
패키징	MIT 라이선스, Docker 친화적, 바이너리 또는 인기 있는 호스팅 패널을 통해 배포 가능

시작하기 (가장 빠른 방법)

리포지토리 복제 후 백엔드 폴더로 이동합니다.

가상 환경 생성, 편집 모드로 패키지 설치 후 FastAPI 서버 실행:

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

다른 터미널에서 프론트엔드 폴더로 이동, npm 종속성 설치 후 개발 서버 시작:
```
cd frontend
npm install --legacy-peer-deps
npm run dev
```
http://localhost:5173에 접속합니다. 시스템이 새로 설치되었기 때문에 /setup으로 리디렉션됩니다. 3단계 마법사를 따라 (로컬 데모는 SQLite, 생산 환경은 MySQL 선택) 설치를 완료합니다.
설정한 관리자 자격 증명으로 로그인하고, 시스템 관리 → 플러그인을 탐색한 후 내장 마켓에서 샘플 플러그인을 설치해 보세요.
AI 채팅을 실험하려면 AI 어시스턴트 → 모델 키에서 모델 키를 추가한 후 대화를 시작하세요. 어시스턴트는 등록된 MCP 도구 (예: system_list_plugins)를 호출할 수 있습니다.

ApeAdmin 확장하기

backend/src/plugins/builtin/ 아래에 새로운 Python 패키지를 추가하여 플러그인을 생성합니다. PluginInterface를 구현하고 on_load, register_routes, register_mcp_tools와 같은 메서드를 구현합니다.
register_mcp_tools 내부에서 @mcp_manager.tool 데코레이터를 사용하여 도구를 노출합니다. 함수 서명은 LLM이 호출할 수 있는 JSON-Schema가 됩니다.
플러그인을 ZIP 파일로 배포하거나 온라인 플러그인 마켓에 푸시하여 다른 사용자가 클릭 한 번으로 설치할 수 있도록 합니다.

커뮤니티 및 기여

Fork → 브랜치 (feat/…, fix/… 등) → PR. 커밋 스타일과 테스트는 리포지토리의 기여 가이드를 따르세요.
실시간 지원 및 토론을 위한 WeChat 그룹 제공 (README에 QR 코드 포함).

결론: ApeAdmin은 실행 가능하고 확장 가능한 관리자 프레임워크로, 전통적인 비즈니스 백엔드와 현대적인 LLM 에이전트를 연결합니다. 보안적인 UI, 플러그인 기반 확장성, 그리고 AI 에이전트가 서비스를 일류 도구처럼 호출할 수 있는 방법이 필요하다면, 이 프로젝트는 즉시 사용 가능한 견고한 기반을 제공합니다.