# AgentRouter

**Repository Path**: w983798109/AgentRouter

## Basic Information

- **Project Name**: AgentRouter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-17
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentRouter

AgentRouter 是一个面向智能照明设备的本地 AI 助手项目。项目由 Vue 3 前端、Spring Boot 后端和 FastAPI AI 服务组成，通过 SSE 返回模型回复和灯光控制指令，并使用 MariaDB、Redis 与 MinIO 保存业务数据、缓存和知识库文件。

> 安全提示：请勿把真实账号、密码、Token、API Key、私钥、内部地址或生产配置提交到仓库。实际配置只能保存在本地 `.env`、操作系统环境变量或专用密钥管理服务中。

## 项目预览

AgentRouter 已经打通从 AI 对话、设备控制到后台管理的核心功能链路，可用于体验和继续扩展智能照明设备助手。

### AI 设备模拟对话

支持面向设备的 AI 对话，并提供推理、联网和工作流等交互入口。

![AgentRouter AI 设备模拟对话](docs/images/agentrouter-ai-device-chat.png)

### 权限角色管理

支持系统用户、账号状态与角色权限的集中管理。

![AgentRouter 权限角色管理](docs/images/agentrouter-role-management.png)

## 主要功能

- **AI 设备模拟对话**：支持设备选择、SSE 流式回复，并可生成智能照明控制指令。
- **指令参数**：集中维护设备控制所需的指令参数和可选值。
- **配置指令参数**：配置灯光控制参数及触发趋势，支撑不同设备和场景的控制需求。
- **知识库管理**：管理知识库条目、上传文件并完成内容解析，为 AI 对话提供知识支持。
- **设备管理与统计**：维护设备信息，查看设备状态与相关统计数据。
- **权限角色管理**：提供登录、注册、验证码、用户管理、角色分配和基于角色的权限控制。
- **完整基础设施**：使用 MariaDB / MySQL 保存业务数据、Redis 提供缓存、MinIO 存储知识库文件。
- **开发与运维支持**：提供后端 OpenAPI 文档、AI 服务 API 文档和健康检查接口。

## 欢迎参与改进

AgentRouter 的核心功能链路已经较为完整，但仍有很多值得继续打磨的地方。欢迎大家实际体验后，帮助寻找可以提升的点，例如交互体验、设备协议适配、AI 能力、性能与稳定性、自动化测试、部署方式和使用文档。

你可以通过 [GitHub Issues](https://github.com/yuyangtang019-sys/AgentRouter/issues) 提交建议或问题，也欢迎阅读 [贡献指南](CONTRIBUTING.md) 并提交 Pull Request。每一条反馈都会帮助这个项目变得更好。

## 技术栈

| 部分 | 主要技术 |
| --- | --- |
| 前端 | Vue 3、TypeScript、Vite 6、Pinia、Element Plus |
| 后端 | Java 17、Spring Boot 3.4.1、MyBatis-Plus、Sa-Token、Maven |
| AI 服务 | Python、FastAPI、LangChain、OpenAI 兼容接口、SQLAlchemy |
| 基础设施 | MariaDB / MySQL、Redis、MinIO、Docker Compose |

## 目录结构

```text
AgentRouter/
├─ agent-router-web/       # Vue 3 前端
├─ agent-router-backed/    # Spring Boot 多模块后端
├─ agent-router-ai/        # FastAPI AI 服务
├─ schema/                 # 不含真实数据的纯表结构 SQL
├─ .env.example            # 根目录安全配置模板
├─ docker-compose.yml      # MariaDB、Redis、MinIO 本地依赖
└─ README.md
```

## 环境要求

- Git
- JDK 17
- Maven 3.9+
- Python 3.11+（当前依赖曾在 Python 3.14 环境验证）
- Node.js 20.11+
- pnpm 9+
- Docker 与 Docker Compose（可选，用于启动基础设施）

默认端口：

| 服务 | 端口或地址 |
| --- | --- |
| 前端 | `http://localhost:5173` |
| Spring Boot 后端 | `http://localhost:8021` |
| 后端 API 文档 | `http://localhost:8021/docs/api` |
| FastAPI AI 服务 | `http://localhost:8022` |
| AI API 文档 | `http://localhost:8022/docs` |
| AI 健康检查 | `http://localhost:8022/health` |
| MariaDB | `localhost:3306` |
| Redis | `localhost:6379` |
| MinIO API | `http://localhost:9000` |
| MinIO 控制台 | `http://localhost:9090` |

## 配置环境变量

先复制安全模板，不要直接修改或提交 `.env.example` 中的占位规则：

```bash
cp .env.example .env
cp agent-router-ai/.env.example agent-router-ai/.env
cp agent-router-web/.env.example agent-router-web/.env.development.local
```

Windows PowerShell：

```powershell
Copy-Item .env.example .env
Copy-Item agent-router-ai/.env.example agent-router-ai/.env
Copy-Item agent-router-web/.env.example agent-router-web/.env.development.local
```

必须修改的变量至少包括：

- Redis：`REDIS_HOST`、`REDIS_PORT`、`REDIS_USERNAME`、`REDIS_PASSWORD`
- MinIO：`MINIO_ENDPOINT`、`MINIO_ACCESS_KEY`、`MINIO_SECRET_KEY`、`MINIO_BUCKET`
- 数据库：`MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_DATABASE`、`MYSQL_USERNAME`、`MYSQL_PASSWORD`、`MYSQL_ROOT_PASSWORD`
- 安全配置：`JWT_SECRET` 和接口加解密公私钥变量
- AI：`DEEPSEEK_API_KEY` 或其他模型提供商的 API Key、`AI_BASE_URL`、`LLM_MODEL`
- 前端：与数据库安全客户端记录对应的 `VITE_CLIENT_ID`

Docker Compose 会自动读取根目录 `.env`。Spring Boot 直接读取操作系统环境变量；在 PowerShell 中可以把 `.env` 导入当前进程：

```powershell
Get-Content .env |
  Where-Object { $_ -match '^[A-Za-z_][A-Za-z0-9_]*=' } |
  ForEach-Object {
    $name, $value = $_ -split '=', 2
    Set-Item -Path "Env:$name" -Value $value
  }
```

## 启动基础设施

配置好根目录 `.env` 后执行：

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

该 Compose 文件只启动 MariaDB、Redis 和 MinIO，不会自动启动三个应用服务。

停止基础设施：

```bash
docker compose down
```

如需同时删除本地数据卷，请自行确认数据不再需要后再执行 `docker compose down -v`。

## 初始化数据库

`schema/mysql_schema.sql` 只包含表结构，不包含默认账号、密码哈希、邮箱、手机号、IP 或业务数据。

Bash 示例：

```bash
mysql -h localhost -P 3306 -u agent_router -p agent_router < schema/mysql_schema.sql
```

Windows 可通过 MariaDB / MySQL 客户端或数据库管理工具导入该文件。

为避免公开默认凭据，本仓库不提供默认登录账号、密码或客户端密钥。首次使用前需要在私有环境中创建租户、客户端和管理员数据，或使用项目实际存在的注册接口建立用户。不要把生成的数据回传到公开仓库。

## 启动后端

```bash
cd agent-router-backed
mvn -Plocal -pl agent-router-admin -am test
mvn -Plocal -pl agent-router-admin -am -DskipTests package
java -jar agent-router-admin/target/agent-router-admin.jar
```

`-Plocal` 会使用仓库内安全的 `application-open.yml`。数据库、Redis、MinIO、JWT 和模型配置均从环境变量读取。

## 启动 AI 服务

```bash
cd agent-router-ai
python -m venv .venv
```

Linux / macOS：

```bash
source .venv/bin/activate
pip install -r requirements.txt
python -m uvicorn app.main:app --host 127.0.0.1 --port 8022
```

Windows PowerShell：

```powershell
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m uvicorn app.main:app --host 127.0.0.1 --port 8022
```

## 启动前端

```bash
cd agent-router-web
pnpm install --frozen-lockfile
pnpm dev
```

类型检查和生产构建：

```bash
pnpm exec vue-tsc --noEmit
pnpm build
```

## 安全说明

- `.env`、`.env.local`、生产配置、本地配置和日志均已被 `.gitignore` 排除。
- 不要在测试、注释、Issue、截图或 README 中粘贴真实密钥。
- 如果密钥曾进入 Git 历史，仅删除当前文件是不够的；必须轮换密钥，并使用干净历史重新发布。
- 日志不得输出完整或部分 API Key、密码、Authorization 请求头、Cookie 或用户数据。
- 生产环境应使用专用密钥管理服务，并为数据库、Redis 和 MinIO 设置最小权限账号。
- 安全问题请按照 [SECURITY.md](SECURITY.md) 处理，不要在公开 Issue 中披露漏洞细节。

## 常见问题

### 为什么没有默认账号和密码？

公开默认凭据会形成安全风险，因此本仓库只提供纯表结构，不提供默认用户、密码哈希或真实客户端配置。

### 为什么启动后提示数据库表存在但没有可登录用户？

这是安全清理后的预期行为。请在私有环境中创建初始化数据，或使用注册接口创建用户，并确保前端 `VITE_CLIENT_ID` 与数据库中的安全客户端记录一致。

### AI 服务提示 API Key 未配置怎么办？

检查 `agent-router-ai/.env` 是否由模板复制，并确认所选模型提供商对应的 Key 已填写。不要在日志或 Issue 中发送 Key。

### 后端无法连接 Redis、MinIO 或数据库怎么办？

确认 Docker 容器已启动、端口未被占用，并检查当前终端中的环境变量。密码需要与根目录 `.env` 中 Compose 使用的值一致。

### 可以提交 `application-local.yml` 吗？

不可以。该文件已被忽略。公开配置应写入安全模板，并通过环境变量注入真实值。

## 许可证

本项目使用 [MIT License](LICENSE)。第三方代码、依赖和素材仍分别遵循其自身许可证，详见 [第三方声明](THIRD_PARTY_NOTICES.md)。