11.3 · Docker 构建系统（Docker Build System）

Docker 构建系统

Docker 构建系统

相关源文件

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

• .devcontainer/Dockerfile
• .devcontainer/README.md
• .devcontainer/devcontainer.json
• .devcontainer/dnsmasq.conf
• .devcontainer/init-dev-user.sh
• .devcontainer/init-firewall.sh
• .devcontainer/zshrc
• .github/actions/setup-python-and-install-dependencies/action.yml
• .github/actions/setup-test-license/action.yml
• .kanban.toml
• .vscode/tasks.json
• backend/Dockerfile
• backend/Dockerfile.model_server
• 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
• 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
• web/Dockerfile
• web/README.md
• web/next.config.js
• web/package-lock.json
• web/package.json
• web/tailwind.config.js

目的与范围

本文档描述了用于创建和部署 Onyx 容器的 Docker 构建系统。内容涵盖后端、模型服务器和 Web 服务的多阶段 Dockerfile 结构、ENABLE_CRAFT 构建时特性集成、安全加固步骤、模型预下载策略以及 docker-bake.hcl 编排。

构建系统架构

Onyx Docker 构建系统会生成三个主要镜像。后端和模型服务器镜像共享 Python 3.11 基础镜像，而 Web 服务器使用 Node.js 24 基础镜像。

镜像构建流程

来源： backend/Dockerfile:1-12, backend/Dockerfile.model_server:1-32, web/Dockerfile:1-8

后端镜像构建

后端 Dockerfile 使用 uv 进行高性能 Python 依赖管理，并包含针对 "Craft" 特性集的条件逻辑。

系统依赖与安全加固

backend/Dockerfile:28-55 安装了 PostgreSQL 连接所需的系统依赖（cmake、libpq-dev）、Vespa 的 zip 工具以及 SAML 所需的 libxmlsec1-dev。

安全加固步骤包括：

• 非 root 用户：创建 onyx 用户（UID 1001）并设置日志目录所有权 backend/Dockerfile:19-24。
• CVE 缓解：在 Playwright 安装后显式移除 perl-base、xserver-common 和 xvfb backend/Dockerfile:92-101。
• 内存优化：通过 LD_PRELOAD 使用 libjemalloc2 以减少长时间运行的 Python 进程中的内存碎片 backend/Dockerfile:52-177。

ENABLE_CRAFT 构建参数

ENABLE_CRAFT 参数允许在后端镜像中包含 Node.js 和 opencode CLI，以支持特定的代理工作流。

当 ENABLE_CRAFT=true 时，构建系统会：

1. 通过 nodesource 安装 Node.js 20 backend/Dockerfile:59-64。
2. 通过 curl 安装 opencode CLI backend/Dockerfile:69-72。
3. 在构建时执行 setup_craft_templates.sh，将演示数据、Python 虚拟环境和 npm 依赖预置到镜像中 backend/Dockerfile:156-159。

模型预下载

为了支持离线或出口受限环境，后端镜像在构建过程中会预下载必要的模型和数据集：

• 分词器：nomic-ai/nomic-embed-text-v1 backend/Dockerfile:114-115。
• NLTK 数据：stopwords 和 punkt_tab backend/Dockerfile:118-120。
• Tiktoken：cl100k_base 编码 backend/Dockerfile:124-125。

来源： backend/Dockerfile:1-177, backend/Dockerfile:59-72, backend/Dockerfile:114-125

模型服务器镜像构建

模型服务器使用多阶段构建，将依赖安装与模型下载分离。

多阶段模型缓存

backend/Dockerfile.model_server:28-30 会下载 nomic-embed-text-v1 模型并初始化 SentenceTransformer，以缓存权重和自定义架构。为确保用户挂载的卷不会覆盖这些预下载的模型，它们会被先复制到临时位置 temp_huggingface backend/Dockerfile.model_server:51。

来源： backend/Dockerfile.model_server:1-80

Web 服务器镜像构建

Web 服务器使用 Next.js 进行多阶段构建，生成独立输出。

构建与运行阶段

web/Dockerfile:11-90 定义了 builder 阶段，其中：

1. 使用 npm ci 安装依赖 web/Dockerfile:22。
2. 使用 npx next build 构建 Next.js 应用 web/Dockerfile:89。
3. 注入构建时环境变量（NEXT_PUBLIC_*）web/Dockerfile:38-75。

web/Dockerfile:92-173 定义了 runner 阶段，其中：

1. 移除全局 node_modules 以减少攻击面 web/Dockerfile:98。
2. 从构建阶段复制 standalone 目录和 static 资源 web/Dockerfile:116-117。
3. 以 nextjs 非 root 用户身份运行应用 web/Dockerfile:108-109。

独立输出配置

web/next.config.js:21 指定了 output: "standalone"。此功能利用输出文件追踪，只包含生产环境所需的必要文件，从而显著减小镜像体积。

来源： web/Dockerfile:1-174, web/next.config.js:18-21

Docker Bake 配置

docker-bake.hcl 文件用于编排复杂的多镜像构建，定义构建目标和构建上下文。

目标定义

构建系统在 docker-bake.hcl 中定义了多个目标：

• backend：构建核心 API 和工作进程镜像。
• model_server：构建机器学习推理镜像。
• web：构建 Next.js 前端镜像。

它使用 ONYX_VERSION backend/Dockerfile:172-173 和 NEXT_PUBLIC_CLOUD_ENABLED web/Dockerfile:55-56 等构建参数，为不同部署环境定制镜像。

安全与优化总结

来源： backend/Dockerfile:1-177, web/Dockerfile:1-174, web/next.config.js:1-198, backend/Dockerfile.model_server:1-81