Gitea Actions服务容器无法启动问题求助

问题场景 #

在自托管Gitea（运行器与Gitea部署在同一台非容器化机器）中配置Actions服务容器时，遇到以下问题：

• 服务容器（mariadb）根本未启动
• 构建任务容器无法通过服务名（db）或localhost访问服务容器
• docker inspect显示服务容器与构建容器之间未配置网络链接

原测试配置 #

name: Build Project
on: [push]

jobs:
  TestWithDb:
    runs-on: ubuntu-latest
    services:
      db:
        image: mariadb:11.4.2-ubi9
        ports:
          - 3306:3306
        environment:
          MARIADB_DATABASE: "test"
          MARIADB_USER: "test"
          MARIADB_PASSWORD: "test"
          MARIADB_ROOT_PASSWORD: "test"
          MARIADB_MYSQL_LOCALHOST_GRANTS: "test"
            
    steps:
      - name: install netcat
        run: apt-get -y update ; apt -y install netcat-openbsd 
      - name: try to connect to db
        run: nc -w5 -z -v db 3306 || nc -w5 -z -v localhost 3306 || sleep 600

报错信息 #

nc: getaddrinfo for host "db" port 3306: Temporary failure in name resolution
nc: connect to localhost (127.0.0.1) port 3306 (tcp) failed: Connection refused
nc: connect to localhost (::1) port 3306 (tcp) failed: Cannot assign requested address

解决方案 #

1. 确保运行器用户拥有Docker权限 #

自托管运行器未在容器内运行时，需保证运行器进程所属用户具备Docker操作权限：

sudo usermod -aG docker $USER
# 重启运行器服务生效
sudo systemctl restart gitea-runner

2. 移除服务容器的宿主机端口映射 #

Gitea Actions的服务容器与构建容器默认处于同一内部网络，无需将端口映射到宿主机，多余的端口映射可能引发网络冲突。修改services配置，删除ports字段：

services:
  db:
    image: mariadb:11.4.2-ubi9
    environment:
      MARIADB_DATABASE: "test"
      MARIADB_USER: "test"
      MARIADB_PASSWORD: "test"
      MARIADB_ROOT_PASSWORD: "test"
      MARIADB_MYSQL_LOCALHOST_GRANTS: "test"

3. 添加服务容器健康检查 #

确保数据库容器完全启动并就绪后，再执行构建步骤。给服务容器添加健康检查配置，并在步骤中等待服务健康：

jobs:
  TestWithDb:
    runs-on: ubuntu-latest
    services:
      db:
        image: mariadb:11.4.2-ubi9
        environment:
          MARIADB_DATABASE: "test"
          MARIADB_USER: "test"
          MARIADB_PASSWORD: "test"
          MARIADB_ROOT_PASSWORD: "test"
          MARIADB_MYSQL_LOCALHOST_GRANTS: "test"
        healthcheck:
          test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-ptest"]
          interval: 10s
          timeout: 5s
          retries: 5
            
    steps:
      - name: install dependencies
        run: apt-get -y update ; apt -y install netcat-openbsd mysql-client
      - name: wait for database to be ready
        run: |
          until mysqladmin ping -h db -u root -ptest --silent; do
            echo "Waiting for database initialization..."
            sleep 5
          done
      - name: test db connection
        run: nc -w5 -z -v db 3306

4. 检查Gitea与运行器版本兼容性 #

部分旧版本Gitea或自托管运行器对服务容器的支持存在bug，建议将Gitea和运行器升级到最新稳定版，确保功能匹配。

5. 查看运行器日志排查启动失败原因 #

通过运行器日志获取服务容器未启动的具体错误信息，针对性解决：

# 若运行器使用systemd管理，执行以下命令查看实时日志
sudo journalctl -u gitea-runner -f

常见失败原因包括：镜像拉取失败、环境变量配置错误、容器资源不足、SELinux/AppArmor限制等。

内容的提问来源于stack exchange，提问作者mbelow