ApeAdmin README

The project's README from github.com/KevinLiss/ApeAdmin. As one markdown file: README.md.


ApeAdmin Logo

ApeAdmin

面向现代AI应用系统打造 · 100%开源后台管理框架

apeadmin官网 · 插件市场 · 开发文档 · demo体验 · 功能 · 架构 · 配置 ·

简体中文 | English

version python vue license platform

本项目由 AI 驱动开发，人工负责产品与质量。 ApeAdmin 在 AI 辅助下高效迭代：人类开发者负责产品方向、架构评审、质量验证与最终决策，AI 负责加速实现、测试和文档工作。

ApeAdmin 是新时代面向 AI 应用打造的后台开发框架，基于 FastAPI + Vue3 搭建平台化管理底座，跳出传统后台系统的设计思路，原生为 AI Agent 能力调用做适配。

项目支持插件化开发，拥有完善的插件社区生态；内置 RBAC 权限管控、插件市场、审计日志等企业级基础能力。框架集成 MCP-SSE 网关，可把系统底座和业务插件的功能直接封装为标准化 AI 工具供 Agent 调用，实现传统业务系统与大模型智能体的无缝打通，同时保留完整的后台管理能力，帮助开发者快速搭建兼具业务管理与 AI 工具输出能力的应用。

你可以把它理解为一个"开箱即用 + 可插拔扩展"的中后台框架——底座提供权限、菜单、日志等基础设施，业务功能以插件形式独立开发和部署，同时通过 MCP 网关将管理能力暴露给 AI Agent 调用。项目采用 MIT 开源协议。

功能特性

安装向导

WordPress 式开箱体验，无需手工编辑配置文件：

RBAC 权限体系

微服务插件架构

MCP-SSE 网关

将底座与插件的管理能力对外暴露为 AI Agent 可调用的工具：

内置 MCP 工具：

工具 说明
system_health_check 系统健康检查
system_list_plugins 列出已安装插件
role_list / create / update / delete 角色管理（需权限）
dept_list / create / update / delete 部门管理（需权限）
menu_list / create / update / delete 菜单管理（需权限）

AI 对话

审计日志

技术栈

层 技术
后端 FastAPI + SQLAlchemy 2.0 (async) + Alembic
前端 Vue 3.5 + Vite 6 + TypeScript 5.7 + Element Plus 2.9
状态管理 Pinia 2.3
图表 ECharts 5.6 + vue-echarts
数据库 MySQL（aiomysql）/ SQLite（aiosqlite）双驱动自动切换
缓存 Redis（可选，缺失自动降级内存）
认证 JWT（access token）+ bcrypt 密码哈希
AI 协议 MCP (Model Context Protocol) — SSE 传输
AI 模型 DeepSeek / 通义千问 / 智谱 GLM / OpenAI（OpenAI 兼容接口）

快速开始

在线体验

无需自己搭建，直接访问线上演示环境：

测试账号为只读访客（viewer）角色，仅可查看各模块数据，无增删改权限。

方式一：安装向导（推荐）

无需手工配置，浏览器里点几下即可完成安装：

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

# 2. 启动前端（开发模式）
cd frontend
npm install --legacy-peer-deps
npm run dev

打开 http://localhost:5173，系统检测到未安装会自动进入安装向导：

  1. 配置数据库 —— 选择 SQLite（零配置）或 MySQL（填连接信息，可自动建库）
  2. 配置站点 —— 站点名称、管理员账号密码、访问地址
  3. 完成安装 —— 写入配置并建表，按提示重启后端，重启后自动初始化管理员账号与基础数据

SQLite 适合本地开发和轻量部署；MySQL 适合生产环境与多服务场景。

方式二：生产部署

服务器（宝塔面板 / Docker / 裸机 Nginx）一键部署方案、部署包构建、SQLite→MySQL 数据迁移，见 deploy/DEPLOY.md。

部署包只包含管理后台底座（RBAC / 菜单 / 插件框架 / MCP 网关），不含业务插件，首次启动进入安装向导。业务插件通过后台的插件导入机制按需安装（上传 ZIP 包 / 插件市场在线安装），与部署包解耦：

默认体验路径

  1. 登录后台（安装向导中设置的管理员账号）
  2. 系统管理 → 用户 / 角色 / 菜单 / 部门 / 插件管理
  3. MCP 管理 → 工具 / 资源 / 提示词 / 调用日志
  4. AI 助手 → 配置模型密钥后即可对话

也可以直接用上方「在线体验」的测试账号登录线上演示环境，无需本地部署。

架构

ApeAdmin 是一个前后端分离的单体应用，后端插件化扩展，内置安装向导：

apeadmin/
  backend/                       # FastAPI 后端
    src/
      api/                       # 路由层
        auth.py                  # 认证（登录/登出/用户信息）
        user.py                  # 用户管理
        role.py                  # 角色管理
        menu.py                  # 菜单管理（树形）
        dept.py                  # 部门管理（树形）
        plugin.py                # 插件管理
        ai_provider.py           # AI 模型密钥管理
        chat.py                  # AI 对话（流式 SSE）
        dashboard.py             # 仪表盘统计
        log.py                   # 系统日志
      core/                      # 基础设施
        config.py                # 配置（pydantic-settings）
        security.py              # 密码哈希 + JWT
        deps.py                  # 依赖注入
        middleware.py            # 中间件（CORS / 请求追踪）
        seed.py                  # 种子数据初始化
        crypto.py                # API Key 加密
      crud/                      # 泛型 CRUD 基类 + RBAC CRUD
      db/                        # 数据库引擎与会话管理
      models/                    # ORM 模型
        rbac.py                  # RBAC 五表
        ai.py                    # AI 供应商
        plugin.py                # 插件记录
        mcp.py                   # MCP 审计日志
        log.py                   # 系统日志
      mcp/                       # MCP 协议体系
        manager.py               # 工具/资源/提示词管理 + RBAC 过滤
        routes.py                # MCP HTTP 路由 + 审计日志
        builtin_resources.py     # 内置工具/资源/提示词
      plugins/                   # 插件系统
        base.py                  # PluginInterface + EventBus
        manager.py               # 插件发现/加载/安装/卸载
        builtin/                 # 内置插件（按需放入，目录动态扫描）
          dev_example/           # 插件开发示例
      setup_wizard/              # 安装向导（未安装时挂载）
        state.py                 # 安装状态（setup.lock / .env 读写）
        api.py                   # 向导 API（状态/测试连接/执行安装）
        setup.html               # 向导页面
      ai/                        # AI 智能体
        agent.py                 # 多模型对话 + 工具调用循环
        tools.py                 # MCP 工具列表构建
      schemas/                   # Pydantic 请求/响应模型
      main.py                    # 应用入口（lifespan + setup 模式切换）
      cli.py                     # 命令行工具
    alembic/                     # 数据库迁移
    pyproject.toml

  frontend/                      # Vue3 前端
    src/
      api/                       # Axios 封装 + 全部接口定义
      components/                # ApeHeader / ApeSidebar
      composables/               # useTheme（深色/浅色切换）
      directives/                # v-permission 权限指令
      layout/                    # 主布局
      router/                    # 路由 + 守卫 + 动态路由生成
      stores/                    # Pinia（用户状态/权限/菜单）
      styles/                    # 全局样式
      views/                     # 页面
        login/                   # 登录
        system/                  # 系统管理（用户/角色/菜单/部门/文件/插件/日志/设置/个人中心）
        mcp/                     # MCP 管理（工具/资源/提示词/审计日志）
        ai/                      # AI 助手（对话/模型密钥管理）
        error/                   # 异常页（404 等）

  deploy/                        # 部署物料
    DEPLOY.md                    # 生产部署文档（宝塔/Docker/Nginx）
    build_deploy_package.sh      # 部署包构建脚本（底座版/完整版）
    nginx/                       # Nginx 站点配置模板
    scripts/                     # 服务器端部署/管理脚本

设计原则

  1. 安装即用 —— 未安装时自动进入 /setup 向导，配置写 .env、建表自动完成，安装锁防止重复执行；安装阶段只建表不跑种子数据，种子在重启后以新密钥执行，避免加密密钥不一致
  2. 底座与插件解耦 —— 底座提供 RBAC、日志、MCP 网关等基础设施，业务功能全部以插件形式开发，互不依赖
  3. 双数据库驱动 —— 开发用 SQLite 零配置启动，生产用 MySQL，通过 DB_TYPE 环境变量切换
  4. Redis 可选 —— 缓存层缺失时自动降级为内存字典，不影响功能
  5. 权限贯穿 AI —— MCP 工具调用和 AI Function Calling 均受 RBAC 权限控制，AI Agent 只能操作有权限的资源
  6. 动态路由 —— 前端路由从后端菜单树动态生成，菜单增减无需改前端代码

插件开发

创建插件

在 backend/src/plugins/builtin/ 下创建 Python 包：

my_plugin/
  __init__.py
  plugin.py          # 插件入口（实现 PluginInterface）
  models.py          # ORM 模型（可选）
  api.py             # 路由（可选）
  services.py        # 业务逻辑（可选）

插件接口

from src.plugins.base import PluginInterface, PluginInfo, EventBus, Event

class MyPlugin(PluginInterface):
    @property
    def info(self) -> PluginInfo:
        return PluginInfo(
            name="my-plugin",
            version="1.0.0",
            description="我的第一个插件",
            author="Your Name",
        )

    def on_load(self):
        """插件加载时调用"""
        pass

    def on_install(self):
        """插件安装时调用（可创建数据库表）"""
        pass

    def register_routes(self, app):
        """注册 FastAPI 路由"""
        @app.get("/api/v1/my-plugin/hello")
        def hello():
            return {"msg": "Hello from MyPlugin!"}

    def register_mcp_tools(self, mcp_manager):
        """注册 MCP 工具，暴露给 AI Agent 调用"""
        @mcp_manager.tool("my_plugin_greet", "问候工具")
        def greet(name: str) -> dict:
            """向指定用户问候"""
            return {"message": f"Hello, {name}!"}

    def on_event(self, event: Event, *args, **kwargs):
        """监听事件总线事件"""
        if event == Event.USER_LOGIN:
            print(f"用户登录: {kwargs.get('username')}")

事件类型

事件 触发时机
APP_STARTUP 应用启动
APP_SHUTDOWN 应用关闭
DB_READY 数据库初始化完成
USER_LOGIN 用户登录
USER_LOGOUT 用户登出
BEFORE_REQUEST 请求处理前
AFTER_REQUEST 请求处理后

配置说明

通过安装向导可自动生成 .env；手工配置时参考下表（后端目录 .env 文件或环境变量）：

配置项 默认值 说明
DB_TYPE sqlite 数据库类型 (sqlite / mysql)
DB_HOST localhost MySQL 地址
DB_PORT 3306 MySQL 端口
DB_USER root MySQL 用户名
DB_PASSWORD — MySQL 密码
DB_NAME apeadmin 数据库名
REDIS_URL redis://localhost:6379/1 Redis 连接（可选）
JWT_SECRET change-me-in-production... JWT 签名密钥（向导安装时自动生成）
JWT_EXPIRE_MINUTES 1440 Token 有效期（分钟）
CORS_ORIGINS localhost:5173,localhost:8000 CORS 白名单
ADMIN_PATH /admin 管理后台访问路径
SITE_URL — 站点对外访问地址
MCP_ENABLED true 是否启用 MCP 网关
PLUGINS_ENABLED true 是否启用插件系统
SUPER_ADMIN_USERNAME admin 超管用户名
SUPER_ADMIN_PASSWORD admin123 超管密码

AI 模型配置

在管理后台 → AI 助手 → 模型密钥管理中添加：

供应商 默认模型 Base URL
DeepSeek deepseek-chat https://api.deepseek.com
通义千问 qwen-plus https://dashscope.aliyuncs.com/compatible-mode/v1
智谱 GLM glm-4-flash https://open.bigmodel.cn/api/paas/v4
OpenAI gpt-4o-mini https://api.openai.com/v1
自定义 — 任意 OpenAI 兼容端点

系统截图

登录页
仪表盘 		监控仪表盘
插件管理
插件市场
权限管理 		系统管理
MCP管理

贡献指南

欢迎贡献！

如何贡献

  1. Fork 仓库
  2. 克隆你的 fork：
    git clone https://github.com/<你的用户名>/ApeAdmin.git
cd ApeAdmin
  3. 创建分支：
    git checkout -b feat/your-feature
  4. 修改代码，确保能运行：
    # 后端
cd backend && pip install -e . && uvicorn src.main:app --reload

# 前端
cd frontend && npm install --legacy-peer-deps && npm run dev
  5. 清晰地写 commit：
    git commit -m "feat: add xxx support"
  6. Push 并向 master 分支提交 Pull Request

分支命名

前缀 用途
feat/ 新功能
fix/ Bug 修复
refactor/ 重构（不改变行为）
docs/ 仅文档
chore/ 构建、CI、工具链

约定

社区交流

用微信扫描下方二维码联系作者加入 ApeAdmin 用户群，反馈问题、分享使用心得，和其他用户、维护者一起交流：

微信用户群二维码

ApeAdmin (KevinLiss/ApeAdmin)

Searching Database…

289 ·GitHub
ApeAdmin
What is this?ApeAdmin is an open-source Python admin backend framework built on FastAPI and Vue3, aimed at modern AI applications. It bundles RBAC permission control and audit logging with a plugin ecosystem and an MCP-SSE gateway that exposes system and plugin capabilities as tools AI agents can call.
Is this a ready-made app or a framework I build on?It is a pluggable backend framework, not a finished app: the core (base) handles RBAC, menus, and logging, while all business features are developed and deployed as separate, decoupled plugins on top of it.
How do I get it running?Open the app in a browser and it auto-redirects first-time visitors to a /setup installation wizard: pick SQLite or MySQL, set the site name and admin account, then restart the backend to finish. Production options (Baota panel, Docker, bare-metal Nginx) are documented in deploy/DEPLOY.md.
Do I need MySQL and Redis to try it out?No - SQLite works with zero configuration for local development and testing, while MySQL is recommended for production. Redis is optional too; if it is missing, caching silently falls back to an in-memory dictionary.
Does the production deployment package include business plugins?No - the deployment package only ships the admin core (RBAC, menus, plugin framework, MCP gateway) with no business plugins included; after first launch you install plugins separately via ZIP upload or the plugin marketplace.
What exactly does the MCP-SSE gateway expose to AI agents?It exposes admin-core and plugin capabilities as standard MCP primitives (Tools, Resources, Prompts) with auto-generated JSON Schema, RBAC-filtered so an agent only sees tools the current user can use, and SSE one-time ticket auth instead of a raw JWT in the URL.
Which AI models can the built-in chat assistant use?DeepSeek, Alibaba Qwen, Zhipu GLM, OpenAI, or any custom OpenAI-compatible endpoint, with streaming SSE output and function calling that lets the model call MCP tools for up to 5 rounds.
How does plugin installation and the plugin marketplace work?Plugins are Python packages auto-discovered via importlib with a full lifecycle (load/install/register/uninstall) and hot enable/disable; you can install them by uploading a ZIP or browsing/downloading from an online plugin marketplace.
Can I try it without installing anything myself?Yes, there's a public online demo with a read-only 'viewer' test account that can browse every module but cannot create, edit, or delete data.
What are similar projects?JeecgBoot, gin-vue-admin, TradingAgents-CN, evenfire, casdoor, emdash, LoomFlow, go-admin
Which topics is it in?audit-log, vue3, jwt, admin-dashboard, rbac, fastapi, plugin-system, mysql, redis, openai-compatible, authentication, deepseek
Creator
KevinLiss
Size
44.2 MB
Stars
289
Updated
CommitOct 10
Age
1mo
Commits · 90 Days