Ubuntu 22.04 安装 act 指南

‍‍​​‌​> 目标：在 Ubuntu 22.04 服务器上从零安装 act（nektos/act，本地运行 GitHub Actions 的命令行工具）v0.2.89，覆盖 Docker Engine 前置准备、官方 install.sh 与手动二进制两种安装方案、actrc 基础配置、升级/降级与卸载清理。本文所有命令与回显均在 Ubuntu 22.04（x86_64）环境逐条实测，act 版本 v0.2.89，实测日期 2026-10-18。act 的定位与选型背景见 《act 介绍与选型指南》。

一、环境信息

本文实测环境与目标环境一致，按以下基准执行：

二、前置条件

2.1 确认系统与架构

act 官方为 Linux x86_64/arm64 等架构提供二进制，先确认服务器架构与发行版：

uname -m && grep PRETTY_NAME /etc/os-release

实测回显（Ubuntu 22.04 服务器）：

x86_64
PRETTY_NAME="Ubuntu 22.04.5 LTS"

架构为 x86_64 时，对应 act 发布包为 act_Linux_x86_64.tar.gz（下文方案 B 使用）。

2.2 安装并启用 Docker Engine

act 自身不含运行环境，执行 Job 时通过本机 Docker API 拉起平台镜像，因此 Docker Engine 是硬前置。Ubuntu 22.04 直接安装仓库内的 docker.io 包（实测包版本 29.1.3）：

apt-get update

实测输出节选（实测首尾）：

Get:1 http://archive.ubuntu.com/ubuntu jammy InRelease [270 kB]
Get:2 http://security.ubuntu.com/ubuntu jammy-security InRelease [129 kB]
...
Fetched 49.0 MB in 7s (6656 kB/s)
Reading package lists...

DEBIAN_FRONTEND=noninteractive apt-get install -y docker.io

实测输出节选（实测首尾）：

Unpacking docker.io (29.1.3-0ubuntu3~22.04.2) ...
Setting up docker.io (29.1.3-0ubuntu3~22.04.2) ...

设置开机自启并立即启动服务（Ubuntu 22.04 服务器由 systemd 托管）：

systemctl enable --now docker

验证安装与运行状态：

docker --version

实测回显：

Docker version 29.1.3, build 29.1.3-0ubuntu3~22.04.2

systemctl is-active docker

预期输出 active。验证通过的标志：docker --version 输出版本号、systemctl is-active docker 返回 active。

⚠️ 注意：Docker 守护进程未运行时，act 的执行类命令会直接失败。实测把 Docker 访问指向不可用套接字时，act 报错（可复现样例）：

failed to connect to the docker API at unix:///run/nonexistent.sock; check if the path is correct and if the daemon is running: dial unix /run/nonexistent.sock: connect: no such file or directory

遇到该形式报错先检查 systemctl is-active docker。

2.3 网络要求

安装与运行阶段需要的网络通路：

• 安装阶段：方案 A 需访问 raw.githubusercontent.com（取 install.sh）与 GitHub API（查版本）；方案 B 需访问 github.com 发布页下载二进制。
• 运行阶段：首次运行需从 ghcr.io 拉取平台镜像（catthehacker/ubuntu 系列，Medium 档实测本地占用约 2.31GB）。实测本环境 ghcr.io 直连稳定，github.com 偶发连接重置/TLS 超时（实测报错样例：net/http: TLS handshake timeout、read: connection reset by peer），重试即可成功。
• 服务器若经代理出网，为 curl 加 -x http://<代理地址>:<端口> 参数即可，act 本身不读取代理配置，平台镜像拉取走 Docker Engine 的代理设置。

三、版本选型说明

act 遵循「最新稳定版优先」即可：项目约每月发布一个补丁版本，v0.2.x 为当前唯一主线。实测 GitHub API 返回的近期版本列表（2026-10-18 查询）：

发布列表可随时用以下命令查询（无需登录）：

curl -s https://api.github.com/repos/nektos/act/releases/latest | grep -E '"tag_name"|"published_at"'

实测回显：

"tag_name": "v0.2.89",
"published_at": "2026-06-01T03:22:22Z",

选型结论：新装直接选 releases/latest 所指版本（本文为 v0.2.89）；存量环境升级前先看 Release Notes，act 升级不改变 workflow 文件本身，风险主要在参数行为变化，详见《act 运维手册》升级与回滚章节的实测流程。

四、方案 A：官方 install.sh 脚本安装（推荐联网服务器）

4.1 方案说明

install.sh 是官方仓库根目录提供的安装脚本，自动判断系统与架构、从 GitHub Releases 下载对应二进制并放到指定目录，支持 -b 指定安装路径。适合可直连 GitHub 的联网服务器，一条命令完成安装。

4.2 下载脚本并安装

先取脚本到本地（也可直接管道执行，建议落盘一份便于复查参数）：

curl -s -o install.sh https://raw.githubusercontent.com/nektos/act/master/install.sh

默认行为安装到当前目录 ./bin/act（实测，在空目录执行）：

bash install.sh v0.2.89

实测回显：

nektos/act info checking GitHub for tag 'v0.2.89'
nektos/act info found version: 0.2.89 for v0.2.89/Linux/x86_64
nektos/act info installed ./bin/act

服务器标准做法是用 -b 装进 PATH 目录，实测回显：

bash install.sh -b /usr/local/bin v0.2.89

nektos/act info checking GitHub for tag 'v0.2.89'
nektos/act info found version: 0.2.89 for v0.2.89/Linux/x86_64
nektos/act info installed /usr/local/bin/act

4.3 验证安装

act --version

实测回显：

act version 0.2.89

command -v act

实测回显：

/usr/local/bin/act

验证通过的标志：command -v act 返回安装路径，act --version 输出预期版本号。

4.4 重复执行的行为

对已装同版本（或更高版本）的环境重跑脚本，act 会被识别并跳过安装（实测）：

nektos/act info checking GitHub for tag 'v0.2.89'
nektos/act info found installed version: 0.2.89
nektos/act info act version 0.2.89 is already installed.

⚠️ 注意：脚本通过 GitHub API 查询版本标签，实测该接口偶发失败，报 nektos/act crit unable to find 'v0.2.89' - use 'latest' or see https://github.com/nektos/act/releases for details（标签实际存在）。重试即可成功；持续失败时改用方案 B 手动安装。

五、方案 B：手动下载二进制安装（离线/内网可控）

5.1 方案说明

直接从 GitHub Releases 下载 x86_64 压缩包，校验 sha256 后解压放进 PATH。适合无法走脚本联网探测的环境、需要对二进制做入库审计的场景，或 install.sh 反复失败的兜底。

5.2 下载与校验

curl -sL -o act_Linux_x86_64.tar.gz https://github.com/nektos/act/releases/download/v0.2.89/act_Linux_x86_64.tar.gz
ls -l act_Linux_x86_64.tar.gz

实测回显：

-rw-r--r--    1 root     root       8200078 Oct 18 02:18 act_Linux_x86_64.tar.gz

校验 sha256（实测值与官方 checksums.txt 一致）：

sha256sum act_Linux_x86_64.tar.gz

实测回显：

0191d6f1f3b716b5c55820032605d05fc3c1cdbf581ebeff655019e5dd1524c0  act_Linux_x86_64.tar.gz

💡 说明：官方随发布件提供 checksums.txt（与二进制同目录：https://github.com/nektos/act/releases/download/v0.2.89/checksums.txt），将其下载后与本地 sha256sum 输出比对，一致才继续安装。

查看压缩包内容：

tar tzf act_Linux_x86_64.tar.gz

实测回显：

LICENSE
README.md
act

5.3 解压并安装到 PATH

压缩包内是单文件二进制 act，用 tar 的 -O 直接释放到目标路径并赋予执行权限：

tar xzf act_Linux_x86_64.tar.gz act -O > /usr/local/bin/act && chmod +x /usr/local/bin/act

5.4 验证安装

act --version

实测回显：

act version 0.2.89

六、方案对比与选择建议

关键差异与选择建议：能联网且追求快，选方案 A 一条命令到位；内网隔离、需要对二进制留档校验，或方案 A 反复报 crit unable to find 时，选方案 B——两者产出的二进制完全相同（同一发布件），可随时互换。

七、配置说明（actrc 与默认文件）

7.1 actrc 的位置与加载顺序

act 支持配置文件 actrc：按 XDG 规范路径、HOME 目录、调用目录三个位置查找，最后合并命令行参数。官方原文表述（来源：https://nektosact.com/usage/index.html Configuration file 节，查询日期 2026-10-18）：「All found arguments will be parsed and appended to a list, in order of: .actrc as per the XDG spec, .actrc in HOME directory, .actrc in invocation directory, cli arguments」。格式为一行一个参数，不支持注释。

实测生效位置为 /root/.config/act/actrc，内容如下（实测 act --bug-report 中 Config files 段原样输出）：

/root/.config/act/actrc:
        -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest
        -P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:act-22.04
        -P ubuntu-20.04=ghcr.io/catthehacker/ubuntu:act-20.04

7.2 推荐的最小 actrc

平台映射是唯一强烈建议预写的配置——不写则首次运行会进入交互选择（见 7.4）。创建文件：

mkdir -p /root/.config/act
cat > /root/.config/act/actrc << 'EOF'
-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest
-P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:act-22.04
-P ubuntu-20.04=ghcr.io/catthehacker/ubuntu:act-20.04
EOF

逐项说明：-P ubuntu-latest=... 把 GitHub 托管 Runner 标签映射到 catthehacker 的 Medium 档平台镜像（兼容大多数 action，实测拉取后本地占用约 2.31GB）；-P ubuntu-22.04=...、-P ubuntu-20.04=... 为使用对应版本 runs-on: 的工作流提供版本匹配的镜像。另一个实用建议：-p --pull 默认 true（每次运行前都向远端确认镜像），本地重复验证场景可在命令行加 --pull=false 跳过远端检查、显著加速。验证配置已被读取：

act --bug-report | sed -n '/Config files/,/Build info/p'

实测输出（节选，实测首尾）：

Config files:
        /root/.config/act/actrc:
                -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest
                -P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:act-22.04
                -P ubuntu-20.04=ghcr.io/catthehacker/ubuntu:act-20.04

7.3 关键参数默认值速查

以下默认值取自 v0.2.89 act --list-options 实测 JSON（节选整理）：

⚠️ 注意：--artifact-server-addr 的默认值取本机接口地址，不同服务器不同（实测环境为 172.17.0.30），多网卡服务器建议显式指定。

7.4 首次运行的平台镜像选择与坑

未预写 actrc 时，首次执行会进入三档镜像的交互选择。实测提示原文：

? Please choose the default image you want to use with act:
  - Large size image: ca. 17GB download + 53.1GB storage, you will need 75GB of free disk space, snapshots of GitHub Hosted Runners without snap and pulled docker images
  - Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with most actions
  - Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions

在非交互终端（定时任务、CI 脚本、无 TTY 会话）中该提示无法应答，act 直接退出（实测回显）：

time="..." level=fatal msg=EOF

解决方法：按 7.2 预写 actrc 后再跑自动化脚本；或在交互终端手动跑一次完成选择（选择结果会写入 actrc）。验证方法：预写 actrc 后执行 act -l，能直接列出工作流且无镜像选择提示即为生效。

7.5 工作区内的默认读取文件

act 在仓库根目录按默认文件名自动读取：.env（环境变量）、.secrets（secrets，日志中自动脱敏）、.vars（vars）、.input（workflow_dispatch 输入）。文件不存在时静默跳过，存在即生效；格式均为 dotenv（KEY=VALUE，支持 export 前缀）。这一行为意味着仓库根目录的 .secrets 不要提交进版本库。

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

8.1 升级

用方案 A 重跑 install.sh 指定新版本即可（存在旧版本时脚本按已安装版本判断）：同版本会跳过（见 4.4 实测回显），更高版本直接覆盖安装。升级后验证：

act --version

预期输出新版本号（形如 act version 0.2.89）。

8.2 降级

install.sh 检测到已装同版本或更高版本时会跳过，降级必须走方案 B 手动覆盖。实测流程（从 0.2.89 降到 0.2.88 再恢复）：

curl -sL -o act_Linux_x86_64.tar.gz https://github.com/nektos/act/releases/download/v0.2.88/act_Linux_x86_64.tar.gz
tar xzf act_Linux_x86_64.tar.gz act -O > /usr/local/bin/act && chmod +x /usr/local/bin/act
act --version

实测回显：

act version 0.2.88

恢复到新版本（重新覆盖 v0.2.89 二进制）：

curl -sL -o act_Linux_x86_64.tar.gz https://github.com/nektos/act/releases/download/v0.2.89/act_Linux_x86_64.tar.gz
tar xzf act_Linux_x86_64.tar.gz act -O > /usr/local/bin/act && chmod +x /usr/local/bin/act
act --version

实测回显：

act version 0.2.89

8.3 多版本并存

act 无内置版本管理，多版本并存用「独立目录 + PATH 优先级」实现：把不同版本二进制分别放 /opt/act/0.2.88/act、/opt/act/0.2.89/act，需要哪个版本时把对应目录前置到 PATH，或直接以全路径调用（如 /opt/act/0.2.88/act -l）。

九、常见问题（FAQ）

Q1：install.sh 报 crit unable to find 'v0.2.89'，但版本明明存在？ 脚本靠 GitHub API 查询标签，接口偶发失败即报此错（实测多次复现，标签实际存在）。处理：直接重试；持续失败改走方案 B 手动下载。

Q2：重跑 install.sh 显示 already installed，怎么强制重装？ 脚本对已装同/更高版本会跳过（实测回显见 4.4）。强制重装先用方案 B 的手动覆盖流程，或先卸载旧二进制再跑脚本。

Q3：act: command not found？ 二进制不在 PATH。执行 command -v act 为空（实测退出码非 0）即说明 PATH 未包含安装目录；确认文件存在后检查 PATH 或用 -b /usr/local/bin 重装。

Q4：首次运行报 level=fatal msg=EOF？ 未预写 actrc 且当前是非交互终端，act 的镜像选择提示无人应答（实测回显见 7.4）。按 7.2 预写平台映射后重跑。

Q5：报 failed to connect to the docker API ...？ Docker Engine 未运行或套接字不可达（实测样例回显见 2.2）。systemctl is-active docker 确认状态，systemctl start docker 启动后重试。

Q6：下载 install.sh 或发布件时报 TLS handshake timeout / connection reset？ GitHub 侧网络波动，实测重试可成功；脚本类失败多试几次或改方案 B；平台镜像拉取失败的处理见《act 运维手册》故障排查手册。

十、卸载与清理

按产生的文件逐项清理：

rm -f /usr/local/bin/act

清理缓存目录（action 缓存与缓存服务数据，默认路径见 7.3）：

rm -rf /root/.cache/act /root/.cache/actcache

清理配置（如不再使用）：

rm -rf /root/.config/act

清理平台镜像（按实际存在的镜像执行，实测回显样例）：

docker rmi ghcr.io/catthehacker/ubuntu:act-latest

Untagged: ghcr.io/catthehacker/ubuntu:act-latest

验证卸载干净：

command -v act

实测回显（已卸载时无输出、退出码非 0，实测 EXIT=127）：

EXIT=127

💡 说明：卸载 act 不影响 Docker Engine 与其上其他业务；若 Docker 仅为 act 安装，可一并执行 apt-get purge -y docker.io 清理（先确认无其他负载依赖）。

十一、参考链接

• 官方安装文档（各平台安装方式总览）：https://nektosact.com/installation/index.html
• install.sh 脚本源码：https://raw.githubusercontent.com/nektos/act/master/install.sh
• 发布页（二进制与 checksums.txt 下载）：https://github.com/nektos/act/releases
• 官方 Usage guide（actrc 配置节）：https://nektosact.com/usage/index.html
• 平台镜像说明（Runners）：https://nektosact.com/usage/runners.html
• 站内相关：《act 介绍与选型指南》（定位与选型）；《Ubuntu 22.04 安装 GitHub Actions Runner 指南》（GitHub 云端/自托管 Runner 对照安装）