agentic_huge_data_base / wiki
页面 Onyx · 11.1 开发设置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 11.1

11.1 · 开发设置（Development Setup）

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

项目Onyx 章节11.1 状态全文译文 模块安装与启动、测试、发布与运维、配置治理、存储与持久化
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Development Setup 上一章11 下一章11.2
源码线索
  • .devcontainer/Dockerfile
  • .devcontainer/README.md
  • .devcontainer/devcontainer.json
  • .devcontainer/dnsmasq.conf
  • .devcontainer/init-dev-user.sh
  • .devcontainer/init-firewall.sh
  • .devcontainer/zshrc
  • .github/CODEOWNERS
  • .kanban.toml
  • .vscode/launch.json
模块标签
  • 安装与启动
  • 测试、发布与运维
  • 配置治理
  • 存储与持久化
  • 文档对象与元数据

章节正文

开发设置

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/11.1-development-setup

开发环境搭建

相关源文件

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

  • .devcontainer/Dockerfile
  • .devcontainer/README.md
  • .devcontainer/devcontainer.json
  • .devcontainer/dnsmasq.conf
  • .devcontainer/init-dev-user.sh
  • .devcontainer/init-firewall.sh
  • .devcontainer/zshrc
  • .github/CODEOWNERS
  • .kanban.toml
  • .vscode/launch.json
  • .vscode/tasks.json
  • AGENTS.md
  • CLAUDE.md
  • backend/ee/onyx/server/billing/api.py
  • backend/ee/onyx/server/billing/models.py
  • backend/ee/onyx/server/billing/service.py
  • backend/ee/onyx/server/license/api.py
  • backend/ee/onyx/server/middleware/tenant_tracking.py
  • backend/ee/onyx/server/settings/__init__.py
  • backend/ee/onyx/server/tenants/api.py
  • backend/ee/onyx/server/tenants/billing.py
  • backend/ee/onyx/server/tenants/billing_api.py
  • backend/ee/onyx/server/tenants/models.py
  • backend/ee/onyx/server/tenants/product_gating.py
  • backend/ee/onyx/server/tenants/proxy.py
  • backend/onyx/error_handling/__init__.py
  • backend/onyx/error_handling/error_codes.py
  • backend/onyx/error_handling/exceptions.py
  • backend/onyx/hooks/executor.py
  • backend/tests/unit/ee/onyx/server/billing/test_billing_api.py
  • backend/tests/unit/ee/onyx/server/billing/test_billing_service.py
  • backend/tests/unit/ee/onyx/server/license/test_api.py
  • backend/tests/unit/ee/onyx/server/tenants/test_billing_api.py
  • backend/tests/unit/ee/onyx/server/tenants/test_product_gating.py
  • backend/tests/unit/ee/onyx/server/tenants/test_proxy.py
  • backend/tests/unit/onyx/connectors/confluence/test_rate_limit_handler.py
  • backend/tests/unit/onyx/error_handling/test_exceptions.py
  • 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 平台的本地开发环境，包括前置条件、仓库设置、环境配置以及运行开发栈（所有端口均暴露以便调试）。

前置条件

必需工具

在搭建开发环境之前，请确保已安装以下工具：

工具最低版本用途
Docker20.10+所有服务的容器运行时
Docker Compose2.0+多容器编排
Python3.11后端运行时
uv最新版高性能 Python 依赖管理
Node.js22前端运行时
Git2.0+版本控制
系统资源

开发环境需要充足的系统资源才能运行完整栈（Vespa、OpenSearch、模型服务器等）：

资源最低要求推荐配置
内存10 GB16 GB 以上
磁盘空间32 GB50 GB 以上
CPU 核心数48 核以上

仓库结构

顶层组织
onyx/
├── backend/               # Python FastAPI 应用
│   ├── onyx/             # 主应用代码
│   ├── model_server/     # 机器学习模型服务
│   ├── alembic/          # 数据库迁移
│   └── Dockerfile        # 后端容器
├── web/                  # Next.js 前端
│   └── Dockerfile        # 前端容器
├── deployment/
│   └── docker_compose/   # Docker Compose 配置
├── pyproject.toml        # Python 依赖（唯一数据源）
└── uv.lock              # 统一依赖锁定文件

来源： AGENTS.md:148-166

开发栈架构

Docker Compose 服务架构

开发栈将所有内部服务暴露给宿主机，方便开发者直接使用本地工具（如 psql、redis-cli 或 Vespa 配置工具）。

Onyx · Docker Compose 服务架构 · 图 1
Onyx · Docker Compose 服务架构 · 图 1

来源： .devcontainer/devcontainer.json:23-29、.vscode/launch.json:72-121

VS 代码调试配置

.vscode/launch.json 文件提供了预配置的调试目标，可用于调试单个微服务或同时调试整个栈。

配置名称类型入口点
Web ServerNode.jsweb/（npm run dev）.vscode/launch.json:72-84
API ServerPythononyx.main:app（端口 8080）.vscode/launch.json:104-121
Model ServerPythonmodel_server.main:app（端口 9000）.vscode/launch.json:86-102
Celery primaryPythononyx.background.celery.versioned_apps.primary .vscode/launch.json:187-214
MCP ServerPythononyx.mcp_server.api:mcp_app（端口 8090）.vscode/launch.json:159-185

初始设置工作流

1. 后端：Python 依赖

Onyx 使用 uv 进行高性能依赖管理。pyproject.toml 是所有后端依赖的唯一数据源。

# 创建虚拟环境并同步依赖
uv venv .venv --python 3.11
source .venv/bin/activate
uv sync --all-extras

# 安装 Playwright（用于网页抓取/测试）
uv run playwright install

来源： AGENTS.md:7-8、AGENTS.md:126-130

2. 前端：Node 依赖

确保使用 Node.js v22（在 package.json 中指定）。

cd web
npm install
3. 环境配置

配置通过环境变量管理。本地开发时，在根目录创建 .env 文件。

变量推荐开发值说明
AUTH_TYPEbasic开发环境最简单的认证模式
GEN_AI_API_KEYsk-...大语言模型（LLM）提供商的密钥（OpenAI/Anthropic）
POSTGRES_HOSTlocalhost关系型数据库主机
VESPA_HOSTlocalhost向量索引主机
LOG_LEVELDEBUG详细日志输出，便于故障排查

来源： AGENTS.md:9-11、.devcontainer/devcontainer.json:20-30

开发环境

方案一：VS 代码 DevContainer（强烈推荐）

仓库中包含一套完整的 DevContainer 配置，提供了一个"沙箱"环境，其中预装了所有系统依赖（如 build-essential、ripgrep、jq 和 uv）。

  • 镜像：onyxdotapp/onyx-devcontainer .devcontainer/devcontainer.json:3
  • 特性：
    • 隔离网络 onyx_default .devcontainer/devcontainer.json:7
    • 通过 init-firewall.sh 自动配置防火墙 .devcontainer/init-firewall.sh:1-137
    • 通过 init-dev-user.sh 自动映射 UID/GID 以支持绑定挂载 .devcontainer/init-dev-user.sh:1-120
    • 预装 Claude Code，支持 AI 辅助开发 .devcontainer/Dockerfile:56-58
方案二：本地微服务

如果更倾向于在 Docker 之外运行服务以便于调试，可以使用 VS Code 中的"Run All Onyx Services"复合启动配置。该配置会启动 Web 服务器、API 服务器、模型服务器以及所有必要的 Celery 工作进程（轻量、重量、文档抓取等）.vscode/launch.json:16-34。

企业版（EE）开发

要开发或测试企业版功能，请确保设置以下环境变量：

  • ENABLE_PAID_ENTERPRISE_EDITION_FEATURES=true
  • MULTI_TENANT=true（如果测试云特定功能）
许可与计费

对于自托管的企业版开发，通过 /license 端点管理席位使用和许可状态 backend/ee/onyx/server/license/api.py:1-11。 对于云/多租户开发，通过统一的 /admin/billing API 管理计费，该 API 会将请求路由到 Onyx 控制平面 backend/ee/onyx/server/billing/api.py:1-22。

来源： backend/ee/onyx/server/license/api.py:1-11、backend/ee/onyx/server/billing/api.py:1-22

常见开发任务

数据库迁移

修改 SQLAlchemy 模型后，使用 Alembic 生成并应用迁移：

# 应用迁移至最新状态
alembic upgrade head

# 针对多租户模式
alembic -n schema_private upgrade head

来源： AGENTS.md:174-180

运行测试
# 运行后端单元测试
pytest backend/tests/unit

# 运行前端测试
cd web && npm test

来源： AGENTS.md:126-130