# jingyu

**Repository Path**: stdtnt/jingyu

## Basic Information

- **Project Name**: jingyu
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JYAI — 企业级 AI 平台

整合 Hermes Agent 对话能力与 Yuxi-Know 知识库管理，支持数据源管理 + NL2SQL，多租户容器化部署。

---

## 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                       用户浏览器 (SPA)                          │
│                   http://localhost:8080                         │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                    ┌─────▼──────────────────────────────────┐
                    │           Nginx / OpenResty             │
                    │          端口 :8080                      │
                    │                                        │
                    │  /api/auth/*  → backend:8001            │
                    │  /api/knowledge/* → backend:8001        │
                    │  /api/datasource/* → backend:8001       │
                    │  /api/nl2sql/* → backend:8001           │
                    │  /api/system/* → backend:8001           │
                    │  /socket.io/* → Koa:8648               │
                    │  /api/hermes/* → Lua 动态路由            │
                    │     ├── JWT 查用户 gateway              │
                    │     └── 转发到对应用户 Pod              │
                    │  /  → SPA 静态文件                      │
                    └─────┬──────────────────────────────────┘
                          │
          ┌───────────────┼──────────────────────────────┐
          │               │                              │
    ┌─────▼─────┐  ┌──────▼──────┐  ┌──────────────────┐ │
    │ Koa 后端   │  │ Python 后端  │  │  Hermes Agent    │ │
    │ :8648     │  │ :8001       │  │  Gateway (:8787)  │ │
    │           │  │             │  │                   │ │
    │ 聊天/会话  │  │ 认证/用户    │  │  消息网关          │ │
    │ Agent 管理 │  │ 知识库管理   │  │  Agent 调度       │ │
    │ Skill/任务 │  │ 数据源/NL2SQL│  │                   │ │
    │ 网关管理   │  │ 部门/图谱    │  │                   │ │
    └─────┬─────┘  └──────┬──────┘  └──────────────────┘ │
          │               │                              │
          └───────────────┼──────────────────────────────┘
                          │
          ┌───────────────┼──────────────────────────────┐
          │               │                              │
    ┌─────▼─────┐  ┌──────▼──────┐  ┌──────────────────┐
    │ PostgreSQL │  │   Milvus    │  │      Redis       │
    │     :5432  │  │   :19530    │  │      :6379       │
    │            │  │             │  │                   │
    │ 主数据库    │  │ 向量检索     │  │ 模型缓存          │
    └───────────┘  └─────────────┘  └──────────────────┘

    ┌──────────────────┐  ┌──────────────────┐
    │     Neo4j        │  │     MinIO        │
    │     :7687        │  │     :9000        │
    │                  │  │                  │
    │ 知识图谱          │  │ 文件存储          │
    └──────────────────┘  └──────────────────┘
```

### 多用户部署架构

每个用户一个 Pod（Koa + Gateway），Nginx + Lua 根据 JWT 动态路由：

```
用户 A → Nginx → Lua 查 gateway → Pod A [Koa + Gateway]
用户 B → Nginx → Lua 查 gateway → Pod B [Koa + Gateway]
         ↓
    共享服务: backend + PostgreSQL + Milvus + Neo4j + MinIO
```

前端 SPA 由 Nginx 全局 serve，不进入用户 Pod。

---

## 目录结构

```
├── web/                        前端 SPA (Vue 3 + Vite)
│   ├── src/                    源代码
│   │   ├── components/         UI 组件
│   │   │   ├── hermes/         Hermes 相关组件
│   │   │   └── layout/         布局组件（侧边栏、导航）
│   │   ├── views/              Hermes 页面
│   │   ├── stores/             Pinia 状态管理
│   │   ├── domains/           业务域模块
│   │   │   ├── knowledge/      知识库管理
│   │   │   ├── datasource/     数据源管理
│   │   │   └── yuxi-shared/    共享组件/工具
│   │   └── router/             路由配置
│   ├── dist/                   构建产物（生产用）
│   ├── package.json
│   └── vite.config.ts
│
├── koa/                        Koa 后端 (TypeScript)
│   ├── src/                    源代码
│   │   ├── routes/             HTTP 路由
│   │   ├── services/           业务服务
│   │   │   └── hermes/         Hermes 服务
│   │   │       ├── run-chat/   聊天运行
│   │   │       └── agent-bridge/ Agent 桥接
│   │   ├── controllers/        控制器
│   │   ├── db/                 数据库层
│   │   └── middleware/         中间件
│   ├── data/                   SQLite 数据库（运行时）
│   └── package.json
│
├── backend/                    Python 后端 (FastAPI)
│   ├── app/                    应用层
│   │   ├── routers/            API 路由
│   │   └── main.py             入口
│   ├── core/                   核心业务
│   │   ├── knowledge/          知识库引擎
│   │   ├── datasource/         数据源管理
│   │   ├── nl2sql/             NL2SQL 模块
│   │   ├── auth/               认证
│   │   └── models/             模型管理
│   └── data/                   运行时数据
│
├── nginx/                      Nginx 配置
│   ├── conf.d/default.conf     路由规则
│   └── lua/proxy.lua           动态路由 Lua 脚本
│
├── proxy-server/               代理服务
│   ├── forward-proxy.js        透明正向代理 (:3128) [未使用，见下文]
│   └── container-manager.js    容器编排
│
├── desktop/                    Electron 桌面端（可选）
├── docker/                      Docker 配置
├── docs/                       文档
└── scripts/                    工具脚本
```

---

## 核心组件

| 组件 | 技术栈 | 端口 | 职责 |
|------|--------|:----:|------|
| **Nginx** | OpenResty + Lua | **8080** | **统一入口 + SPA serve + 动态路由** |
| 前端 SPA | Vue 3 + Vite | nginx serve | 管理界面 |
| **Koa** | Node.js/Koa | **8648** | 聊天/会话/技能/网关管理 |
| **backend** | Python/FastAPI | **8001** | 认证/知识库/数据源/NL2SQL/用户 |
| Hermes Gateway | Python | 8787 | Agent 消息网关 |
| forward-proxy | Node.js | 3128 | Pod 出站代理（当前未使用，详见下方说明） |
| PostgreSQL | 16 | 5432 | 主数据库 |
| Milvus | 2.5 | 19530 | 向量检索 |
| Neo4j | 5.26 | 7687 | 知识图谱 |
| Redis | 7 | 6379 | 模型缓存 |
| MinIO | - | 9000 | 文件存储 |

### 关于 forward-proxy

`proxy-server/forward-proxy.js` **目前未被使用**，保留仅作参考。

**为什么不需要了：** Agent（Hermes Gateway）访问 backend 时，请求经过 Koa 转发，由 Koa 完成认证。不再需要 forward-proxy 做 JWT 注入和出站代理。

**如果以后需要：** 当 Pod 需要独立出站代理（如访问外部 API 时统一鉴权/审计），可重新启用。

---

## 开发环境启动

### 前置条件

- Python 3.12+
- Node.js 23+
- Docker + Docker Compose
- OpenResty（可选，开发时可直连前端 Vite dev server）

### 1. 启动基础设施（数据库/中间件）

```bash
# 启动 PostgreSQL、Milvus、Neo4j、Redis、MinIO
docker compose -f docker-compose-middleware.yaml up -d
```

### 2. 启动 Python 后端

```bash
cd backend

# 激活虚拟环境
source .venv/bin/activate

# 启动 FastAPI 服务
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
```

### 3. 启动 Koa 后端

```bash
cd koa
npm install
npx tsx src/index.ts
```

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

```bash
cd web
npm install
npx vite --host --port 8649
```

前端开发服务器通过 Vite 反向代理到 Koa（`:8648`），API 请求自动转发。

### 5. 访问

- **前端开发**：`http://localhost:8649`（Vite dev server，热更新）
- **前端生产**：`http://localhost:8080`（通过 Nginx 构建）
- **Koa API**：`http://localhost:8648`
- **Python API**：`http://localhost:8001`

---

## 生产环境部署

### 1. 构建前端

```bash
cd web
npm install
npm run build     # 输出到 web/dist/
```

### 2. 安装 OpenResty（首次部署）

```bash
brew tap openresty/brew
brew install openresty
opm get ledgetech/lua-resty-http
```

### 3. 配置 Nginx

前端静态文件目录指向 `web/dist/`：

```nginx
# nginx/conf.d/default.conf
location / {
    root /path/to/web/dist;      # 改为实际路径
    try_files $uri $uri/ /index.html;
}
```

### 4. 启动服务

```bash
# 1) 基础设施
docker compose -f docker-compose-middleware.yaml up -d

# 2) Python 后端
cd backend
.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001

nohup .venv/bin/python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8001 > /tmp/backend.log 2>&1 &

# 3) Koa 后端
cd koa
npx tsx src/index.ts

# 4) Nginx
openresty -p $(pwd)/nginx -c conf.d/default.conf
```

### 5. 验证

打开 `http://localhost:8080`，使用默认管理员账号登录：

- 账号：`admin`
- 密码：`admin123`

---

## 路由总览

| 路径 | 目标 | 说明 |
|------|------|------|
| `/bk_api/auth/*` | backend:8001 | 用户认证 |
| `/bk_api/knowledge/*` | backend:8001 | 知识库管理 |
| `/bk_api/datasource/*` | backend:8001 | 数据源管理 |
| `/bk_api/nl2sql/*` | backend:8001 | 自然语言转 SQL |
| `/bk_api/system/*` | backend:8001 | 系统/模型配置 |
| `/bk_api/departments/*` | backend:8001 | 部门管理 |
| `/bk_api/graph/*` | backend:8001 | 知识图谱 |
| `/bk_api/evaluation/*` | backend:8001 | 评估 |
| `/bk_api/mindmap/*` | backend:8001 | 思维导图 |
| `/api/hermes/*` | Lua → 用户 Pod | 聊天/会话/技能 |
| `/socket.io/*` | Koa:8648 | WebSocket（聊天） |
| `/` | SPA 静态文件 | 前端页面 |