Ubuntu 22.04 安装 dagger 0.21.10 指南

Ubuntu 22.04（x86_64）从零安装 dagger CLI v0.21.10 实测指南：官方脚本 BIN_DIR 与 Release 离线包双方案、sha256 校验、PATH 与补全配置、引擎按需拉起、升级/多版本/卸载，含镜像拉取失败代理重建实测排障。

daggerCICDDocker容器GoPython2026/10/19

Ubuntu 22.04 安装 dagger 0.21.10 指南

目标：在 Ubuntu 22.04 服务器上从零安装 dagger CLI（v0.21.10），覆盖官方脚本与 Release 离线包两种安装方案、sha256 校验、PATH 配置、引擎按需拉起说明、版本检查、升级/多版本管理与卸载清理。已在 Ubuntu 22.04.4 LTS（x86_64）实测通过。

一、环境信息

本章记录本次安装实测的服务器环境与版本依据，保证命令与回显可复现。

  • 操作系统：Ubuntu 22.04.4 LTS（x86_64），内核 6.8.0-138-generic
  • 安装对象：dagger CLI v0.21.10（GitHub Releases 最新稳定 Release，2026-09-30 发布，非 prerelease；版本依据实查日期 2026-10-19）
  • 配套引擎版本：registry.dagger.io/engine:v0.21.10（CLI 首次执行任务时自动按需拉起，与 CLI 版本一一对应）
  • 下载通道：本文实测在内网代理环境执行，命令示例中的 -x http://192.168.1.62:7897 为代理参数（curl 通用语法）；公网直连可达的服务器去掉该参数即可，其余步骤完全一致
  • 实测安装位置：/root/.local/bin/dagger（方案 B 手动指定），二进制大小 64,573,602 字节
  • 版本验证回显（实测）：
dagger version

dagger v0.21.10 (image://registry.dagger.io/engine:v0.21.10) linux/amd64

二、前置条件

本章列出安装前需要确认的系统条件，逐项给出检查命令与实测回显。

  1. 基础工具：curl（下载）、tar（解压）、sha256sum（校验），Ubuntu 22.04 默认自带；缺则安装：
apt-get update && apt-get install -y curl tar coreutils
  1. 容器运行时（引擎依赖）：dagger 本职运行时即容器化引擎——CLI 执行任务时若本机没有运行中的引擎实例，会自动创建并启动一个 dagger-engine-<版本> 运行实例，因此服务器需具备可用的容器运行时环境（Linux 上通常为 Docker）。检查命令与实测回显：
docker --version

Docker version 29.8.1, build 4a63305
  1. 网络可达性：需要访问 dl.dagger.io（官方下载分发）下载 CLI；首次执行任务时引擎还需要访问容器镜像源拉取引擎镜像与流水线用基础镜像。受限网络环境请提前配置代理（见八、常见问题）。
  2. 磁盘空间：CLI 二进制约 62 MiB，引擎镜像约数百 MiB，预留 2 GiB 以上余量即可。

三、版本选型说明

本章说明版本获取方法与选型原则，避免使用臆造或过时的版本号。

  • 最新稳定版查询（实查命令，2026-10-19 执行）：
curl -s https://api.github.com/repos/dagger/dagger/releases?per_page=5 | grep -E '"tag_name"|"prerelease"'

  "tag_name": "v0.21.10",
  "prerelease": false,
  "tag_name": "sdk/typescript/v0.21.10",
  "prerelease": false,
  "tag_name": "sdk/rust/v0.21.10",
  "prerelease": false,

输出节选（实测首尾）：返回列表同时包含主版本标签与各语言 SDK 子标签（sdk/<语言>/v0.21.10），prerelease 均为 false；安装认准不带 / 的主版本标签 v0.21.10。

  • 选型原则：
    • 生产环境选最新稳定 Release（本文 v0.21.10），不用 Pre-release 与 draft；
    • CLI 与引擎镜像版本强绑定（CLI 二进制内嵌对应引擎镜像地址），升级 CLI 即升级引擎；
    • 官方迭代节奏约每月一个稳定版（v0.21.9 于 2026-08-26、v0.21.8 于 2026-07-29 发布），升级周期建议按月跟随。

四、方案 A：官方安装脚本（在线安装）

本章使用官方一键脚本安装。脚本自动判断系统架构、下载对应压缩包、校验并释放二进制。特别注意：脚本默认把二进制安装到"当前工作目录下的 ./bin"（实测结论），不是系统路径；通过环境变量 BIN_DIR 指定目标目录（脚本内用法为 BIN_DIR=<path/to/dir> $0，见脚本第 246 行）。

4.1 默认目录安装（安装到 ./bin）

mkdir -p /opt/dagger-install && cd /opt/dagger-install
curl -x http://192.168.1.62:7897 https://dl.dagger.io/dagger/install.sh | bash

实测回显：

bash debug downloading files into /tmp/tmp.aB6CUkVWhE
bash debug http_download https://dl.dagger.io/dagger/releases/0.21.10/dagger_v0.21.10_linux_amd64.tar.gz
bash debug http_download https://dl.dagger.io/dagger/releases/0.21.10/checksums.txt
bash debug display shell completion instructions
bash info installed ./bin/dagger

安装后二进制位于 /opt/dagger-install/bin/dagger，验证：

ls -la /opt/dagger-install/bin/

total 63072
drwxr-xr-x 2 root root     4096 10月 19 12:59 .
drwxr-xr-x 3 root root     4096 10月 19 12:59 ..
-rwxr-xr-x 1 root root 64573602 10月 19 12:59 dagger

4.2 指定目录安装（安装到 /usr/local/bin，推荐）

curl -x http://192.168.1.62:7897 https://dl.dagger.io/dagger/install.sh | BIN_DIR=/usr/local/bin bash

⚠️ 注意：不要写成 bash install.sh -d /usr/local/bin——实测 -d 参数不会改变安装目录（二进制仍落在 ./bin），该脚本只认 BIN_DIR 环境变量。无 /usr/local/bin 写权限（非 root）时，改用 BIN_DIR=$HOME/.local/bin。

4.3 脚本安装后的 PATH 与验证

若安装到了非 PATH 目录，先配置 PATH（以 /root/.local/bin 为例）：

grep -q '/root/.local/bin' /root/.bashrc || echo 'export PATH="/root/.local/bin:$PATH"' >> /root/.bashrc
export PATH="/root/.local/bin:$PATH"

验证（实测回显）：

which dagger && dagger version

/root/.local/bin/dagger
dagger v0.21.10 (image://registry.dagger.io/engine:v0.21.10) linux/amd64

五、方案 B：Release 离线包手动安装

本章适用于无法直连官方脚本源、或需要把安装包预先下载分发到多台服务器的场景：从 Release 分发地址手动下载 tar.gz，用官方 checksums.txt 做 sha256 校验后解压安装。整个过程只依赖 curl/tar/sha256sum，可完全离线执行（提前把两个文件拷贝到目标机）。

5.1 下载压缩包与校验文件

cd /tmp
curl -x http://192.168.1.62:7897 -LO https://dl.dagger.io/dagger/releases/0.21.10/dagger_v0.21.10_linux_amd64.tar.gz
curl -x http://192.168.1.62:7897 -LO https://dl.dagger.io/dagger/releases/0.21.10/checksums.txt

5.2 sha256 校验（必做）

grep linux_amd64 checksums.txt
sha256sum dagger_v0.21.10_linux_amd64.tar.gz

实测回显（两行哈希一致即校验通过）：

f9ee083767dd12cdac583f9db3fedbebbbb3064f69152998be1f121d1a6cc103  dagger_v0.21.10_linux_amd64.tar.gz
f9ee083767dd12cdac583f9db3fedbebbbb3064f69152998be1f121d1a6cc103  dagger_v0.21.10_linux_amd64.tar.gz

5.3 解压并安装到系统目录

tar -xzf dagger_v0.21.10_linux_amd64.tar.gz
install -m 0755 dagger /root/.local/bin/dagger

压缩包内共两个文件：dagger 二进制与 LICENSE。目标目录需已在 PATH 中（/usr/local/bin 或自建目录配 PATH 均可，见 4.3）。

5.4 验证安装

dagger version

dagger v0.21.10 (image://registry.dagger.io/engine:v0.21.10) linux/amd64

再执行一次带更新检查的版本命令，确认 CLI 可正常访问版本服务（受限网络需给该命令单独设代理）：

https_proxy=http://192.168.1.62:7897 dagger version --check

dagger v0.21.10 (image://registry.dagger.io/engine:v0.21.10) linux/amd64

回显与不带 --check 相同，表示当前已是最新稳定版；若有新版本，输出中会带更新提示。

六、方案对比与选择建议

维度方案 A：官方脚本方案 B：Release 离线包
是否需联网执行是（脚本现场下载）下载可离线预先完成
版本指定默认装最新稳定版，支持环境变量指定版本下载 URL 中显式写死版本号
完整性校验脚本内部自动校验 checksums需手动 grep + sha256sum 对比
安装目录控制BIN_DIR 环境变量（默认 ./bin）install -m 0755 任意指定
适用场景单机快速上手批量分发、内网隔离、审计要求留包

选择建议：单机联网环境直接方案 A（记得用 BIN_DIR 指定系统目录）；内网/批量/合规场景用方案 B 把版本与校验握在手里。

七、配置说明

本章说明安装后的三项常规配置：PATH、Shell 补全、引擎的按需拉起行为。

7.1 PATH 持久化

方案 A 默认目录与自建目录都需要写进 shell 配置，方法见 4.3（追加 export PATH=... 到 /root/.bashrc 并 source 生效）。验证：

echo $PATH | tr ':' '\n' | grep -n local

1:/root/.local/bin

7.2 Shell 自动补全

官方脚本安装完成时会提示补全配置方式（实测提示"display shell completion instructions"）。以 bash 为例生成：

dagger completion bash

该命令输出一段 bash 补全脚本（内容较长，此处不整段摘录），按官方惯例落盘到 /etc/bash_completion.d/dagger 或 ~/.local/share/bash-completion/completions/dagger 后重开 shell 生效。

7.3 引擎按需拉起说明（组件本职行为）

CLI 本身不跑构建——首次执行 dagger call/query 等任务时，CLI 自动完成三步：检测本机引擎实例 → 不存在则创建（实例名 dagger-engine-v0.21.10，与 CLI 版本一致）→ 连接后执行。实例随用随起、用完常驻以便复用缓存。可随时用容器运行时命令查看实例状态：

docker ps -a --filter name=dagger-engine --format '{{.Names}}  {{.Status}}'

dagger-engine-v0.21.10  Up 2 minutes

⚠️ 引擎实例需要访问容器镜像源拉取引擎镜像与流水线基础镜像；受限网络下的代理配置见八、常见问题第 3 条。

八、常见问题（FAQ）

本章沉淀安装与首跑过程中实测遇到的三个问题，均给出错误现象、定位过程与解决方案。

Q1：install.sh | bash -s -- -d /usr/local/bin 执行后，/usr/local/bin/dagger 不存在？

  • 现象（实测）：脚本回显 bash info installed ./bin/dagger，目标目录没有文件。
  • 定位：查看脚本源码，第 378 行 bin_dir="${BIN_DIR:-./bin}"——默认 ./bin，只认环境变量 BIN_DIR，命令行参数 -d 会被忽略。
  • 解决：curl -s https://dl.dagger.io/dagger/install.sh | BIN_DIR=/usr/local/bin bash；或用方案 B 手动 install -m 0755 dagger <目录>。

Q2：安装后执行 dagger version 报 command not found？

  • 现象：No such file or directory 或 shell 提示找不到命令。
  • 定位：which dagger 无输出——安装目录不在 PATH（方案 A 默认 ./bin 最常见）。
  • 解决：把实际安装目录加入 PATH（4.3），或重装到 /usr/local/bin。

Q3：首次执行任务时镜像拉取失败，报 dial tcp ...:443: connect: connection refused？

  • 现象（实测原文）：
Error: make request: input: container.from failed to resolve image "docker.io/library/hello-world:latest"
(platform: "linux/amd64"): failed to do request: Head
"https://registry-1.docker.io/v2/library/hello-world/manifests/latest": dial tcp 202.160.128.40:443:
connect: connection refused
  • 定位：引擎实例访问容器镜像源走的是引擎自身进程的网络栈，不走宿主机容器运行时守护进程的代理配置；受限网络下引擎进程直连被拒。
  • 解决：删除引擎实例后，带代理环境变量手动重建同名实例（命令按 2026-10-19 实测记录，代理地址换成实际值）：
docker rm -f dagger-engine-v0.21.10
docker run -d --name dagger-engine-v0.21.10 --privileged \
  -e HTTP_PROXY=http://192.168.1.62:7897 \
  -e HTTPS_PROXY=http://192.168.1.62:7897 \
  -e NO_PROXY=localhost,127.0.0.1 \
  registry.dagger.io/engine:v0.21.10

重建后重跑任务即可正常拉取。注意：引擎实例被删除后 CLI 会自动重建，但自动重建的实例不带代理变量（实测验证），受限网络环境需按上述命令手工重建。

九、升级、降级与多版本管理

本章说明版本切换的三种实操方式。

  • 升级到最新稳定版：重跑方案 A 脚本（默认拉最新版覆盖安装）；方案 B 用户把下载 URL 中的版本号改成目标版本重下重装。升级后引擎实例按新 CLI 版本自动重建（实例名含版本号，互不冲突）：
dagger version
  • 降级/回滚：用方案 B 下载旧版本压缩包覆盖二进制即可（版本号写进 URL，如 .../releases/0.21.9/dagger_v0.21.9_linux_amd64.tar.gz）；旧版引擎实例名独立存在，无需额外清理。
  • 多版本共存：把不同版本二进制装到不同目录（如 /opt/dagger/0.21.10/bin/dagger、/opt/dagger/0.21.9/bin/dagger），用 PATH 顺序或别名切换：
alias dagger-0.21.9='/opt/dagger/0.21.9/bin/dagger'

⚠️ 模块的 dagger.json 记录了开发时的 engineVersion，跨版本调用函数前建议保持 CLI 版本不低于模块记录版本。

十、卸载与清理

本章给出完整卸载步骤，从 CLI 到引擎实例逐层清理。

# 1. 删除 CLI 二进制（按实际安装路径）
rm -f /root/.local/bin/dagger /usr/local/bin/dagger

# 2. 删除引擎实例（实例名含版本号，先查后删）
docker ps -a --filter name=dagger-engine --format '{{.Names}}'
docker rm -f dagger-engine-v0.21.10

# 3. 删除 shell 补全（如配置过）
rm -f /etc/bash_completion.d/dagger

# 4. 清理 PATH 配置（编辑 /root/.bashrc 删除对应 export 行）

验证卸载干净：

which dagger; docker ps -a --filter name=dagger-engine --format '{{.Names}}'

两条命令均无输出即清理完成。

十一、参考链接