10 · 前端应用（Frontend Application）

企业连接器与统一搜索 · 本章是 Onyx DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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

翻译时间：2026-05-27T08:44:48.827Z

翻译模型：deepseek-chat

原文字符数：10774

项目：Onyx (onyx)

---

前端应用

目的与范围

本文档介绍了作为 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`

graph TB
    subgraph ["Next.js 应用结构"]
        NextConfig["next.config.js<br/>- output: standalone<br/>- transpilePackages<br/>- typedRoutes"]
        PackageJson["package.json<br/>- next: 16.2.6<br/>- react: 19.2.4<br/>- typescript: 5.9.3"]
        TailwindConfig["tailwind.config.js<br/>- 主题合并<br/>- NEXT_PUBLIC_THEME"]
        GlobalCSS["src/app/globals.css<br/>- 排版系统<br/>- CSS 变量<br/>- 自定义动画"]
    end

    subgraph ["配置流程"]
        EnvVars["环境变量<br/>NEXT_PUBLIC_*"]
        BuildArgs["Docker 构建参数<br/>ARG NEXT_PUBLIC_*"]
        RuntimeEnv["运行时环境<br/>ENV 变量"]
    end

    PackageJson --> NextConfig
    NextConfig --> EnvVars
    TailwindConfig --> GlobalCSS
    EnvVars --> BuildArgs
    BuildArgs --> RuntimeEnv
    NextConfig --> Standalone[".next/standalone"]

来源： 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 布局结构中。

graph LR
    subgraph ["代码实体：UI 组件"]
        AppPage["AppPage<br/>web/src/refresh-pages/AppPage.tsx"]
        AppInputBar["AppInputBar<br/>web/src/sections/input/AppInputBar.tsx"]
        ChatUI["ChatUI<br/>web/src/sections/chat/ChatUI.tsx"]
        DocumentsSidebar["DocumentsSidebar<br/>web/src/sections/document-sidebar/DocumentsSidebar.tsx"]
    end

    subgraph ["自然语言：UI 区域"]
        ChatInterface["主要聊天体验"]
        InputRegion["消息输入与工具"]
        ResultsRegion["消息流与搜索结果"]
        SidebarRegion["文档参考面板"]
    end

    ChatInterface --> AppPage
    AppPage --> AppInputBar
    AppPage --> ChatUI
    AppPage --> DocumentsSidebar
    AppInputBar --> InputRegion
    ChatUI --> ResultsRegion
    DocumentsSidebar --> SidebarRegion

来源： 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。

graph TB
    subgraph ["代码实体：状态与数据"]
        SWR["swr 包<br/>（远程状态）"]
        Zustand["zustand 包<br/>（本地存储）"]
        useChatSessions["useChatSessions<br/>（钩子）"]
        useChatSessionStore["useChatSessionStore<br/>（Zustand 存储）"]
        useLlmManager["useLlmManager<br/>（钩子）"]
    end

    subgraph ["自然语言：应用状态"]
        SessionHistory["对话历史"]
        CurrentMessage["活跃聊天状态"]
        LLMConfig["模型与提供商设置"]
    end

    SessionHistory --> useChatSessions
    useChatSessions --> SWR
    CurrentMessage --> useChatSessionStore
    useChatSessionStore --> Zustand
    LLMConfig --> useLlmManager

来源： 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