10 · 前端应用（Frontend Application）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节10 状态全文译文模块界面与交互、文档对象与元数据、系统架构、安装与启动

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Frontend Application 上一章9.4 下一章10.1

源码线索

.github/actions/setup-python-and-install-dependencies/action.yml
.github/actions/setup-test-license/action.yml
backend/Dockerfile
backend/Dockerfile.model_server
backend/scripts/seed_dev_license.py
backend/tests/daily/conftest.py
backend/tests/daily/embedding/test_embeddings.py
backend/tests/integration/Dockerfile
backend/tests/integration/mock_services/mock_connector_server/Dockerfile
backend/tests/utils/__init__.py

模块标签

界面与交互
文档对象与元数据
系统架构
安装与启动
测试、发布与运维

章节正文

前端应用

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/10-frontend-application

前端应用

目的与范围

本文档介绍了作为 Onyx 用户界面的 Next.js 前端应用。该前端是一个基于 Next.js 16 构建的独立 React 应用，提供聊天界面、管理仪表盘和搜索功能。关于该前端通信的后端 API，请参阅后端核心系统。关于包括 Docker Compose 配置在内的部署信息，请参阅Docker Compose 部署。

前端应用位于 web/ 目录下，包含以下内容：

基于 React 19 和 TypeScript 的 Next.js 应用。
服务端渲染（SSR）和静态站点生成能力。
基于 Tailwind CSS 构建的自定义主题系统。
通过服务器发送事件（SSE）实现的实时流式传输。
通过 Sentry 和 PostHog 实现的全面监控。

应用结构与配置

该应用使用 Next.js 16.2.6，并在 web/next.config.js web/next.config.js:19-167 中定义了若干关键配置。它使用 standalone 输出模式生成适合容器化环境的最小化生产构建包 web/next.config.js:21。关于脚本、Sentry 集成和分析代理的深入介绍，请参阅应用结构与配置。

关键配置选项：

配置项	值	用途
`output`	`"standalone"`	生成用于 Docker 部署的最小化生产构建包 `web/next.config.js:21`
`transpilePackages`	`["@onyx-ai/opal"]`	转译内部 Opal 设计系统包 `web/next.config.js:22`
`typedRoutes`	`true`	启用 TypeScript 类型安全路由 `web/next.config.js:23`
`reactCompiler`	`true`	启用 React 19 的提前编译以提升性能 `web/next.config.js:24`

Onyx · 应用结构与配置 · 图 1

来源： web/next.config.js:19-167, web/package.json:84-154, web/Dockerfile:1-173

样式与主题系统

Onyx 使用基于 Tailwind CSS 构建的设计令牌驱动样式系统。关于设计令牌、自定义断点和 Opal 组件库的详细信息，请参阅样式与主题系统。

排版与变量

该应用实现了基于基础 CSS 层中定义的设计令牌的全面排版系统 web/src/app/globals.css:175-320。所有颜色和间距都映射到 CSS 变量，以实现动态主题 web/tailwind-themes/tailwind.config.js:95-174。

变量	字体栈	用途
`--font-hanken-grotesk`	"Hanken Grotesk", sans-serif	主要 UI 字体 `web/src/app/globals.css:181`
`--font-dm-mono`	"DM Mono", monospace	代码和技术内容 `web/src/app/globals.css:183`
`--font-kh-teka`	"KH Teka", sans-serif	品牌/Logo 字体 `web/src/app/globals.css:185`

布局架构

该应用为不同功能区使用专门的布局。主要聊天体验由 AppPage 驱动 web/src/refresh-pages/AppPage.tsx:111，而管理组件则组织在 admin 布局结构中。

Onyx · 布局架构 · 图 2

来源： web/src/app/globals.css:1-320, web/tailwind-themes/tailwind.config.js:1-174, web/src/refresh-pages/AppPage.tsx:111-177

状态管理

该应用利用 SWR 进行服务端状态同步，使用 Zustand 进行客户端状态管理。关于 useLlmManager 等特定钩子或过滤模式的文档，请参阅状态管理。

数据获取与钩子

前端使用自定义钩子管理复杂的领域逻辑，例如使用 useChatSessions 管理历史记录，使用 useAgents 管理助手选择 web/src/refresh-pages/AppPage.tsx:141-174。

Onyx · 数据获取与钩子 · 图 3

来源： web/package.json:108, 114, web/src/refresh-pages/AppPage.tsx:141-174, web/src/sections/input/AppInputBar.tsx:67-68

类型系统与数据模型

前端维护了一个健壮的 TypeScript 类型系统，与后端模型保持一致以确保一致性。关于 User、Connector 和 ChatMessage 等接口的完整参考，请参阅类型系统与数据模型。

核心实体：

角色/助手：由 MinimalPersonaSnapshot 表示 web/src/sections/input/AppInputBar.tsx:12。
文档：由 MinimalOnyxDocument web/src/refresh-pages/AppPage.tsx:12 和 OnyxDocument 表示。
文件：通过 ProjectFile 和 UserFileStatus 接口管理 web/src/sections/input/AppInputBar.tsx:35-37。

来源： web/src/refresh-pages/AppPage.tsx:12, 33, web/src/sections/input/AppInputBar.tsx:12-37

构建与安全

Docker 多阶段构建

前端使用 web/Dockerfile web/Dockerfile:1-173 中定义的两阶段 Docker 构建流程。

构建阶段：使用 npm ci 和 next build 安装依赖并构建 Next.js 应用 web/Dockerfile:11-89。
运行阶段：使用 Alpine Linux 创建轻量级生产镜像，仅复制必要的 standalone 文件和静态资源 web/Dockerfile:92-173。

安全加固

CSP 请求头：在 next.config.js 中定义了严格的内容安全策略（CSP）请求头，以防止 XSS 攻击和未授权资源加载 web/next.config.js:4-16。
非 root 执行：生产镜像以专用 nextjs 用户（UID 1001）身份运行，遵循安全最佳实践 web/Dockerfile:107-109。
遥测：在构建和运行时环境中均显式禁用了 Next.js 遥测功能 web/Dockerfile:31, 104。

来源： web/Dockerfile:1-173, web/next.config.js:4-79