ApeAdmin

ApeAdmin

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

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

简体中文 | English

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

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

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

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

功能特性

安装向导

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

• 自动检测 —— 首次访问自动跳转 /setup 安装向导，已完成安装的系统直接进入后台
• 三步安装 —— 配置数据库 → 配置站点与管理员账号 → 完成安装
• 自动建库 —— MySQL 连接自动检测，数据库不存在时自动创建（utf8mb4）
• 密钥自动生成 —— JWT_SECRET 随机生成并写入 .env，无需手工处理
• 安装锁保护 —— 安装完成后写入 setup.lock，防止向导被重复执行

RBAC 权限体系

• 五表模型 —— 用户 / 角色 / 菜单 / 部门 + 关联表，标准 RBAC 基础设施
• 四层权限 —— 免登录 → 免鉴权 → 规则鉴权 → 数据范围（本部门 / 本部门及以下 / 全部）
• 菜单三类型 —— 目录(M) / 菜单(C) / 按钮(F)，支持无限层级树形结构
• 超管通配 —— 超级管理员自动拥有所有权限，普通用户按角色菜单分配
• 前端权限指令 —— v-permission 指令控制按钮级显示，路由守卫校验页面级权限

微服务插件架构

• 自动发现 —— 插件以 Python 包形式开发，通过 importlib 自动扫描发现
• 独立部署 —— 业务插件支持 Docker 服务独立部署，与底座完全解耦
• 完整生命周期 —— load → install → register → uninstall，支持热启用禁用
• 事件总线 —— EventBus 支持 7 种内置事件（APP_STARTUP / DB_READY / USER_LOGIN 等），插件间松耦合通信
• ZIP 安装 —— 支持上传 ZIP 包导入插件，无需手动放置文件
• 插件市场 —— 在线浏览、搜索、下载社区插件，开发者发布插件与安装包
• 能力注册 —— 插件可注册自有路由、MCP 工具、事件监听器

MCP-SSE 网关

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

• 三原语 —— Tools（工具调用）/ Resources（资源读取）/ Prompts（模板渲染）
• 自动 Schema —— 工具注册时自动从函数签名推断 JSON Schema，无需手写
• RBAC 过滤 —— AI Agent 只能看到当前用户有权限调用的工具
• 安全传输 —— SSE 一次性 ticket 认证（替代 URL 裸 JWT），工具调用 30s 超时保护
• 持久化恢复 —— 插件注册信息持久化，服务重启后自动恢复 MCP 工具注册
• 审计日志 —— 每次工具调用自动记录请求、响应、耗时、调用者
• 插件扩展 —— 插件可向 MCP 网关注册工具，实现能力级对外开放

内置 MCP 工具：

AI 对话

• 多模型支持 —— DeepSeek / 通义千问 / 智谱 GLM / OpenAI / 自定义端点，OpenAI 兼容接口
• 流式 SSE —— 流式输出 + Markdown 实时渲染 + 代码高亮
• Function Calling —— AI 可调用 MCP 工具完成管理操作，最多 5 轮工具调用循环
• 密钥管理 —— 后台管理 AI 供应商密钥，Fernet 加密存储（密钥派生自 JWT_SECRET）

审计日志

• 请求链路追踪 —— RequestContextMiddleware 全局唯一请求 ID
• 操作日志 —— 记录用户操作行为，支持按模块、时间、用户筛选
• 请求耗时监控 —— 自动记录每个 API 请求耗时

技术栈

快速开始

在线体验

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

• 案例地址：
• 测试账号：ceshi110
• 密码：ceshi110

测试账号为只读访客（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')}")

事件类型

配置说明

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

AI 模型配置

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

系统截图

   ![登录页](assets/screenshots/login.png)   

  仪表盘




   ![监控仪表盘](assets/screenshots/dashboard.png)   

  插件管理








   ![插件市场](assets/screenshots/plugins.png)   

  权限管理




   ![系统管理](assets/screenshots/system.png)   

  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

分支命名

约定

• 插件保持独立，不直接依赖其他插件
• 破坏性操作必须需要用户确认
• API 遵循 RESTful 风格，前缀 /api/v1
• 提交前确保后端可启动、前端可编译

社区交流

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