在 Apple 硬件上跑一套和 GitHub Actions 语法兼容的 CI/CD听起来像绕远路其实很香。Gitea 本身就带 Actions不用额外装几十个组件而你手头那台 Mac mini、MacBook 甚至 Mac Studio完全可以当作自托管 Runner 用起来。尤其是 Apple Silicon 设备性能和功耗比都很合适适合做私有仓库的自动构建、iOS/macOS 编译、跨架构测试。这篇文章会从架构选型讲起带你把 Gitea 服务端和 act_runner 跑起来写一个真正能提交到仓库触发的 workflow再聊接口 API、并发批量任务、资源占用观察和常见踩坑点。所有命令都以当前稳定版本为准具体版本号请以你下载时的发布页为准。1. 核心能力速览能力项说明项目类型自托管 CI/CD 平台Gitea 内置 Actions 机制核心组件Gitea 服务端 act_runner 运行器工作流语法与 GitHub Actions 的 YAML 语法高度兼容硬件适配macOS Intel、Apple Silicon也可在 Linux 虚拟机中运行部署方式原生二进制、Docker、虚拟化三类路径Runner 类型Docker 执行器、Host 本地执行器接口能力Gitea REST APIRunner 通过 API 轮询任务批量任务支持多 Runner 注册、队列并发、矩阵策略典型用途iOS/macOS 构建、Xcode 编译、跨架构测试、私有仓库 CI上手难度中等需要理解 Actions 事件与 Runner 标签机制这个方案的优点很直接不依赖第三方 CI 平台代码和构建记录都留在自己的 Gitea 实例里Runner 跑在本地 Mac 上Apple 生态相关的编译任务可以原生执行不需要额外开远程 macOS 云主机。2. 适用场景与使用边界这套方案最合适的用户是已经有 Mac 设备、又不想把 CI 任务放到云上的开发者或小团队。比如个人开发者用一台 Mac mini 做自己开源项目的自动测试。团队内部用 Gitea 管理代码希望 push 之后自动跑测试、打镜像。做 iOS/macOS 应用开发需要一台真实 macOS 环境执行xcodebuild。需要同时在 x86_64 和 arm64 两套架构下验证兼容性。不太适合的场景也要说清楚。如果你需要几百个并发任务的超大规模 CIGitea Actions 的 Runner 调度能力不如专业 CI 平台如果完全没有 Mac 设备也不需要 Apple 生态构建那直接把 Gitea 和 Runner 部署在 Linux 服务器上会更省事。另外在 Apple 硬件上跑 Linux 容器时如果任务需要模拟 x86_64 架构性能和稳定性会打折扣这一点放到后面性能部分细说。使用边界方面重点提示三点仓库中的 Secrets、访问令牌、部署密钥不要明文写入 workflow 文件。如果仓库公开注意 workflow 中不要打印敏感环境变量。从第三方拉取 Actions 时先检查脚本内容避免执行不可信代码。3. 环境准备与前置条件开始之前先确认你手上的设备满足基本条件。3.1 操作系统与芯片macOS 版本建议 12 以上Apple Silicon 和 Intel 芯片都支持。如果要跑 Docker 执行器需要安装 Docker Desktop 或 OrbStack。如果要执行 iOS 工程编译需要安装 Xcode 和 Command Line Tools。不装 Docker 也可以act_runner 支持 Host 模式直接用 macOS 本机环境执行任务。3.2 需要准备的组件组件作用Gitea 服务端提供代码托管、Actions 任务调度、Web 管理界面act_runner从 Gitea 拉取任务并执行可注册多个实例GitmacOS 自带用于 clone 仓库和版本管理Docker可选Docker 执行器需要Host 模式不需要Xcode按需编译 macOS/iOS 工程时需要3.3 磁盘与目录规划建议把 Gitea 数据目录、Runner 工作目录、构建缓存分开方便后续清理和维护# 示例目录结构 ~/gitea/data # Gitea 仓库和数据库数据 ~/gitea/runner # act_runner 二进制和配置 ~/gitea/cache # 构建缓存4. 安装部署与启动方式Gitea Actions 的部署思路分两层先启动 Gitea 服务端再启动 act_runner。下面给出 Docker 和原生的两条路径。4.1 路径一Docker 部署 Gitea如果你习惯用 Docker这是最快的起步方式。在 Apple Silicon 上gitea/gitea默认拉取 arm64 镜像Intel Mac 会拉取 amd64 镜像。mkdir -p ~/gitea/data docker run -d --name gitea \ --restartunless-stopped \ -p 3000:3000 \ -p 2222:22 \ -v ~/gitea/data:/data \ gitea/gitea:latest说明3000是 Gitea Web 端口。2222是容器内 SSH 端口映射映射到宿主机 2222避免和 macOS 本机 22 端口冲突。数据全部放在~/gitea/data容器重建不影响数据。启动后浏览器访问http://127.0.0.1:3000按向导完成初始化。初始配置文件会写入~/gitea/data/gitea/conf/app.ini。4.2 路径二原生二进制部署 Gitea如果不想在 Mac 上常驻 Docker可以下载 Gitea 的 macOS 原生二进制。Gitea 官方发布页会提供darwin-amd64和darwin-arm64两种包按芯片选择。# 以 arm64 为例具体版本号以发布页为准 curl -L -o /usr/local/bin/gitea \ https://github.com/go-gitea/gitea/releases/latest/download/gitea-latest-darwin-arm64 chmod x /usr/local/bin/gitea mkdir -p ~/gitea/data cd ~/gitea gitea web --port 3000通过 Homebrew 也可以安装 Gitea命令是brew install gitea brew services start gitea但用 Homebrew 时要注意配置文件路径和默认数据目录与官方二进制的默认值可能不同建议安装后先查看brew info gitea的提示再决定是否调整。4.3 下载并注册 act_runneract_runner 是 Gitea 官方维护的 Runner 程序同样提供 macOS 二进制。下载后放到固定目录mkdir -p ~/gitea/runner cd ~/gitea/runner # 以 arm64 为例版本号以发布页为准 curl -L -o act_runner \ https://github.com/gitea/act_runner/releases/latest/download/act_runner-0.2.x-darwin-arm64 chmod x act_runner注册 Runner 之前需要先生成注册令牌。登录 Gitea 管理后台进入“站点管理 → 操作 → Runners”或者进入仓库的“Settings → Actions → Runners”创建一个新的注册令牌。拿到令牌后执行注册命令cd ~/gitea/runner ./act_runner register \ --instance http://127.0.0.1:3000 \ --token 你的注册令牌 \ --name mac-mini-m2 \ --labels macos-latest:host,self-hosted:host \ --no-interactive这里的关键是--labels。runs-on: macos-latest对应标签macos-latest:host表示使用 Host 执行器runs-on: self-hosted对应self-hosted:host。注册完成后当前目录会生成.runner文件里面记录了 Runner 的 ID、令牌和标签信息。如果不想用 Host 模式而是希望任务跑在 Docker 容器里可以把标签改成./act_runner register \ --instance http://127.0.0.1:3000 \ --token 你的注册令牌 \ --name mac-mini-m2-docker \ --labels ubuntu-latest:docker://node:20-bookworm \ --no-interactive需要说明的是不同版本的 act_runner 参数细节可能有差异执行./act_runner register --help查看当前版本的帮助信息最可靠。4.4 启动 act_runner注册完成后直接启动cd ~/gitea/runner ./act_runner daemon启动后可以看到日志输出正常情况下会打印与 Gitea 服务端的连接状态。回到 Gitea 管理后台的 Runner 页面如果 Runner 状态显示在线说明注册成功。如果希望 Mac 合盖或长时间不关机也能稳定运行可以用caffeinate防止系统睡眠caffeinate -s ./act_runner daemon更稳妥的做法是用 launchd 把 act_runner 注册为后台服务但这不是必须项先跑通流程更重要。5. 功能测试与效果验证Runner 在线后接下来验证整条 Actions 链路。我们创建一个测试仓库写入一个最简单的 workflow确认任务能被正确调度和执行。5.1 创建测试仓库和 workflow在 Gitea 中新建一个仓库比如ci-test然后在仓库根目录创建.gitea/workflows/ci.ymlname: mac-ci-demo on: push: branches: [ main ] pull_request: jobs: system-info: runs-on: macos-latest steps: - name: Show system info run: | uname -a sw_vers echo arch$(arch) sysctl -n machdep.cpu.brand_string把文件推送到仓库git add .gitea/workflows/ci.yml git commit -m test gitea actions git push origin main5.2 观察任务执行推送之后在 Gitea 仓库页面切到 “Actions” 标签可以看到一个新的任务排队。此时 act_runner 日志会显示任务被拉取和执行。点击任务可以看到每个步骤的输出uname -a输出 Darwin 内核信息。sw_vers显示 macOS 版本。arch在 Apple Silicon 上输出arm64在 Intel 上输出x86_64。sysctl显示 CPU 型号字符串。如果这一步能跑通说明 Gitea Actions 的调度链路完全正常。5.3 测试 Host 模式下的代码检出Host 执行器的工作目录里Gitea 通常会先把仓库代码准备好。你可以写一个步骤验证- name: Check files run: | pwd ls -la如果发现代码已经在目录里直接操作即可。如果需要把仓库代码重新拉取到指定目录可以在步骤里用git clonegit clone --depth 1 http://127.0.0.1:3000/you/ci-test.git /tmp/ci-test注意如果 Gitea 开启了私有仓库访问控制git clone时需要配置访问令牌或 SSH key。5.4 测试 Docker 执行器如果你的 Runner 注册时用了 Docker 标签可以写一个跑在 Linux 容器里的 workflowname: docker-ci-demo on: push: jobs: linux-build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Show container info run: | uname -a cat /etc/os-release - name: Run a command run: echo docker runner works这个任务会拉取对应标签的 Docker 镜像并在容器内执行。Apple Silicon 上默认拉取 arm64 架构的 Linux 镜像无模拟层时执行速度接近原生。5.5 测试最基本的构建任务既然跑在真实 Mac 上自然要验证编译能力。以一个最简单的 Swift 可执行文件为例name: swift-build-demo on: push: jobs: swift: runs-on: macos-latest steps: - name: Build swift file run: | mkdir -p build echo print(hello gitea actions) build/main.swift swiftc build/main.swift -o build/hello ./build/hello如果 Mac 上已经安装 Xcode Command Line Tools输出会显示hello gitea actions。5.6 判断成功的标准一个 workflow 跑通需要满足以下条件Gitea 的 Actions 页面显示任务状态为绿色成功。act_runner 日志无fetch task或execution报错。每个步骤的日志输出符合预期。如果使用 Docker 执行器对应镜像能正常拉取并创建容器。如果任务一直处于排队状态说明 Runner 标签和工作流的runs-on不匹配优先排查这个点。6. 接口 API 与批量任务Gitea Actions 本身依赖 Gitea 的 API 进行任务调度act_runner 会定期轮询任务。对使用方来说除了在 Web 页面观察还可以通过 Gitea REST API 做集成。6.1 用 API 查询任务状态Gitea 的 Swagger 接口文档一般在/api/swagger页面可以查看。一个常用需求是查询某个仓库的 Actions 任务列表请求路径通常是curl -s -H Authorization: token 你的访问令牌 \ http://127.0.0.1:3000/api/v1/repos/{owner}/{repo}/actions/tasks具体返回字段以你部署的 Gitea 版本为准。由于不同版本的 API 差异较大建议先打开 Swagger 页面确认路径再写集成代码。6.2 通过外部脚本触发任务Actions 任务的触发方式主要是 push、pull_request、tag 等 Git 事件。如果你希望外部流程触发 CI常见做法是提交一个空提交并推送git commit --allow-empty -m trigger ci git push origin main某些 Gitea 版本可能支持通过 API 直接下发工作流但这不是所有版本都具备的能力。稳妥的判断是先查当前 Gitea 版本的文档确认是否支持 workflow dispatch 接口再决定是否依赖它。6.3 并发与批量策略一个 act_runner 默认同一时间只执行一个任务配置文件的runner.capacity控制并发数。如果你有多台 Mac可以分别注册 RunnerGitea 会自动分配任务。批量场景可以这么设计一台 Mac mini 作为常用 Runner注册标签macos-latest:host。一台 Linux 服务器或 Mac 上的 Docker 执行器注册标签ubuntu-latest:docker://...。仓库里用矩阵策略同时跑多任务。矩阵示例name: matrix-demo on: push: jobs: test: runs-on: macos-latest strategy: matrix: version: [15, 16, 17] steps: - name: Print version run: echo testing version ${{ matrix.version }}这个任务会拆成三个并行任务Runner 会按顺序或并发执行取决于capacity设置。7. 资源占用与性能观察在 Apple 硬件上跑 CI资源占用是核心关注点。Gitea 服务端本身并不重真正影响性能的是 Runner 执行的任务类型和并发数。7.1 观察方法任务执行过程中可以通过几种方式观察资源占用# 查看本机整体负载 top -o cpu top -o mem # 查看 Docker 容器资源占用 docker stats在 workflow 里也可以直接输出系统信息sysctl hw.memsize sysctl -n hw.ncpu vm_stat如果有多个 Runner 并发执行建议用docker stats和top配合观察重点看内存占用和 CPU 调度是否失衡。7.2 CPU 推理与架构差异如果任务跑的是 Docker 容器Apple Silicon 上默认执行 arm64 容器性能接近原生。但如果 workflow 强制使用 amd64 镜像Docker 会通过模拟层运行性能和稳定性都会下降。尤其是编译大型项目时x86_64 模拟的耗时可能是 arm64 原生编译的数倍。避免模拟层影响的方法是优先使用arm64或linux/arm64镜像。在 workflow 中显式指定平台。如果必须跑 x86_64在 Docker Desktop 设置里开启 Rosetta 模拟选项但需自行验证兼容性。7.3 影响性能的主要因素因素影响并发任务数并发越高CPU 和内存压力越大Docker 镜像网络拉取首次拉取镜像耗时较长构建缓存缓存命中率高时任务耗时显著下降任务体积大仓库 clone 和依赖安装影响整体耗时Xcode 编译编译大工程时 CPU 和内存占用会明显上升7.4 降低资源占用的方法调低runner.capacity避免并发任务挤爆内存。关闭不必要的 Docker 容器清理无用镜像docker system prune使用 Host 执行器跑轻量任务省掉容器开销。为 Runner 配置独立的构建缓存目录避免缓存和仓库数据互相占磁盘。8. 常见问题与排查方法问题现象可能原因排查方式解决方案Runner 显示离线act_runner 未启动或连接失败查看 act_runner 日志启动或重启 act_runner任务一直排队标签不匹配检查 workflow 的runs-on与 Runner 标签修改 Runner 标签或 workflow 中的runs-onDocker 容器拉取失败镜像名错误或网络不通手动执行docker pull测试修正镜像名配置代理或更换镜像源Host 模式下代码不存在工作目录行为与预期不符打印pwd和ls -la使用git clone或actions/checkout显式拉取Gitea 无法访问端口被占用或服务未启动curl http://127.0.0.1:3000修改端口或重启服务Xcode 编译签名报错测试构建未关闭签名检查xcodebuild参数添加CODE_SIGNING_ALLOWEDNORunner 认证失败令牌失效或.runner文件损坏删除.runner重新注册重新生成令牌并注册任务执行中途卡住并发过高或资源不足查看任务日志和系统负载降低并发清理缓存9. 最佳实践与合规提醒9.1 工程化建议第一第一次跑任务时先用最少的步骤验证链路不要一上来就写几十步的 Complex workflow。确认 Runner 能拉取任务、执行命令、上报日志再逐步增加功能。第二保持一份最小可运行配置。.runner文件和config.yaml是 Runner 的核心身份丢失后任务会无法正确认领。备份时把这些文件一并备份。第三目录管理要清晰。Gitea 数据目录、Runner 工作目录、Docker 缓存目录分开方便清理和迁移。第四批量任务要记录日志。Runner 的日志默认会输出到标准输出建议重定向到文件./act_runner daemon ~/gitea/runner/runner.log 21第五接口服务要限制访问范围。Gitea 默认监听127.0.0.1如果开放到局域网务必设置好访问控制和 HTTPS。9.2 安全与合规提醒仓库中的 Secrets 不要在 workflow 中明文输出。从第三方仓库引入 Actions 时先审阅脚本内容。如果 Runner 用于公司项目确认代码和构建产物不涉及未授权分发。涉及 Apple 开发者证书、签名密钥的内容必须通过 Gitea 的 Secrets 或外部密钥管理服务注入不要写进源码。Public 仓库的 workflow 会被外部触发避免在公开仓库中暴露内部地址或敏感信息。10. 总结与下一步在 Apple 硬件上跑 Gitea Actions核心价值是把闲置的 Mac 变成私有 CI 节点而不需要依赖第三方 CI 平台。整个链路最值得验证的功能有三个Runner 是否能正常注册并在线、Host 和 Docker 两种执行模式是否都能跑通、以及任务日志是否能如实回传。最容易踩的坑也在前面说过了标签不匹配导致任务排队、Docker 镜像架构不对导致性能下降、Runner 令牌失效需要重新注册。这些问题都不难排查关键是先跑通最小链路再逐步增加复杂度。如果这一步已经跑通下一步可以试着把现有的 GitHub Actions workflow 迁移到 Gitea改一下.github/workflows路径为.gitea/workflows再逐个动作测试兼容性。也可以考虑把多台 Mac 注册成多个 Runner搭配矩阵策略做跨架构并行测试彻底把手头的 Apple 硬件利用率提上来。建议收藏备用尤其是想在 Mac mini 上搭一套私有 CI 的时候这份流程可以直接照着操作。