container：如何提交高质量 Bug 报告——从环境信息采集到日志抓取完整指南

本文基于 docs/bug-report-how-to.md 展开，讲解在 container（一个运行于 macOS、使用轻量级虚拟机承载 Linux 容器的工具）中提交有效 bug 报告的完整方法论：如何组织可复现步骤、如何描述问题、如何采集操作系统/工具链/CLI 三类环境信息，以及如何用 --debug、container logs、container system logs 抓取得有诊断价值的日志，并结合仓库源码说明这些命令背后的实现机制。读完后，你将能独立产出一份维护者可直接复现、快速定位问题的 bug 报告。

为什么信息的完整性决定修复速度

container 的故障排查链路涉及多层组件：CLI 前端（Swift 编写）、API Server 守护进程、每个容器背后的轻量虚拟机、XPC 服务以及 vmnet 网络插件。一份缺少上下文的信息会让维护者反复追问，而维护者自己也很难凭空还原你机器上的状态。因此该指南的核心思想是：在提交前就提供维护者复现问题所需的全部输入——起始状态、精确命令、环境版本、相关日志。

指南在开头即给出正例参考：项目维护者指出，官方仓库的 Issue #1094 就是一份体现本指南诸多最佳实践的“好 bug 报告”范例，可在提交前对照自查。

复现步骤：三个必备要素

1. 起始状态（Starting state）

维护者首先要知道“问题发生前你的环境长什么样”。文档要求交代以下四点：

• 是全新安装（fresh installation），还是已有项目/长期使用的状态？
• 是否有特殊的配置文件？如有，应一并附上；
• 导致当前状态的前置命令序列是什么？
• 机器近期是否重启过？——这一点尤其重要，因为 container 的系统级守护服务（API Server 等）在重启后可能需要重新拉起，部分“连接不上服务”类问题往往与系统未启动有关。

2. 精确命令（Exact commands）

• 原样粘贴你执行过的命令，包含所有 flags 与参数，不要改写、不要概括；
• 用代码块包裹，保证复制后可直接重放。

3. 可复现性（Reproducibility）

明确说明问题出现的频率与条件：

• 每次都能复现（always reproducible）；
• 间歇性出现（如有，描述触发条件，例如是否与并发、网络、资源占用相关）；
• 只发生过一次（尽量补充当时的上下文）。

文档给出的示例步骤如下，可直接作为模板：

1. Create new container: `container create --name test-app ubuntu:latest`
2. Start the container: `container start test-app`
3. Container fails during bootstrap with error:
   "failed to bootstrap container test-app"
4. Container exits with code 1

注意该示例同时给出了精确命令和具体错误文本，这正是维护者定位问题所需的最小信息闭环。

问题描述：现状、预期与日志

当前行为（Current behavior）

描述时请覆盖：

• 精确的错误信息——原文复制粘贴，不要转述或翻译；
• 退出码或状态指示（如容器以退出码 1 结束）；
• 性能类问题（卡顿、挂起、崩溃）的表现；
• 任何不符合预期的输出或结果。

预期行为（Expected behavior）

说明你期望发生的正确结果，可附上：

• 相关文档的引用（如 docs/command-reference.md 中对应命令的语义说明）；
• 在旧版本上正常工作的事实（如果适用）；
• 基于该命令语义的合理预期。

相关日志（Relevant logs）

把能佐证问题的日志贴进报告：错误信息与堆栈、与问题相关的警告、失败命令的完整输出。如果默认输出信息不足，请使用调试开关重新执行命令以获取详细信息——具体方法见下文“日志信息”一节。

环境信息：三条命令采集三类版本

操作系统版本

在终端运行：

sw_vers

示例输出：

ProductName:		macOS
ProductVersion:		26.0
BuildVersion:		12A345

Xcode 版本

container 依赖 Xcode 提供的工具链（构建、开发插件运行时等），因此需要记录 Xcode 版本：

xcodebuild -version

示例输出：

Xcode 15.0
Build version 15A240d

Container CLI 版本

container --version

示例输出：

container CLI version 0.10.0-27-g9fd15f0 (build: debug, commit: 9fd15f0)

从源码看，这个输出一行即携带了三个关键定位维度。版本字符串由 ReleaseVersion.swift 中的 singleLine(appName:) 生成：版本号来自应用包信息（CFBundleShortVersionString），build 字段区分 debug/release 构建（由编译期条件分支决定），commit 字段截取 7 位 git commit 前缀。CLI 的 --version 值在 Application.swift 中注册（version: ReleaseVersion.singleLine(appName: "container CLI")）。这意味着维护者拿到这行输出后，能立即确认你运行的确切代码版本、构建类型，甚至判断你跑的是不是本地 debug 构建——而 debug 构建本身在启动时就会向 stderr 打印性能警告（见 Application.swift 中 #if DEBUG 分支），这一点在报告中也应说明。

日志信息：三种层次的抓取手段

这是指南中最具实操价值的部分。container 的日志分为两个层面：CLI 自身的调试日志与系统服务的运行日志，两者抓取方式不同。

1. CLI 调试输出：container --debug <command>

对 Container CLI 自身的问题，在要执行的命令前加 --debug 开关：

container --debug <command>

源码印证了这条命令的实际机制：--debug flag 定义在 Flags.swift 的 Flags.Logging 结构中，帮助文本明确标注了等价的环境变量 CONTAINER_DEBUG。在 Application.swift 的 validate() 方法中，当 --debug 被设置或 CONTAINER_DEBUG 环境变量存在时，引导日志器的级别从默认的 .info 提升到 .debug：

let debugEnvVar = ProcessInfo.processInfo.environment["CONTAINER_DEBUG"]
if self.logOptions.debug || debugEnvVar != nil {
    bootstrapLogger.logLevel = .debug
}

也就是说，两种开启方式等价：临时加 --debug，或长期 export CONTAINER_DEBUG=1 后正常执行命令——后者适合需要连续跑多条命令、逐条收集日志的场景。

此外，validate() 中还有一个值得在报告中留意的检查：CLI 会通过 sysctl.proc_translated 检测自身是否运行在 Rosetta 转译之下，若是会直接抛出错误提示关闭转译（Application.swift）。如果你在 Apple silicon 机器上遇到怪异故障，也应确认终端没有把 container 以 x86_64 模式跑起来。

2. 容器日志：container logs

用于获取容器内应用的 stdio 输出：

container logs <container-id>

该命令的完整参数定义在 ContainerLogs.swift，提交报告时可以按需使用：

参数	作用
--boot	显示虚拟机引导与 init 过程的日志，而非应用 stdio
-f, --follow	持续跟踪日志输出
-n <lines>	只打印日志末尾的指定行数

从实现看，run() 通过 API 客户端拿到一对文件句柄（fhs[0] 为应用 stdio，fhs[1] 为 boot 日志），--boot 只是切换到后者；-n 未指定时走“整文件读”的快速路径，-f 则通过 readabilityHandler 流式读取并处理日志文件被截断（容器重启）后重新定位到末尾的情况（ContainerLogs.swift）。

实践建议：容器起不来、卡在 bootstrap 时，container logs --boot <container-id> 往往能直接暴露引导阶段的根因（内核启动、vminitd 初始化、gRPC/vsock 通信等），而 --boot 与不带 --boot 的两份日志最好都附上。更多示例可参考 docs/logs.md。

3. 系统日志：container system logs

对系统级问题（守护进程、插件、XPC 通信），使用内置的系统日志命令：

container system logs

从 SystemLogs.swift 的实现可以看到它的具体行为：它本质上是系统 log 命令的封装——不带 -f 时执行 log show --info ... --last 5m --predicate "subsystem = 'com.apple.container'"，带 -f/--follow 时改用 log stream。关键细节：

• 日志按 subsystem 过滤，只保留 com.apple.container 域的消息；
• --last 默认值为 5m，支持 <number>[m|h|d] 格式（纯数字视为秒，如 30、5m、1h、2d），建议提交报告时把时间窗调大，例如 container system logs --last 30m，以覆盖完整的问题窗口；
• 加上 --debug 后会在底层 log show 参数中追加 --debug 级别输出（SystemLogs.swift），即 container system logs --debug -f 可获得最细粒度的服务日志。

系统日志中出现的消息带有各服务组件的标签，例如 container-apiserver、container-runtime-linux、container-network-vmnet，能直接指出故障发生在哪个子系统，这也是把原始日志（而非人工摘要）贴进报告的原因。

一个高频前置错误

如果在执行任何 container 命令时看到 XPC 连接类错误，CLI 会在错误信息中追加提示：请确认已执行 container system start 启动系统服务（见 Application.swift）。机器重启后忘记启动系统是常见诱因，报告中也应说明这一点。

常见信息缺口：提交前自查

文档总结了报告中最常被追问、却最容易被遗漏的三类缺口：

缺失的上下文（Missing context）

• 你当时想完成什么目标？
• 配置最近有什么变化？
• 问题在 main 分支全新安装下是否仍然出现？——这能帮维护者快速区分“环境脏了”与“代码回归”。

不完整的错误信息（Incomplete error information）

• 完整错误信息（不能只贴最后一行）；
• 相关场景下的堆栈；
• 伴随出现的警告信息。

环境差异排查（Environment variations）

• 换一个全新的容器实例是否正常？
• 重新全新安装 Container 包后是否正常？
• 网络配置近期是否变化？
• Xcode 或 macOS 版本近期是否变化？

这四问本质是做控制变量：把“容器/安装/网络/工具链”四个维度逐一隔离，往往能在提交前就缩小甚至定位问题范围。

报告模板与检查清单

综合以上各节，一份可直接套用的报告结构如下：

【复现步骤】
- 起始状态：全新安装 / 已有项目；是否重启过机器；前置命令序列
- 精确命令（代码块原样粘贴）：
    container create --name test-app ubuntu:latest
    container start test-app
- 复现性：每次必现 / 偶发（条件：...）/ 仅一次

【问题描述】
- 当前行为：完整错误原文 + 退出码
- 预期行为：依据命令语义应发生的结果

【环境信息】
- sw_vers 输出
- xcodebuild -version 输出
- container --version 输出（含 build 类型与 commit）

【日志】
- container --debug <失败命令> 的输出
- container logs <id>（必要时附 container logs --boot <id>）
- container system logs --last 30m 的相关片段

提交前检查清单：

1. 命令可原样复制重放，含全部 flags；
2. 错误信息为逐字粘贴，含退出码；
3. sw_vers、xcodebuild -version、container --version 三项齐全；
4. 至少包含 CLI 层（--debug）与系统层（system logs）两级日志之一，容器启动类问题应补 --boot 日志；
5. 已说明是否重启过机器、系统服务是否已通过 container system start 启动；
6. 已做过“全新容器 / 全新安装”控制变量排查并记录结论。

小结

container 的 bug 报告方法论可以概括为三层信息：可复现的操作序列（起始状态 + 精确命令 + 复现频率）、可对比的行为描述（现状 vs 预期）、可定位的运行证据（三段环境版本 + 两级日志）。这些要求并非形式主义——从源码看，--version 一行即携带版本/构建类型/commit 三个定位维度（ReleaseVersion.swift），--debug 与 CONTAINER_DEBUG 是同一开关的两种等价形式（Application.swift），system logs 则按 com.apple.container subsystem 精确过滤服务日志（SystemLogs.swift）。按本指南采集到的信息，维护者无需往返追问即可进入复现与定位阶段，这正是高质量 bug 报告的价值所在。