DevPod：让 Dev Container 经 Provider 变成可验证工作区
设想团队给私有镜像仓库配置了 prebuild，开发者执行 devpod up 后也顺利进入 workspace，于是大家自然认为预构建已经生效。新成员首次启动却仍等待很久；此时 debug 日志可能揭示本地没有 registry 凭据，DevPod 跳过不可读的 prebuild，回退到现场构建。工作区“创建成功”并不能证明“命中 prebuild”。
同类误判还会出现在 provider 与生命周期上。仓库提交的是 devcontainer.json，真正创建容器或虚拟机的是当前 context 选中的 provider；本地 client 经 tunnel 部署 agent，再由 IDE 或 SSH 连接。stop、delete 与 delete --force 对底层资源的含义也不同。只有把项目声明、本地执行上下文、远端资源和清理证据分开，DevPod 才能把同一份开发环境声明可靠地带到不同承载位置。
安装 client，并固定 provider 来源
下面以 DevPod CLI 0.6.15 为操作基线。DevPod 安装入口提供 macOS AMD64/ARM64、Windows AMD64、Linux AMD64/ARM64 二进制；Desktop 还提供 macOS、Windows 与 Linux AppImage，Linux Desktop 不再以 deb/rpm 作为官方入口。团队应从明确 release 下载对应架构资产，记录校验值，不把 latest/download 放进可复现安装脚本。
devpod version
devpod provider list-available
devpod provider list第一条应显示受测 client 版本；第二条是该 client 可见的 provider 目录；第三条是当前 context 已安装的实例。若 Desktop 能打开而终端找不到 devpod，应检查 CLI 是否单独安装及 PATH；若 Linux AppImage 无法启动，则先核对 glibc、FUSE 与发行版支持条件，不要把 client 启动问题归因于 provider。
DevPod provider不是 client 内部的一行配置，而是由 provider.yaml 描述、可包含独立 helper binary 的 CLI 程序。manifest 可以声明不同 OS/arch 的下载 URL、压缩包路径和 checksum。machine provider 负责 VM 的 create/start/stop/delete；Docker、Kubernetes、SSH 一类 non-machine provider 通常直接在已有目标上管理容器。官方与 community provider 的来源、版本、校验和、支持承诺及许可证都应分别审查。
以下命令适合在本机可丢弃 Docker 环境中发现 provider 并建立第一条链路：
devpod provider add docker
devpod provider listdevpod provider add docker 使用的是一方 provider 短名，只适合发现和首次建立基线，不等于版本锁定。生产基线不要省略 provider 版本：添加 GitHub provider 时，未指定版本可能解析 latest release；应使用 repo@version、固定 manifest URL 或经审核的本地 manifest，并保存 manifest 与二进制校验信息，再用 devpod provider list 留存实际安装版本。同类型 provider 可以建立多个命名实例，例如不同云区域或机型，但 workspace 创建时选定的 provider 不能原地更换。迁移意味着创建新 workspace，并搬运由项目或外部存储明确持久化的数据。
machine provider 默认可以为每个 workspace 创建独立机器；启用 devpod provider use PROVIDER --single-machine 后，多个 workspace 会复用一台机器。复用能降低冷启动与云资源成本，也会把内核、磁盘、镜像缓存、端口和故障域绑在一起。团队只有在 provider 明确支持隔离、容量配额和逐 workspace 清理，并完成跨 workspace 凭据与数据反证后才应启用；否则一个磁盘打满或宿主失陷会同时影响多名开发者。
DevPod 主仓库采用 MPL-2.0；这个许可证不会自动覆盖 provider、云 CLI、IDE 或其底层运行时。团队允许列表应记录 client 与 provider 的版本、来源、checksum、许可、维护者和退出方法，而不是只写一个“已批准 DevPod”。
Context 是本地执行环境，不是项目合同
context 保存默认 provider、凭据注入、dotfiles 等本地控制面选项。provider、machine 和 workspace 都带 context 标识，状态位于 DEVPOD_HOME 下；切换 context 或改变 DEVPOD_HOME，看到的 workspace 清单也会改变。Windows 与 WSL 的路径、权限和凭据代理不同，不应让两边随意共用同一控制目录。
devpod context list
devpod context use default
devpod list排障时先记录当前 context、DEVPOD_HOME 和 provider，再看 workspace。常见的“昨天的工作区消失了”并不是远端资源被删除，而是 shell 指向另一个 home 或 context。反过来，直接删除 DEVPOD_HOME 也不等于 provider 已清理资源，它可能只是让 client 丢失索引。
context 不应提交进仓库。项目可复现声明仍属于 .devcontainer/devcontainer.json、语言锁文件、镜像 digest 与 Feature 版本；个人或组织的 provider、凭据、dotfiles 和 IDE 偏好属于执行上下文。DevPod 没有一个统一的 DevPod.lock 自动锁住这些输入。
让仓库显式消费 Dev Container 声明
在可丢弃仓库创建 .devcontainer/devcontainer.json：
{
"name": "orders-dev",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
"remoteUser": "vscode",
"postCreateCommand": "printf 'ready\\n' > \"$HOME/.devpod-ready\"",
"forwardPorts": [3000],
"containerEnv": {
"APP_ENV": "development"
}
}正式项目应把 image 换成组织验证过的 digest 或稳定版本，并继续提交语言依赖锁文件。DevPod 找不到配置时可以按语言生成默认值，但自动探测结果不是团队合同。它会解析 Dev Container 与 Features，追加构建 stage，再由当前 driver 选择 Docker、BuildKit 或 Kaniko 等路径形成 OCI image；相同 JSON 在不同 CPU 架构、mount 能力或构建后端上仍可能产生差异。
创建时显式给出 provider 与 IDE 模式：
devpod up . --id orders-dev --provider docker --ide none
devpod list
devpod ssh orders-dev --command 'id && pwd && test -f "$HOME/.devpod-ready"'--id orders-dev 把名称固定下来，避免目录改名或同仓库多 workspace 时后续命令误操作。这个 ID 创建后不能重命名，provider 也不能原地更换；迁移应创建新 ID，并分别核对源码、持久数据和外部服务。marker 放在远端用户主目录，避免把 workspace 名误当成固定挂载路径；pwd 的实际输出仍需单独与项目目录核对。预期证据包括：workspace 归属预期 context/provider，容器内用户与工作目录正确，marker 存在。若 up 成功而 SSH 失败，应把构建与连接拆开：先看 provider 资源是否存在，再看 agent 是否部署、tunnel 是否存活、SSH 会话是否建立。
DevPod 的工作链采用 client-agent 架构，没有一个长期共享 SaaS 控制面替代本地 client。client 通过 provider 特定 tunnel 部署 host/container agent，agent 再经 tunnel 的 STDIO 提供 SSH、日志、端口转发与凭据辅助。本地 IDE 连接的是这条 agent 会话。使用 --ide none 且没有活跃 devpod ssh 会话时，普通 DevPod 端口转发可能并不存在；Compose 自身 publish 则是另一条网络路径。看到容器内 localhost:3000 正常监听，仍需从实际 IDE/SSH 会话验证宿主入口。
IDE 接入应先把 SSH 当作最低公共入口。DevPod 会在 ~/.ssh/config 写入 orders-dev.devpod，因此可先执行 ssh orders-dev.devpod 验证主机条目，再使用 devpod ide list 查看当前 client 支持的 IDE。VS Code 需要本地 code CLI 与 Remote SSH 扩展；JetBrains 路径还依赖 Gateway 和对应订阅；openvscode 会在 workspace 安装服务端并经 tunnel 暴露到本机。IDE 打不开而 devpod ssh 正常时，应检查本地 IDE CLI、扩展、服务端下载和代理，不要重建一个健康 workspace。
端口验证也要经过连接入口：先在 workspace 内让服务监听 0.0.0.0:3000，再保持 IDE 或 SSH 会话，从本机访问 DevPod 提供的转发端口。故意把服务改为只监听错误端口，预期容器内探针和本机访问都失败；若容器内成功而本机失败，证据指向 tunnel 或会话生命周期，而不是应用构建。
正向实验要经过停止、恢复与正常删除
执行前应使用唯一 workspace 名、隔离 context、可丢弃 provider 资源和专用只读凭据，并记录 client、provider manifest 与底层资源标识。
在唯一命名的隔离 workspace 上执行：
devpod up . --id orders-dev --provider docker --ide none
devpod list
devpod ssh orders-dev --command 'test -f "$HOME/.devpod-ready"'
devpod stop orders-dev
devpod up orders-dev --ide none
devpod ssh orders-dev --command 'test -f "$HOME/.devpod-ready"'
devpod delete orders-dev
devpod list预期是首次启动能验证用户、源码路径与 marker；stop 后连接不可用；再次 up 后 marker 按 provider 的持久化语义恢复；正常 delete 成功，并且 Docker、Kubernetes 或云控制面中的对应资源消失。实验前后都执行 devpod list，删除前再次核对名称，避免把同名业务工作区当成试验对象。
stop 对 non-machine provider 通常是停止容器，对 machine provider 通常是关闭 VM。它可以释放 CPU、内存或计算费用，却不保证磁盘、IP、snapshot、registry 与云存储停止计费。恢复后 marker 仍在只证明这个 provider 保留了某些可变状态；可重建证据仍要来自正常 delete 后，用同一项目声明重新创建。
devpod up orders-dev --recreate 与 --reset 不能互换。recreate 用更新后的 Dev Container 声明重建开发容器，项目路径或挂载卷可以保留，容器内的手工修改会丢失；reset 从干净状态重新开始，连这些保留内容也不应继续依赖。修改 devcontainer.json 后先提交源码，再在可丢弃 workspace 演练 recreate；需要验证彻底重建时再用 reset。任何未提交代码、数据库文件或个人配置都必须在动作前按归属导出，不能把 provider 快照当成唯一备份。
用失败实验识别 prebuild 静默回退
prebuild由下面的命令写入 registry：
devpod build . --repository registry.example.com/platform/devpod-prebuilds
devpod up . --provider docker --ide none \
--prebuild-repository registry.example.com/platform/devpod-prebuilds --debugDevPod 根据 devcontainer.json 生成 devpod-HASH tag。命中时可省去现场构建，但 registry 中找不到对应 image，或者本地没有拉取凭据时，DevPod 可能跳过 prebuild 并回退到现场构建。因此不能用“workspace 最终启动”证明 prebuild 已命中；还要检查 debug 日志、实际 image/tag、registry 拉取记录和构建阶段耗时。
反向实验应使用隔离 registry 路径：先撤去该路径的读取凭据，执行带 --prebuild-repository 的 up，预期可能仍然成功，但日志显示拉取失败或现场构建；恢复短期凭据后删除并重新创建，预期命中同一 devpod-HASH image。日志只保留错误类型、registry 路径与 hash，不得记录 token。若两次都现场构建，要继续核对源目录、devcontainer 内容、目标架构和 provider driver 是否改变了 hash 或构建链。
prebuild 把等待时间转移成 registry 存储、构建资源和网络流量。团队可按 hash 命中率、现场构建时长、镜像体积、拉取流量与过期 tag 数量观察收益；若命中率长期低于预期，应先修复版本漂移或凭据分发，而不是无限延长镜像保留期。
registry 清理必须按 hash 引用关系执行。仍被活跃分支、受支持版本或离线恢复流程引用的 tag 不能仅按创建时间删除；多架构团队还要确认 manifest list 与各平台 image 一起保留。缓存命中率只能衡量速度，不能证明镜像来源可信，prebuild 仍应经过漏洞扫描、签名或摘要校验，并限制构建身份的 push 权限与开发者的 pull 权限。
凭据转发减少复制，不消除授权风险
DevPod 凭据辅助默认可通过 credential helper 向 workspace 提供本地 Git HTTPS 与 Docker registry 凭据，SSH 使用 agent forwarding；Git/Docker 注入可在 context 关闭，GPG agent forwarding 则需显式开启。provider option 还能调用本地命令获取云 token，并用类似 cache: 5m 的设置定期刷新短期值。
helper 与 forwarding 的价值是减少私钥或 token 落盘，但 workspace 内进程仍能借助代理访问已授权资源。postCreateCommand、Features、陌生仓库脚本和 IDE 扩展都属于可使用凭据的代码执行面。接入不可信仓库时，应使用权限更小的临时 context，关闭不需要的 Git/Docker 注入，只开放最小范围短期凭据，并在实验后撤销。
provider manifest 中的 password: true 只影响 UI/CLI 遮蔽，hidden 只控制显示；它们不是秘密保险库，也不保证 provider 子进程、环境变量或日志不会泄露。可在预先创建的隔离 context 中设计受控反例，先记录原值，再把 TEST_CONTEXT 替换成真实名称执行：
devpod context set-options TEST_CONTEXT -o SSH_INJECT_GIT_CREDENTIALS=false
devpod context set-options TEST_CONTEXT -o SSH_INJECT_DOCKER_CREDENTIALS=false
# 访问专用私有仓库与 registry，预期非零退出
devpod context set-options TEST_CONTEXT -o SSH_INJECT_GIT_CREDENTIALS=true
devpod context set-options TEST_CONTEXT -o SSH_INJECT_DOCKER_CREDENTIALS=true关闭注入后访问应明确失败，恢复原值后才应成功，同时扫描经过脱敏的 debug 日志确认没有 token 明文。set-options 影响该 context 的后续 workspace，不能在个人默认 context 上随手试验；若原值并非 true，最后必须恢复记录到的原值，而不是机械照抄示例。实验应使用专用只读凭据，并在结束后撤销，而不是使用个人长期云管理员身份。
普通删除失败时，不要急着 force
devpod delete NAME 试图删除 workspace 状态与 DevPod 记录，具体是删容器还是整台 VM 由 provider 决定。普通删除非零退出时，错误本身保留了可重试线索和本地映射；先记录 context、provider、workspace 名、provider resource ID 与底层标签，再处理网络、权限或 provider 故障。
devpod delete NAME --force 只删除本地 DevPod 记录并忽略 provider 错误，可能遗留云 VM、磁盘、IP、Kubernetes 对象或容器。它不是更彻底的删除。只有已记录底层 resource ID、确认普通删除无法恢复，并准备在 provider API/CLI 二次核销时才使用。安全的反向演练应在隔离云账号或 mock provider 中让 delete 返回失败：普通删除应非零并保留线索；force 后，再从 provider 控制面查找并删除遗留资源。共享账号和未知资源名不适合做这种实验。
删除 provider 前，先迁移或删除所有依赖它的 workspace，否则 client 失去后续交互入口，通常只能重新安装原 provider 才能恢复管理。stop workspace、delete workspace、delete provider、删除 DEVPOD_HOME、清理 registry prebuild 是五个独立动作。退出时还应撤销短期云凭据、Git/registry token、SSH agent 授权，并从 provider 账单与资源清单证明计算、磁盘、IP 和网络对象都已核销。
把容量与成本放回 Provider
DevPod client-only 不代表承载资源免费，也不会自动提供跨 provider 的统一配额和账单。成本来自实际 provider 的 VM 或容器、持久盘、IP、出站流量，以及 prebuild 的构建和 registry 存储。inactivity timeout 可以让闲置 workspace 自动停止，但应按 provider 验证它究竟停止容器、关闭 VM，还是删除计算后依赖持久盘重建。
团队治理应把 workspace 标签与云 resource ID 对齐，持续比较 DevPod 清单和 provider 实际资源；观察并发启动数、启动等待、现场构建比例、停止后仍计费资源、孤立磁盘/IP 和 registry tag 增长趋势。容量阈值来自 provider 配额、团队峰值和启动 SLO，不能套用一个与机型、区域无关的固定数字。
长期核销应维护两张账：DevPod context 中的 workspace/machine/provider 引用，以及云平台、Kubernetes、Docker 和 registry 中的实际对象。每天或每个结算周期按 context + workspace ID + provider resource ID 对账，识别“本地有记录但远端缺失”和“远端仍计费但本地无记录”两类漂移。停止策略先以一批低风险 workspace 观察恢复成功率和遗留费用，再扩大；删除策略连续执行两轮后，孤立资源数、持久盘容量与 registry 无引用 tag 应回到稳定基线，而不是随轮次增长。
当项目已经维护 Dev Container、希望在本地 Docker、Kubernetes、SSH 或云 VM 间选择承载位置，并接受逐 provider 验证差异时，DevPod 能提供轻量的 client-agent 入口。若需求依赖完整 guest 内核、传统系统服务、不同操作系统 VM 或强宿主隔离，Vagrant 的 provider/box 模型通常更直接。无论选哪一种，恢复现有状态都不能代替干净重建，转发凭据也不能代替最小权限，删除本地记录更不能代替远端资源核销。