agentic_huge_data_base / wiki
页面 Onyx · 10.1 应用结构与配置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 10.1

10.1 · 应用结构与配置（Application Structure and Configuration）

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

项目Onyx 章节10.1 状态全文译文 模块配置治理、测试、发布与运维、系统架构、安装与启动
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Application Structure and Configuration 上一章10 下一章10.2
源码线索
  • .github/actions/setup-python-and-install-dependencies/action.yml
  • .github/actions/setup-test-license/action.yml
  • backend/Dockerfile
  • backend/Dockerfile.model_server
  • backend/onyx/auth/email_utils.py
  • 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
模块标签
  • 配置治理
  • 测试、发布与运维
  • 系统架构
  • 安装与启动
  • 接口与服务契约

章节正文

应用结构与配置

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/10.1-application-structure-and-configuration

应用结构与配置

相关源文件

本章引用的主要源码文件：

  • .github/actions/setup-python-and-install-dependencies/action.yml
  • .github/actions/setup-test-license/action.yml
  • backend/Dockerfile
  • backend/Dockerfile.model_server
  • backend/onyx/auth/email_utils.py
  • 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
  • backend/tests/utils/aws_secrets.py
  • backend/tests/utils/pytest_secrets.py
  • backend/tests/utils/secret_names.py
  • web/Dockerfile
  • web/README.md
  • web/next.config.js
  • web/package-lock.json
  • web/package.json
  • web/src/app/auth/join/page.tsx
  • web/src/app/auth/login/EmailPasswordForm.tsx
  • web/src/app/auth/login/LoginPage.tsx
  • web/src/app/auth/login/SignInButton.tsx
  • web/src/app/auth/login/page.tsx
  • web/src/app/auth/signup/page.tsx
  • web/src/app/auth/verify-email/Verify.tsx
  • web/src/app/auth/waiting-on-verification/page.tsx
  • web/src/app/layout.tsx
  • web/src/app/page.tsx
  • web/src/components/OnyxInitializingLoader.tsx
  • web/src/components/auth/AuthFlowContainer.tsx
  • web/src/components/settings/lib.ts
  • web/src/hooks/useCurrentUser.ts
  • web/src/lib/constants.ts
  • web/src/lib/user.ts
  • web/src/lib/userSS.ts
  • web/tailwind.config.js
  • web/tests/e2e/auth/email_verification.spec.ts

本文档介绍 Next.js 前端应用的结构、配置文件、构建系统和环境变量。它涵盖了位于 web/ 目录下的 Web 应用的技术架构，包括 Next.js 配置、Docker 构建流程、依赖管理和基于环境的定制化配置。

有关样式和主题的信息，请参阅 10.2 样式与主题系统。有关状态管理模式，请参阅 10.3 状态管理。有关 TypeScript 类型定义，请参阅 10.4 类型系统与数据模型。

Next.js 应用架构

Onyx 前端是一个使用 App Router 架构的 Next.js 16 应用，基于 React 19 构建 web/package.json:84,89。该应用配置为独立应用的生产部署模式，并启用了多项优化。

核心配置
Onyx · 核心配置 · 图 1
Onyx · 核心配置 · 图 1

来源： web/next.config.js:19-24, web/package.json:1-31, web/src/app/layout.tsx:24-131

Next.js 配置特性

next.config.js 文件定义了生产环境的几个关键设置：

设置项值用途
output"standalone"自动利用输出追踪，仅打包必要文件以减小镜像体积 web/next.config.js:21。
transpilePackages["@onyx-ai/opal"]转译本地工作区组件库 web/next.config.js:22。
reactCompilertrue启用 React 编译器以实现自动记忆化 web/next.config.js:24。
images.unoptimizedtrue禁用图片优化，避免在所有环境中依赖 Sharp 库 web/next.config.js:35。

来源： web/next.config.js:19-36

API 重写与重定向

应用使用重写机制代理后端 API 请求，并通过重定向保持向后兼容性：

  • PostHog 代理：通过 /ph_ingest 代理分析流量，以规避广告拦截器。它会路由到 NEXT_PUBLIC_POSTHOG_HOST，或默认使用 https://us.i.posthog.com web/next.config.js:83-91。
  • 后端代理：将 /api/docs 和 /openapi.json 代理到 INTERNAL_URL（默认为 http://localhost:8080）web/next.config.js:93-110。
  • 旧版重定向：将 /chat 重定向到 /app，将旧版 /assistants 路径重定向到 /agents（例如 /admin/assistants 重定向到 /admin/agents）web/next.config.js:115-165。

来源： web/next.config.js:80-167

环境变量

Onyx 区分了仅服务端使用的变量和通过 NEXT_PUBLIC_ 前缀暴露给客户端的变量。

关键环境变量
变量作用域用途
AUTH_TYPE服务端决定认证方式（basic、google_oauth、oidc 等）web/src/lib/constants.ts:24-25。
INTERNAL_URL服务端FastAPI 后端的内部地址 web/src/lib/constants.ts:13。
WEB_DOMAIN服务端Web 应用的公网访问地址 web/src/lib/constants.ts:11。
NEXT_PUBLIC_CLOUD_ENABLED客户端启用云服务专属的 UI 功能 web/src/lib/constants.ts:68-69。
NEXT_PUBLIC_POSTHOG_KEY客户端PostHog 分析集成的密钥 web/Dockerfile:138。
NEXT_PUBLIC_SENTRY_DSN客户端Sentry 错误追踪的 DSN web/Dockerfile:144。
ENABLE_PAID_ENTERPRISE_EDITION_FEATURES服务端切换企业版专属功能 web/src/lib/constants.ts:50-53。

来源： web/src/lib/constants.ts:1-87, web/Dockerfile:124-167

Docker 构建系统

Web 应用使用多阶段 Docker 构建来生成精简的生产镜像。

构建管线
Onyx · 构建管线 · 图 2
Onyx · 构建管线 · 图 2
  1. 构建阶段：安装依赖，包括用于 Alpine 兼容性的 libc6-compat web/Dockerfile:13。它将构建时的 ARG 值设置为 ENV，以便 Next.js 将其嵌入客户端包中 web/Dockerfile:38-78。
  2. 运行阶段：出于安全考虑，使用非 root 用户 nextjs web/Dockerfile:107-109。仅复制 standalone 文件夹和 static 资源，以最小化镜像体积 web/Dockerfile:116-117。

来源： web/Dockerfile:1-174

依赖管理

项目使用基于工作区的结构，通过 npm 进行管理。

核心依赖
  • 框架：Next.js 16.2.6，React 19.2.4 web/package.json:84,89。
  • 组件库：位于 web/lib/opal 的 @onyx-ai/opal web/package.json:40。
  • UI 原语：Radix UI（Accordion、Dialog、Popover 等）和 Headless UI web/package.json:38-58。
  • 数据获取：swr 用于客户端缓存 web/package.json:108。
  • 分析：posthog-js web/package.json:87。
  • 错误追踪：@sentry/nextjs web/package.json:59。

来源： web/package.json:32-115, web/package-lock.json:7-96

包脚本

package.json 包含开发周期的标准脚本：

  • npm run dev：启动开发服务器 web/package.json:9。
  • npm run build：触发生产环境的 Next.js 构建 web/package.json:11。
  • npm run lint：执行 ESLint 检查 web/package.json:13。
  • npm run test：运行 Jest 测试套件 web/package.json:21。
  • npm run types:check：使用 tsgo 进行快速的 TypeScript 类型校验 web/package.json:17。

来源： web/package.json:8-31

可观测性与分析

Sentry 集成

Sentry 通过 @sentry/nextjs 集成。它仅在同时提供 SENTRY_AUTH_TOKEN 和 NEXT_PUBLIC_SENTRY_DSN 时才会条件启用 web/next.config.js:174-176。

  • 构建时：Sentry Webpack 插件默认将源码映射上传到 onyx-vl 组织 web/next.config.js:180-195。
  • 运行时：捕获客户端、服务端和 Edge 运行时的错误 web/package.json:59-60。
PostHog 代理

为防止浏览器跟踪保护功能阻止分析，Next.js 充当 PostHog 的反向代理。对 /ph_ingest/* 的请求会被重写到 NEXT_PUBLIC_POSTHOG_HOST 中定义的 PostHog 主机 web/next.config.js:83-91。

来源： web/next.config.js:83-91,174-198