# 我的助手 Gateway 服务

> 我的助手 项目的核心API网关服务，基于Express + TypeScript构建，提供统一的API接口、WebSocket实时通信、权限控制等能力。

## ✨ 核心特性

- 🚀 **高性能**：基于Express框架，轻量高效，支持高并发
- 🔒 **安全可靠**：内置Helmet安全防护、CORS内网访问控制、JWT权限校验
- 📡 **实时通信**：集成WebSocket服务，支持消息推送、实时通知
- 🎯 **模块化设计**：路由、中间件、服务层分离，易于扩展和维护
- 📦 **开箱即用**：内置用户认证、模型管理、技能管理、聊天、任务等核心API
- ⚡ **开发友好**：TypeScript类型支持，热重载，完善的错误处理机制

## 🛠️ 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Node.js | >=18.x | 运行环境 |
| Express | 4.x | Web框架 |
| TypeScript | 5.x | 开发语言 |
| WebSocket | - | 实时通信 |
| SQLite | - | 本地数据存储 |
| pnpm | 8.x | 包管理工具 |

## 🚀 快速开始

### 环境要求

- Node.js >= 18.0.0
- pnpm >= 8.0.0

### 安装依赖

```bash
# 进入gateway目录
cd gateway

# 安装依赖
pnpm install
```

### 开发模式运行

```bash
pnpm dev
```

服务启动后默认运行在 `http://localhost:3100`

### 生产构建

```bash
pnpm build
```

### 生产运行

```bash
pnpm start
```

## 📁 项目结构

```
gateway/
├── src/
│   ├── api/                # 第三方API调用封装
│   ├── config/             # 配置文件
│   ├── middleware/         # 中间件（错误处理、权限校验等）
│   ├── routes/             # 路由定义
│   │   ├── auth.js         # 用户认证相关接口
│   │   ├── agent.js        # AI代理相关接口
│   │   ├── models.js       # 模型管理接口
│   │   ├── skills.js       # 技能管理接口
│   │   ├── skillHub.js     # 技能市场接口
│   │   ├── chat.js         # 聊天相关接口
│   │   ├── config.js       # 配置相关接口
│   │   ├── settings.js     # 设置相关接口
│   │   ├── tasks.js        # 任务管理接口
│   │   └── upload.js       # 文件上传接口
│   ├── services/           # 业务逻辑层
│   │   └── WebSocketService.js # WebSocket服务
│   ├── stores/             # 数据存储层
│   ├── utils/              # 工具函数
│   └── index.ts            # 服务入口文件
├── migrations/             # 数据库迁移文件
├── data/                   # 运行时数据存储目录
├── dist/                   # 构建输出目录
├── package.json
├── tsconfig.json
└── .npmrc
```

## 📡 API 接口

所有接口都以 `/api/v1` 为前缀：

| 接口前缀 | 说明 |
|----------|------|
| `/api/v1/auth` | 用户登录、登出、信息查询等认证相关接口 |
| `/api/v1/agent` | AI代理执行、工具调用相关接口 |
| `/api/v1/models` | 大语言模型的增删改查、配置管理 |
| `/api/v1/skills` | 本地技能的安装、卸载、运行管理 |
| `/api/v1/skill-hubs` | 技能市场搜索、安装、更新 |
| `/api/v1/chats` | 聊天会话、消息管理 |
| `/api/v1/config` | 系统配置获取、更新 |
| `/api/v1/settings` | 用户设置管理 |
| `/api/v1/tasks` | 定时任务、后台任务管理 |
| `/api/v1/upload` | 文件上传、资源管理 |

### 健康检查接口

```
GET /health
```

返回示例：
```json
{
  "status": "ok",
  "service": "gateway",
  "version": "2.0.0",
  "wsOnline": 1
}
```

## ⚙️ 配置说明

### CORS配置
默认仅允许内网地址访问，支持的内网地址范围：
- localhost
- 127.x.x.x
- 10.x.x.x
- 172.16.x.x ~ 172.31.x.x
- 192.168.x.x
- *.local 域名

### 端口配置
默认端口为3100，可以通过修改 `src/config/index.js` 中的 `appConfig.port` 调整。

### 上传限制
请求体大小限制为10MB，支持大文件上传。

## 🧩 WebSocket 服务

服务启动时自动挂载WebSocket服务，支持：
- 实时消息推送
- 任务进度通知
- AI代理执行状态同步
- 系统事件广播

连接地址：`ws://localhost:3100`

## 🔧 开发指南

### 新增API接口

1. 在 `src/routes/` 下创建对应的路由文件
2. 在 `src/index.ts` 中注册路由：
```typescript
import yourRoutes from './routes/yourRoutes.js';
app.use('/api/v1/your-path', yourRoutes);
```

### 新增业务逻辑

1. 在 `src/services/` 下创建对应的服务类
2. 在路由中引入并调用服务方法

### 数据库迁移

新增数据模型时，在 `migrations/` 目录下添加迁移文件，启动时自动执行迁移。

## 📝 常见问题

### 端口被占用
修改 `src/config/index.js` 中的端口配置，或者杀掉占用3100端口的进程：
```bash
npx kill-port 3100
```

### 跨域问题
默认仅允许内网访问，如果需要开放外网访问，修改 `src/index.ts` 中的CORS配置。

### 数据丢失
所有运行时数据都保存在 `data/` 目录下，备份该目录即可完整备份所有数据。

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目！