# 集成架构

在您设计需要依赖 Luxonis Hub 的客户门户、运营仪表板或后端集成时，请参考本页面。它说明了生产环境集成的默认架构，以及身份验证、控制平面 API 调用和浏览器会话引导应处于的位置。

## 经典架构

对于大多数生产部署，Luxonis Hub 应位于您自己的产品后端之后，而不是作为主要前端身份验证边界。

默认的集成模型如下：

 1. 客户用户向您的产品进行身份验证。
 2. 您的前端调用您的后端。
 3. 您的后端调用 Luxonis Hub API 和浏览器会话引导操作。
 4. 您的前端只接收其渲染、控制或设备会话所需的衍生有效载荷。

请明确遵守以下规则：

 * 客户身份验证保持在您的用户、您的前端和您的后端之间。
 * Hub API 密钥仅保留在您的后端或服务器端工具中。
 * 浏览器不应接收 Hub API 密钥。

### cloud.api.integration-architecture.toml

```toml
[config]
height = 190

[[nodes]]
id = "customer_frontend"
type = "default"
position.x = 0
position.y = 48
sourcePosition = "right"
targetPosition = "left"
style.width = 170
style.fontSize = "15px"
style.backgroundColor = "#ffffff"
style.border = "1px solid #cbd5e1"
style.borderRadius = "16px"
data.label = "Customer frontend"

[[nodes]]
id = "customer_backend"
type = "default"
position.x = 210
position.y = 48
sourcePosition = "right"
targetPosition = "left"
style.width = 170
style.fontSize = "15px"
style.backgroundColor = "#ffffff"
style.border = "1px solid #cbd5e1"
style.borderRadius = "16px"
data.label = "Customer backend"

[[nodes]]
id = "luxonis_hub_api"
type = "default"
position.x = 420
position.y = 48
sourcePosition = "right"
targetPosition = "left"
style.width = 170
style.fontSize = "15px"
style.backgroundColor = "#dbeafe"
style.border = "1px solid #93c5fd"
style.borderRadius = "16px"
data.label = "Luxonis Hub API"

[[edges]]
id = "customer_frontend__customer_backend"
source = "customer_frontend"
target = "customer_backend"
type = "straight"
markerStart = "arrowclosed"
markerEnd = "arrowclosed"
zIndex = 50
style.strokeWidth = 1.5
style.stroke = "#94a3b8"

[[edges]]
id = "customer_backend__luxonis_hub_api"
source = "customer_backend"
target = "luxonis_hub_api"
type = "straight"
markerStart = "arrowclosed"
markerEnd = "arrowclosed"
zIndex = 50
style.strokeWidth = 1.5
style.stroke = "#94a3b8"
```

## 典型集成流程

这是面向客户的 Hub 集成最常见的实际形态：

 1. 用户打开您的客户门户或内部运营界面。
 2. 您的前端向您的后端请求设备状态、应用状态或会话访问权限。
 3. 您的后端调用 Luxonis Hub GraphQL，并在必要时调用会话引导操作。
 4. 您的后端仅返回您的前端所需的应用程序数据或连接有效载荷。
 5. 您的前端渲染结果或打开远程会话。

这样可将身份验证和 Hub 凭据保留在服务器端，同时在需要时仍允许直接的浏览器端会话传输。

## 公共 API 划分

Luxonis Hub 目前对外提供两种客户导向的 API 风格：

 * GraphQL 控制 API：用于设备、应用、快照、控制平面读取、修改和浏览器会话引导。
 * REST 模型 API：用于高级模型注册和转换自动化。

这种划分是正常的。如果您的产品同时使用车队控制和工作流管理，您将需要与两者集成。

对于外部 GraphQL 集成，请使用公共的 team { ... } 查询面。

## 浏览器会话引导

对于浏览器端的设备和应用会话，您的后端应调用 GraphQL 控制 API，并将引导有效载荷返回给前端。

相关的 GraphQL 操作包括：

 * requestDeviceWebrtcConfig：用于设备会话（如 Web 终端和实时日志）
 * requestDeviceAppConnection：通过 oak-webrtc 实现应用和可视化器会话

这样可将 Hub 凭据保留在您的后端，同时允许浏览器直接连接到远程会话传输通道。

## 前端渲染指南

对于客户门户，推荐的渲染原语是可视化器 (visualizer)。

当您需要以下功能时，请使用可视化器：

 * 实时视频
 * 检测结果和叠加层
 * 更丰富的输出，如点云

若可视化器不适用，可将完全自定义渲染视为高级/自定义路径。

直接同局域网 websocket 或设备本地访问仍可用作备用路径，但它并非客户门户的标准远程集成模型。

## 当前产品边界

在您的集成设计中，请明确以下边界：

 * Hub API 密钥目前是全员可访问的团队秘密。
 * 请结合模式检查使用官方的 GraphQL 指南和参考页面。
 * Webhook 目前还不是广泛稳定的公共集成面。
 * 基于清单的发布和大规模部署编排功能目前不可用。
 * 自托管的主机操作系统仍由客户自行管理。

## 后续步骤

### 关于 GraphQL

了解用于控制平面集成的公共 `team { ... }` 请求结构。

[关于 GraphQL](https://docs.luxonis.com/cloud/api/graphql.md)

### 流媒体与可视化器

使用推荐的后端中介引导流程，用于浏览器会话和客户门户。

[流媒体与可视化器](https://docs.luxonis.com/cloud/api/guides/streaming-and-visualizer.md)

### 设备管理

从用于列出和检查设备的公共读取路径开始。

[设备管理](https://docs.luxonis.com/cloud/api/guides/device-management.md)

### 模型 API

使用独立的模型 API 进行高级模型注册和转换自动化。

[模型 API](https://docs.luxonis.com/cloud/api/reference/models-api.md)