# 七虎AI — 智能自动化 PaaS 平台

> **私有化部署 | 零代码 AI SOP | 多模型聚合 | 技能市场 | IM Bot**

**版本**: v3.0 | **构建日期**: 2026-08-12 | **公网**: https://ai.qihuyun.com | **后台**: `admin / admin123`

---

## 🚀 快速开始

```bash
# 1. 克隆仓库
git clone http://git.qihuyun.com/qyyfw/qihuaiflow.git
cd qihuaiflow

# 2. 配置环境
cp .env.example .env  # 编辑 API keys

# 3. 一行启动
docker-compose up -d

# 4. 访问
open https://ai.qihuyun.com          # 前台
open https://ai.qihuyun.com/admin    # 后台
```

**前置要求**: Docker Compose v2 + 8GB RAM

---

## ✨ 核心能力

| 能力 | 描述 | 状态 |
|------|------|------|
| 🤖 **AI 对话** | SSE 流式对话、多模型自动路由、Markdown 渲染、代码高亮 | ✅ 生产 |
| 📚 **知识库 RAG** | 文档上传 → 切片 → pgvector 向量化 → BM25+语义检索 | ✅ 生产 |
| 🛒 **技能市场** | 97+ Skill 发现-安装-执行，Meilisearch 中文搜索，14 类 capability | ✅ 生产 |
| 🎨 **媒体生成** | 图片/视频 AI 生成，media relay 中转，微信内联渲染 | ✅ 生产 |
| 📊 **Token 驾驶舱** | 实时用量监控、趋势图表、预警告警、计费追踪 | ✅ 生产 |
| 💰 **会员订阅** | 多套餐对比、微信支付、增值单点付费 | ✅ 生产 |
| 🏪 **应用市场** | 第三方应用集成，产品定价，webhook 回调 | ✅ 生产 |
| 🤖 **Agent 编排** | DAG 图引擎 + Supervisor 模式 | 🔨 迭代中 |
| 📱 **IM Bot** | 微信扫码连接，AI 对话 + 图片生成 | ✅ 生产 |
| 🛡️ **安全纵深** | 四层防护: 限流+扫描器拦截+IP黑名单+JWT认证 | ✅ 生产 |

---

## 🏗️ 架构总览

```
┌──────────────────────────────────────────────────┐
│          React SPA (Vite 5 + Tailwind 4)          │
│  Landing | Chat | Knowledge | Market | Agent      │
├──────────────────────────────────────────────────┤
│          Nginx (限流 + 扫描器 + SSL)               │
├──────────────────────────────────────────────────┤
│          FastAPI uvicorn (Python 3.11)             │
│  EngineCore (双 Claw 单引擎) | LLM Router         │
├──────────────────────────────────────────────────┤
│    LiteLLM      │  MCP SDK   │  Casdoor OAuth     │
│   (模型网关)     │ (工具协议) │  (统一认证)        │
├──────────────────────────────────────────────────┤
│  PostgreSQL+pgvector │ Redis │ Meilisearch        │
└──────────────────────────────────────────────────┘
```

详见 [ARCHITECTURE.md](ARCHITECTURE.md)

---

## 📦 技术栈

| 层 | 技术 |
|----|------|
| 前端 | React 18 + TypeScript 5.6 + Vite 5 + Tailwind CSS 4 + Zustand 5 |
| 后端 | Python 3.11 + FastAPI + SQLAlchemy 2.0 + Pydantic |
| 数据库 | PostgreSQL 18 + pgvector (向量) + Redis 7 (缓存) |
| 认证 | Casdoor (OAuth2/OIDC) + JWT |
| LLM 网关 | LiteLLM (模型路由 + 费用追踪 + 协议转换) |
| 搜索引擎 | Meilisearch v1.11 (BM25 + jieba 中文分词) |
| 可观测 | Prometheus + Grafana + Alloy (OTel) |
| 部署 | Docker Compose (一行启动，自包含) |
| 设计 | qihu-design-system (53 modules, indigo #5B5FED) |

---

## 🗂️ 项目结构

```
qihuaiflow/
├── backend/python/app/        # FastAPI 后端
│   ├── api/                   # API 路由
│   │   ├── admin/             # 后台管理 API (models/skills/agents/users/...)
│   │   ├── chat.py            # AI 对话核心 (SSE流式 + 媒体生成)
│   │   ├── auth.py            # JWT 认证
│   │   └── im_llm.py          # IM Bot LLM 薄壳
│   ├── core/                  # 核心引擎
│   │   ├── llm_router.py      # LLM 路由 + 熔断
│   │   ├── claw_adapters.py   # 双 Claw 适配器 (SSE/Buffer)
│   │   ├── litellm_sync.py    # LiteLLM 模型同步服务
│   │   ├── node_registry.py   # Agent 节点注册
│   │   └── capability_discovery.py  # 能力发现
│   └── models/                # 数据库模型
├── frontend/                  # React 前端
│   └── src/
│       ├── pages/admin/       # 后台页面 (39 modules)
│       ├── pages/front/       # 前台页面
│       ├── components/        # 设计系统组件
│       │   ├── ui/            # Button/Badge/Input/Card
│       │   ├── canvas/        # GenUiCard/StatusRing/ChatComposer
│       │   └── layout/        # AppShell/ThemeToggle
│       └── styles/            # 全局 CSS + chat 样式
├── nginx/                     # Nginx 配置文件
├── config/                    # LiteLLM + 平台配置
├── migrations/                # 数据库迁移 SQL
├── docker-compose.yml         # Docker Compose 编排
├── Dockerfile                 # 主应用镜像
├── ARCHITECTURE.md            # 架构设计文档
└── DESIGN.md                  # 设计系统规范
```

---

## 🔧 开发指南

### 环境要求

- Docker Compose v2
- Python 3.11+ (本地开发)
- Node.js 22+ (前端开发)
- Git

### 本地开发

```bash
# 后端
cd backend/python
pip install -r requirements.txt
uvicorn main:app --reload --port 18080

# 前端
cd frontend
npm install
npm run dev  # Vite dev server :5173
```

### 部署

```bash
# 生产部署
docker-compose up -d --build

# 查看状态
docker-compose ps
docker logs qihu-aiflow --tail 50

# 重启
docker restart qihu-aiflow
```

### 测试

```bash
# 后端测试
docker exec qihu-aiflow bash -c "cd /app/backend/python && .venv/bin/python -m pytest"
# 当前: 165 passed / 2 skipped

# 前端测试
docker exec qihu-aiflow bash -c "cd /app/frontend && npx vitest run"
```

---

## 📊 平台数据

| 指标 | 数值 |
|------|------|
| LLM 模型数 | 14 (含 OCR/Rerank/Embedding/TTS/ASR) |
| 技能数 | 97 |
| MCP 工具数 | 26 |
| 后台管理页面 | 39 |
| API 端点 | 300+ |
| 容器数 | 12 |
| 代码行数 | 50,000+ |

---

## 🌐 线上环境

| 资源 | 地址 |
|------|------|
| 前台 | https://ai.qihuyun.com |
| 后台 | https://ai.qihuyun.com/admin |
| Grafana | http://210.16.161.218:3000 |
| Prometheus | http://210.16.161.218:9090 |
| Casdoor | http://210.16.161.218:8000 |
| Git 仓库 | http://git.qihuyun.com/qyyfw/qihuaiflow |

---

## 📝 更新日志

详见 [CHANGELOG.md](CHANGELOG.md) 和 [RELEASES.md](RELEASES.md)

**v3.0 重点更新 (2026-08-12)**:
- ✅ 修复 `/admin/models` 空白页 (React hooks + 缓存问题)
- ✅ 实现 LiteLLM 模型同步 (管理员 UI → LiteLLM REST API)
- ✅ 实现 media_relay 端点 (微信 Bot 图片中转)
- ✅ 设计系统全量收口 + ErrorBoundary + safeLazy
- ✅ Docker Compose STORE_MODEL_IN_DB 模式
- ✅ Nginx 限流 + 扫描器拦截 + IP 黑名单

---

## 📄 许可证

私有项目。© 2026 七虎AI. All rights reserved.