📦 ApeAdmin 详细部署教程

ApeAdmin 是一个面向现代 AI 应用的开源后台管理框架，基于 FastAPI + Vue3 构建。它内置了 RBAC 权限管控、审计日志、插件市场等企业级基础能力，并集成了 MCP-SSE 网关，可以将后台功能直接封装为 AI 工具供 Agent 调用。项目采用 MIT 开源协议，100% 开源。

本教程将指导您通过安装向导（推荐）和生产部署两种方式完成部署。

⚙️ 部署前准备

1. 基础环境要求

  • 操作系统：Windows、macOS 或 Linux。
  • Python 环境：Python 3.9 或更高版本（推荐 3.11+）。
  • Node.js 环境：Node.js 18 或更高版本（用于前端开发/构建）。
  • 包管理器：pip（Python）和 npm（Node.js）。
  • 数据库（可选）：
    • 开发/测试：可使用内置的 SQLite，无需额外安装。
    • 生产环境：推荐使用 MySQL 5.7+ 或 8.0+，并提前创建好数据库（字符集 utf8mb4）。
  • 缓存（可选）：Redis，用于提升性能。如果未配置，系统会自动降级为内存缓存，不影响核心功能。

🚀 方式一：安装向导部署（推荐新手和开发者）

这是项目推荐的快速体验方式，通过浏览器中的可视化向导完成配置，无需手动编辑配置文件。

步骤 1：获取源代码

1
2
git clone https://github.com/KevinLiss/ApeAdmin.git
cd ApeAdmin

步骤 2：启动后端服务

  1. 进入后端目录，创建并激活 Python 虚拟环境：

    1
    2
    3
    4
    5
    cd backend
    python -m venv .venv
    # 激活虚拟环境
    # Windows: .venv\Scripts\activate
    # macOS/Linux: source .venv/bin/activate

  2. 安装后端依赖（以可编辑模式安装项目自身）：

    1
    pip install -e .

  3. 启动后端开发服务器：

    1
    uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

    后端服务将在 http://localhost:8000 运行。

步骤 3：启动前端服务（开发模式）

  1. 打开新的终端，进入前端目录并安装依赖：

    1
    2
    cd frontend
    npm install --legacy-peer-deps

  2. 启动前端开发服务器：

    1
    npm run dev

    前端服务将在 http://localhost:5173 运行。

步骤 4：通过浏览器完成安装向导

  1. 打开浏览器，访问前端地址 http://localhost:5173。系统检测到未安装，会自动跳转到安装向导页面（/setup）。
  2. 按照向导的三步指引操作：
    • 配置数据库：选择 SQLite（零配置，适合开发）或 MySQL（填写连接信息，数据库不存在时可自动创建）。
    • 配置站点：设置站点名称、你的管理员账号（用户名/密码）和站点访问地址。
    • 完成安装：点击安装，系统会写入 .env 配置文件并创建数据表。
  3. 重要：安装完成后，请重启后端服务（在终端按 Ctrl+C 停止后重新执行 uvicorn 命令）。重启后，系统会自动初始化管理员账号和基础数据。

☁️ 方式二：生产环境部署（适用于服务器）

对于生产环境，推荐使用部署包 + Nginx + MySQL + Supervisor 的方式。项目提供了详细的部署文档和构建脚本。

步骤 1：构建部署包

在项目根目录下，执行部署包构建脚本（需要 Linux 环境或 WSL）：

1
2
cd deploy
bash build_deploy_package.sh

该脚本会生成一个包含后端、前端构建产物、Nginx 配置和安装脚本的压缩包（如 apeadmin_deploy_*.tar.gz）。

步骤 2：上传并解压到服务器

将生成的压缩包上传到服务器的目标目录（如 /var/www/apeadmin）并解压。

步骤 3：配置 MySQL 数据库

  1. 在服务器上安装并启动 MySQL。

  2. 创建一个数据库（字符集 utf8mb4）和具有相应权限的用户。

  3. 在部署包目录中找到 .env 文件（或按部署脚本提示生成），修改数据库连接信息：

    1
    2
    3
    4
    5
    6
    DB_TYPE=mysql
    DB_HOST=localhost
    DB_PORT=3306
    DB_USER=你的数据库用户名
    DB_PASSWORD=你的数据库密码
    DB_NAME=你创建的数据库名

步骤 4：配置并启动服务

  1. 配置 Nginx：将部署包中 deploy/nginx/ 目录下的站点配置模板复制到 Nginx 配置目录，并修改 server_name 为你的域名。配置会代理前端静态文件和后端 API 请求。
  2. 配置 Python 环境与后端：在部署目录中创建 Python 虚拟环境，安装依赖，并使用 Supervisor（或 systemd）管理后端进程，确保服务持久运行。
  3. 执行安装：通过浏览器访问你配置的域名，会再次进入安装向导。按提示完成数据库初始化和管理员账号设置（方法与开发模式一致）。
  4. 安装业务插件：登录后台后，通过 系统管理 → 插件管理 中的“上传 ZIP 包”或“插件市场”功能，按需安装你需要的业务插件（部署包本身只包含底座）。

注意：更详细的服务器配置步骤（如 SSL 证书配置、Supervisor 配置示例、SQLite 到 MySQL 的数据迁移），请务必阅读项目 deploy/DEPLOY.md 文件，它是生产部署的权威指南。

🔧 初始化配置与体验

无论通过哪种方式部署，安装完成后，你都应该：

  1. 登录后台：使用安装时设置的管理员账号密码登录。
  2. 熟悉基础功能：在 系统管理 中体验用户、角色、菜单、部门管理，并查看完整的审计日志。
  3. 配置 AI 模型：进入 AI 助手 → 模型密钥管理，添加 DeepSeek、通义千问、OpenAI 等供应商的 API Key。密钥会通过 Fernet 加密存储。
  4. 体验 AI 对话与 MCP 工具：在 AI 助手界面开始对话，或进入 MCP 管理 查看系统内置的工具（如 system_health_check）。AI Agent 可通过 Function Calling 调用你有权限的 MCP 工具。

🧩 插件开发与扩展

ApeAdmin 的强大之处在于其插件化架构。业务功能应全部以插件形式开发。

  1. 创建插件：在后端 backend/src/plugins/builtin/ 目录下，参考 dev_example/ 示例，创建一个新的 Python 包。
  2. 实现插件接口：在 plugin.py 中定义继承自 PluginInterface 的类，实现 on_load、register_routes、register_mcp_tools 等方法。
  3. 注册 MCP 工具：使用 @mcp_manager.tool 装饰器，即可将任何函数暴露为 AI Agent 可调用的工具，并自动生成 JSON Schema。
  4. 监听事件：通过 on_event 方法，插件可以响应 USER_LOGIN、APP_STARTUP 等 7 种系统事件，实现松耦合通信。

❓ 常见问题与故障排查

  • 访问页面自动跳转到 /setup 安装向导：这是正常行为，说明系统检测到尚未安装。安装完成后，确保 setup.lock 文件已生成，并重启了后端服务。
  • 前端 npm install 报错：尝试使用 --legacy-peer-deps 参数。如果仍失败，请检查 Node.js 版本是否 >= 18。
  • 后端启动失败，提示数据库连接错误：
    • 检查 MySQL 服务是否运行，连接信息（主机、端口、用户名、密码）是否正确。
    • 检查数据库字符集是否为 utf8mb4。
    • 如果使用 SQLite，请确保后端进程对数据库文件有写入权限。
  • AI 对话无响应或报错：
    • 检查 AI 模型密钥是否已在后台正确添加并启用。
    • 确认网络环境可以访问对应 AI 提供商的 API 端点。
    • 检查 MCP 网关是否启用（MCP_ENABLED=true）。
  • 如何升级 ApeAdmin 版本：通常需要拉取新代码，合并更改，然后重新运行安装向导（注意备份 .env 和数据库）。具体升级步骤请参阅项目文档或更新日志。

更多详细配置、API 文档和深度定制指南，请参考 ApeAdmin 官方文档。祝你部署顺利！