名称：act-docker-setup 用户可调用：false 描述：用于配置act的Docker环境，选择运行器镜像，管理容器资源，或解决本地GitHub Actions测试中的Docker相关问题。允许工具：

读取
写入
编辑
Bash
Grep
Glob

Act - Docker 配置与设置

当配置Docker用于act，选择运行器镜像，管理容器资源，以及优化Docker性能用于本地GitHub Actions工作流测试时使用此技能。

运行器镜像

镜像大小类别

Act支持三种镜像大小类别：

大小	镜像	工具	使用案例
微型	`node:16-buster-slim`	最小	简单的Node.js工作流
中型	`catthehacker/ubuntu:act-*`	常用工具	大多数工作流
大型	`catthehacker/ubuntu:full-*`	所有工具	最大兼容性

官方catthehacker镜像

# 最新Ubuntu (22.04)
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

# 特定Ubuntu版本
act -P ubuntu-22.04=catthehacker/ubuntu:act-22.04
act -P ubuntu-20.04=catthehacker/ubuntu:act-20.04

# 完整镜像（更大，更多工具）
act -P ubuntu-latest=catthehacker/ubuntu:full-latest
act -P ubuntu-22.04=catthehacker/ubuntu:full-22.04

# 运行器镜像（最接近GitHub）
act -P ubuntu-latest=catthehacker/ubuntu:runner-latest

语言特定镜像

# Node.js
act -P ubuntu-latest=node:20
act -P ubuntu-latest=node:20-alpine

# Python
act -P ubuntu-latest=python:3.12
act -P ubuntu-latest=python:3.12-slim

# Go
act -P ubuntu-latest=golang:1.22
act -P ubuntu-latest=golang:1.22-alpine

# Ruby
act -P ubuntu-latest=ruby:3.3
act -P ubuntu-latest=ruby:3.3-alpine

平台配置

.actrc 配置

在项目根目录创建 .actrc 以持久化设置：

# 默认平台镜像
-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
-P ubuntu-20.04=catthehacker/ubuntu:act-20.04

# 重用容器
--reuse

# 容器选项
--container-architecture linux/amd64
--container-daemon-socket -

# 资源限制
--container-cap-add SYS_PTRACE
--container-cap-add NET_ADMIN

每工作流配置

创建 .github/workflows/.actrc 以工作流特定设置：

-P ubuntu-latest=node:20
--env-file .env.ci

命令行覆盖

# 覆盖 .actrc 设置
act -P ubuntu-latest=python:3.12 --no-reuse

容器管理

重用容器

# 重用容器以加速迭代
act --reuse

# 重用特定作业
act --reuse -j build

# 强制重新创建容器
act --rm

容器生命周期

# 列出运行的act容器
docker ps --filter "label=act"

# 停止所有act容器
docker stop $(docker ps -q --filter "label=act")

# 移除所有act容器
docker rm $(docker ps -aq --filter "label=act")

# 清理act卷
docker volume prune

检查容器

# 执行进入运行容器
docker exec -it act-<job-name> /bin/bash

# 查看容器日志
docker logs act-<job-name>

# 检查容器配置
docker inspect act-<job-name>

卷挂载和绑定

默认挂载

Act自动挂载：

当前目录 → /github/workspace
Act缓存 → /root/.cache/act
Docker套接字（如果需要）

自定义绑定挂载

# 挂载额外目录
act --bind /host/path:/container/path

# 挂载多个目录
act --bind /data:/data --bind /config:/config

# 只读挂载
act --bind /readonly:/readonly:ro

持久化缓存

# 配置缓存位置
export ACT_CACHE_DIR=$HOME/.cache/act

# 清理缓存
rm -rf $HOME/.cache/act

Docker配置

Docker套接字

# 使用默认Docker套接字
act --container-daemon-socket -

# 使用自定义套接字
act --container-daemon-socket /var/run/docker.sock

# 使用Docker Desktop套接字（Mac）
act --container-daemon-socket unix:///Users/$USER/.docker/run/docker.sock

容器架构

# 指定架构
act --container-architecture linux/amd64

# 适用于Apple Silicon Macs
act --container-architecture linux/arm64

网络配置

# 使用主机网络
act --network host

# 使用自定义网络
act --network my-network

# 创建隔离网络
docker network create act-network
act --network act-network

资源管理

内存限制

# 设置内存限制
act --memory 4g

# 设置内存和交换
act --memory 4g --memory-swap 8g

CPU限制

# 限制CPU核心
act --cpus 2

# 设置CPU份额
act --cpu-shares 512

磁盘空间

# 检查Docker磁盘使用
docker system df

# 清理未使用资源
docker system prune -a

# 移除旧act缓存
find ~/.cache/act -type d -mtime +30 -exec rm -rf {} +

安全

能力

# 添加Linux能力
act --container-cap-add SYS_PTRACE

# 移除能力
act --container-cap-drop ALL

# 安全配置
act --security-opt seccomp=unconfined

特权模式

# 以特权模式运行（谨慎使用）
act --privileged

# 更安全：添加特定能力
act --container-cap-add SYS_ADMIN

多平台构建

Docker Buildx

# 使用buildx的工作流
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v5
        with:
          platforms: linux/amd64,linux/arm64

用act测试：

# 在act中启用buildx
act --use-gitignore=false \
    -P ubuntu-latest=catthehacker/ubuntu:act-latest

故障排除

镜像拉取失败

# 手动拉取镜像
docker pull catthehacker/ubuntu:act-latest

# 使用缓存镜像
act --pull=false

# 强制拉取最新
act --pull=true

权限问题

# 修复工作空间权限
act --container-options "--user $(id -u):$(id -g)"

# 以root运行（不推荐）
act --container-options "--user root"

DNS问题

# 使用自定义DNS
act --container-options "--dns 8.8.8.8"

# 使用主机DNS
act --container-options "--dns-search ."

容器退出码

# 继续在错误上
act --continue-on-error

# 捕获退出码
act; echo $?

性能优化

镜像选择

选择满足需求的最小镜像：

# 快速但有限
act -P ubuntu-latest=node:20-alpine

# 平衡
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

# 全面但慢
act -P ubuntu-latest=catthehacker/ubuntu:full-latest

层缓存

# 优化Dockerfile以缓存
FROM node:20

# 首先安装系统依赖（很少变化）
RUN apt-get update && apt-get install -y git

# 复制包文件（有时变化）
COPY package*.json ./

# 安装依赖（有时变化）
RUN npm ci

# 复制源码（经常变化）
COPY . .

并行作业

# 并行运行作业
act --parallel

# 限制并行性
act --parallel --jobs 2

自定义镜像

构建自定义镜像

创建 Dockerfile：

FROM catthehacker/ubuntu:act-latest

# 添加自定义工具
RUN apt-get update && apt-get install -y \
    postgresql-client \
    redis-tools \
    && rm -rf /var/lib/apt/lists/*

# 安装特定Node版本
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs

# 安装全局npm包
RUN npm install -g pnpm yarn

构建和使用：

docker build -t my-act-runner .
act -P ubuntu-latest=my-act-runner

发布自定义镜像

# 标记镜像
docker tag my-act-runner username/act-runner:latest

# 推送到Docker Hub
docker push username/act-runner:latest

# 在团队中使用
act -P ubuntu-latest=username/act-runner:latest

最佳实践

做

✅ 使用 .actrc 以团队一致配置 ✅ 根据需求选择适当镜像大小 ✅ 在开发中使用 --reuse ✅ 定期清理Docker资源 ✅ 在生产工作流中固定镜像版本 ✅ 使用层缓存以加速构建 ✅ 在README中记录镜像需求

不做

❌ 在生产中使用 :latest 标签 ❌ 不必要地以特权模式运行容器 ❌ 忽略Docker磁盘空间使用 ❌ 对简单工作流使用过大的镜像 ❌ 将大型镜像提交到版本控制 ❌ 跳过Docker资源清理 ❌ 在容器日志中暴露敏感数据

常见模式

开发设置

# 快速迭代设置
cat > .actrc << 'EOF'
-P ubuntu-latest=catthehacker/ubuntu:act-latest
--reuse
--rm=false
--container-architecture linux/amd64
EOF

CI验证

# 严格验证设置
act --dryrun \
    --pull=true \
    --no-reuse \
    -P ubuntu-latest=catthehacker/ubuntu:full-latest

单体仓库设置

# 每作业不同镜像
act -j backend -P ubuntu-latest=node:20 \
    -j frontend -P ubuntu-latest=node:20-alpine \
    -j database -P ubuntu-latest=postgres:16