Onyx：企业级AI搜索助手部署与使用指南

📋 官方信息

🎯 项目背景

Onyx（原名 Danswer）是一个开源的企业级 AI 搜索和问答平台。它解决的核心问题是：现代公司的信息散落在 Slack、Confluence、Google Drive、GitHub、Notion、Jira 等几十种工具中，员工想找个文件或答案要在各个系统之间切换搜索。Onyx 把这些所有工具连接起来，建立统一的索引，然后用自然语言提问，AI 会从所有关联的数据源中检索相关内容，给出带来源引用的答案。

项目由 Yuhong Wang 和 Chris Pichardo 创建，2023 年首次开源，2024 年从 Danswer 改名为 Onyx。它在 GitHub 上获得了超过 1.5 万 Star，是企业搜索（Enterprise Search）+ RAG 领域最活跃的开源项目之一。Onyx 提供两种部署模式：Lite 模式适合个人和小团队快速上手，Standard 模式包含完整的向量索引、后台同步容器和企业级功能。它支持 50+ 种数据源连接器，是目前连接器生态最丰富的开源 RAG 平台。

✨ 核心特性

• 50+ 数据源连接器：Slack、Confluence、Google Drive、GitHub、Notion、Jira、SharePoint、Slab 等
• 统一搜索：一个搜索框搜遍所有工作工具
• AI 问答：基于 RAG 技术，回答附带来源引用
• 混合检索：向量搜索 + 关键词搜索，召回率更高
• 实时同步：后台持续同步数据源更新
• 权限继承：自动同步数据源的访问权限，安全可控
• Craft 写作助手：内置 AI 写作功能，基于公司知识生成文档
• 两种部署模式：Lite（轻量）和 Standard（完整）

💻 环境要求

• Docker 部署：Docker 20.10+，Docker Compose v2+
• 内存：Lite 模式 4GB+，Standard 模式 8GB+（推荐 16GB）
• 磁盘空间：Lite 约 5GB，Standard 约 15GB
• LLM 配置：需要 OpenAI API Key 或其他 LLM 提供商密钥

🚀 详细部署步骤

方式一：Onyx CLI 安装（官方推荐）

# 安装 Onyx CLI
uv tool install onyx-cli

# 运行引导安装器
onyx-cli deploy install

安装器会自动：

1. 检查系统资源和要求（Linux 上自动安装 Docker）
2. 让你选择 Lite 还是 Standard 部署模式
3. 提示输入要部署的 Onyx 版本
4. 自动配置部署环境

方式二：Docker Compose 手动部署

# 1. 克隆仓库
git clone --depth 1 https://github.com/onyx-dot-app/onyx.git
cd onyx/deployment/docker_compose

# 2. 复制环境变量模板
cp env.prod.template .env
cp env.azure.template .env.azure  # 如使用 Azure

# 3. 编辑 .env 文件，填入必要配置
# 至少需要：
# OPENAI_API_KEY=sk-xxx
# PUBLIC_SITE_URL=http://localhost:3000

# 4a. 启动 Lite 模式（轻量，适合个人）
docker compose -f docker-compose.yml -f docker-compose.lite.yml up -d

# 4b. 启动 Standard 模式（完整功能，适合团队）
docker compose -f docker-compose.yml -f docker-compose.standalone.yml up -d

📝 环境变量关键配置

编辑 .env 文件：

# ===== 必需配置 =====
# LLM 提供商（任选其一）
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

# 你的站点 URL
PUBLIC_SITE_URL=http://localhost:3000

# ===== 可选配置 =====
# 管理后台密钥（生产环境务必修改）
AUTH_SECRET_KEY=your_secure_random_string_here
SESSION_EXPIRE_TIME=60*60*24*7

# 数据库（默认内置 PostgreSQL，一般不需要改）
POSTGRES_USER=onyx
POSTGRES_PASSWORD=onyx

# 启用 Craft 写作助手
ENABLE_CRAFT=true
SANDBOX_BACKEND=docker

🔧 Lite vs Standard 模式对比

✅ 启动验证

1. 等待所有容器启动（首次约 3-5 分钟，需要初始化数据库）
2. 访问 http://服务器IP:3000
3. 首次注册的账号即为管理员
4. 进入 Admin 后台，添加第一个数据源连接器
5. 等待同步完成后，在搜索框测试查询
6. 切换到 Chat 模式，提问测试 AI 问答

⚠️ 常见坑

• Lite 模式没有后台同步容器，新增文档需要手动触发同步
• 连接器配置需要 OAuth 授权，部分企业应用需要在对方平台创建 App
• Standard 模式容器较多，确保 Docker 内存限制足够（建议 8GB+）
• 如果 Craft 功能不显示，检查 ENABLE_CRAFT=true 并重启 API 和 Web 容器

📖 使用方法

连接数据源

进入 Admin → Connectors，选择要连接的数据源（如 Google Drive、Slack、Confluence），按照引导完成 OAuth 授权。Onyx 会自动开始拉取和索引文档。

搜索

在顶部搜索框输入关键词，Onyx 会从所有已连接的数据源中搜索相关文档，按相关性排序显示。

AI 问答

切换到 Chat 模式，直接用自然语言提问。AI 会检索相关文档片段，综合生成回答，并标注每条信息的来源链接。点击来源可以跳转到原文。

Craft 写作

使用 Craft 功能，基于公司知识库生成文档、邮件、报告。AI 会自动引用内部文档作为参考。

❓ 常见问题

Q1: 必须用 OpenAI 吗？
A: 支持多种 LLM，包括 Anthropic Claude、Azure OpenAI、Ollama 本地模型等。在 Admin 设置中切换即可。

Q2: 支持多少用户？
A: 开源版没有用户数限制。权限模型继承自数据源，用户只能看到自己有权访问的文档。

Q3: 数据隐私如何？
A: 自托管版本所有数据都在你的服务器上。只有发送给 LLM 的查询内容会经过 OpenAI 等 API。

Q4: 如何更新？
A: git pull && docker compose pull && docker compose up -d。官方自动处理数据库迁移。

Q5: 支持中文数据源吗？
A: 支持。Embedding 模型对中文有良好支持，搜索和问答都能正常工作。

🔗 跳转链接

• GitHub 仓库：https://github.com/onyx-dot-app/onyx
• 官方网站：https://onyx.app
• 官方文档：https://docs.onyx.app
• 在线体验：https://cloud.onyx.app