dstack架构原理深度剖析：从Server到Runner的完整流程

dstack架构原理深度剖析：从Server到Runner的完整流程

【免费下载链接】dstackVendor-agnostic orchestration for training, inference and agentic workloads across NVIDIA, AMD, TPU, and Tenstorrent on clouds, Kubernetes, and bare metal.项目地址: https://gitcode.com/gh_mirrors/ds/dstack

dstack是一个开源的跨平台编排工具，支持在云端、Kubernetes和裸机上管理NVIDIA、AMD、TPU和Tenstorrent等多种硬件的训练、推理和智能代理工作负载。本文将深入解析dstack的架构原理，带你了解从Server到Runner的完整工作流程。

一、dstack核心组件概览

dstack平台由六个主要组件构成，它们协同工作以实现高效的工作负载编排：

• Server：提供HTTP API，负责提交运行任务和管理所有dstack功能，包括用户、项目、后端、仓库、密钥和网关
• Python API：包括低级和高级Python API，CLI基于高级API实现
• CLI：用户与dstack交互的命令行界面
• Runner：在Docker容器中执行用户命令，管理日志和作业状态
• Shim：根据云类型提供VM管理功能，处理Docker镜像和容器生命周期
• Gateway（可选）：通过公共URL提供作业访问，作为反向代理通过SSH隧道转发请求

图1：dstack架构组件关系图，展示了从基础模型到云服务的完整技术栈

二、Server：dstack的大脑中枢

Server是dstack的核心组件，采用FastAPI构建，后端支持SQLite或Postgres数据库。其主要职责包括：

1. 接收和处理用户请求：通过HTTP API接收来自CLI或Python API的运行配置
2. 资源调度：迭代配置的后端以获取匹配需求的实例报价和可用性
3. 作业管理：为每个运行创建一个或多个作业，处理作业提交和重试
4. 实例 provisioning：通过后台工作器在不同云平台上 provision 实例
5. 状态监控：定期 ping runner 以获取作业状态和日志更新

Server的源代码位于src/dstack/_internal/server/目录，其中包含API端点实现、业务逻辑服务、数据库模型和背景工作器等模块。

三、Runner：作业执行的核心引擎

Runner是用Go编写的组件，作为Docker容器的入口点运行，负责实际执行用户命令。其主要工作流程如下：

1. 等待作业规范提交：接收来自Server的作业定义
2. 代码准备：等待代码（tarball或diff）并准备仓库
3. 环境配置：设置环境变量和密钥
4. 命令执行：运行作业规范中的命令
5. 日志管理：收集和提供日志给Server和CLI
6. 作业终止：响应Server的终止信号，优雅关闭作业

Runner与Server之间的所有通信都通过SSH隧道的HTTP API进行。Runner收集作业日志和自身日志，其中作业日志通过WebSocket实时提供给CLI。

图2：dstack工作流架构图，展示了从加载模型数据到调度微调工作负载的完整流程

四、Shim：云环境的适配层

Shim是可选组件，根据云类型决定是否需要。对于提供Docker镜像API的GPU云，不需要Shim；对于传统的VM云，则需要Shim来管理VM上的Docker环境。

Shim的主要功能包括：

1. 任务管理：处理多个并行任务，每个任务对应一个Docker容器
2. 资源分配：分配GPU资源，查找和挂载卷，拉取镜像
3. 容器配置：根据实例和作业类型配置网络模式（host或bridge）
4. 生命周期管理：运行容器并监控其状态，处理终止请求
5. 清理资源：任务完成后释放GPU资源，卸载卷

Shim与Server之间的通信同样通过SSH隧道的HTTP API进行。通常，Shim由cloud-init用户数据脚本启动。

五、从提交到执行：完整工作流程

当用户使用dstack apply提交运行配置时，整个流程如下：

1. 提交与规划：CLI将运行配置发送到Server以获取运行计划，Server评估后端实例报价
2. 代码上传：用户确认后，CLI将代码上传到Server（使用git仓库时仅上传diff）
3. 作业创建：Server在数据库中存储提交的运行，并为每个运行创建一个或多个作业
4. 实例 provisioning：后台工作器迭代配置的后端，provision 最佳匹配的实例
5. 容器启动：实例启动后运行Shim（如需要），Shim拉取并运行包含Runner的Docker镜像
6. 作业执行：Server通过SSH隧道连接到Runner，提交作业并监控执行状态
7. 结果收集：作业完成后，Runner标记作业为完成，容器退出，Shim终止实例

六、关键技术细节

网络通信

dstack使用SSH隧道确保安全通信：

• Server通过SSH隧道与Runner和Shim的HTTP API通信
• Gateway使用SSH服务器转发来自公共端点的请求
• CLI使用SSH服务器作为跳转主机连接到容器

容器网络模式

根据实例类型和作业需求，容器使用不同的网络模式：

• host模式：用于非共享实例，避免网络开销，适合分布式训练
• bridge模式：用于共享实例（GPU块），避免端口冲突，容器端口映射到主机临时端口

代码传输与同步

dstack采用高效的代码传输机制：

• 使用git仓库时，仅传输代码diff而非完整仓库
• 首次初始化时，dstack init上传git凭据到Server，使Runner能访问私有仓库
• Runner拉取仓库并应用diff以获取用户文件的副本

七、项目结构与源码组织

dstack的代码组织结构清晰，主要目录包括：

• docker/：dstack镜像的Dockerfile
• docs/：mkdocs生成的文档源文件
• runner/：Runner和Shim的源代码
• scripts/：开发/CI/CD脚本和打包文件
• src/：dstack Python包的源代码，包括Server、CLI和Python API
• gateway/src/dstack/gateway：网关应用的源代码

总结

dstack通过Server、Runner、Shim等组件的协同工作，实现了跨平台、跨硬件的工作负载编排。其架构设计注重灵活性和可扩展性，能够适应不同的云环境和硬件类型。通过SSH隧道的安全通信和高效的资源管理，dstack为AI训练和推理提供了强大的基础设施支持。

无论是新手用户还是资深开发者，理解dstack的架构原理都有助于更好地利用这一工具来管理和扩展AI工作负载。如需深入了解更多细节，可以参考官方文档contributing/ARCHITECTURE.md和contributing/RUNNER-AND-SHIM.md。

【免费下载链接】dstackVendor-agnostic orchestration for training, inference and agentic workloads across NVIDIA, AMD, TPU, and Tenstorrent on clouds, Kubernetes, and bare metal.项目地址: https://gitcode.com/gh_mirrors/ds/dstack