diff options
Diffstat (limited to 'doc/pl/admin')
| -rw-r--r-- | doc/pl/admin/administrator_guide.md | 593 | ||||
| -rw-r--r-- | doc/pl/admin/hub_snapshots.md | 127 |
2 files changed, 720 insertions, 0 deletions
diff --git a/doc/pl/admin/administrator_guide.md b/doc/pl/admin/administrator_guide.md new file mode 100644 index 000000000..540828e0d --- /dev/null +++ b/doc/pl/admin/administrator_guide.md @@ -0,0 +1,593 @@ +### Przegląd + +$Projectname to więcej niż prosta aplikacja internetowa. Jest to złożony system +komunikacyjny, który bardziej przypomina serwer poczty elektronicznej niż serwer +WWW. Aby zapewnić niezawodność i wydajność, wiadomości są dostarczane w tle i +umieszczane w kolejce do późniejszego dostarczenia, gdy lokacje są wyłączone. +Ten rodzaj funkcjonalności wymaga nieco więcej zasobów hosta niż typowy dziennik. +Nie każdy dostawca hostingu PHP-MySQL będzie w stanie obsługiwać $Projectname. Tak więc, przed instalacją zapoznaj się z wymaganiami i potwierdź je u dostawcy usług hostingowych. + +Bardzo staraliśmy się, aby Hubzilla działała na zwykłych platformach hostingowych, takich jak te używane do hostowania blogów Wordpress i stron internetowych Drupal. Będzie ona działać na większości systemów VPS Linux. Platformy Windows LAMP, takie jak XAMPP i WAMP, nie są obecnie oficjalnie obsługiwane, jednak mile widziane są poprawki, jeśli uda Ci się je uruchomić. + +### Gdzie można znaleźć więcej pomocy + +Jeśli napotkasz problemy lub sam masz jakiś problem, które nie zostały opisane w tej dokumentacji, poinformuj nas o tym za pośrednictwem narzędzia do [śledzenia problemów na Github](https://framagit.org/hubzilla/core/issues). Prosimy o jak najdokładniejsze opisanie swojego środowiska operacyjnego i podanie jak największej ilości informacji o wszelkich komunikatach o błędach, które mogą się pojawić, abyśmy mogli zapobiec ich występowaniu w przyszłości. Ze względu na dużą różnorodność istniejących systemów operacyjnych i platform PHP możemy mieć ograniczone możliwości debugowania instalacji PHP lub pozyskiwania brakujących modułów, ale dołożymy wszelkich starań, aby rozwiązać wszelkie ogólne problemy z kodem. + +### Zanim zaczniesz + +#### Wybierz nazwę domeny lub subdomeny dla swojego serwera + +Platformę $Projectname można zainstalować tylko w katalogu głównym domeny lub +subdomeny i nie może ona działać na niestandardowych portach TCP. + +#### Zdecyduj, czy będziesz używać SSL i uzyskaj certyfikat SSL przed instalacją oprogramowania + +POWINNO się używać SSL. Jeśli używasz SSL, MUSISZ użyć certyfikatu uznawanego +przez przeglądarki. **NIE WOLNO używać certyfikatów z podpisem własnym!** + +Przetestuj swój certyfikat przed instalacją. Narzędzie internetowe do testowania +certyfikatu jest dostępne pod adresem `http://www.digicert.com/help/`. +Odwiedzając witrynę po raz pierwszy, użyj adresu URL SSL (`https: //`), jeśli +protokół SSL jest dostępny. Pozwoli to uniknąć późniejszych problemów. Procedura +instalacji nie pozwoli na użycie certyfikatu, który nie jest zaufany dla przeglądarki. + +To ograniczenie zostało wprowadzone, ponieważ Twoje publiczne wpisy mogą zawierać +odniesienia do obrazów na Twoim hubie. Inni członkowie przeglądający swój strumień +w innych centrach otrzymają ostrzeżenia, jeśli Twój certyfikat nie jest zaufany +w ich przeglądarce internetowej. To zmyli wiele osób, ponieważ jest to +zdecentralizowana sieć i otrzymają ostrzeżenie o Twoim hubie podczas przeglądania +własnego huba i mogą pomyśleć, że ich własny hub ma problem. Te ostrzeżenia +są bardzo techniczne i przerażające dla niektórych osób, z których wielu nie +będzie wiedziało, jak postępować, z wyjątkiem przestrzegania zaleceń przeglądarki. +Jest to destrukcyjne dla społeczności. To powiedziawszy, zdajemy sobie sprawę z +problemów związanych z obecną infrastrukturą certyfikatów i zgadzamy się, że +istnieje wiele problemów, ale to nie zmienia wymagania. + +Bezpłatne certyfikaty zgodne z przeglądarkami są dostępne od dostawców, takich +jak StartSSL i LetsEncrypt. + +Jeśli NIE używasz SSL, może wystąpić opóźnienie do minuty dla startowego skryptu +instalacyjnego - podczas sprawdzania portu SSL, aby zobaczyć, czy tam jest wszystko +w porządku. Podczas komunikowania się z nowymi witrynami Hubzilla zawsze najpierw +próbuje połączyć się z portem SSL, zanim powróci do mniej bezpiecznego połączenia. +Jeśli nie używasz SSL, twój serwer WWW NIE MOŻE w ogóle nasłuchiwać na porcie 443. + +Jeśli używasz LetsEncrypt do dostarczania certyfikatów i tworzenia pliku pod +`well-known` lub `acme-challenge`, aby LetsEncrypt mógł zweryfikować własność +domeny, usuń lub zmień nazwę katalogu `.well-known` zaraz po wygenerowaniu +certyfikatu. $Projectname zapewni własną procedurę obsługi usług `.well-know` po +zainstalowaniu, a istniejący katalog w tej lokalizacji może uniemożliwić poprawne +działanie niektórych z tych usług. Nie powinno to stanowić problemu w przypadku +Apache, ale może to być problem z Nginx lub innymi platformami serwera internetowego. + +### Wdrożenie +Nowy hub można wdrożyć na kilka sposobów: + +* ręczna inastalaja na istniejącym serwerze; +* automatyczna instalacja na istniejącym serwerze przy użyciu skryptu instalacyjnego; +* automatyczne wdrożenie przy użyciu prywatnego serwera wirtualnego OpenShift (VPS).) + +### Wymagania +* Apache z włączonym modułem `mod-rewrite` i ustawioną dyrektywą "AllowOverride + All", tak aby można było stosować plik `.htaccess`. Niektóre osoby z powodzeniem + stosowały Nginx czy Lighttpd.Przykładowe skrypty konfiguracyjne są dostępne na + tej platformie w [doc/install](). Apache and Nginx mają najlepsze wsparcie. + +* PHP 7.1 lub w wersji wyższej. + * _Proszę mieć na uwadze, że w niektórych środowiskach hostinu + współdzielonego, wersja wiersza poleceń PHP różni się od wersji + serwera internetowego_ + +* Dostęp do wiersza poleceń PHP z ustawionym w pliku php.ini parametrem + `register_argc_argv` na `true` i bez ograniczeń dostawcy hostingu w zakresie + stosowania fumkcji `exec()` i `proc_open()`. + +* Rozszerzenia curl, gd (z obsługą co najmmniej jpeg i png), mysqli, mbstring, + mcrypt, zip i openssl. Tozszerzenie imagick nie jest wymagane ale jest zalecane. + +* Wymagane jest rozszerzenie xml, jeśli chce sie mieć działajacą obsługę webdav. + +* Jakaś forma serwera pocztowego lub bramy pocztowej, taka jak działa PHP mail(). + +* Serwer bazy danych Mysql 5.x lub MariaDB lub PostgreSQL. + +* Możliwość planowania zadań dla crona. + +* WYMAGANA jest instalacja w katalogu głównym hosta WWW (wirtualnego hosta w + Apache i bloku w Nginx). + +### Instalacja ręczna + +##### Krok 1. + +Rozpakuj pliki $Projectname do katalogu głównego obszaru dokumentów serwera WWW. +Jeśli kopiujesz drzewo katalogów na swój serwer WWW, upewnij się, że dołączasz +ukryte pliki, takie jak `.htaccess`. + +Jeśli możesz to zrobić, zalecamy użycie Git do sklonowania repozytorium źródłowego +zamiast używania spakowanego pliku tar lub zip. To znacznie ułatwia późniejszą +aktualizację oprogramowania. Polecenie Linux do sklonowania repozytorium do katalogu +"mywebsite: wyglądałoby tak: + + git clone https://framagit.org/hubzilla/core.git mywebsite + +a następnie, w dowolnym momencie, możesz pobrać najnowsze zmiany za pomocą: + + git pull + +upewnij się, że istniejeją foldery `store/[data]/smarty3` i `store` i że są +one możliwe do zapisu przez właściciela procesu serwera WWW: + + mkdir -p "store/[data]/smarty3" + chmod -R 777 store + +To uprawnienie (777) jest bardzo niebezpieczne i jeśli masz wystarczające +uprawnienia i wiedzę powinieneś umożliwić zapisywanie w tych katalogach tylko +przez serwer WWW i użytkownika, który uruchomia crona (patrz poniżej), jeśli jest +taki. W wielu współdzielonych środowiskach hostingowych może to być trudne, bez +zgłoszenia problemu u dostawcy. Powyższe uprawnienia pozwolą oprogramowaniu +działać, ale nie są optymalne. + +Aby działały niektóre internetowe narzędzia administracyjne, serwer WWW musi mieć +możliwość zapisu w następujących katalogach: + +* `addon` +* `extend` +* `view/theme` +* `widget` + +##### Krok 2. + +Utwórz pustą bazę danych i zanotuj szczegóły dostępu (nazwa hosta, nazwa +użytkownika, hasło, nazwa bazy danych). Biblioteki bazy danych PDO powracają do +komunikacji przez gniazdo uniksowe, gdy nazwą hosta jest `localhost`, ale +niektóre osoby zgłosiły problemy z implementacją gniazda. Użyj gniazd, jeśli +Twoje uprawnienia na to pozwalają. W przeciwnym razie, jeśli baza danych jest +udostępniana na hoście `localhost`, jako nazwę hosta wpisz `127.0.0.1`. + +Wewnętrznie używamy teraz biblioteki PDO do połączeń z bazą danych. Jeśli masz +do czynienia z konfigyracją bazy danych, którą nie możesz obsłużyć poprzez +formularz konfiguracyjny (ma przykład w przypadku uzywania MySQL z nietypową +lokalizacją gniazd) - możesz podać ciąg połączenia PDO jako nazwę hosta. +Na przykład: + + :/path/to/socket.file + +W razie potrzeby nadal trzeba wypełnić w formularzu konfiguracyjnym wszystkie +inne wartości mające zastosowanie. + +##### Krok 3. + +Utwórz pusty plik o nazwie `.htconfig.php` i uczyń go możliwymm do zapisania +przez serwer WWW. Krok ten wykonaj, jeśli wiesz, że serwer WWW nie będzie +mógł sam utworzyć tego pliku. + +##### Krok 4. + +Odwiedź swoją witrynę za pomocą przeglądarki internetowej i postępuj zgodnie z +instrukcjami. Zanotuj wszelkie komunikaty o błędach i popraw je przed +kontynuowaniem. Jeśli używasz protokołu SSL (od znanego urzędu autoryzacyjnego), +użyj schematu `https` w adresie URL swojej witryny. + +##### Krok 5. + +Jeśli automatyczna instalacja nie powiedzie się z jakiegoś powodu, +sprawdź następujące rzeczy: + +* Czy istnieje plik `.htconfig.php`? Jeśli nie, edytuj plik `htconfig.php` + i zmień w nim ustawienia systemowe. Następnie zmień jego nazwę na .htconfig.php. +* Czy baza danych jest wypełniona. Jeśli nie, zaimportuj treść skryptu + `install/schema_xxxxx.sql` w phpmyadmin lub wierszu poleceń mysql (zamień + 'xxxxx' na własciwy typ bazy danych). + +##### Krok 6. + +Po udanej instalacji odwiedż ponownie swoją witrynę i zarejestruj swoje osobiste +konto. Błędy rejestracji powinny dać sie naprawić automatycznie. + +Jeśli w tym momencie wystąpiła jakakolwiek *krytyczna* awaria, to na ogół +przyczyna leży w źle funkcjonującej bazie danych. W takim przypadku, aby zacząć +od nowa, usuń lub zmień nazwę pliku `.htconfig.php` i usuń tabele bazy danych. + +Aby Twoje konto miało dostęp administratora, powinno to być utworzone jako +pierwsze, a adres e-mail podany podczas rejestracji musi być zgodny z adresem +administratora podanym podczas instalacji. Jeśli stało sie inaczej, aby dać +dostęp administracyjny jakiemuś kontu, dodaj `4096` w rekordzie tabeli +`account_roles` tego konta. + +Ze względu na bezpieczeństwo witryny, nie ma możliwości zapewnienia dostępu +administracyjnego za pomocą formularzy konfiguracyjnych. + +##### Krok 7. BARDZO WAŻNY! + +Skonfiguruj zadanie Crona lub *zadanie zaplanowane*, tak aby uruchamiać menedżera +Crona co 10-15 minut w celu przetwarzania i konserwacji w tle. Przykład: + + cd /base/directory; /path/to/php Zotlabs/Daemon/Master.php Cron + + +Zmień tutaj `/base/directory` i `/path/to/php` na właściwe dla siebie ścieżki. + +Jeśli używasz serwera linuksowego, uruchom polecenie `crontab -e` i dodaj wiersz +taki jak poniżej, zmieniając odpowiednio ścieżki i ustawienia: + + */10 * * * * cd /home/myname/mywebsite; /usr/bin/php Zotlabs/Daemon/Master.php Cron > /dev/null 2>&1 + +Lokalizację PHP na ogół można ustalić wykonując polecenie `which php`. Jeśli +masz problemy z ustawienie Crona, skontaktuj się z dostawcą hostingu w celu +uzyskania pomocy. Hubzilla nie będzie działać prawidłowo bez tego kroku. + +Powinno się również sprawdzić ustawienie parametru +`App::$config['system']['php_path']` w pliku `.htconfig.php`. +Powinno to wyglądać tak (zmień to zgodnie z lokalizacją PHP w swoim systemie): + + + App::$config['system']['php_path'] = '/usr/local/php56/bin/php'; + +#### Oficjalne dodatki + +##### Instalacja + +Przejdź do swojej witryny. Następnie sklonuj repozytorium dodatków (osobno). +Nadamy temu repozytorium pseudonim `hzaddons`. Możesz pobrać inne repozytoria +dodatków Hubzilla, nadając im różne pseudonimy: + + cd mywebsite + util/add_addon_repo https://framagit.org/hubzilla/addons.git hzaddons + +##### Aktualizacja + +W celu aktualizacji drzewa dodatków, powinno się, z poziomu głównego katalogu +witryny, wydać polecenie aktualizacji tego repozytorium: + + cd mywebsite + util/update_addon_repo hzaddons + +Stwórz reprezentację dokumentacji online z możliwością wyszukiwania. Możesz to +zrobić za każdym razem, gdy dokumentacja jest aktualizowana: + + cd mywebsite + util/importdoc + +### Automatyczna instalacja poprzez skrypt .homeinstall + +Istnieje skrypt powłoki `.homeinstall/hubzilla-setup.sh`, który po +uruchomieniu zainstaluje Hubzillę i jego zależności na nowej instalacji stabilnej +dystrybucji Debiana 9 (Stetch). Powinien działać na podobnych systemach Linux, +ale wyniki mogą się różnić. + +#### Wymagania + +Skrypt instalacyjny został pierwotnie zaprojektowany dla małego serwera +sprzętowego za routerem domowym. Jednak został przetestowany też na kilku +systemach z Debian 9: + +* Home-PC (Debian-9.2-amd64) i Rapberry-Pi 3 (Rasbian = Debian 9.3) + * Połączenie z Internetem i domowy router + * Mini-PC lub Raspi połaczone z router + * Napęd USB dla kopii zapasowych + * Świeża instalacja Debian na swoim mini-pc + * Router z otwartymi portami 80 i 443 dla Debiana + +#### Etapy instalacji +1. `apt-get install git` +1. `mkdir -p /var/www/html` +1. `cd /var/www/html` +1. `git clone https://framagit.org/hubzilla/core.git .` +1. `nano .homeinstall/hubzilla-config.txt` +1. `cd .homeinstall/` +1. `./hubzilla-setup.sh` +1. `service apache2 reload` +1. Open your domain with a browser and step throught the initial configuration of $Projectname. + +### Zalecane dodatki + +Zalecamy zainstalowanie następujących dodatków we wszystkich publicznych witrynach: + + nsfw - hide inappropriate posts/comments + superblock - block content from offensive channels + +### Dodatki federacyjne + +Kilka społeczności internetowych zaczęło łączyć się przy użyciu wspólnych +protokołów. Stosowane protokoły mają nieco ograniczone możliwości. Na przykład +protokół GNU-Social nie oferuje żadnych trybów prywatności, a protokół Diaspora +jest nieco bardziej restrykcyjny w zakresie dozwolonych rodzajów komunikacji. +Wszystkie komentarze muszą być podpisane w bardzo unikalny sposób przez +oryginalnego autora. Rozważany jest również protokół ActivityPub, który może być +obsługiwany w przyszłości. Żaden inny istniejący protokół nie obsługuje +lokalizacji nomadycznej używanej w tym projekcie. Stwarza to pewne problemy z +obsługą, ponieważ niektóre funkcje działają w niektórych sieciach, a w innych nie. +Niemniej jednak protokoły federacyjne umożliwiają nawiązywanie połączeń ze znacznie +większą społecznością ludzi na całym świecie. Są dostarczane jako dodatki. + +* _diaspora_ - protokół diaspory używany przez Diasporę i Friendica. Najpierw + należy włączyć „Diaspora Statistics” (statystyki), aby włączyć wszystkie + dostępne funkcje. + +* _gnusoc_ - protokół społecznościowy GNU, używany przez GNU-Social, Mastodon i + kilka innych społeczności. Ten dodatek wymaga najpierw zainstalowania usługi + `pubsubhubbub` (także dodatku). + +Każdy członek Twojej siatki musi indywidualnie zdecydować, czy zezwolić na te +protokoły, ponieważ mogą one kolidować z kilkoma pożądanymi podstawowymi funkcjami +i możliwościami Hubzilla (takimi jak migracja kanałów i klonowanie). Robi się to +na swojej stronie _Ustawienia_ -> _Ustawienia funkcji i dodatków_. Administrator +może również ustawić: + + util/config system.diaspora_allowed 1 + util/config system.gnusoc_allowed 1 + +i włączać te protokoły automatycznie dla wszystkich nowo tworzonych kanałów. + +### Klasy usług + +Klasy usług pozwalają na ustawienie limitów zasobów systemowych poprzez +ograniczenie tego, co mogą robić poszczególne konta, w tym przechowywania plików +i najwyższych limitów wpisów. Zdefiniuj niestandardowe klasy usług zgodnie ze +swoimi potrzebami w pliku `.htconfig.php`. Na przykład utwórz klasę standard +i premium, używając następujących wierszy: + + // Service classes + + App::$config['system']['default_service_class']='standard'; // this is the default service class that is attached to every new account + + // configuration for standard service class + App::$config['service_class']['standard'] = + array('photo_upload_limit'=>2097152, // total photo storage limit per channel (here 2MB) + 'total_identities' =>1, // number of channels an account can create + 'total_items' =>0, // number of top level posts a channel can create. Applies only to top level posts of the channel user, other posts and comments are unaffected + 'total_pages' =>100, // number of pages a channel can create + 'total_channels' =>100, // number of channels the user can add, other users can still add this channel, even if the limit is reached + 'attach_upload_limit' =>2097152, // total attachment storage limit per channel (here 2MB) + 'chatters_inroom' =>20); + + // configuration for premium service class + App::$config['service_class']['premium'] = + array('photo_upload_limit'=>20000000000, // total photo storage limit per channel (here 20GB) + 'total_identities' =>20, // number of channels an account can create + 'total_items' =>20000, // number of top level posts a channel can create. Applies only to top level posts of the channel user, other posts and comments are unaffected + 'total_pages' =>400, // number of pages a channel can create + 'total_channels' =>2000, // number of channels the user can add, other users can still add this channel, even if the limit is reached + 'attach_upload_limit' =>20000000000, // total attachment storage limit per channel (here 20GB) + 'chatters_inroom' =>100); + +Aby zastosować klasę usług do istniejącego konta, użyj narzędzia wiersza poleceń +z katalogu głównego instalacji Hubzilla: + +* uzyskanie listy klas usług: + + util/service_class + + +* ustawienie domyślnej klasy usług na `firstclass`: + + util/config system default_service_class firstclass + +* uzyskanie listy usług, które należą do klasy `firstclass`: + + util/service_class firstclass + +* ustawienie całkowitego użycia dysku ze zdjęciami `firstclass` na 10 milionów bajtów + + util/service_class firstclass photo_upload_limit 10000000 + +* ustawienie konta z identyfikatorem 5 na klasę `firstclass` (z potwierdzeniem): + + util/service_class --account=5 firstclass + +* ustawienie konta, które jest właścicielem kanału `bdziennikchan` na klasę `firstclass` (z potwierdzeniem) + + util/service_class --channel=bdziennikchan firstclass + +**Service class limit options** + +##### Opcje limitów klas usług: + +* `photo_upload_limit` - maksymalna łączna liczba bajtów na zdjęcia +* `total_items` - maksymalna liczba wpisów na najwyższym poziomie +* `total_pages` - maksymalna liczba stron comanche +* `total_identities` - maksymalna liczba kanałów posiadanych na koncie +* `total_channels` - maksymalna liczba kanałów +* `total_feeds` - maksymalna liczba kanałów RSS +* `attach_upload_limit` - maksymalna pojemność przesyłania plików (w bajtach) +* `minimum_feedcheck_minutes` - najniższe ustawienie dozwolone dla odpytywania kanałów RSS +* `chatrooms` - maksymalna liczba czatów +* `chatters_inroom` - maksymalna liczba rozmówców w czacie +* `access_tokens` - maksymalna liczba tokenów dostępu gościa na kanał + +### Zarządzanie motywami + +#### Przykład zarządzania repozytorium + +1) Przejdź na poziom katalogu głównego serwera: + + ``` + root@hub:/root# cd /var/www + ``` + +2) Dodaj repozytorium motywu i nadaj mu nazwę + + ``` + root@hub:/var/www# util/add_theme_repo https://github.com/DeadSuperHero/redmatrix-themes.git DeadSuperHero + ``` +3) Zaktualizuj repozytorium motywu + + ``` + root@hub:/var/www# util/update_theme_repo DeadSuperHero + ``` + +### Katalog kanałów + +#### Słowa kluczowe + +Na stronie katalogu kanałów może pojawiać się „chmura tagów” słów kluczowych. +Jeśli chcesz ukryć te słowa kluczowe, które są pobierane z serwera katalogów, +możesz użyć narzędzia `config`: + + util/config system disable_directory_keywords 1 + +Jeśli twój hub pracuje w trybie autonomicznym, ponieważ nie chcesz łączyć się +z globalną siecią, możesz zamiast tego ustawić opcję systemową `directory_server` +na wartość pustą: + + util/config system directory_server "" + +### Administrowanie + +#### Administrowanie witryną + +Administracja witryną jest zwykle wykonywana za pośrednictwem strony administratora +znajdującej się na ścieżce `/admin` adresu URL Twojej witryny. Aby uzyskać dostęp +do tej strony, trzeba mieć uprawnienia administratora na serwerze. Prawa +administracyjne są przyznawane pierwszemu kontu, które zostało zarejestrowane w +witrynie, pod warunkiem, że adres e-mail tego konta dokładnie odpowiada adresowi +e-mail podanemu jako adres e-mail administratora podczas konfiguracji. + +Istnieje kilka sposobów, w jakie może to się nie powieść i pozostawić system bez +konta administratora, na przykład jeśli pierwsze konto, które zostało utworzone, +miało inny adres e-mail niż adres e-mail administratora, który został podany +podczas konfiguracji. + +Ze względów bezpieczeństwa w systemie nie ma strony internetowej ani interfejsu, +który daje dostęp administratora. Jeśli potrzebujesz poprawić sytuację, w której +system nie ma konta administratora, musisz to zrobić edytując tabelę kont w bazie +danych. Nie ma innego wyjścia. Aby to zrobić, będziesz musiał zlokalizować wpis +w tabeli kont, który należy do żądanego administratora i ustawić `account_roles` +dla tego wpisu na `4096`. Będziesz wtedy mógł uzyskać dostęp do strony +administratora z menu profilu twojego systemu lub bezpośrednio na ścieżce `/admin`. + +Hub może mieć wielu administratorów i nie ma ograniczeń co do ich liczby. +Powtórz powyższą procedurę dla każdego konta, któremu chcesz przyznać uprawnienia +administracyjne. + +### Rozwiązywanie problemów + +#### Pliki dzienników + +Plik dziennika systemowego jest niezwykle przydatnym źródłem informacji do +śledzenia błędów. Można to włączyć na stronie konfiguracji `admin/dziennik`. +Ustawienie poziomu o wartości `dziennikGER_DEBUG` jest preferowany w stabilnej +instalacji produkcyjnej. Większość problemów związanych z komunikacją lub +przechowywaniem jest tutaj wymieniona. Ustawienie na `dziennikGER_DATA` +zapewnia znacznie więcej szczegółów, ale może wypełnić dysk. W obu przypadkach +zalecamy użycie `dziennikrotate` w systemie operacyjnym do cyklicznego tworzenia +dzienników i usuwania starszych wpisów. + +Na dole twojego `.htconfig.php` znajduje się kilka linii (zakomentowanych), +które umożliwiają rejestrowanie błędów PHP. Zgłaszane są problemy ze składnią i +wykonywaniem kodu i jest to też pierwszym miejscem, w którym należy szukać +problemów, które powodują "biały ekran" lub pustą stronę. Zwykle jest to wynikiem +problemów z kodem lub składnią. Błędy bazy danych są zgłaszane do pliku dziennika +systemowego, ale uznaliśmy, że przydatne jest umieszczenie w katalogu najwyższego +poziomu pliku `dbfail.out`, który gromadzi tylko informacje o problemach +związanych z bazą danych. Jeśli plik istnieje i można go zapisać, będą rejestrowane +w nim błędy bazy danych, a także w pliku dziennika systemowego. + +W przypadku błędów "500: problemy mogą być często rejestrowane w dziennikach +serwera internetowego, często w `/var/dziennik/apache2/error.dziennik` lub +podobnym. Zapoznaj się z dokumentacją systemu operacyjnego. + +Istnieją trzy różne obiekty dziennika. + +**Pierwsza to dziennik błędów bazy danych**. Jest on używane tylko wtedy, gdy +tworzy ssię plik o specyficznej nazwie `dbfail.out` w folderze głównym swojej +witryny i pozwala się na zapisywanie w nim przez serwer WWW. Jeśli masz +jakiekolwiek zapytania do bazy danych, które nie powiodły się, wszystkie są +zgłaszane tutaj. Zwykle wskazują na literówki w naszych zapytaniach, ale występują +również w przypadku rozłączenia serwera bazy danych lub uszkodzenia tabel. +W rzadkich przypadkach zobaczymy tutaj warunki wyścigu, w których dwa procesy +próbowały utworzyć wpis `xchan` lub `cache`z tym samym identyfikatorem. Należy +zbadać wszelkie inne błędy (zwłaszcza błędy uporczywe). + +**Drugi to dziennik błędów PHP**. Jest tworzony przez procesor języka i zgłasza +tylko problemy powstałe w środowisku językowym. Znowu mogą to być błędy składniowe +lub błędy programistyczne, ale generalnie są one fatalne i skutkują "białym ekranem"; +na przykład PHP kończy działanie. Prawdopodobnie powinieneś zajrzeć do tego pliku +też, jeśli coś pójdzie nie tak, co nie powoduje białego ekranu. Często zdarza się, +że plik ten jest pusty przez wiele dni. + +Na dole dostarczonego pliku `.htconfig.php` znajduje się kilka linii, które, +jeśli nie są zakomentowane, włączają dziennik PHP (niezwykle przydatny do +znajdowania źródła błędów białego ekranu). Nie jest to robione domyślnie ze względu +na potencjalne problemy z własnością pliku dziennika i uprawnieniami do zapisu +oraz fakt, że domyślnie nie ma rotacji pliku dziennika. + +**Trzeci to "dziennik aplikacji"**. Jest to używane przez Hubzillę do zgłaszania +tego, co dzieje się w programie i zwykle zapisywane są tu wszelkie trudności lub +nieoczekiwane dane, które otrzymaliśmy. Czasami zgłasza się tu również komunikaty +o stanie "pulsu", aby wskazać, że osiągnęliśmy określony punkt w skrypcie. Jest +to dla nas najważniejszy plik dziennika, ponieważ tworzymy go samodzielnie +wyłącznie w celu zgłaszania stanu zadań w tle i wszystkiego, co wydaje się dziwne +lub nie na miejscu. To może nie być śmiertelne, ale może po prostu nieoczekiwane. +Jeśli wykonujesz zadanie i występuje problem, daj nam znać, co znajduje się w tym +pliku, gdy wystąpił problem. Proszę nie wysyłaj mi 100 milionów zrzutów, tylko +mnie wkurzysz! Tylko kilka odpowiednich wierszy, abym mógł wykluczyć kilkaset +tysięcy wierszy kodu i skoncentrować się na tym, gdzie zaczyna się pojawiać +problem. + +To są dzienniki Twojej witryny, a nie moje. Zgłaszamy poważne problemy na każdym +poziomie dziennika. Gorąco polecam poziom dziennika `DEBUG` dla większości witryn. +Dostarcza on trochę dodatkowych informacji i nie tworzy dużych plików dziennika. +Kiedy pojawia się problem, który uniemożliwia wszelkie próby śledzenia, możesz +wtedy włączyć na krótki czas poziom `DATA`, aby uchwycić wszystkie szczegóły +struktur, z którymi mieliśmy do czynienia w tym czasie. Ten poziom dziennika +zajmuje dużo miejsca, więc jest zalecany tylko na krótkie okresy lub w przypadku +witryn testowych dla programistów. + +Zalecam skonfigurowanie `logrotate` zarówno dla dziennika php, jak i dziennika +aplikacji. Zazwyczaj co tydzień lub dwa zaglądam do `dbfail.out`, naprawiam +zgłoszone problemy i zaczynam od nowego pliku. Podobnie jest z plikiem dziennika +PHP. Odwołuję się do tego od czasu do czasu, aby sprawdzić, czy jest coś, co +wymaga naprawy. + +Jeśli coś pójdzie nie tak i nie jest to błąd krytyczny, patrzę na plik dziennika +aplikacji. Często robię to: + +``` +tail -f logfile.out +``` + +ponieważ powtarza operację, która ma problemy. Często wstawiam w kodzie dodatkowe +instrukcje logowania, jeśli nie ma żadnej wskazówki, co się dzieje. Nawet coś tak +prostego jak "got here" lub drukuję wartości zmiennej, która może być podejrzana. +Ty też możesz to zrobić - wręcz zachęcam Cię do tego. Gdy już znajdziesz to, czego +potrzebujesz, możesz wykonać: + +``` +git checkout file.php +``` + +aby natychmiast wyczyścić wszystkie dodane elementy rejestrowania. Skorzystaj z +informacji z tego dziennika i wszelkich szczegółów, które możesz podać podczas +badania problemu, aby zgłosić błąd - chyba że analiza wskazuje na źródło problemu. +W takim przypadku po prostu to napraw. + +##### Rotowanie plików dziennika + +1. Włącz dodatek *Logrot* w [oficjalnym repozytorium dodatków hubzilla](https://framagit.org/hubzilla/addons). +1. Utwórz katalog w swoim katalogu głównym o nazwie `log` z uprawnieniami do zapisu przez serwer WWW. +1. Przejdź do ustawień administratora programu *Logrot* i wprowadź nazwę folderu, a także maksymalny rozmiar i liczbę zachowanych plików dziennika. + +#### Zgłaszanie problemów + +Zgłaszając problemy, staraj się podać jak najwięcej szczegółów, które mogą być +potrzebne programistom do odtworzenia problemu i podać pełny tekst wszystkich +komunikatów o błędach. + +Zachęcamy do dołożenia wszelkich starań, aby wykorzystać te dzienniki w połączeniu +z posiadanym kodem źródłowym w celu rozwiązywania problemów i znajdowania ich +przyczyn. Społeczność często jest w stanie pomóc, ale tylko Ty masz dostęp do +plików dziennika swojej witryny i ich udostępnianie jest uważane za zagrożenie +bezpieczeństwa. + +Jeśli problem z kodem został odkryty, zgłoś go w bugtrackerze projektu +(https://framagit.org/hubzilla/core/issues). Ponownie podaj jak najwięcej szczegółów, +aby uniknąć ciągłego zadawania pytań o konfigurację lub powielanie problemu, +abyśmy mogli przejść od razu do problemu i dowiedzieć się, co z nim zrobić. +Zapraszamy również do oferowania własnych rozwiązań i przesyłania poprawek. +W rzeczywistości zachęcamy do tego, ponieważ wszyscy jesteśmy wolontariuszami i +mamy mało wolnego czasu. Im więcej osób pomaga, tym łatwiejsze jest obciążenie +pracą dla wszystkich. W porządku, jeśli Twoje rozwiązanie nie jest idealne. +Wszystko pomaga i być może uda nam się to poprawić. + diff --git a/doc/pl/admin/hub_snapshots.md b/doc/pl/admin/hub_snapshots.md new file mode 100644 index 000000000..1a5bd2d4f --- /dev/null +++ b/doc/pl/admin/hub_snapshots.md @@ -0,0 +1,127 @@ +### Hub Snapshot Tools + +Programiści Hubzilli często muszą przełączać się między gałęziami, które mogą +mieć niekompatybilne schematy lub zawartość bazy danych. Poniższe dwa skrypty +tworzą i przywracają pełne migawki instancji Hubzilli, w tym zarówno główny +katalog sieciowy, jak i stan całej bazy danych. Każdy skrypt wymaga pliku +konfiguracyjnego o nazwie `hub-snapshot.conf` znajdującego się w tym samym +folderze i zawiera on określone katalogi i szczegóły bazy danych huba. + +### Konfiguracja + +Format pliku konfiguracyjnego jest bardzo ścisły. Między nazwą zmiennej a +wartością nie może być spacji. Zastąp tylko treść w cudzysłowach swoją +konfiguracją. Zapisz ten plik jako `hub-snapshot.conf` obok skryptów. + + # Location of hub root. Typically this is the location of the Hubzilla repo clone. + HUBROOT="/var/www/" + # MySQL database name + DBNAME="hubzilla" + # MySQL database user + DBUSER="hubzilla" + # MySQL database password + DBPWD="akeufajeuwfb" + # The target snapshot folder where the git repo will be initialized + SNAPSHOTROOT="/root/snapshots/hubzilla/" + +### Migawka + +Przykład użycia: + + sh hub-snapshot.sh my-hub.conf "Commit message for the snapshot" + +**hub-snapshot.sh**: + + #!/bin/bash + + if ! [ -f "$1" ]; then + echo "$1 is not a valid file. Aborting..." + exit 1 + fi + source "$1" + #echo "$DBNAME" + #echo "$DBUSER" + #echo "$DBPWD" + #echo "$HUBROOT" + #echo "$SNAPSHOTROOT" + MESSAGE="snapshot: $2" + + if [ "$DBPWD" == "" -o "$SNAPSHOTROOT" == "" -o "$DBNAME" == "" -o "$DBUSER" == "" -o "$HUBROOT" == "" ]; then + echo "Required variable is not set. Aborting..." + exit 1 + fi + + if [ ! -d "$SNAPSHOTROOT"/db/ ]; then + mkdir -p "$SNAPSHOTROOT"/db/ + fi + if [ ! -d "$SNAPSHOTROOT"/www/ ]; then + mkdir -p "$SNAPSHOTROOT"/www/ + fi + + if [ ! -d "$SNAPSHOTROOT"/www/ ] || [ ! -d "$SNAPSHOTROOT"/db/ ]; then + echo "Error creating snapshot directories. Aborting..." + exit 1 + fi + + echo "Export database..." + mysqldump -u "$DBUSER" -p"$DBPWD" "$DBNAME" > "$SNAPSHOTROOT"/db/"$DBNAME".sql + echo "Copy hub root files..." + rsync -va --delete --exclude=.git* "$HUBROOT"/ "$SNAPSHOTROOT"/www/ + + cd "$SNAPSHOTROOT" + + if [ ! -d ".git" ]; then + git init + fi + if [ ! -d ".git" ]; then + echo "Cannot initialize git repo. Aborting..." + exit 1 + fi + + git add -A + echo "Commit hub snapshot..." + git commit -a -m "$MESSAGE" + + exit 0 + +### Przywracanie + + #!/bin/bash + # Restore hub to a previous state. Input hub config and commit hash + + if ! [ -f "$1" ]; then + echo "$1 is not a valid file. Aborting..." + exit 1 + fi + source "$1" + COMMIT=$2 + + if [ "$DBPWD" == "" -o "$SNAPSHOTROOT" == "" -o "$DBNAME" == "" -o "$DBUSER" == "" -o "$HUBROOT" == "" ]; then + echo "Required variable is not set. Aborting..." + exit 1 + fi + RESTOREDIR="$(mktemp -d)/" + + if [ ! -d "$RESTOREDIR" ]; then + echo "Cannot create restore directory. Aborting..." + exit 1 + fi + echo "Cloning the snapshot repo..." + git clone "$SNAPSHOTROOT" "$RESTOREDIR" + cd "$RESTOREDIR" + echo "Checkout requested snapshot..." + git checkout "$COMMIT" + echo "Restore hub root files..." + rsync -a --delete --exclude=.git* "$RESTOREDIR"/www/ "$HUBROOT"/ + echo "Restore hub database..." + mysql -u "$DBUSER" -p"$DBPWD" "$DBNAME" < "$RESTOREDIR"/db/"$DBNAME".sql + + chown -R www-data:www-data "$HUBROOT"/{store,extend,addon,.htlog,.htconfig.php} + + echo "Restored hub to snapshot $COMMIT" + echo "Removing temporary files..." + + rm -rf "$RESTOREDIR" + + exit 0 + |