@@ -0,0 +1,183 @@
# act_runner 配置参考
工作流 `runs-on: ubuntu-latest` ； `docker` job 额外使用 `catthehacker/ubuntu:act-22.04` 容器（含 Docker CLI）。
## 构建镜像必须：挂载 Docker Socket
`docker` job 需要访问宿主机 Docker 引擎。在 **runner 所在机器 ** 的 `config.yaml` 中配置：
``` yaml
container :
options : -v /var/run/docker.sock:/var/run/docker.sock
valid_volumes :
- /var/run/docker.sock
```
推荐 job 镜像（含 Node + Docker CLI）：
``` yaml
runner :
labels :
- "ubuntu-latest:docker://catthehacker/ubuntu:act-22.04"
- "ubuntu-22.04:docker://catthehacker/ubuntu:act-22.04"
```
修改后 **重启 runner ** （例如 `docker restart <runner容器>` 或重启 Gitea Runner 服务）。
## 1Panel 宿主机：配置 Docker 镜像加速（推荐）
Runner 通过 `docker.sock` 使用宿主机 Docker。在 **1Panel ** 中配置加速器后，普通 `docker pull` 会走加速；**buildx 多架构构建**仍建议配合 workflow 内的 `IMAGE_PREFIX` （默认 `docker.1panel.live` ）。
1. 登录 1Panel → **容器 ** → **配置 **
2. **镜像加速地址 ** 填入：
```text
https://docker.1panel.live
` ``
3. 保存并 **重启 Docker**
验证（在 runner 宿主机）：
` ``bash
docker info | grep -A5 'Registry Mirrors'
docker pull alpine:3.20
` ``
等价 ` daemon.json`：
` ``json
{
"registry-mirrors": ["https://docker.1panel.live"]
}
` ``
CI 工作流默认 ` IMAGE_PREFIX=docker.1panel.live/library/`（ DOCKER_IMAGE_PREFIX=daocloud` 或 ` hub`。
参考：[1Panel 容器配置文档](https://1panel.cn/docs/user_manual/containers/setting)
## 验证
在 runner 宿主机执行：
` ``bash
docker info
ls -l /var/run/docker.sock
` ``
## 从零部署 runner（可选）
` ``bash
cd .gitea/act-runner
cp .env.example .env # 填入 Registration Token
docker compose up -d
` ``
## GitHub Actions 镜像（替代 ghfast）
日志里出现 ` git clone 'https://ghfast.top/https://github.com/actions/checkout'` 说明 **runner 宿主机** 的 ` config.yaml` 配置了 ` github_mirror`，与仓库 workflow 无关。
在 runner 的 ` config.yaml` 中修改（修改后重启 runner）：
` ``yaml
runner:
github_mirror: 'https://gitea.com' # 推荐
` ``
常用替代方案：
| ` github_mirror` 值 | 说明 |
|------------------|------|
| ` ''`（留空） | 直连 ` github.com`，网络可达时最简单 |
| ` https://gitea.com` | Gitea 官方 actions 镜像，国内较稳 |
| ` https://gitclone.com/github.com` | 第三方 GitHub 克隆镜像 |
| ` https://ghfast.top/https://github.com` | 部分环境需代理认证，易报 ` Proxy Authentication Required` |
前提：Gitea ` app.ini` 中 ` [actions] DEFAULT_ACTIONS_URL = github`（默认）。
**推荐写法**（与 Prism 等仓库一致，由 runner ` github_mirror` 拉取 Action）：
` ``yaml
uses: actions/checkout@v4
` ``
也可写 Gitea 镜像绝对 URL（不依赖 runner 配置）：
` ``yaml
uses: https://gitea.com/actions/checkout@v4
` ``
勿写 ` https://github.com/actions/checkout@v4 `：会绕过 ` github_mirror` 直连 GitHub，内网 runner 易报 ` unexpected EOF`。
修改 ` github_mirror` 后建议清理 runner 缓存目录（如 ` /root/.cache/act`），否则旧缓存可能仍指向 ghfast。
## 常见错误
| 报错 | 原因 | 处理 |
|------|------|------|
| ` registry-1.docker.io` i/o timeout | Docker Hub 不可达 | 1Panel 配 ` docker.1panel.live`； DOCKER_IMAGE_PREFIX=1panel` |
| ` ghfast.top` Proxy Authentication Required | runner ` github_mirror` 指向 ghfast 且需代理认证 | 改 ` github_mirror` 或删掉；见上文「GitHub Actions 镜像」 |
| ` docker: command not found` | job 容器无 Docker CLI | 工作流已指定 act 镜像；或 runner 改用 catthehacker/ubuntu |
| ` Cannot connect to Docker daemon` | 未挂载 docker.sock | 按上文修改 config.yaml 并重启 runner |
| ` node not in PATH` | job 镜像无 Node | 标签映射改用 catthehacker/ubuntu:act-22.04 |
| ` http: server gave HTTP response to HTTPS client` 且 token 指向 ` 127.0.0.1` | **Gitea Registry 配置/反代错误** | 见下文「Registry 登录失败」 |
## Registry 登录失败（127.0.0.1 / HTTP vs HTTPS）
若 ` docker login git.rc707blog.top` 报错类似：
` ``text
Get "https://127.0.0.1:xxxxx/v2/token?...": http: server gave HTTP response to HTTPS client
` ``
说明 Gitea 把 **Docker 认证 token 地址** 配成了本机内网地址，CI runner 访问不到。需在 **Gitea 服务器** 修复，而非改 workflow。
### 1. 检查 ` app.ini`
` ``ini
[server]
ROOT_URL = https://git.example.com/
LOCAL_ROOT_URL = http://127.0.0.1:3000/
; 内网穿透 / 错误 Host 时（Gitea 1.26+）：
; PUBLIC_URL_DETECTION = never
[packages]
ENABLED = true
` ``
` ROOT_URL` 必须与浏览器访问 Gitea 的 **HTTPS 外网地址** 完全一致（含末尾 ` /`）。
### 2. 反向代理必须转发 ` /v2` 并带上头
Container Registry 固定使用根路径 ` /v2`。Nginx 示例：
` ``nginx
location / {
client_max_body_size 0;
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
` ``
关键：` X-Forwarded-Proto: https` 和正确的 ` Host`（与 Gitea ` ROOT_URL` 域名一致）。
### 3. 在 runner 宿主机验证（修复后）
` ``bash
GITEA_HOST=git.example.com # 改成你的 Gitea 域名
curl -s -D - "https://${GITEA_HOST}/v2/" -o /dev/null | grep -i www-authenticate
echo "$REGISTRY_TOKEN" | docker login "${GITEA_HOST}" -u 你的用户名 --password-stdin
` ``
应返回 ` 401 Unauthorized`（正常，表示 registry 可达）且 ` docker login` 显示 **Login Succeeded**。
参考：[Gitea 反向代理文档](https://docs.gitea.com/administration/reverse-proxies)
## Gitea Runner v0.6.x（个人 runner）
1. 找到 runner 的配置文件或环境（安装目录 / docker compose）
2. 确保 runner 进程能访问宿主机 ` /var/run/docker.sock`
3. Runners 页标签含 ` ubuntu-latest` 且状态 **空闲/在线**
若使用 Gitea 网页注册的个人 runner（ config.yaml` 里加入 socket 挂载，具体路径取决于你的安装方式。
renjue