actDocker配置技能：把本地 GitHub Actions 测试的 Docker 环境一次配明白
- 一句话定位：act-docker-setup（actDocker配置技能）是一个专注于「act + Docker」环境配置的 AI 技能，帮你选对运行器镜像、配好
.actrc、管好容器资源，让本地跑 GitHub Actions 工作流不再卡在环境问题上。 - 核心能力：镜像大小类别与语言专用镜像推荐、
.actrc与每工作流配置生成、容器重用与生命周期管理、卷挂载、架构与网络配置、内存/CPU 资源限制、安全能力控制、故障排查与性能优化。 - 工作方式：技能可直接读取/写入/编辑你的配置文件，并通过 Bash 执行
docker、act相关命令，用 Grep/Glob 在仓库中定位工作流文件与已有配置。 - 适用人群：需要在本地复现 CI 行为的开发者、维护多语言单体仓库的团队、使用 Apple Silicon 的 Mac 用户、以及为团队制定统一本地测试规范的技术负责人。
- 使用提示：技能的元信息显示其「用户可调用」为 false，通常作为辅助技能被配合使用，具体调用入口与安装方式以官方说明为准。
该技能叫什么？如何下载安装 AI 技能提升开发效率？
基本信息
- 中文名：actDocker配置技能
- 英文名：act-docker-setup
- 技能 ID：13993
它解决什么问题？
act 是本地运行 GitHub Actions 工作流的常用工具，但它真正的门槛往往不在命令行参数，而在 Docker 环境本身：镜像选大了，拉取慢、占空间；镜像选小了，工作流里的工具缺失导致莫名失败；没有 .actrc 时，每条命令都要重复敲一长串 -P 参数；容器不复用时，每轮迭代都要重装依赖；Mac 上架构不匹配、权限不匹配、DNS 不通，报错信息还常常看不出根因。
act-docker-setup 技能就是把这些分散在文档、经验和报错堆栈里的知识固化下来：它会根据你的项目语言、工作流内容和机器环境，给出镜像选型、配置文件内容、容器管理命令和排错思路，并直接帮你把配置文件写进仓库。
「一键安装」提升开发效率的思路
这个技能的价值在于把「查文档—试参数—踩坑—再试」的循环压缩成一次对话。安装与环境准备的通用思路如下（具体命令、入口、价格等信息以官方说明为准）：
- 确认安装前提：本地已安装可用的 Docker 环境（Docker Desktop 或 Docker Engine），已安装 act 命令行工具；已在一个支持 AI 技能（Skill）的客户端或技能市场中登录，具备技能安装权限。
- 进入技能入口：在技能市场的搜索框中使用技能名称「act-docker-setup」或技能 ID「13993」进行检索，找到对应技能条目。
- 执行安装：点击安装/启用按钮，按提示确认所需的工具权限（读取、写入、编辑、Bash、Grep、Glob）。这些权限决定了技能能否直接改写
.actrc、执行docker ps等命令。 - 验证是否生效：安装后发起一次对话，让技能「检查当前项目的 act 与 Docker 配置情况」。如果它能返回 Docker 版本检查思路、
.actrc是否存在、当前使用的工作流文件清单等信息，说明技能已正常工作。 - 建立首个配置：在项目根目录让技能「为 Node.js 项目生成开发用的
.actrc」，若仓库中得到预期的配置文件内容，即证明读写能力可用。
该技能的主要功能和特点
- 运行器镜像分级推荐：技能内置三类镜像思路——微型（如
node:16-buster-slim，适合简单 Node.js 工作流）、中型（catthehacker/ubuntu:act-*，覆盖常用工具，适配大多数工作流）、大型（catthehacker/ubuntu:full-*，工具最全、体积最大、兼容性最强）。相比凭经验瞎试，它能把「体积/速度/兼容性」的取舍讲清楚。 - 语言专用镜像方案：针对 Node.js、Python、Go、Ruby 等语言，给出
node:20、python:3.12-slim、golang:1.22、ruby:3.3等轻量替代方案，显著加快本地测试的镜像拉取与启动速度。 - 配置持久化能力：帮助生成项目根目录的
.actrc（默认平台镜像、容器重用、架构、资源限制、能力添加等），以及.github/workflows/.actrc的工作流级配置，避免每次敲长参数。 - 容器生命周期管理：给出
--reuse、--rm等重用与重建策略，以及按label=act过滤列出、停止、移除容器与清理卷的命令，帮你把残留容器的问题收干净。 - 挂载与缓存管理：说明 act 默认挂载的
/github/workspace、/root/.cache/act、Docker 套接字，并支持自定义--bind挂载（含只读挂载）与ACT_CACHE_DIR缓存目录持久化。 - 架构与网络适配：覆盖
--container-architecture linux/amd64/linux/arm64（Apple Silicon 场景）、--container-daemon-socket（Docker Desktop 套接字）、--network host与自定义网络隔离。 - 资源与安全控制：
--memory、--memory-swap、--cpus、--cpu-shares限制资源；--container-cap-add、--container-cap-drop ALL、--security-opt、--privileged说明权限边界，并强调特权模式的谨慎使用。 - 排错与性能优化知识库：镜像拉取失败（
--pull=false/--pull=true）、权限问题（--user $(id -u):$(id -g)）、DNS 问题（--dns 8.8.8.8）、退出码处理（--continue-on-error），以及分层缓存写法和--parallel --jobs并行执行。 - 自定义镜像全流程：从基于
catthehacker/ubuntu:act-latest编写 Dockerfile、构建、打标签到推送 Docker Hub 并在团队内共用。 - 能力强于「普通搜索」的地方：它能结合你的仓库实际情况（工作流文件、已有
.actrc、语言栈）给出一份可落地的配置，而不是一堆需要自己拼装的参数列表。
如何使用该技能？
以下为通用的使用流程与可直接参考的对话示例，具体入口以官方说明为准。
第 1 步：交代环境与目标
先说明项目语言、工作流内容和本机情况。示例提问：
「我用的是 M 系列芯片的 Mac，项目是 Node.js 20 + pnpm，工作流里有 build 和 test 两个 job。帮我配一套本地开发用的 act Docker 环境。」
第 2 步：让技能做现状检查
技能会借助 Grep/Glob 找到 .github/workflows 下的工作流文件，并检查是否已有 .actrc、使用了哪些 runs-on 标签，从而确定需要映射的平台镜像。
第 3 步：确认镜像选型
技能通常会给出三种取舍方案，例如：
- 追求速度：
act -P ubuntu-latest=node:20-alpine - 平衡常用：
act -P ubuntu-latest=catthehacker/ubuntu:act-latest - 最大兼容：
act -P ubuntu-latest=catthehacker/ubuntu:full-latest
第 4 步：生成并写入 .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-cap-add SYS_PTRACE
第 5 步：执行与迭代
用 act --reuse -j build 快速迭代；需要强制重建容器时用 act --rm；需要覆盖配置时在命令行加参数，例如 act -P ubuntu-latest=python:3.12 --no-reuse。
第 6 步：清理与收尾
让技能给出清理命令：docker ps -q --filter "label=act" 找到容器，docker system df 检查磁盘占用，docker system prune -a 与清理过期 act 缓存目录。
输入/输出说明：输入是「项目情况 + 目标 + 报错信息」；输出通常是「镜像选型建议 + 可直接落盘的配置片段 + 执行命令 + 排错方向」。如果工作流跑失败，把报错原文贴给技能，它能对照权限、DNS、架构、镜像缺失等常见根因给出定位思路。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| act-docker-setup（本技能） | 面向 act + Docker 环境的 AI 配置助手 | 镜像选型、.actrc 生成、容器与资源管理、排错与优化建议 |
需具备 Docker、act 与技能客户端；通过对话驱动，门槛较低 | 本地复现 CI、团队统一本地测试配置、Mac 架构与权限问题排查 | 优势：把分散经验结构化，能直接改写配置文件；不足：元信息显示非用户直接调用型技能，依赖配套技能与客户端，具体能力边界以官方说明为准 |
| 手写 act 命令行 + 自行查文档 | 传统手工方式 | 完全自由地拼装参数 | 需要熟悉 act 参数、Docker 镜像体系与容器排错 | 一次性简单任务、临时验证 | 优势：零额外依赖、可控；不足：配置不可复用、易踩坑、团队协同差、排错成本高 |
| 云端 GitHub Actions 直接运行 | 官方托管 CI | 完整官方运行器环境 | 需要推送代码、消耗云端额度 | 最终验证、上线前流水线 | 优势：环境最接近真实、无需本地 Docker；不足：反馈链路长、消耗额度、调试迭代慢 |
| 自建 Docker Compose / 自制脚本封装 | 工程化自建方案 | 自定义容器编排与脚本封装 | 需要较强 Docker 与脚本能力，维护成本高 | 大型团队定制化流水线 | 优势：高度可定制；不足：建设与维护成本高，缺乏 act 生态的镜像与参数知识沉淀 |
选型建议：如果你只是想偶尔本地跑一次工作流，手工命令足够；如果 CI 是日常开发的一部分，需要频繁迭代、多人协作、跨 Mac/Windows/Linux 环境，那么用本技能把配置固化成 .actrc + 团队约定的方式，收益最明显。
该技能的典型应用场景与实际体验情况
场景一：前端开发者本地复现 CI 失败
角色：前端工程师，工作流在云端偶发失败但本地无法复现。痛点：不知道本地该用哪个镜像，凭感觉用 full-latest 结果每次拉取都要等很久。使用方式：把工作流的 runs-on 与失败日志交给技能，得到「用 catthehacker/ubuntu:act-latest + --reuse」的组合建议，并把结果写入 .actrc。实际体验：镜像体积与启动速度的取舍被明确量化，重复迭代时因容器重用而明显加快；注意首次拉取镜像仍需耐心等待，且固定版本标签比 :latest 更稳。
场景二：多语言单体仓库的差异化镜像映射
角色：平台工程师维护包含 backend、frontend、database 的工作流。痛点：一个镜像跑所有 job 既慢又不兼容。使用方式：技能给出按 job 指定镜像的方案，如 act -j backend -P ubuntu-latest=node:20、act -j frontend -P ubuntu-latest=node:20-alpine、-j database -P ubuntu-latest=postgres:16。实际体验：单体仓库的资源浪费明显下降；注意事项是要把每个 job 的镜像映射写进 .actrc 或文档，避免新人再问一遍。
场景三：Apple Silicon 用户的架构与套接字问题
角色：Mac 用户，容器启动后大量二进制不兼容或连不上 Docker。痛点：不清楚该用 linux/amd64 还是 linux/arm64，Docker Desktop 套接字路径也常写错。使用方式：技能给出 --container-architecture linux/amd64，以及在 Mac 上使用 --container-daemon-socket unix:///Users/$USER/.docker/run/docker.sock 的思路。实际体验：这类问题一旦配对就基本不再复发，属于「配一次省很久」的收益；注意在 .actrc 里写死架构后，跨机器协作时需要说明差异。
场景四：团队规范化与资源清理
角色：技术负责人制定本地测试规范。痛点：每个人的本地环境各不相同，Docker 磁盘被旧镜像和容器占满。使用方式：技能输出的「最佳实践清单」——用 .actrc 统一配置、开发时用 --reuse、定期 docker system prune -a、生产工作流固定镜像版本、在 README 中记录镜像需求。实际体验：规范落地后新人上手时间缩短，磁盘告警减少；注意事项是「禁止特权模式、避免 :latest、日志中不暴露敏感数据」这几条纪律要写进团队文档才会真正生效。
该技能能为用户带来的价值
- 配置时间从「小时级」降到「分钟级」：镜像选型、
.actrc编写、容器参数组合这些原本需要反复查文档与试错的环节，被压缩成一次对话加一次落盘。 - 降低 act 的使用门槛：act 真正的难点是 Docker 侧的镜像体系、架构、权限、网络、资源与安全，本技能把这些隐式知识显性化，让不熟悉 Docker 内部机制的开发者也能配出可用环境。
- 减少无效资源消耗：通过微型/中型/大型镜像的分级选择，避免「简单工作流用超大镜像」的浪费；通过
--reuse与缓存管理，减少重复拉取与重复安装依赖。 - 提高本地测试与云端 CI 的一致性：用
.actrc把镜像映射固化下来，团队成员与本地/CI 环境的分歧变小，减少「本地过了线上挂」的沟通成本。 - 风险可控：技能明确给出安全边界建议（谨慎使用
--privileged、优先按需--container-cap-add、必要时--container-cap-drop ALL），把「为了跑通而放开全部权限」的坏习惯挡在前面。 - 长期价值：沉淀为仓库内的配置文件与团队文档后，这套知识不依赖任何个人记忆，可被持续复用和review。
常见问题 FAQ
Q1：怎么安装这个技能？安装后怎么确认生效？
在支持 AI 技能的客户端或技能市场中搜索技能名称「act-docker-setup」或技能 ID「13993」，找到条目后安装并授予所需工具权限。安装前提是本地有可用的 Docker 与 act 环境。验证方式：让技能检查项目中的工作流文件与 .actrc 现状，若能得到准确回答并可写入配置文件，说明生效。具体入口与命令以官方说明为准。
Q2：这个技能收费吗？
技能本身的价格、额度与计费方式由提供该技能的官方平台决定，本文不包含价格信息，请以官方说明为准。使用成本主要来自 AI 客户端的调用额度，以及本地 Docker 镜像的磁盘与带宽占用。
Q3：适合谁用？完全不懂 Docker 也能用吗？
最适合需要在本地复现 GitHub Actions 的开发者、维护多语言仓库的团队、使用 Apple Silicon 的 Mac 用户。完全不懂 Docker 也能获得可用的配置建议，但建议至少理解「镜像」「容器」「挂载」的基本概念，否则难以判断建议是否符合自己的场景。
Q4：技能元信息显示「用户可调用」为 false，是代表不能用吗？
「用户可调用：false」表示该技能在平台侧的调用方式受限，通常作为配套/辅助技能被使用，而不是由用户直接点名调用。这不影响你通过对话获得 act 与 Docker 的配置建议，但具体调用路径和可用范围以官方说明为准。
Q5：和直接用云端 GitHub Actions，或者自己手敲 act 命令相比，应该怎么选？
临时一次性验证、或需要最接近官方运行器环境时，云端 Actions 更合适；只跑简单工作流且熟悉参数时，手敲命令成本最低。当本地测试变成日常开发环节、需要多人协作与反复迭代时，用本技能把镜像映射、容器重用、资源限制固化成 .actrc 与团队规范，投入产出比最高。