refactor: Apply cache fixes directly to existing runner configs

- Update all runner configuration files with cache networking fixes:
  - config_docker.yaml
  - config_heavy.yaml
  - config_light.yaml
  - config_security.yaml
- Remove separate config_cache_fixed.yaml file
- Update troubleshooting scripts to use updated configs
- Update documentation to reference existing config files

All runner configs now have:
- Fixed cache host: host.docker.internal
- Fixed cache port: 44029
- Host networking for better container connectivity

This provides a cleaner approach by updating existing configs
instead of maintaining a separate fixed configuration file.

.gitea/workflows/api-docs.yml

@@ -43,6 +43,7 @@ jobs:
           ${{ runner.os }}-node-${{ matrix.node-version }}-
           ${{ runner.os }}-node-
           ${{ runner.os }}-
+        fail-on-cache-miss: false
       id: npm-cache
       
     - name: Cache status
@@ -136,6 +137,7 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-node-18-
           ${{ runner.os }}-node-
+        fail-on-cache-miss: false
         
     - name: Install dependencies
       run: |

.gitea/workflows/api-gateway.yml

@@ -50,6 +50,7 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-m2-${{ matrix.java-version }}-
           ${{ runner.os }}-m2-
+        fail-on-cache-miss: false
         
     - name: Validate POM
       run: ./mvnw validate
@@ -114,6 +115,7 @@ jobs:
         path: ~/.m2
         key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
         restore-keys: ${{ runner.os }}-m2
+        fail-on-cache-miss: false
         
     - name: Build application
       run: ./mvnw clean package -DskipTests

.gitea/workflows/ci.yml

@@ -34,6 +34,7 @@ jobs:
         path: ~/.m2
         key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
         restore-keys: ${{ runner.os }}-m2
+        fail-on-cache-miss: false
         
     - name: Run tests
       run: mvn test
@@ -69,6 +70,7 @@ jobs:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
         restore-keys: ${{ runner.os }}-pip
+        fail-on-cache-miss: false
         
     - name: Install dependencies
       run: |
@@ -121,6 +123,7 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-node-18-
           ${{ runner.os }}-node-
+        fail-on-cache-miss: false
         
     - name: Install dependencies
       run: |
@@ -166,6 +169,7 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-node-18-
           ${{ runner.os }}-node-
+        fail-on-cache-miss: false
         
     - name: Install dependencies
       run: |

.gitea/workflows/frontend.yml

@@ -43,6 +43,7 @@ jobs:
           ${{ runner.os }}-node-${{ matrix.node-version }}-
           ${{ runner.os }}-node-
           ${{ runner.os }}-
+        fail-on-cache-miss: false
         
     - name: Install dependencies
       run: |

.gitea/workflows/service-adapters.yml

@@ -43,6 +43,7 @@ jobs:
           ${{ runner.os }}-pip-${{ matrix.python-version }}-
           ${{ runner.os }}-pip-
           ${{ runner.os }}-
+        fail-on-cache-miss: false
       id: pip-cache
       
     - name: Cache status

docs/CACHE_TROUBLESHOOTING.md

@@ -0,0 +1,152 @@
+# Cache Troubleshooting Guide
+
+## Problem Description
+
+The LabFusion CI/CD pipelines were experiencing cache timeout errors:
+```
+::warning::Failed to restore: getCacheEntry failed: connect ETIMEDOUT 172.31.0.3:44029
+```
+
+This error occurs when the cache service is not accessible from the job containers due to Docker networking issues.
+
+## Root Cause
+
+The issue is caused by:
+1. **Docker Networking**: Containers can't reach the cache server on the host
+2. **Random Port Assignment**: Using port 0 causes unpredictable port assignments
+3. **Cache Service Location**: The cache service binds to an IP that containers can't access
+
+## Solutions Implemented
+
+### 1. Workflow-Level Fixes
+
+Added `fail-on-cache-miss: false` to all cache actions in:
+- `.gitea/workflows/api-gateway.yml`
+- `.gitea/workflows/frontend.yml`
+- `.gitea/workflows/service-adapters.yml`
+- `.gitea/workflows/api-docs.yml`
+- `.gitea/workflows/ci.yml`
+
+This ensures that cache failures don't cause the entire pipeline to fail.
+
+### 2. Runner Configuration Fixes
+
+Updated all existing runner configuration files with:
+- **Fixed Host**: `host.docker.internal` (allows containers to access host)
+- **Fixed Port**: `44029` (instead of random port 0)
+- **Host Network**: Uses host networking for better connectivity
+
+Updated files:
+- `runners/config_docker.yaml`
+- `runners/config_heavy.yaml`
+- `runners/config_light.yaml`
+- `runners/config_security.yaml`
+
+### 3. Troubleshooting Tools
+
+Created diagnostic scripts:
+- `runners/fix-cache-issues.sh` (Linux/macOS)
+- `runners/fix-cache-issues.ps1` (Windows)
+
+These scripts help diagnose and fix cache issues.
+
+## How to Apply the Fixes
+
+### Option 1: Use the Updated Configuration
+
+1. Stop your current runner:
+   ```bash
+   pkill -f act_runner
+   ```
+
+2. Start with an updated configuration:
+   ```bash
+   ./act_runner daemon --config config_docker.yaml
+   # or
+   ./act_runner daemon --config config_heavy.yaml
+   # or
+   ./act_runner daemon --config config_light.yaml
+   # or
+   ./act_runner daemon --config config_security.yaml
+   ```
+
+### Option 2: Run the Troubleshooting Script
+
+**Linux/macOS:**
+```bash
+cd runners
+./fix-cache-issues.sh
+```
+
+**Windows:**
+```powershell
+cd runners
+.\fix-cache-issues.ps1
+```
+
+### Option 3: Manual Configuration
+
+Update your runner configuration with these key changes:
+
+```yaml
+cache:
+  enabled: true
+  host: "host.docker.internal"  # Fixed host
+  port: 44029                   # Fixed port
+
+container:
+  network: "host"               # Use host networking
+```
+
+## Verification
+
+After applying the fixes:
+
+1. **Check Runner Logs**: Look for cache service startup messages
+2. **Test a Workflow**: Run a simple workflow to verify cache works
+3. **Monitor Cache Hits**: Check if dependencies are being cached properly
+
+## Expected Results
+
+- ✅ No more `ETIMEDOUT` errors
+- ✅ Cache hits show "✅ Cache hit!" messages
+- ✅ Faster build times due to dependency caching
+- ✅ Workflows continue even if cache fails
+
+## Troubleshooting
+
+If issues persist:
+
+1. **Check Docker Networking**:
+   ```bash
+   docker network ls
+   docker network inspect bridge
+   ```
+
+2. **Verify Cache Service**:
+   ```bash
+   netstat -tlnp | grep 44029
+   ```
+
+3. **Test Connectivity**:
+   ```bash
+   curl http://host.docker.internal:44029/
+   ```
+
+4. **Check Runner Logs**:
+   ```bash
+   tail -f runner.log
+   ```
+
+## Additional Resources
+
+- [Gitea Act Runner Documentation](https://gitea.com/gitea/act_runner/src/branch/main/docs/configuration.md)
+- [GitHub Actions Cache Documentation](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
+- [Docker Networking Documentation](https://docs.docker.com/network/)
+
+## Support
+
+If you continue to experience cache issues after applying these fixes, please:
+1. Run the troubleshooting script and share the output
+2. Check the runner logs for any error messages
+3. Verify your Docker and network configuration

runners/config_docker.yaml

@@ -54,22 +54,20 @@ cache:
   # If it's empty, the cache data will be stored in $HOME/.cache/actcache.
   dir: ""
   # The host of the cache server.
-  # It's not for the address to listen, but the address to connect from job containers.
-  # So 0.0.0.0 is a bad choice, leave it empty to detect automatically.
-  host: ""
-  # The port of the cache server.
-  # 0 means to use a random available port.
-  port: 0
+  # Use host.docker.internal to allow containers to access the host
+  # This fixes the common networking issue where containers can't reach the cache server
+  host: "host.docker.internal"
+  # Use a fixed port instead of random to avoid connection issues
+  port: 44029
   # The external cache server URL. Valid only when enable is true.
   # If it's specified, act_runner will use this URL as the ACTIONS_CACHE_URL rather than start a server by itself.
   # The URL should generally end with "/".
   external_server: ""
 
 container:
-  # Specifies the network to which the container will connect.
-  # Could be host, bridge or the name of a custom network.
-  # If it's empty, act_runner will create a network automatically.
-  network: ""
+  # Use host network to avoid Docker networking issues with cache
+  # This ensures containers can access the cache server on the host
+  network: "host"
   # Whether to use privileged mode or not when launching task containers (privileged mode is required for Docker-in-Docker).
   privileged: false
   # And other options to be used when the container is started (eg, --add-host=my.gitea.url:host-gateway).

runners/config_heavy.yaml

@@ -54,22 +54,20 @@ cache:
   # If it's empty, the cache data will be stored in $HOME/.cache/actcache.
   dir: ""
   # The host of the cache server.
-  # It's not for the address to listen, but the address to connect from job containers.
-  # So 0.0.0.0 is a bad choice, leave it empty to detect automatically.
-  host: ""
-  # The port of the cache server.
-  # 0 means to use a random available port.
-  port: 0
+  # Use host.docker.internal to allow containers to access the host
+  # This fixes the common networking issue where containers can't reach the cache server
+  host: "host.docker.internal"
+  # Use a fixed port instead of random to avoid connection issues
+  port: 44029
   # The external cache server URL. Valid only when enable is true.
   # If it's specified, act_runner will use this URL as the ACTIONS_CACHE_URL rather than start a server by itself.
   # The URL should generally end with "/".
   external_server: ""
 
 container:
-  # Specifies the network to which the container will connect.
-  # Could be host, bridge or the name of a custom network.
-  # If it's empty, act_runner will create a network automatically.
-  network: ""
+  # Use host network to avoid Docker networking issues with cache
+  # This ensures containers can access the cache server on the host
+  network: "host"
   # Whether to use privileged mode or not when launching task containers (privileged mode is required for Docker-in-Docker).
   privileged: false
   # And other options to be used when the container is started (eg, --add-host=my.gitea.url:host-gateway).

runners/config_light.yaml

@@ -54,22 +54,20 @@ cache:
   # If it's empty, the cache data will be stored in $HOME/.cache/actcache.
   dir: ""
   # The host of the cache server.
-  # It's not for the address to listen, but the address to connect from job containers.
-  # So 0.0.0.0 is a bad choice, leave it empty to detect automatically.
-  host: ""
-  # The port of the cache server.
-  # 0 means to use a random available port.
-  port: 0
+  # Use host.docker.internal to allow containers to access the host
+  # This fixes the common networking issue where containers can't reach the cache server
+  host: "host.docker.internal"
+  # Use a fixed port instead of random to avoid connection issues
+  port: 44029
   # The external cache server URL. Valid only when enable is true.
   # If it's specified, act_runner will use this URL as the ACTIONS_CACHE_URL rather than start a server by itself.
   # The URL should generally end with "/".
   external_server: ""
 
 container:
-  # Specifies the network to which the container will connect.
-  # Could be host, bridge or the name of a custom network.
-  # If it's empty, act_runner will create a network automatically.
-  network: ""
+  # Use host network to avoid Docker networking issues with cache
+  # This ensures containers can access the cache server on the host
+  network: "host"
   # Whether to use privileged mode or not when launching task containers (privileged mode is required for Docker-in-Docker).
   privileged: false
   # And other options to be used when the container is started (eg, --add-host=my.gitea.url:host-gateway).

runners/config_security.yaml

@@ -54,22 +54,20 @@ cache:
   # If it's empty, the cache data will be stored in $HOME/.cache/actcache.
   dir: ""
   # The host of the cache server.
-  # It's not for the address to listen, but the address to connect from job containers.
-  # So 0.0.0.0 is a bad choice, leave it empty to detect automatically.
-  host: ""
-  # The port of the cache server.
-  # 0 means to use a random available port.
-  port: 0
+  # Use host.docker.internal to allow containers to access the host
+  # This fixes the common networking issue where containers can't reach the cache server
+  host: "host.docker.internal"
+  # Use a fixed port instead of random to avoid connection issues
+  port: 44029
   # The external cache server URL. Valid only when enable is true.
   # If it's specified, act_runner will use this URL as the ACTIONS_CACHE_URL rather than start a server by itself.
   # The URL should generally end with "/".
   external_server: ""
 
 container:
-  # Specifies the network to which the container will connect.
-  # Could be host, bridge or the name of a custom network.
-  # If it's empty, act_runner will create a network automatically.
-  network: ""
+  # Use host network to avoid Docker networking issues with cache
+  # This ensures containers can access the cache server on the host
+  network: "host"
   # Whether to use privileged mode or not when launching task containers (privileged mode is required for Docker-in-Docker).
   privileged: false
   # And other options to be used when the container is started (eg, --add-host=my.gitea.url:host-gateway).

runners/fix-cache-issues.ps1

@@ -0,0 +1,179 @@
+# Cache Troubleshooting and Fix Script for LabFusion CI/CD
+# This script helps diagnose and fix common cache timeout issues
+
+Write-Host "🔧 LabFusion Cache Troubleshooting Script" -ForegroundColor Cyan
+Write-Host "==========================================" -ForegroundColor Cyan
+
+# Function to check if running in Docker
+function Test-Docker {
+    if (Test-Path "/.dockerenv") {
+        Write-Host "🐳 Running inside Docker container" -ForegroundColor Green
+        return $true
+    } else {
+        Write-Host "🖥️  Running on host system" -ForegroundColor Yellow
+        return $false
+    }
+}
+
+# Function to check cache service status
+function Test-CacheService {
+    Write-Host "📊 Checking cache service status..." -ForegroundColor Cyan
+    
+    # Check if act_runner process is running
+    $processes = Get-Process -Name "act_runner" -ErrorAction SilentlyContinue
+    if ($processes) {
+        Write-Host "✅ act_runner process found" -ForegroundColor Green
+    } else {
+        Write-Host "❌ act_runner process not found" -ForegroundColor Red
+        return $false
+    }
+    
+    # Check cache directory
+    $cacheDir = "$env:USERPROFILE\.cache\actcache"
+    if (Test-Path $cacheDir) {
+        Write-Host "✅ Cache directory exists: $cacheDir" -ForegroundColor Green
+        $size = (Get-ChildItem $cacheDir -Recurse | Measure-Object -Property Length -Sum).Sum
+        Write-Host "   Size: $([math]::Round($size / 1MB, 2)) MB" -ForegroundColor Gray
+    } else {
+        Write-Host "⚠️  Cache directory not found: $cacheDir" -ForegroundColor Yellow
+        Write-Host "   Creating cache directory..." -ForegroundColor Yellow
+        New-Item -ItemType Directory -Path $cacheDir -Force | Out-Null
+    }
+    
+    return $true
+}
+
+# Function to test network connectivity
+function Test-NetworkConnectivity {
+    Write-Host "🌐 Testing network connectivity..." -ForegroundColor Cyan
+    
+    # Test basic connectivity
+    try {
+        $ping = Test-Connection -ComputerName "8.8.8.8" -Count 1 -Quiet
+        if ($ping) {
+            Write-Host "✅ Internet connectivity OK" -ForegroundColor Green
+        } else {
+            Write-Host "❌ Internet connectivity failed" -ForegroundColor Red
+        }
+    } catch {
+        Write-Host "❌ Internet connectivity test failed: $($_.Exception.Message)" -ForegroundColor Red
+    }
+    
+    # Test Docker daemon
+    try {
+        docker info | Out-Null
+        Write-Host "✅ Docker daemon accessible" -ForegroundColor Green
+    } catch {
+        Write-Host "❌ Docker daemon not accessible" -ForegroundColor Red
+    }
+}
+
+# Function to fix common cache issues
+function Fix-CacheIssues {
+    Write-Host "🔧 Applying cache fixes..." -ForegroundColor Cyan
+    
+    # Create cache directory with proper permissions
+    $cacheDir = "$env:USERPROFILE\.cache\actcache"
+    New-Item -ItemType Directory -Path $cacheDir -Force | Out-Null
+    
+    # Set proper environment variables
+    $env:ACTIONS_CACHE_URL = "http://host.docker.internal:44029/"
+    $env:ACTIONS_RUNTIME_URL = "http://host.docker.internal:44029/"
+    
+    Write-Host "✅ Cache directory created and configured" -ForegroundColor Green
+    Write-Host "✅ Environment variables set" -ForegroundColor Green
+}
+
+# Function to restart cache service
+function Restart-CacheService {
+    Write-Host "🔄 Restarting cache service..." -ForegroundColor Cyan
+    
+    # Stop existing runners
+    Get-Process -Name "act_runner" -ErrorAction SilentlyContinue | Stop-Process -Force
+    Start-Sleep -Seconds 2
+    
+    # Start with updated configuration
+    if (Test-Path "config_docker.yaml") {
+        Write-Host "✅ Using updated Docker configuration" -ForegroundColor Green
+        Start-Process -FilePath ".\act_runner.exe" -ArgumentList "daemon", "--config", "config_docker.yaml" -WindowStyle Hidden
+    } elseif (Test-Path "config_heavy.yaml") {
+        Write-Host "✅ Using updated heavy configuration" -ForegroundColor Green
+        Start-Process -FilePath ".\act_runner.exe" -ArgumentList "daemon", "--config", "config_heavy.yaml" -WindowStyle Hidden
+    } else {
+        Write-Host "⚠️  Updated configuration not found, using default" -ForegroundColor Yellow
+        Start-Process -FilePath ".\act_runner.exe" -ArgumentList "daemon" -WindowStyle Hidden
+    }
+    
+    Start-Sleep -Seconds 5
+    
+    $processes = Get-Process -Name "act_runner" -ErrorAction SilentlyContinue
+    if ($processes) {
+        Write-Host "✅ Cache service restarted successfully" -ForegroundColor Green
+    } else {
+        Write-Host "❌ Failed to restart cache service" -ForegroundColor Red
+        return $false
+    }
+    
+    return $true
+}
+
+# Function to test cache functionality
+function Test-CacheFunctionality {
+    Write-Host "🧪 Testing cache functionality..." -ForegroundColor Cyan
+    
+    # Create a test cache entry
+    $testKey = "test-cache-$(Get-Date -Format 'yyyyMMddHHmmss')"
+    $testValue = "test-value-$(Get-Date -Format 'yyyyMMddHHmmss')"
+    
+    Write-Host "   Creating test cache entry: $testKey" -ForegroundColor Gray
+    $testValue | Out-File -FilePath "C:\temp\cache-test.txt" -Force
+    
+    # Try to test cache service (this will fail but we can check the error)
+    Write-Host "   Testing cache service response..." -ForegroundColor Gray
+    try {
+        $response = Invoke-WebRequest -Uri "http://host.docker.internal:44029/cache/$testKey" -TimeoutSec 5 -ErrorAction SilentlyContinue
+        Write-Host "✅ Cache service responding" -ForegroundColor Green
+    } catch {
+        Write-Host "❌ Cache service not responding: $($_.Exception.Message)" -ForegroundColor Yellow
+        Write-Host "   This is expected if no cache entry exists" -ForegroundColor Gray
+    }
+    
+    # Clean up
+    Remove-Item "C:\temp\cache-test.txt" -ErrorAction SilentlyContinue
+}
+
+# Main execution
+function Main {
+    Write-Host "Starting cache troubleshooting..." -ForegroundColor Cyan
+    Write-Host ""
+    
+    Test-Docker
+    Write-Host ""
+    
+    Test-CacheService
+    Write-Host ""
+    
+    Test-NetworkConnectivity
+    Write-Host ""
+    
+    Fix-CacheIssues
+    Write-Host ""
+    
+    Restart-CacheService
+    Write-Host ""
+    
+    Test-CacheFunctionality
+    Write-Host ""
+    
+    Write-Host "🎉 Cache troubleshooting complete!" -ForegroundColor Green
+    Write-Host ""
+    Write-Host "Next steps:" -ForegroundColor Yellow
+    Write-Host "1. Check runner logs in the current directory" -ForegroundColor White
+    Write-Host "2. Test a workflow to see if cache issues are resolved" -ForegroundColor White
+    Write-Host "3. If issues persist, check Docker networking configuration" -ForegroundColor White
+    Write-Host ""
+    Write-Host "For more help, see: https://gitea.com/gitea/act_runner/src/branch/main/docs/configuration.md" -ForegroundColor Cyan
+}
+
+# Run main function
+Main

runners/fix-cache-issues.sh

@@ -0,0 +1,170 @@
+#!/bin/bash
+
+# Cache Troubleshooting and Fix Script for LabFusion CI/CD
+# This script helps diagnose and fix common cache timeout issues
+
+set -e
+
+echo "🔧 LabFusion Cache Troubleshooting Script"
+echo "=========================================="
+
+# Function to check if running in Docker
+check_docker() {
+    if [ -f /.dockerenv ]; then
+        echo "🐳 Running inside Docker container"
+        return 0
+    else
+        echo "🖥️  Running on host system"
+        return 1
+    fi
+}
+
+# Function to check cache service status
+check_cache_service() {
+    echo "📊 Checking cache service status..."
+    
+    # Check if cache service is running
+    if pgrep -f "act_runner" > /dev/null; then
+        echo "✅ act_runner process found"
+    else
+        echo "❌ act_runner process not found"
+        return 1
+    fi
+    
+    # Check cache directory
+    CACHE_DIR="${HOME}/.cache/actcache"
+    if [ -d "$CACHE_DIR" ]; then
+        echo "✅ Cache directory exists: $CACHE_DIR"
+        echo "   Size: $(du -sh "$CACHE_DIR" 2>/dev/null || echo "Unknown")"
+    else
+        echo "⚠️  Cache directory not found: $CACHE_DIR"
+        echo "   Creating cache directory..."
+        mkdir -p "$CACHE_DIR"
+    fi
+}
+
+# Function to test network connectivity
+test_network() {
+    echo "🌐 Testing network connectivity..."
+    
+    # Test basic connectivity
+    if ping -c 1 8.8.8.8 > /dev/null 2>&1; then
+        echo "✅ Internet connectivity OK"
+    else
+        echo "❌ Internet connectivity failed"
+    fi
+    
+    # Test Docker daemon
+    if docker info > /dev/null 2>&1; then
+        echo "✅ Docker daemon accessible"
+    else
+        echo "❌ Docker daemon not accessible"
+    fi
+}
+
+# Function to fix common cache issues
+fix_cache_issues() {
+    echo "🔧 Applying cache fixes..."
+    
+    # Create cache directory with proper permissions
+    CACHE_DIR="${HOME}/.cache/actcache"
+    mkdir -p "$CACHE_DIR"
+    chmod 755 "$CACHE_DIR"
+    
+    # Set proper environment variables
+    export ACTIONS_CACHE_URL="http://host.docker.internal:44029/"
+    export ACTIONS_RUNTIME_URL="http://host.docker.internal:44029/"
+    
+    echo "✅ Cache directory created and configured"
+    echo "✅ Environment variables set"
+}
+
+# Function to restart cache service
+restart_cache_service() {
+    echo "🔄 Restarting cache service..."
+    
+    # Stop existing runners
+    pkill -f "act_runner" || true
+    sleep 2
+    
+    # Start with updated configuration
+    if [ -f "config_docker.yaml" ]; then
+        echo "✅ Using updated Docker configuration"
+        nohup ./act_runner daemon --config config_docker.yaml > runner.log 2>&1 &
+    elif [ -f "config_heavy.yaml" ]; then
+        echo "✅ Using updated heavy configuration"
+        nohup ./act_runner daemon --config config_heavy.yaml > runner.log 2>&1 &
+    else
+        echo "⚠️  Updated configuration not found, using default"
+        nohup ./act_runner daemon > runner.log 2>&1 &
+    fi
+    
+    sleep 5
+    
+    if pgrep -f "act_runner" > /dev/null; then
+        echo "✅ Cache service restarted successfully"
+    else
+        echo "❌ Failed to restart cache service"
+        return 1
+    fi
+}
+
+# Function to test cache functionality
+test_cache() {
+    echo "🧪 Testing cache functionality..."
+    
+    # Create a test cache entry
+    TEST_KEY="test-cache-$(date +%s)"
+    TEST_VALUE="test-value-$(date +%s)"
+    
+    echo "   Creating test cache entry: $TEST_KEY"
+    echo "$TEST_VALUE" > "/tmp/cache-test"
+    
+    # Try to restore (this will fail but we can check the error)
+    echo "   Testing cache restore..."
+    if curl -s "http://host.docker.internal:44029/cache/$TEST_KEY" > /dev/null 2>&1; then
+        echo "✅ Cache service responding"
+    else
+        echo "❌ Cache service not responding"
+        echo "   This is expected if no cache entry exists"
+    fi
+    
+    # Clean up
+    rm -f "/tmp/cache-test"
+}
+
+# Main execution
+main() {
+    echo "Starting cache troubleshooting..."
+    echo ""
+    
+    check_docker
+    echo ""
+    
+    check_cache_service
+    echo ""
+    
+    test_network
+    echo ""
+    
+    fix_cache_issues
+    echo ""
+    
+    restart_cache_service
+    echo ""
+    
+    test_cache
+    echo ""
+    
+    echo "🎉 Cache troubleshooting complete!"
+    echo ""
+    echo "Next steps:"
+    echo "1. Check runner logs: tail -f runner.log"
+    echo "2. Test a workflow to see if cache issues are resolved"
+    echo "3. If issues persist, check Docker networking configuration"
+    echo ""
+    echo "For more help, see: https://gitea.com/gitea/act_runner/src/branch/main/docs/configuration.md"
+}
+
+# Run main function
+main "$@"