Siirry pääsisältöön

Mukautetut virhe- ja huoltotilasivut

Opi toteuttamaan mukautetut huoltotila-, tietokantavirhe- ja PHP-virhesivut WordPressin drop-in-tiedostoilla (db-error.php, php-error.php) sekä nginx-palvelinasetuksilla Seravon ympäristössä.

Oletusarvoiset virheilmoitukset ja tyhjät valkoiset ruudut heikentävät käyttäjäkokemusta vikatilanteiden tai huoltotöiden aikana. Seravon ympäristössä voit toteuttaa mukautettuja huoltotila- ja virhesivuja usealla eri tasolla sen mukaan, kuinka syvällä järjestelmässä vika ilmenee:

  • WordPressin drop-in-tiedostot (wp-content/): Suositeltu tapa huoltotilalle (maintenance.php), tietokantavirheille (db-error.php) ja PHP-virheille (php-error.php).

  • Staattinen index.html: Nopein hätätilanneratkaisu, joka ohittaa PHP:n kokonaan.

  • Palvelintason säännöt (nginx): Toimii silloinkin, kun koko PHP-prosessi on kaatunut.

WordPressin sisäänrakennettu huoltotila (maintenance.php)

WordPress käyttää päivitysten aikana sisäänrakennettua huoltotilaa, jonka voit kytkeä päälle ja pois myös käsin WP-CLI-komennoilla:

# Kytke huoltotila päälle
wp maintenance-mode activate

# Poista huoltotila käytöstä
wp maintenance-mode deactivate

Kun huoltotila on aktiivinen, WordPress palauttaa kävijöille automaattisesti hakukoneystävällisen 503 Service Unavailable -tilakoodin. Voit mukauttaa huoltotilan ulkoasun luomalla tiedoston /data/wordpress/htdocs/wp-content/maintenance.php ja kirjoittamalla siihen haluamasi HTML-rakenteen ja tyylit.

Huoltotilasivu nginx-tasolla

Jos haluat ohjata kaiken liikenteen väliaikaiselle huoltotilasivulle palvelintasolla ilman WordPressin kuormittamista, luo tiedosto /data/wordpress/nginx/maintenance.conf.

Jotta hakukoneet eivät indeksoi huoltotilasivua sivuston varsinaisena sisältönä, palauta huoltotilan aikana HTTP-tilakoodi 503 ja Retry-After-otsake:

# Ohjaa kaikki muut pyynnöt paitsi varsinainen huoltotiedosto tilakoodiin 503
if ($uri != "/maintenance.html") {
    return 503;
}

error_page 503 @maintenance;
location @maintenance {
    add_header Retry-After 3600 always;
    rewrite ^(.*)$ /maintenance.html break;
}

Luo tämän jälkeen staattinen /data/wordpress/htdocs/maintenance.html-tiedosto ja ota nginx-muutokset käyttöön komennolla:

wp-restart-nginx

Jos haluat ohjata liikenteen tilapäisesti kokonaan toiselle palvelimelle, voit käyttää sääntöä return 302 https://status.esimerkki.fi/;.

Pelkistetty staattinen huoltotilasivu (index.html)

Seravon nginx-asetuksissa index.html on määritelty ensisijaiseksi hakemistoindeksiksi ennen index.php-tiedostoa. Jos sijoitat tiedoston /data/wordpress/htdocs/index.html, palvelin tarjoilee sen kaikille etusivulle saapuville kävijöille käynnistämättä PHP:tä tai WordPressiä lainkaan.

Staattinen sivu on hyödyllinen varakeino esimerkiksi palvelunestohyökkäyksen (DDoS) tai kuormituspiikin aikana, sillä pelkän HTML-tiedoston lähettäminen selaimeen on palvelimelle huomattavasti kevyempää kuin PHP:n ja WordPressin ajaminen.

Mukautettu tietokantayhteysvirhesivu (db-error.php)

Jos WordPress ei pysty muodostamaan yhteyttä tietokantaan, se etsii automaattisesti tiedostoa /data/wordpress/htdocs/wp-content/db-error.php. Luomalla tämän tiedoston voit korvata WordPressin karun oletusilmoituksen omalla brändätyllä virhesivullasi.

Muista asettaa tiedoston alussa 503-tilakoodi sekä välimuistin esto, jotta virhesivu ei tallennu HTTP-välimuistiin:

<?php
http_response_code( 503 );
header( 'Retry-After: 600' );
header( 'Cache-Control: no-store, no-cache, must-revalidate, max-age=0' );
header( 'Pragma: no-cache' );
?>
<!DOCTYPE html>
<html lang="fi">
<head>
    <meta charset="UTF-8">
    <title>Tilapäinen yhteysvirhe</title>
</head>
<body>
    <h1>Sivustolla on tilapäinen häiriö</h1>
    <p>Yhteyttä tietokantaan ei juuri nyt saatu muodostettua. Yritä hetken kuluttua uudelleen.</p>
</body>
</html>

Huomio: db-error.php suoritetaan ennen teeman tai lisäosien latautumista, joten tiedostossa ei voi käyttää WordPressin teemafunktioita (kuten get_header()).

Mukautetut PHP-fataalivirhesivut (php-error.php ja index.php)

Vaihtoehto A: WordPressin oma php-error.php (Suositus)

Nykyaikainen WordPress (versio 5.2 ja uudemmat) sisältää sisäänrakennetun palautustilan (Recovery Mode), joka ottaa kiinni vakavat PHP-virheet ja lähettää ylläpitäjälle sähköpostilinkin. Voit mukauttaa kävijöille näytettävän virhesivun luomalla tiedoston /data/wordpress/htdocs/wp-content/php-error.php samaan tapaan kuin yllä olevan db-error.php-tiedoston.

Vaihtoehto B: Varhainen virheenkäsittelijä index.php-tiedostossa

Jos haluat ottaa kiinni myös aikaisen vaiheen jäsennysvirheet (E_PARSE), jotka tapahtuvat ennen WordPressin oman virheenkäsittelijän latautumista, voit lisätä tiedoston /data/wordpress/htdocs/index.php alkuun PHP:n suorituksen päättyessä ajettavan virheenkäsittelijän (register_shutdown_function), joka näyttää kävijälle staattisen 500.html-sivun:

<?php
function custom_error_handler_at_shutdown() {
    $error = error_get_last();
    if ( $error && in_array( $error['type'], array( E_ERROR, E_PARSE ), true ) ) {
        http_response_code( 500 );
        header( 'Cache-Control: no-store, no-cache, must-revalidate, max-age=0' );
        header( 'Pragma: no-cache' );
        if ( file_exists( __DIR__ . '/500.html' ) ) {
            include __DIR__ . '/500.html';
        }
    }
}
register_shutdown_function( 'custom_error_handler_at_shutdown' );

define( 'WP_USE_THEMES', true );
require __DIR__ . '/wordpress/wp-blog-header.php';

Mukautetut virhesivut nginx-palvelimella

Suosittelemme virheiden käsittelyä ensisijaisesti WordPressin ja PHP:n tasolla. Tarvittaessa voit kuitenkin määrittää nginx-palvelimen kaappaamaan PHP-FPM:n palauttamat virhekoodit luomalla tiedoston /data/wordpress/nginx/error-pages.conf:

fastcgi_intercept_errors on;
error_page 500 502 503 504 /wp-content/500.html;

Ota asetus käyttöön komennolla wp-restart-nginx.

Huomio vianmäärityksestä: fastcgi_intercept_errors on; korvaa PHP:n omat virhetulosteet staattisella tiedostolla, mikä voi vaikeuttaa virheiden selvittämistä kehitystyön aikana. Lisäksi Seravon HTTP-välimuisti saattaa tietyissä vikatilanteissa palauttaa sivusta tallennetun välimuistiversion (stale cache) virhesivun sijaan.

Yleisimmät virhetilanteet

  • Muutokset nginx-asetuksissa eivät tule voimaan: Palvelin ei lataa uusia .conf-tiedostoja automaattisesti. Aja muutosten jälkeen aina komento wp-restart-nginx ja tyhjennä tarvittaessa välimuisti komennolla wp-purge-cache.

  • Virhe- tai huoltosivu jää jumiin välimuistiin: Varmista, että mukautetut PHP-virhesivut lähettävät otsakkeen Cache-Control: no-store, no-cache, must-revalidate, max-age=0 ja palauttavat oikean virhekoodin (500 tai 503), jotta HTTP-välimuisti tai selain ei tallenna virhesivua normaalina sivulatauksena.

  • Huoltotila jää päälle päivityksen keskeydyttyä: Jos sivusto näyttää päivityksen jälkeen viestiä "Sivustolla tehdään parhaillaan huoltotöitä", poista web rootissa oleva piilotiedosto /data/wordpress/htdocs/.maintenance tai aja komento wp maintenance-mode deactivate.

  • Mukautettu db-error.php tai php-error.php näyttää tyhjän sivun: Tiedostossa on todennäköisesti kutsuttu WordPressin teema- tai ydin-funktioita (kuten wp_head() tai esc_html()), joita ei ole vielä ladattu virhetilanteen sattuessa. Pidä virhesivut täysin itsenäisinä HTML/PHP-tiedostoina ja tarkista mahdolliset virheet lokista /data/log/php-error.log.

Katso myös

Hyvin suunnitellut virhe- ja huoltotilasivut pitävät kävijät ajan tasalla poikkeustilanteissa ja suojaavat sivuston hakukonenäkyvyyttä oikeilla HTTP-tilakoodeilla. Mikäli tarvitset apua mukautettujen nginx-sääntöjen tai virhesivujen testaamisessa, asiakaspalvelumme auttaa osoitteessa [email protected].

Aiheeseen liittyvät artikkelit
Vastasiko tämä kysymykseesi?