新用户教程 04

算力接入：把构建任务交给外部 Runner

夜猫子主机主要负责保存仓库、数据库和软件包。需要编译固件、运行测试或打包项目时，可以把任务交给性能更强的 Runner 节点。

1. Runner 是什么

Runner 是外部构建设备。它从 Gitea 接收 Actions 任务，在自己的 CPU、内存和磁盘上执行编译或测试，再把日志和构建产物回传到平台。

主机保存数据，Runner 负责计算。
可以准备多台 Runner，按项目或标签分配。
用户自己的设备也可以作为 Runner，但需要管理员审核。

2. 工作流文件放在哪里

Actions 工作流文件放在仓库的 `.gitea/workflows/` 目录。文件提交后，平台会根据触发条件创建构建任务。

仓库根目录
└── .gitea
    └── workflows
        └── build-firmware.yml

3. 一个固件构建示例

下面是一个简化示例。实际项目需要根据编译工具链、芯片平台和输出文件名调整。

name: build-firmware
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: ./scripts/build.sh

4. 使用规则

Runner 有算力和安全边界。新用户提交构建任务前，应先确认项目负责人允许使用哪个节点，以及构建产物应该上传到哪里。

不要在工作流中写明文密码或私钥。
大文件产物优先上传到 Release 或 Packages。
构建失败时先看日志，再联系项目负责人或管理员。

后续如果增加多台 Runner，可以按 `firmware`、`docker`、`test` 等标签区分，让不同项目选择合适的算力节点。