hcsshim快速上手：10分钟用Go调用Host Compute Service创建第一个容器

hcsshim快速上手：10分钟用Go调用Host Compute Service创建第一个容器

【免费下载链接】hcsshimWindows - Host Compute Service Shim项目地址: https://gitcode.com/gh_mirrors/hc/hcsshim

想在 Windows 上直接用 Go 语言管理容器，却不知道从哪开始？hcsshim 就是微软官方的答案——它是 Windows Host Compute Service（HCS）的 Go 语言接口，负责在 Windows 上创建、启动和管理 Windows 容器与 Hyper-V 容器。本教程将带你用最短的路径上手 hcsshim：从环境准备、拉取源码，到用十几行 Go 代码创建并运行你的第一个容器，全程约 10 分钟即可完成。

什么是 hcsshim？它解决了什么问题？

Windows 系统本身并不直接提供"容器"这种抽象，真正干活的底层服务叫Host Compute Service（HCS），它是 Windows 上所有容器的总管家。而hcsshim正是封装 HCS 的 Go 库，让你不必手写复杂的 JSON 协议、不必直接操作 Windows API，就能用熟悉的 Go 代码完成容器的全生命周期管理。

hcsshim 还被 Moby（Docker）和 Containerd 等项目广泛使用，稳定性经过了大规模生产环境验证。除此之外，它还附带 Host Network Service（HNS）网络接口、Linux 容器（LCOW）的 Guest Agent 等工具，是理解 Windows 容器体系的最佳入口。

环境准备：3 项前置条件

开始之前，请确认你的机器满足以下要求：

检查项	要求
操作系统	Windows 10/11 或 Windows Server 2016+，已开启容器功能
Go 环境	Go 1.21 及以上，go version可正常输出
容器运行时	Docker Desktop（Windows 容器模式）或直接使用 HCS 原生能力

小提示：hcsshim 的代码带有//go:build windows编译约束，因此编译和运行都必须在 Windows 上进行，Linux 机器无法完成本教程的实操部分。

第 1 步：获取 hcsshim 源码（1 分钟）

hcsshim 本身就是一个 Go 模块，你可以像普通依赖一样在go.mod中引用它，也可以直接克隆完整源码进行学习：

git clone https://gitcode.com/gh_mirrors/hc/hcsshim cd hcsshim

在go.mod中引入依赖：

go get github.com/Microsoft/hcsshim

拿到源码后，建议先浏览几个核心文件，它们构成了整个库的地基：

• hcsshim.go：库的入口，定义错误码与顶层类型
• container.go：容器核心 API，如CreateContainer、Start、Shutdown
• interface.go：Container与Process接口定义
• internal/hcs/schema1/schema1.go：ContainerConfig、ProcessConfig等配置结构

第 2 步：理解核心概念（3 分钟）

上手前，先搞懂三个关键概念，后面的代码就一目了然：

1. HCS（Host Compute Service）：Windows 上的系统级服务，负责容器的创建、启停与销毁，hcsshim 只是它的一层 Go 封装。
2. WCOW 与 LCOW：WCOW 指 Windows 容器，LCOW 指运行在 Windows 上的 Linux 容器（通过轻量级虚拟机 UVM 承载）。hcsshim 两者都支持。
3. ContainerConfig：创建容器所需的全部配置，包括存储层（Layers）、内存限制、CPU 份额、网络端点等，最终会被序列化成 JSON 发给 HCS。

下面这段代码就是最精简的容器配置，注意SystemType必须固定为"Container"，这是 HCS 的硬性要求：

config := &hcsshim.ContainerConfig{ SystemType: "Container", // HCS 要求固定值 Name: "my-first-container", HvPartition: false, // false 为进程隔离，true 为 Hyper-V 隔离 MemoryMaximumInMB: 1024, ProcessorCount: 2, }

第 3 步：编写第一个容器程序（4 分钟）

现在动手写一个完整的 Go 程序：创建容器 → 启动容器 → 在容器内运行一条命令 → 等待退出。新建main.go，内容如下：

package main import ( "fmt" "log" "time" "github.com/Microsoft/hcsshim" ) func main() { // 1. 创建容器（此时尚未启动） container, err := hcsshim.CreateContainer("demo", &hcsshim.ContainerConfig{ SystemType: "Container", Name: "demo-container", HvPartition: false, ProcessorCount: 1, }) if err != nil { log.Fatalf("创建容器失败: %v", err) } defer container.Close() // 2. 启动容器 if err := container.Start(); err != nil { log.Fatalf("启动容器失败: %v", err) } fmt.Println("✅ 容器已成功启动") // 3. 在容器内运行一条命令 process, err := container.CreateProcess(&hcsshim.ProcessConfig{ CommandLine: "cmd.exe /c echo Hello from hcsshim!", }) if err != nil { log.Fatalf("创建进程失败: %v", err) } // 4. 等待进程退出并获取退出码 if err := process.WaitTimeout(30 * time.Second); err != nil { log.Fatalf("等待进程失败: %v", err) } exitCode, _ := process.ExitCode() fmt.Printf("进程退出码: %d\n", exitCode) // 5. 优雅关闭容器 _ = container.Shutdown() fmt.Println("容器已关闭，演示完成 🎉") }

编译并运行：

go build -o demo.exe . .\demo.exe

第 4 步：代码逐行拆解（2 分钟）

整个流程只有 5 个步骤，掌握了它你就掌握了容器管理的核心套路：

方法	作用	对应生命周期阶段
CreateContainer	创建容器对象，不启动	创建
Start	正式启动容器	运行
CreateProcess	在容器内启动新进程	执行命令
Shutdown/Terminate	优雅关闭 / 强制终止	停止
Wait/WaitTimeout	等待容器或进程结束	清理

需要注意两点：

• CreateContainer只负责"创建"而不"启动"，必须显式调用Start()，这与 Docker 的create/start两个命令的设计完全一致。
• Shutdown是异步请求，返回后容器可能仍在关闭过程中，建议配合Wait()等待真正结束。

第 5 步：进阶探索方向

跑通第一个容器后，你可以沿着以下方向继续深入：

• 查看容器状态与统计信息：调用container.Properties系列方法获取内存、CPU、网络等实时指标，接口定义见container.go。
• 管理容器内进程：ProcessList可以列出容器内所有进程，OpenProcess可以接管已有进程。
• 对接 Containerd：hcsshim 提供了cmd/containerd-shim-runhcs-v1和cmd/containerd-shim-lcow-v2两个 shim，让 Windows 容器无缝接入 Kubernetes 生态。
• 研究配置细节：ContainerConfig中的Layers（分层存储）、MappedDirectories（目录映射）、EndpointList（网络端点）是生产环境中最高频的配置项。

常见问题排错

Q：编译时报错 "build constraints exclude all Go files"？A：说明你在非 Windows 平台编译。请切换到 Windows 环境，或使用GOOS=windows go build交叉编译。

Q：CreateContainer返回The parameter is incorrect？A：通常是ContainerConfig配置不完整，最常见的是缺少SystemType字段或Layers存储层信息，请对照internal/hcs/schema1/schema1.go逐项检查。

Q：容器启动后立刻退出？A：检查ProcessConfig中的CommandLine是否正确，并确认容器镜像/基础层已正确配置。

写在最后

hcsshim 是通往 Windows 容器世界的钥匙，10 分钟足以让你跑通"创建 → 启动 → 执行 → 关闭"的完整闭环。它不仅是 Docker 与 Containerd 在 Windows 上的基石，也是你深入理解 Windows 容器底层原理的最佳教材。下一步，不妨动手改造上面的示例：加上Layers存储层、映射一个目录、或者尝试 Hyper-V 隔离模式，你会对 Windows 容器有更直观的认识。

如果你希望了解 LCOW（Linux 容器）如何运行、或者如何让 hcsshim 与 Kubernetes 集成，欢迎持续关注后续教程。

【免费下载链接】hcsshimWindows - Host Compute Service Shim项目地址: https://gitcode.com/gh_mirrors/hc/hcsshim