先把结论放在前面如果你手头有 Mac mini、MacBook 或者黑苹果主机想用它跑 Gitea Actions完全可行。而且相比租用云上的 macOS 构建机自建 Runner 更省钱、更可控尤其适合需要做 iOS 签名、多架构编译、本地联调的场景。这篇文章会从 Gitea Actions 的基本概念讲起带你完成 Runner 的安装、注册、配置再给一个能在 Apple 硬件上直接运行的 Workflow 示例。最后会整理常见报错和排查思路方便你照着配置、照着排错。文章内容适用于 Apple SiliconM 系列和 Intel 芯片的 Mac重点讲思路和步骤版本差异会在关键位置提醒你按实际环境调整。1. Gitea Actions 是什么为什么要在 Apple 硬件上跑1.1 Gitea 与 Gitea Actions 的关系Gitea 是一个轻量级的自托管 Git 服务可以用很低的内存跑起来适合个人、团队或企业内部使用。它提供仓库管理、Issue、Pull Request、Wiki 等常用功能界面和 GitHub 很像。Gitea Actions 是 Gitea 从 1.19 版本开始内置的 CI/CD 功能。它兼容 GitHub Actions 的工作流语法也就是说你可以在 Gitea 仓库里创建.gitea/workflows/*.yaml文件用类似 GitHub Actions 的写法定义自动化任务。一个 Gitea Actions 任务由两部分组成Gitea 服务端负责解析 Workflow、调度任务、记录日志。Runner真正执行任务的机器需要单独安装和注册。Runner 可以跑在 Linux、Windows、macOS 等系统上。官网和多数教程默认使用 Linux 服务器作为 Runner这很常见但如果你需要在 Apple 硬件上跑任务就要手动把 Runner 部署到 Mac 上。1.2 为什么需要 Apple 硬件上的 Runner最常见的需求是 iOS 或 macOS 应用的自动构建。Xcode 只能运行在 macOS 系统上如果你用 Gitea 管理代码又希望提交代码后自动触发xcodebuild、fastlane或pod install就必须有一个 macOS 环境的 Runner。即使你不做 iOS 开发也有其他场景值得在 Apple 硬件上跑 Runner场景原因iOS/macOS 应用编译依赖 Xcode、Command Line ToolsApple Silicon 专属构建某些依赖或二进制只提供 arm64 macOS 版本Unity 构建Unity 的 macOS 版本更适合在 Mac 上执行多架构验证同一份代码既要在 amd64 上跑也要在 arm64 上跑本地调试 CI 流程Runner 就在旁边出问题可以直接看进程和日志如果你用的是 GitHub官方虽然有 macOS Runner但排队时间长、费用也高。Gitea Actions 自建 Runner 可以让你用现有的 Mac mini 或 MacBook 作为任务执行机成本和自由度都更好。1.3 Gitea Actions 的执行流程先看整体流程开发者推送代码到 Gitea 仓库 ↓ Gitea 服务端检测到 .gitea/workflows/*.yaml 文件 ↓ Gitea 创建任务并发送给已注册的 Runner ↓ Runner 根据 Workflow 中的 jobs 步骤执行任务 ↓ 执行日志回传到 Gitea Web 界面这个流程里Runner 是关键角色。Runner 不一定需要和 Gitea 服务端在同一台机器你可以让 Gitea 跑在一台低配 Linux 服务器上然后让一台 Mac mini 作为 Runner 连接过去。2. 环境准备与前置条件2.1 本文使用的环境说明因为硬件和系统版本会影响具体命令这里先说明我假设的环境Apple 硬件Mac mini / MacBookApple Silicon 或 Intel 均可操作系统macOS建议较新的稳定版本Gitea较新的稳定版本至少为 1.19 或更高Runneract_runnerGitea 官方推荐的 Runner 实现依赖工具Git、Go可选用于源码编译版本需要根据你的项目实际情况调整。本文重点演示配置思路如果你的 Gitea 版本较老建议先升级到较新稳定版因为 Gitea Actions 的很多功能在旧版本上不可用。2.2 确认芯片架构Apple Silicon 和 Intel Mac 的架构不同下载 Runner 时要选择对应的版本。执行以下命令确认uname -m输出结果arm64Apple SiliconM1、M2、M3、M4 系列x86_64Intel Mac后续下载 Runner 时需要根据这个结果选择对应的二进制文件。2.3 检查必要工具在 Mac 终端里确认 Git 是否已安装git --version如果提示找不到命令可以先安装 Command Line Toolsxcode-select --install这个命令会弹出图形化安装窗口安装完成后 Git、make等常用命令基本就齐了。如果你准备从源码编译 act_runner还需要安装 Gogo version如果 Go 不存在可以使用 Homebrew 安装brew install go2.4 准备一台独立 Mac 作为 Runner安全提醒在开始之前有一个非常重要的安全提醒Gitea Actions 的工作流代码可能会被执行任意命令。如果 Runner 注册到公开仓库仓库的贡献者可以通过修改 Workflow 来执行命令。建议不要使用日常办公或存放敏感数据的 Mac 作为 Runner最好准备一台专用测试机或者至少使用独立的用户账号、独立的文件目录。后面在第 7 节还会展开说安全策略。3. 安装并注册 act_runner3.1 act_runner 是什么act_runner 是 Gitea 官方提供的 Runner 程序用于接收 Gitea 服务端下发的任务然后执行 Workflow 中定义的步骤。act_runner 有两种运行模式host模式直接在宿主机上执行命令适合需要 Xcode、系统签名等 macOS 原生能力的任务。docker模式通过 Docker 容器执行命令隔离性更好但 macOS 上使用 Docker 需要额外安装 Docker Desktop 或 colima且无法直接访问 Xcode。在 Apple 硬件上最常用的模式是host模式。这样 Workflow 里可以直接调用xcodebuild、fastlane等工具。3.2 下载 act_runneract_runner 可以从 Gitea 官方仓库的 Release 页面下载也可以在安装了 Go 的机器上编译。这里以二进制下载为例。打开终端创建一个用于存放 Runner 的目录sudo mkdir -p /opt/act_runner sudo chown $(whoami) /opt/act_runner cd /opt/act_runner然后根据你的芯片架构下载对应文件。以 Apple Silicon 为例大致命令如下注意版本号请以官方 Release 页面为准curl -L -o act_runner https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-darwin-arm64如果是 Intel Mac换成对应的darwin-amd64文件名即可。下载后赋予执行权限chmod x act_runner验证是否可运行./act_runner --version如果输出版本信息说明二进制正常。3.3 获取 Runner 注册令牌在 Gitea Web 界面中有两种方式可以创建 Runner Token站点管理员进入“站点管理”→“Runner”可以创建全局 Runner。仓库所有者进入仓库的“设置”→“Actions”可以创建当前仓库可用的 Runner。以仓库级别为例打开 Gitea 仓库页面。点击顶部“设置”。在左侧菜单中选择“Actions”。点击“创建新 Token”或类似按钮。复制生成的 Token。Token 是 Runner 连接 Gitea 的凭证请妥善保存不要提交到 Git 仓库。3.4 注册 Runner回到终端执行注册命令./act_runner register \ --instance http://127.0.0.1:3000 \ --token 你的Token \ --name mac-runner \ --labels macos-latest:host参数说明参数含义--instanceGitea 服务的地址如果 Gitea 在其他机器改成对应的 IP 或域名--token上一步复制的注册令牌--nameRunner 显示名称方便在管理界面识别--labelsRunner 可以执行的任务标签macos-latest:host表示使用宿主机模式执行注意macos-latest:host的格式冒号前面是标签名冒号后面是执行器类型。host表示直接在宿主机上执行不是启动容器。注册成功后目录下会生成一个.runner文件。这个文件包含 Runner 的 ID、密钥等信息不要删除也不要提交到仓库。3.5 启动 Runner注册完成后启动 Runner./act_runner daemon看到类似下面的日志说明 Runner 已成功连接 GiteaINFO[0000] Starting runner daemon INFO[0000] Successfully connected to Gitea此时回到 Gitea 管理界面可以看到名为mac-runner的 Runner 显示为在线状态。daemon命令会占据当前终端你可以保持终端打开或者使用nohup放到后台nohup ./act_runner daemon act_runner.log 21 如果需要开机自启可以配置 macOS 的 launchd后面第 7 节会说到。4. 编写 Workflow 在 Apple 硬件上执行任务4.1 创建 Workflow 文件在 Gitea 仓库中创建一个目录.gitea/workflows/然后新建一个 YAML 文件例如build.yml。下面是一个最简单的 Workflow用于验证 Runner 是否正常工作name: Test on macOS on: push: workflow_dispatch: jobs: test-macos: runs-on: macos-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Show system info run: | uname -a uname -m sw_vers说明on.push代码推送到仓库时触发。workflow_dispatch允许在 Gitea 页面手动触发任务。runs-on: macos-latest对应注册 Runner 时的标签macos-latest:host。actions/checkoutv4从 Gitea 拉取当前仓库代码。Gitea Actions 兼容这个 Action。保存并推送代码后在 Gitea 仓库的“Actions”页面可以看到任务开始执行。点击任务可以查看实时日志。预期日志会输出类似Darwin mac-mini.local 23.4.0 Darwin Kernel Version 23.4.0: arm64 arm64 ProductName: macOS ProductVersion: 14.5这就说明 Runner 已经在 Apple 硬件上成功执行了 Gitea Actions 任务。4.2 在 Workflow 中使用 Xcode 构建接下来看一个更贴近实际需求的例子在 Apple 硬件上执行 Xcode 构建。name: iOS Build on: push: tags: - v* jobs: build: runs-on: macos-latest steps: - name: Checkout uses: actions/checkoutv4 - name: List available SDKs run: xcodebuild -showsdks - name: Show Xcode version run: xcodebuild -version - name: Build project run: | xcodebuild \ -project YourProject.xcodeproj \ -scheme YourScheme \ -configuration Release \ -sdk iphoneos \ -derivedDataPath build \ CODE_SIGNING_ALLOWEDNO \ build这个示例有两个关键点-derivedDataPath build把构建产物输出到当前目录下的build文件夹方便后续上传或查看。CODE_SIGNING_ALLOWEDNO在没有配置签名证书的环境下先关闭代码签名只验证编译是否通过。如果你需要完整签名和导出 IPA可以在 Runner 上安装好证书和描述文件然后在 Workflow 中使用环境变量或密钥传入签名信息这里不再展开但一定要避免把签名文件直接提交到仓库。4.3 使用仓库 Secrets 传入敏感信息如果你的构建脚本需要 API Key、证书密码等敏感信息不要写在 YAML 文件里。建议在 Gitea 仓库的“设置”→“Actions”→“Secrets”中添加密钥。然后在 Workflow 中通过环境变量引用- name: Build with secret run: | echo $MY_SECRET secret.txt # 这里继续执行构建命令 env: MY_SECRET: ${{ secrets.MY_SECRET }}这样的好处是敏感信息不会出现在 Git 历史中。不同仓库可以使用不同的密钥。可以在不修改 Workflow 的情况下轮换密钥。4.4 在 Workflow 中选择 amd64 或 arm64如果你有多台 Runner或者希望同一台 Mac 上区分架构可以注册多个标签。例如在注册时使用./act_runner register \ --instance http://127.0.0.1:3000 \ --token 你的Token \ --name mac-arm64-runner \ --labels macos-arm64:host,macos-latest:host这样 Workflow 可以这样写jobs: test-arm64: runs-on: macos-arm64 steps: - name: Show arch run: uname -m注意--labels多个标签之间用逗号分隔标签名不能重复否则会造成 Runner 匹配混乱。5. 进阶常见构建场景与 Runner 维护5.1 场景一macOS 应用编译macOS 应用和 iOS 应用类似都需要 Xcode 工具链。在 Workflow 中可以直接执行xcodebuild不过要注意需要提前打开一次 Xcode或者在终端执行sudo xcodebuild -license accept接受许可协议。如果使用 Command Line Tools部分 GUI 功能可能缺失建议安装完整 Xcode。5.2 场景二多架构验证很多跨平台项目需要同时产出 amd64 和 arm64 的构建产物。在 Apple Silicon 上macOS 的 CGO 编译可能涉及架构问题。例如 Go 项目- name: Build amd64 run: | GOOSdarwin GOARCHamd64 go build -o bin/app-amd64 . - name: Build arm64 run: | GOOSdarwin GOARCHarm64 go build -o bin/app-arm64 .如果还要交叉编译 Linux 版本要注意 CGO 依赖可能导致失败需要关闭 CGO 或使用对应的交叉编译工具链。5.3 场景三Runner 更新act_runner 更新比较频繁。建议定期关注官方 Release更新时先停止旧 Runner替换二进制文件再启动新 Runner。更新步骤cd /opt/act_runner # 停止当前 Runner 进程 kill $(pgrep act_runner) # 备份旧配置 cp .runner .runner.bak # 下载新版本二进制 curl -L -o act_runner 新的下载地址 chmod x act_runner # 启动新版本 nohup ./act_runner daemon act_runner.log 21 .runner.bak在确认新版本运行正常后可以删除。5.4 使用 launchd 开机自启如果你希望 Mac 重启后 Runner 自动运行可以配置 launchd。创建 plist 文件?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.example.actrunner/string keyProgramArguments/key array string/opt/act_runner/act_runner/string stringdaemon/string /array keyWorkingDirectory/key string/opt/act_runner/string keyRunAtLoad/key true/ keyKeepAlive/key true/ keyStandardOutPath/key string/opt/act_runner/act_runner.log/string keyStandardErrorPath/key string/opt/act_runner/act_runner.err.log/string /dict /plist保存到/Library/LaunchDaemons/com.example.actrunner.plist然后加载sudo chown root:wheel /Library/LaunchDaemons/com.example.actrunner.plist sudo launchctl load /Library/LaunchDaemons/com.example.actrunner.plist这里用/Library/LaunchDaemons而不是~/Library/LaunchAgents是因为 Runner 通常需要以系统级服务运行不受用户登录状态影响。注意如果 Runner 需要访问钥匙串中的证书建议单独配置登录钥匙串避免权限问题。6. 常见问题与排查思路在 Apple 硬件上跑 Gitea Actions最容易踩到的是下面几个坑。问题现象常见原因解决思路Runner 显示离线Runner 未启动、网络不通、Token 失效查看 Runner 日志确认 Gitea 地址可达重新注册任务一直卡在 queued标签不匹配、Runner 正忙检查runs-on标签确认 Runner 在线且空闲执行命令提示无法找到PATH 环境不一致在 Workflow 中使用绝对路径或先执行which排查xcodebuild无法使用未安装 Xcode 或未接受许可执行xcode-select --installsudo xcodebuild -license acceptdocker相关步骤失败macOS 上没有 Docker改用host模式或安装 Docker Desktop / colima签名失败证书未导入、钥匙串权限不足将证书导入 Runner 的钥匙串并设置访问权限网络下载慢国内网络到 GitHub 资源受限使用代理或镜像站但要注意合规性6.1 Runner 显示离线首先确认进程是否还在ps aux | grep act_runner如果进程存在再查看日志tail -f /opt/act_runner/act_runner.log常见错误是 Gitea 地址被写成了localhost但 Runner 在远端机器上。此时要把--instance改成 Gitea 所在机器的局域网 IP 或域名。6.2 任务一直处于 queued 状态打开 Gitea 仓库的 Actions 页面查看任务详情。如果显示waiting for a runner说明没有找到匹配的 Runner。检查点注册 Runner 时的--labels是否包含 Workflow 中使用的标签。该 Runner 是否已经离线。Gitea 版本是否支持该标签格式。6.3 macOS 安全策略阻止执行如果是下载的二进制macOS 可能提示“无法打开因为无法验证开发者”。这时需要手动允许打开“系统设置”→“隐私与安全性”。在“安全性”部分找到被阻止的 App。点击“仍要打开”。这个操作只在图形界面下可用如果通过 SSH 远程管理 Mac可以先在本地设置一次之后就不会再拦截。6.4 Actions 日志看不到输出如果任务显示成功但日志没有内容可能是 Runner 使用了host模式且输出缓冲问题。可以尝试在 Workflow 中加timeout-minutes或者在命令后加; echo step done验证步骤是否真正执行。7. 最佳实践与工程建议7.1 Runner 安全边界Gitea Actions 可以执行仓库内定义的任意命令因此它的风险等价于“让仓库维护者在你的 Mac 上执行代码”。一定要明确一件事如果 Runner 注册到了不受信任的仓库等于给了对方代码执行权。建议从以下几个方面控制风险只把 Runner 注册给私人仓库或可信团队仓库。使用独立 macOS 用户账号运行 Runner不要用管理员账号日常登录。尽量在虚拟机或者单独的 Mac 上运行 Runner不要使用主开发机。对 Runner 能访问的网络、文件系统做最小授权。多仓库共用 Runner 时考虑容器隔离但在 macOS 上容器隔离会牺牲 Xcode 访问能力。7.2 签名与密钥管理iOS/macOS 构建最常见的敏感信息是证书和描述文件。不要把.p12、.mobileprovision提交到仓库。推荐做法将证书和描述文件保存到 Runner 本机路径固定例如~/signing/。在 Gitea Secrets 中保存证书密码Workflow 运行时动态读取。使用 fastlane 的match或自定义脚本来管理描述文件。定期轮换证书并注意 Apple Developer 后台的吊销规则。7.3 标签命名规范Runner 的标签决定了 Workflow 如何选择执行机器。建议用清晰的命名标签示例含义macos-latest通用 macOS 任务macos-arm64Apple Silicon 专用任务macos-amd64Intel Mac 专用任务macos-iosiOS 构建专用任务如果标签设置得太粗糙会出现“任务被分到不支持的机器上”的问题如果太细又会导致 Runner 匹配效率低。按项目规模控制在 2 到 4 个标签比较合适。7.4 日志与监控Runner 本机的日志默认输出到终端或指定文件。建议为act_runner配置独立的日志文件并设置日志轮转。定期检查 Gitea 管理后台的 Runner 在线状态。如果 Runner 长时间无任务可以考虑增加一个定时健康检查任务每隔一段时间向它的管理接口请求一次。7.5 性能与温度控制Mac mini 长期跑 CI 构建任务散热和性能会是一个实际问题。建议在 Workflow 中设置合理的timeout-minutes避免异常任务一直占用资源。高负载任务尽量错开执行。如果使用 MacBook 作为 Runner屏幕可以关闭但要注意电源设置避免合盖后进入休眠。8. 总结与下一步学习方向这篇文章从概念到实践带你完成了一条完整的链路理解了 Gitea Actions 的组成架构和 Runner 在其中的作用。在 Apple 硬件上安装并注册了 act_runner。编写并运行了第一个 macOS Workflow。了解了签名、密钥、多架构等进阶使用方式。整理了常见问题排查思路和安全注意事项。如果你只是想在个人 Mac 上跑通 CI按照第 3 步和第 4 步操作即可。如果你要用于生产环境我建议先从小项目验证 Runner 稳定性再逐步接入正式仓库不要第一天就把所有项目都挂到同一个 Runner 上。接下来你可以继续研究这几个方向Gitea Actions 的actions/checkout和actions/cache在 macOS 上的行为差异。fastlane 在 Gitea Actions 中的完整 iOS 发布流程。如何在同一台 Mac 上用多个用户配多套 Runner实现任务隔离。如何使用 colima 或 Docker 实现 macOS 下的容器化 Runner。如果这篇文章对你有帮助可以收藏备用。等你在自己的 Apple 硬件上跑通第一个 Gitea Actions 任务后再回来对照排查清单做一次体检后续踩坑会少很多。