agentic_huge_data_base / wiki
页面 Onyx · 11 开发与操作·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 11

11 · 开发与操作（Development and Operations）

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

项目Onyx 章节11 状态全文译文 模块安装与启动、测试、发布与运维、文档对象与元数据、工作流与编排
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Development and Operations 上一章10.4 下一章11.1
源码线索
  • .devcontainer/Dockerfile
  • .devcontainer/README.md
  • .devcontainer/devcontainer.json
  • .devcontainer/dnsmasq.conf
  • .devcontainer/init-dev-user.sh
  • .devcontainer/init-firewall.sh
  • .devcontainer/zshrc
  • .github/actions/slack-notify/action.yml
  • .github/actions/slack-notify/user-mappings.json
  • .github/dependabot.yml
模块标签
  • 安装与启动
  • 测试、发布与运维
  • 文档对象与元数据
  • 工作流与编排
  • 智能体运行时

章节正文

开发与操作

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/11-development-and-operations

开发与运维

相关源文件

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

  • .devcontainer/Dockerfile
  • .devcontainer/README.md
  • .devcontainer/devcontainer.json
  • .devcontainer/dnsmasq.conf
  • .devcontainer/init-dev-user.sh
  • .devcontainer/init-firewall.sh
  • .devcontainer/zshrc
  • .github/actions/slack-notify/action.yml
  • .github/actions/slack-notify/user-mappings.json
  • .github/dependabot.yml
  • .github/workflows/deployment.yml
  • .github/workflows/docker-tag-beta.yml
  • .github/workflows/docker-tag-latest.yml
  • .github/workflows/helm-chart-releases.yml
  • .github/workflows/post-merge-beta-cherry-pick.yml
  • .github/workflows/pr-database-tests.yml
  • .github/workflows/pr-external-dependency-unit-tests.yml
  • .github/workflows/pr-helm-chart-testing.yml
  • .github/workflows/pr-integration-tests.yml
  • .github/workflows/pr-jest-tests.yml
  • .github/workflows/pr-playwright-tests.yml
  • .github/workflows/pr-python-checks.yml
  • .github/workflows/pr-python-connector-tests.yml
  • .github/workflows/pr-python-model-tests.yml
  • .github/workflows/pr-python-tests.yml
  • .github/workflows/pr-quality-checks.yml
  • .github/workflows/release-cli.yml
  • .github/workflows/release-devtools.yml
  • .github/workflows/sandbox-deployment.yml
  • .github/workflows/zizmor.yml
  • .kanban.toml
  • .vscode/tasks.json
  • cli/Dockerfile
  • docker-bake.hcl
  • tools/ods/cmd/dev.go
  • tools/ods/cmd/dev_exec.go
  • tools/ods/cmd/dev_into.go
  • tools/ods/cmd/dev_tunnel.go
  • tools/ods/cmd/dev_up.go

本页面提供了 Onyx 代码库的开发工作流、依赖管理、构建系统、测试基础设施和代码质量工具的高层概览。它是为项目贡献代码或管理运维流程的开发者的入口点。

有关特定主题的详细指南，请参阅各章节中链接的子页面。

开发环境搭建

Onyx 开发环境旨在通过本地服务和 Docker 管理的基础设施相结合，实现快速迭代。它支持具有完整检索增强生成（RAG）能力的"标准"模式和用于轻量级聊天 UI 开发的"精简"模式。

  • 前置条件： Python 3.11、Node.js 和 Docker。
  • 后端： 通过 uv 管理，自动设置虚拟环境，依赖组定义在 pyproject.toml 中。
  • 前端： Next.js 应用，需要在 web/ 目录下执行 npm install，并由一个预提交钩子确保 package-lock.json 保持更新 .github/workflows/pr-quality-checks.yml:32-40。
  • VS Code 支持： 提供了 .devcontainer 配置，可自动搭建开发环境，并预配置了扩展和设置 .devcontainer/devcontainer.json:1-50。
  • 本地基础设施： 开发者可以使用 docker-compose.dev.yml 启动所需服务（Postgres、Redis、Vespa、MinIO）.github/workflows/pr-external-dependency-unit-tests.yml:133-145。

有关入门的分步指南，请参阅 开发环境搭建。

来源： .github/workflows/pr-quality-checks.yml:32-40、.devcontainer/devcontainer.json:1-50、.github/workflows/pr-external-dependency-unit-tests.yml:133-145

依赖管理

Onyx 使用 uv 作为统一的包管理器，以处理后端和模型服务器之间的复杂依赖关系。该系统通过单一事实来源确保高速解析和一致的环境。

Onyx · 依赖管理 · 图 1
Onyx · 依赖管理 · 图 1
  • 工作区： 项目被组织为一个 uv 工作区，使用 uv.lock 实现确定性构建 .github/workflows/deployment.yml:46-51。
  • 自动导出： CI 工作流和预提交钩子确保旧的 requirements/*.txt 文件与 uv.lock 文件同步，以保持与标准 Docker 构建的兼容性 .github/workflows/pr-python-connector-tests.yml:68-74。

有关管理 Python 和 Node 包的详细信息，请参阅 依赖管理。

来源： .github/workflows/deployment.yml:46-51、.github/workflows/pr-python-connector-tests.yml:68-74

Docker 构建系统

Onyx 采用多阶段 Docker 构建系统，为生产和测试生成优化的镜像。

  • 构建编排： GitHub Actions 根据 Git 标签和分支名称确定要构建的组件（web、backend、model-server、desktop）.github/workflows/deployment.yml:20-155。
  • 构建优化： 系统利用基于注册表的缓存（type=registry）和 docker-bake.hcl 来加速 CI 构建，并管理复杂的多镜像构建 .github/workflows/pr-playwright-tests.yml:115-123、docker-bake.hcl:1-20。
  • 特定构建参数： 像 CRAFT 后端（用于代码执行）这样的功能在需要时会作为单独的标签构建 .github/workflows/deployment.yml:125-128。

有关容器化策略的详细信息，请参阅 Docker 构建系统。

来源： .github/workflows/deployment.yml:20-155、.github/workflows/pr-playwright-tests.yml:115-123、docker-bake.hcl:1-20

测试基础设施

Onyx 维护了一套严格的测试套件，涵盖单元测试、集成测试和端到端测试场景。

测试类别框架目的
单元测试pytest对后端组件进行隔离的逻辑测试 .github/workflows/pr-python-tests.yml:51-53
集成测试pytest涉及 Vespa、Redis 和 Postgres 等多组件的流程测试 .github/workflows/pr-integration-tests.yml:1-10
连接器测试pytest验证第三方 API 集成（HubSpot、Salesforce、GitHub 等）.github/workflows/pr-python-connector-tests.yml:105-159
端到端测试Playwright完整的用户流程验证和视觉回归测试 .github/workflows/pr-playwright-tests.yml:1-5
前端测试Jest对 Next.js 应用的组件和工具函数进行测试 .github/workflows/pr-jest-tests.yml:1-5
Helm 测试ct对 Kubernetes 图表进行 lint 检查和安装测试 .github/workflows/pr-helm-chart-testing.yml:49-68
Onyx · 测试基础设施 · 图 2
Onyx · 测试基础设施 · 图 2

有关完整的测试指南和 CI 工作流详细信息，请参阅 测试基础设施。

来源： .github/workflows/pr-python-tests.yml:51-53、.github/workflows/pr-integration-tests.yml:1-10、.github/workflows/pr-python-connector-tests.yml:105-159、.github/workflows/pr-playwright-tests.yml:1-5、.github/workflows/pr-helm-chart-testing.yml:49-68

代码质量与预提交钩子

代码质量通过一套强制性的预提交钩子和 CI 检查来保障。

  • 静态分析： 项目使用 zizmor 审计 GitHub Actions 工作流，以发现安全漏洞 .github/workflows/zizmor.yml:1-42。
  • Python 类型检查： 使用 ty（mypy 或 pyright 的封装）进行类型检查，以确保后端的类型安全 .github/workflows/pr-python-checks.yml:49-52。
  • 标准化： ruff、black 和 prettier 等工具被集成到工作流中，以保持整个代码库的格式一致性 .github/workflows/pr-quality-checks.yml:41-46。

有关完整的钩子列表及其配置方法，请参阅 代码质量与预提交钩子。

来源： .github/workflows/zizmor.yml:1-42、.github/workflows/pr-python-checks.yml:49-52、.github/workflows/pr-quality-checks.yml:41-46