# FutureBirdAdmin框架

**Repository Path**: futurebird/future-bird-admin-framework

## Basic Information

- **Project Name**: FutureBirdAdmin框架
- **Description**: FutureBirdAdmin框架是一个基于 Next.js 16 + React 19 的开源企业管理应用框架。它提供了完整的多租户、认证授权、插件系统等基础能力，让企业可以独立部署并开发自己的应用插件。，基于现代前端技术构建，提供高效、可扩展的权限管理与数据可视化能力，助力开发者快速搭建企业级后台系统。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-01
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FutureBirdAdmin Framework

<div align="center">

![License](https://img.shields.io/badge/license-MIT-green)
![Version](https://img.shields.io/badge/version-2.1.0-blue)
![Next.js](https://img.shields.io/badge/Next.js-16-black)
![React](https://img.shields.io/badge/React-19-blue)
![TypeScript](https://img.shields.io/badge/TypeScript-5-blue)
![PostgreSQL](https://img.shields.io/badge/PostgreSQL-14+-blue)

**开源企业管理应用框架**

让每个企业都能拥有自己的管理平台

</div>

---

## 项目简介

FutureBirdAdmin 是一个基于 Next.js 16 + React 19 的开源企业管理应用框架。它提供了完整的多租户、认证授权、计费订阅、插件体系等基础能力，让企业可以独立部署并开发自己的应用插件。

### 为什么选择 FutureBirdAdmin？

| 特性 | FutureBirdAdmin | 传统 SaaS | 自研系统 |
|------|:-:|:-:|:-:|
| 完全开源免费 | ✅ | ❌ | ✅ |
| 可独立部署 | ✅ | ❌ | ✅ |
| 插件化架构 | ✅ | ❌ | ❌ |
| 多租户支持 | ✅ | ✅ | 需自建 |
| 认证授权体系 | ✅ 内置 | ✅ | 需自建 |
| 计费订阅 | ✅ 内置 | ✅ | 需自建 |
| 数据自主权 | 完全自主 | 受限 | 完全自主 |

## 核心特性

### 框架能力

- **多租户架构** - 租户级数据隔离、成员邀请与角色分配，独立空间开箱即用
- **认证授权** - JWT + RBAC 统一认证体系，三层防护（Edge 中间件 → 页面守卫 → API 鉴权）
- **安全加固** - refresh token 轮换与复用吊销、登录限流、失败锁定、操作审计日志
- **插件系统** - 应用清单注册机制 + 应用市场（内置插件与平台自定义应用安装/启停/配置/卸载）
- **计费订阅** - 套餐定价、租户自助订阅、资源配额（应用/成员/存储）与用量统计
- **多端布局** - 平台端与租户端双控制台，各自独立仪表盘
- **动态菜单** - 由已安装应用驱动，自动渲染
- **主题系统** - 亮色/暗色双主题，全页面语义化配色，品牌定制
- **国际化** - zh-CN / en-US 多语言，框架与业务页统一接入
- **审计日志** - 操作记录追踪

### 内置插件应用

| 应用 | 说明 | 菜单数 | 权限数 |
|------|------|:------:|:------:|
| 示例应用 | 演示插件开发流程 | 3 | 3 |
| 客户管理 (CRM) | 客户信息、跟进记录、销售漏斗 | 4 | 6 |
| 项目管理 | 项目跟踪、任务看板、团队协作 | 4 | 6 |
| 文档管理 | 企业文档、知识库、文档共享 | 4 | 6 |

### 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 前端框架 | Next.js (App Router) | 16 |
| UI 库 | React | 19 |
| 语言 | TypeScript | 5 |
| 样式 | Tailwind CSS | 4 |
| 组件库 | Arco Design | 2.66 |
| 图标 | lucide-react | 0.468 |
| ORM | Drizzle ORM | 0.45 |
| 状态管理 | Zustand | 5 |
| 数据库 | PostgreSQL | 14+ |
| JWT | jose (Edge 兼容) | 6 |
| 表单 | React Hook Form + Zod | - |

## 快速开始

### 环境要求

- Node.js 18+
- PostgreSQL 14+
- pnpm 9+

### 1. 克隆项目

```bash
git clone https://gitee.com/futurebird/future-bird-admin-framework.git
cd future-bird-admin-framework
pnpm install
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
DATABASE_URL=postgresql://localhost:5432/future_bird_admin
JWT_SECRET=your-secret-key-here
STORAGE_DRIVER=local
```

### 3. 初始化数据库

```bash
# 创建数据库
createdb future_bird_admin

# 创建表结构
pnpm db:push

# 填充种子数据（默认账号 / 套餐 / 内置应用）
pnpm db:seed
pnpm tsx scripts/seed-plans.ts
pnpm tsx scripts/install-builtin-apps.ts
```

### 4. 启动开发服务器

```bash
pnpm dev
```

打开 http://localhost:3000 即可访问。

### 默认账号

| 端 | 账号 | 密码 | 说明 |
|----|------|------|------|
| 平台管理端 | admin | admin123 | 平台超级管理员 |
| 企业端 | tenant | tenant123 | 租户管理员 |

## 插件开发

### 三步创建应用

**第一步：创建应用清单**

```typescript
// src/apps/my-app/manifest.ts
import type { AppManifest } from '@/framework/plugin/types';

export default {
  id: 'my-app',
  name: '我的应用',
  version: '1.0.0',
  description: '一个自定义应用',
  icon: 'AppWindow',
  entry: '/tenant/my-app',
  menus: [
    {
      id: 'my-app-dashboard',
      label: '仪表盘',
      path: '/tenant/my-app',
      icon: 'LayoutDashboard',
      order: 0,
    },
    {
      id: 'my-app-list',
      label: '数据列表',
      path: '/tenant/my-app/list',
      icon: 'Table',
      permission: 'my-app.list.view',
      order: 1,
    },
  ],
  permissions: [
    { code: 'my-app.list.view', name: '查看列表', module: 'my-app' },
    { code: 'my-app.list.manage', name: '管理列表', module: 'my-app' },
  ],
} satisfies AppManifest;
```

**第二步：创建页面**

```tsx
// src/apps/my-app/pages/dashboard.tsx
'use client';
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui';
import { useAuth } from '@/framework/auth';

export default function Dashboard() {
  const { user } = useAuth();
  return (
    <Card>
      <CardHeader><CardTitle>欢迎，{user?.name}</CardTitle></CardHeader>
      <CardContent>这是我的应用仪表盘</CardContent>
    </Card>
  );
}
```

**第三步：注册应用**

```typescript
// src/apps/index.ts
import { pluginRegistry } from '@/framework/plugin/PluginRegistry';
import myApp from './my-app/manifest';

pluginRegistry.register(myApp);
```

搞定！应用菜单自动出现在侧边栏。

详见 [插件开发指南](docs/plugin-development.md)。

## 项目结构

```
future-bird-admin-framework/
├── src/
│   ├── framework/              # 框架核心
│   │   ├── auth/              #   认证授权（JWT + RBAC + 统一 Store）
│   │   ├── plugin/             #   插件系统（Registry + Provider + 应用市场）
│   │   ├── layout/             #   布局框架（ProLayout）
│   │   ├── theme/             #   主题（亮/暗切换 + 初始化）
│   │   ├── i18n/              #   国际化（zh-CN / en-US）
│   │   ├── compat/            #   React 19 兼容补丁
│   │   ├── config/            #   配置（应用 + 主题）
│   │   └── hooks/             #   框架 Hooks（useApps/useMenus）
│   ├── app/                    # Next.js App Router
│   │   ├── admin/             #   平台管理端（控制台/租户/用户/应用/套餐/审计/设置）
│   │   ├── tenant/            #   企业端（控制台/成员/应用/计费/账号）
│   │   ├── login/             #   登录页
│   │   ├── register/          #   注册页
│   │   └── api/               #   API 路由
│   │       ├── auth/          #     认证 API
│   │       └── admin/         #     管理端 API
│   ├── apps/                   # 应用插件
│   │   ├── demo-app/          #   示例应用
│   │   ├── crm/               #   客户管理
│   │   ├── project/           #   项目管理
│   │   └── docs/              #   文档管理
│   ├── components/ui/          # UI 组件库
│   ├── db/                     # 数据库层（Schema）
│   ├── lib/                    # 通用工具（鉴权/配额/审计/限流）
│   └── proxy.ts                # 中间件（路由鉴权）
├── scripts/                    # 脚本
│   ├── seed.ts                #   种子数据
│   ├── seed-plans.ts          #   套餐数据
│   └── install-builtin-apps.ts #   内置应用安装
├── docs/                       # 文档
├── .gitee/                     # Gitee 配置（Issue/PR 模板）
├── Dockerfile                  # Docker 部署
├── docker-compose.yml          # Docker 编排
├── CONTRIBUTING.md             # 贡献指南
├── CHANGELOG.md                # 变更日志
└── SECURITY.md                 # 安全政策
```

## 文档

| 文档 | 说明 |
|------|------|
| [快速开始](docs/getting-started.md) | 详细安装和配置步骤 |
| [插件开发指南](docs/plugin-development.md) | 从零开发一个应用插件 |
| [架构设计](docs/architecture.md) | 框架整体架构说明 |
| [常见问题](docs/faq.md) | FAQ |
| [开发路线图](docs/roadmap.md) | 版本规划和未来计划 |
| [版本管理](docs/versioning.md) | 升级指南和兼容性说明 |
| [贡献指南](CONTRIBUTING.md) | 如何参与项目贡献 |
| [安全政策](SECURITY.md) | 安全漏洞报告流程 |

## 部署

### Docker 部署（推荐）

```bash
docker-compose up -d
```

### PM2 部署

```bash
pnpm build
pm2 start "node server.js" --name future-bird-admin
```

详见 [部署指南](docs/deployment.md)。

## 参与贡献

欢迎提交 PR、报告 Bug、开发插件、完善文档！

1. Fork 本仓库
2. 创建分支 (`git checkout -b feature/my-feature`)
3. 提交代码 (`git commit -m 'feat: 添加某功能'`)
4. 推送分支 (`git push origin feature/my-feature`)
5. 创建 PR

详见 [贡献指南](CONTRIBUTING.md)。

## 开源协议

[MIT License](LICENSE)

## 仓库

- **Gitee**: https://gitee.com/futurebird/future-bird-admin-framework