Luminary/.gitea/act-runner/README.md

act_runner 配置参考

工作流 runs-on: ubuntu-latest；docker job 额外使用 catthehacker/ubuntu:act-22.04 容器（含 Docker CLI）。

构建镜像必须：挂载 Docker Socket

docker job 需要访问宿主机 Docker 引擎。在 runner 所在机器 的 config.yaml 中配置：

container:
  options: -v /var/run/docker.sock:/var/run/docker.sock
  valid_volumes:
    - /var/run/docker.sock

推荐 job 镜像（含 Node + Docker CLI）：

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. 镜像加速地址 填入：

   https://docker.1panel.live
   

3. 保存并 重启 Docker

验证（在 runner 宿主机）：

docker info | grep -A5 'Registry Mirrors'
docker pull alpine:3.20

等价 daemon.json：

{
  "registry-mirrors": ["https://docker.1panel.live"]
}

CI 工作流默认 IMAGE_PREFIX=docker.1panel.live/library/（buildkit 拉基础镜像）。若 1Panel 加速不可用，可在仓库 Variables 设 DOCKER_IMAGE_PREFIX=daocloud 或 hub。

参考：1Panel 容器配置文档

验证

在 runner 宿主机执行：

docker info
ls -l /var/run/docker.sock

从零部署 runner（可选）

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）：

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（默认）。

不依赖 runner 镜像 的写法（workflow 内写绝对 URL，仅改写 github.com 的请求）：

uses: https://gitea.com/actions/checkout@v4

本模板 ci.yml 已采用此写法。若其他 workflow 仍写 uses: actions/checkout@v4，仍需配置 github_mirror 或改为绝对 URL。

修改 github_mirror 后建议清理 runner 缓存目录（如 /root/.cache/act），否则旧缓存可能仍指向 ghfast。

常见错误

报错	原因	处理
registry-1.docker.io i/o timeout	Docker Hub 不可达	1Panel 配 docker.1panel.live；Variable 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 报错类似：

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

[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 示例：

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 宿主机验证（修复后）

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 反向代理文档

Gitea Runner v0.6.x（个人 runner）

1. 找到 runner 的配置文件或环境（安装目录 / docker compose）
2. 确保 runner 进程能访问宿主机 /var/run/docker.sock
3. Runners 页标签含 ubuntu-latest 且状态 空闲/在线

若使用 Gitea 网页注册的个人 runner（docker 模式），通常需在 runner 启动参数或 config.yaml 里加入 socket 挂载，具体路径取决于你的安装方式。