# actory-gateway

**Repository Path**: actory-suite/actory-gateway

## Basic Information

- **Project Name**: actory-gateway
- **Description**: Actory Suite — actory-gateway
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# actory-gateway

> Actory 的无状态流量入口。所有前端请求经过 gateway，验签后按路由规则分发到后端——不查库，不碰业务。

![Node.js](https://img.shields.io/badge/Node.js-22-green) ![Fastify](https://img.shields.io/badge/Fastify-5-blue) ![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue) ![port](https://img.shields.io/badge/port-3100-darkgreen)

---

## 目录

- [项目定位](#项目定位)
- [系统架构](#系统架构)
- [功能清单](#功能清单)
- [路由清单](#路由清单)
- [SSE 透传机制](#sse-透传机制)
- [跨仓协作](#跨仓协作)
- [项目结构](#项目结构)
- [开发指南](#开发指南)

---

## 项目定位

gateway 是 Actory 的**流量入口层**。前端所有请求先到 gateway，经 JWT 无状态验签后，按 54 条正则规则路由分发到 platform / engine / im-gateway 三个后端服务。

| ✅ 负责 | ❌ 不负责 |
|---------|---------|
| JWT 无状态验签（只看签名+过期） | Token 签发（在 platform） |
| 路由转发（54 条规则） | 业务逻辑 |
| SSE 长连接透传 | RBAC / 配额检查 |
| 限流（按租户） | 数据库操作 |
| Header 注入（X-User-Id 等） | |

---

## 系统架构

### 请求流转全链路

```
用户浏览器
    │
    │  /api/v1/*（next.config rewrite）
    ▼
┌──────────────────────────────────────────────────┐
│  gateway :3003                                    │
│                                                  │
│  中间件链（顺序敏感，前一层通过才进下一层）：      │
│                                                  │
│  请求 → ┌─ cors ──────── 跨域允许                │
│         ├─ rateLimit ─── 按租户限流               │
│         ├─ authPlugin ── JWT 验签                │
│         │   ├─ 白名单（/health）→ 放行           │
│         │   ├─ 验签失败 → 401 Unauthorized       │
│         │   └─ 验签成功 → 注入 req.user           │
│         ├─ headerInject ─ req.user → 请求头       │
│         │   X-User-Id / X-Tenant-Id /            │
│         │   X-User-Email / X-User-Role            │
│         └─ proxy ─────── 反向代理                 │
│             ├─ SSE 请求 → proxySSE（长连接无超时） │
│             └─ 普通请求 → proxyRequest             │
│                                                  │
└──────┬──────────┬──────────┬─────────────────────┘
       │          │          │
       │ 28条     │ 24条     │ 2条
       ▼          ▼          ▼
   platform    engine    im-gateway
   :3002       :8000     :8003
```

### 上游服务拓扑

```
┌─────────────────────────────────────────────┐
│              gateway :3003                   │
│                                             │
│  upstream 配置:                              │
│  ┌─ platform  → http://localhost:3002       │
│  ├─ engine    → http://localhost:8000       │
│  └─ im-gateway→ http://localhost:8003       │
│                                             │
│  匹配策略:                                    │
│  1. 按路由表顺序正则匹配                      │
│  2. /scenes/{id}/run 等运行态规则            │
│     放在 scenes CRUD 之前（前缀冲突裁决）     │
│  3. 未匹配的 /api/v1/* → 默认转发 engine     │
└─────────────────────────────────────────────┘
```

---

## 功能清单

| 模块 | 功能 | 说明 |
|------|------|------|
| **JWT 验签** | 无状态验证 | jose HS256，只看签名+过期，不查库不签发。白名单直接放行，失败返回 401 |
| **Token 提取** | Bearer 提取 | 从 `Authorization: Bearer ***` 提取纯 token 字符串 |
| **路由分发** | 54 条规则 | 正则匹配，按语义分流到 3 个后端服务 |
| **Header 注入** | 身份传递 | 验签后从 JWT payload 提取 userId/tenantId/email/role，注入为 `X-*` 请求头传给后端 |
| **SSE 透传** | 长连接转发 | 检测 `text/event-stream` + `/sse/` 路径 → 流式无超时转发 |
| **限流** | 租户级限流 | `@fastify/rate-limit`，按 `X-Tenant-Id` 限流 |
| **CORS** | 跨域配置 | 白名单跨域允许 |

---

## 路由清单

### → platform（28 条）— 设计态 + 运营治理 + 本体域

| 前缀 | 说明 |
|------|------|
| `/auth` | 认证签发（login / refresh / me / logout） |
| `/agents` `/agent-builder` `/agent-roles` | Agent 设计态 CRUD + 构建 + 角色模板 |
| `/skills` `/models` `/prompts` `/tools` | 技能市场 / 模型管理 / Prompt 版本 / 工具设计态 |
| `/knowledge` `/mcp` `/audit` | 知识库 / MCP Server / 审计日志 |
| `/tenants` `/billing` `/providers` | 租户管理 / 计费 / LLM Provider |
| `/alert` `/notifications` `/stats` `/constraint` | 告警 / 通知 / 统计 / 约束方案 |
| `/automations` `/users` `/roles` | 自动化触发器 / 用户 / 角色 |
| `/delivery` | ★R14 IM 渠道管理面 |
| `/scenes` | 场景 CRUD + publish（不含 /run） |
| `/ontology` `/ask` | ★R12 本体域 + 自然语言查询 |
| `/datasets` `/data-sources` `/data-syncs` `/pipelines` | ★R12 数据管道 |

### → engine（24 条）— 运行态

| 前缀 | 说明 |
|------|------|
| `/scenes/{id}/run` | ★ 场景执行（方案 C 双态） |
| `/scenes/{id}/executions` | ★ 场景执行历史 |
| `/executions` | ★ 执行查询（ExecutionDto） |
| `/scenes/{id}/orchestrate` `/agent/orchestrate` | 多 Agent 编排 |
| `/chat` `/sse/*` | 对话入口 / SSE 实时事件流 |
| `/task/*` `/hitl/*` | 任务控制（status/result/cancel/retry/progress/stream）/ 人工审批 |
| `/playground/*` `/traces/*` | Playground 调试 / 轨迹回放 |
| `/results` `/report` `/rails` | 结果查询 / 报告 / Rail 链状态 |
| `/evolution` `/observability` | 进化闭环 / 可观测性 |
| `/session` `/feedback` `/eval` `/nlu` | 会话 / 反馈 / 评测 / 意图识别 |
| `/storage` `/file` | 对象存储 / 文件管理 |

### → im-gateway（2 条）— R14 IM 渠道

| 前缀 | 说明 |
|------|------|
| `/im/webhook` | IM 平台 webhook 接收（飞书/企微/钉钉/Telegram） |
| `/im/health` | im-gateway 健康检查 |

> **兜底策略**：未匹配的 `/api/v1/*` 默认转发到 engine。

---

## SSE 透传机制

```
普通请求                              SSE 请求
    │                                     │
    ▼                                     ▼
proxyRequest                         proxySSE
    │                                     │
    ├─ 标准 HTTP 转发                     ├─ reply.hijack() 接管 socket
    ├─ 有超时                              ├─ 无超时（长连接保持）
    ├─ 有 buffer                           ├─ 无 buffer（流式直传）
    └─ 有压缩                              └─ 无压缩
```

**检测条件**（满足任一即走 SSE 通道）：
- Response `content-type` 含 `text/event-stream`
- 请求路径含 `/sse/`
- 请求路径含 `/events`

---

## 跨仓协作

### 依赖关系

```
┌──────────┐     ┌──────────┐     ┌──────────┐
│ frontend │────→│ gateway  │────→│ platform │
└──────────┘     └────┬─────┘     └──────────┘
                      │
              ┌───────┼───────┐
              ▼       ▼       ▼
          ┌──────┐ ┌─────┐ ┌──────────┐
          │engine│ │engine│ │im-gateway│
          │      │ │     │ │          │
          └──────┘ └─────┘ └──────────┘
```

### 协作矩阵

| 方向 | 说明 |
|------|------|
| frontend → gateway | 统一 `/api/v1/*` 前缀，next.config rewrite 到 :3003 |
| gateway → platform | JWT 共享密钥验签 + 路由转发 |
| gateway → engine | 路由转发 + SSE 透传 |
| gateway → im-gateway | ★R14 webhook 转发 |
| contracts → gateway | OpenAPI spec 定义路径 → 路由规则对齐 |

### 铁律

- **零 DB**：无 Prisma / 无数据库引用
- **零业务逻辑**：只验签 + 转发
- **零 Token 签发**：签发在 platform，gateway 只验签

---

## 项目结构

```
actory-gateway/
├── src/
│   ├── index.ts                    Fastify 启动 + 中间件注册链 + /health
│   │
│   ├── auth/                       JWT 验签（3 文件）
│   │   ├── jwt-verify.ts           jose HS256 签名验证 + 过期检查
│   │   ├── auth-plugin.ts           onRequest hook：白名单 + 验签 + 注入 req.user
│   │   └── token-extract.ts        Bearer token 提取
│   │
│   ├── router/                     路由层（2 文件）
│   │   ├── route-table.ts          54 条正则规则 + matchRoute() 匹配函数
│   │   └── upstream.ts             上游服务地址配置
│   │
│   ├── proxy/                      反向代理（1 文件）
│   │   └── proxy.ts                SSE 检测 + proxySSE / proxyRequest 分流
│   │
│   └── middleware/                 中间件（2 文件）
│       ├── header-inject.ts        req.user → X-User-Id / X-Tenant-Id / X-User-Role
│       └── rate-limit.ts           @fastify/rate-limit（按租户）
│
├── docs/
│   └── Gateway-仓库架构设计.md
├── package.json
└── .env.example
```

---

## 开发指南

```bash
pnpm install
cp .env.example .env     # 配置 JWT_SECRET
pnpm dev                  # → http://localhost:3003/health
```

### 配置项

| 环境变量 | 必填 | 默认值 | 说明 |
|----------|------|--------|------|
| `PORT` | — | 3003 | 监听端口 |
| `JWT_SECRET` | ✅ | — | HS256 密钥（与 platform 一致） |
| `PLATFORM_URL` | — | http://localhost:3002 | |
| `ENGINE_URL` | — | http://localhost:8000 | |
| `IM_GATEWAY_URL` | — | http://localhost:8003 | |
| `RATE_LIMIT_MAX` | — | 100 | 每租户每分钟请求上限 |
| `CORS_ORIGIN` | — | * | CORS 允许源 |

### 门禁

```bash
npx tsc --noEmit     # 类型检查 ✅
npx vitest run        # ⚠️ 0 测试（待补）
```
## 文档

仓库详细设计见 [docs/README.md](./docs/README.md)（架构蓝图 / 仓库架构设计）。