客户端应用
客户端应用
相关源文件
本章引用的主要源码文件：
cli/cmd/chat.gocli/cmd/experiments.gocli/cmd/root.gocli/internal/config/config.gocli/internal/config/config_test.gocli/internal/config/experiments.gocli/internal/starprompt/starprompt.gocli/internal/tui/app.gocli/internal/tui/commands.gocli/internal/tui/experiments.gocli/internal/tui/help.gocli/internal/tui/input.gocli/internal/tui/viewport.gocli/internal/tui/viewport_test.godeployment/docker_compose/docker-compose.onyx-lite.ymldeployment/docker_compose/install.ps1deployment/docker_compose/install.shdeployment/helm/charts/onyx/values-lite.yamldesktop/.gitignoredesktop/README.mddesktop/package-lock.jsondesktop/package.jsondesktop/scripts/generate-icons.shdesktop/src-tauri/Cargo.lockdesktop/src-tauri/Cargo.tomldesktop/src-tauri/build.rsdesktop/src-tauri/gen/schemas/acl-manifests.jsondesktop/src-tauri/gen/schemas/capabilities.jsondesktop/src-tauri/gen/schemas/desktop-schema.jsondesktop/src-tauri/gen/schemas/macOS-schema.jsondesktop/src-tauri/src/main.rsdesktop/src-tauri/tauri.conf.jsondesktop/src-tauri/tauri.windows.conf.jsondesktop/src/index.htmldesktop/src/titlebar.js
Onyx 生态系统为用户提供了多种与 AI 驱动的知识管理系统交互的入口点。虽然核心逻辑位于后端，但这些客户端应用提供了专门的界面，从功能完备的 Web 仪表盘到轻量级浏览器扩展和基于终端的工具，一应俱全。
所有客户端应用都通过 Onyx 后端的 REST API 进行通信，该 API 通常由 FastAPI 应用 backend/onyx/main.py:1-100 定义并提供服务。
应用概览
Onyx 支持五种主要类别的客户端界面：
| 客户端类型 | 技术栈 | 主要用途 |
|---|---|---|
| Web 应用 | Next.js、React、Tailwind CSS | 完整的管理、文档管理和深度对话。 |
| 桌面应用 | Tauri、Rust、Next.js | 原生操作系统集成，支持全局键盘快捷键。 |
| CLI（onyx-cli） | Go | 面向开发者的基于终端的搜索和交互式对话。 |
| 聊天组件 | Lit（Web 组件） | 将 Onyx 搜索/对话嵌入外部网站。 |
| Chrome 扩展 | JavaScript/TypeScript | 浏览时进行上下文搜索和侧边栏对话。 |
Web 应用
Onyx 的主要界面是一个高性能的 Next.js 应用，位于 web/ 目录中。它处理从初始设置和连接器配置到最终用户对话体验的所有功能。
- 架构：基于 Next.js 构建，利用
standalone输出模式实现优化的 Docker 部署web/next.config.js:21-21。 - 状态管理：使用
SWR进行数据获取，使用Zustand管理客户端状态。 - 样式：采用基于 Tailwind CSS 构建的自定义主题系统，通过 CSS 变量支持动态品牌定制
web/src/app/globals.css:1-50。 - 认证：支持多种认证流程，包括 OAuth、OIDC 和 SAML，通过
AUTH_TYPE后端设置进行配置。
详情请参见前端应用。
来源： web/next.config.js:1-189、web/src/app/globals.css:1-50
桌面应用
桌面应用为 Onyx 体验提供了原生封装，使其能够与主机操作系统（macOS、Windows 和 Linux）进行更紧密的集成。
- 框架：使用 Tauri 构建
desktop/src-tauri/Cargo.toml:12-12，它使用基于 Rust 的后端实现原生功能，并使用 WebView 呈现用户界面。 - 配置：将本地设置（如
server_url）存储在本地config.json文件中desktop/src-tauri/src/main.rs:35-36。默认指向https://cloud.onyx.appdesktop/src-tauri/src/main.rs:35-35。 - 原生功能：通过
TrayIconBuilder实现系统托盘集成desktop/src-tauri/src/main.rs:18-18，在 macOS 上支持窗口毛玻璃效果desktop/src-tauri/src/main.rs:29-29，以及自定义标题栏处理desktop/src-tauri/src/main.rs:38-38。 - 构建目标：支持通用 Apple 二进制文件、通过
cargo-xwin构建的 Windows MSI 安装包，以及 Linux 的.deb/.rpm包desktop/package.json:9-11。
详情请参见桌面应用。
来源： desktop/src-tauri/src/main.rs:1-47、desktop/src-tauri/Cargo.toml:1-28、desktop/src-tauri/tauri.conf.json:1-32、desktop/package.json:1-20
CLI（onyx-cli）
onyx-cli 是一个基于 Go 的终端界面，专为喜欢在 Shell 环境中工作的开发者和高级用户设计。
- 交互式 TUI：使用
bubbletea框架启动完整的交互式对话界面cli/cmd/chat.go:4-4。 - 命令套件：支持子命令，如
ask用于一次性查询，agents用于列出角色，以及serve用于 SSH 模式cli/cmd/root.go:93-101。 - 配置：通过
config.Load()进行管理，该函数从本地 JSON 文件或环境变量（如ONYX_SERVER_URL）中读取配置cli/cmd/chat.go:24-24。 - 入门引导：包含一个交互式向导，用于首次设置
cli/cmd/chat.go:27-33。
详情请参见CLI（onyx-cli）。
来源： cli/cmd/chat.go:1-53、cli/cmd/root.go:1-113
可嵌入聊天组件
聊天组件允许开发者使用轻量级 Web 组件将 Onyx 直接集成到自己的网站中。
- 技术：使用 Lit 开发核心 Web 组件
widget/package.json:1-30，确保其与框架无关，并通过 Shadow DOM 实现隔离。 - 参考实现：在
examples/widget/中提供了一个基于 Next.js 的示例examples/widget/package.json:1-29。 - 模式：支持"启动器"（浮动气泡）和"内联"两种显示模式。
- 配置：通过 HTML 属性进行配置，例如
backend-url、api-key和agent-id。
详情请参见可嵌入聊天组件。
来源： examples/widget/package.json:1-29、examples/widget/src/app/widget/Widget.tsx:1-50
Chrome 扩展
Chrome 扩展将 Onyx 搜索和对话直接带入浏览器工作流程中。
- 访问方式：提供侧边栏用于快速访问（通过
Ctrl+O或Alt+O触发），并与浏览器的新标签页集成。 - 连接性：连接到 Onyx 后端，在用户浏览时提供对已索引公司知识的语义搜索。
详情请参见Chrome 扩展。
系统交互图
下图展示了各种客户端如何与核心后端服务进行交互。
客户端到后端的连接
来源： backend/onyx/main.py:1-100、desktop/src-tauri/src/main.rs:35-35、cli/cmd/root.go:38-43
自然语言到代码实体的映射
此图将面向用户的客户端操作映射到仓库中的底层代码实体。
来源： cli/cmd/chat.go:12-12、desktop/src/index.html:89-89、examples/widget/src/app/widget/Widget.tsx:1-20、desktop/src-tauri/src/main.rs:35-35