# X360 Web Queue — Linux / Docker / Xbox 360 RGH Samodzielna aplikacja WWW do pobierania i przygotowywania posiadanych legalnie obrazow gier Xbox 360. Wszystkie zadania wykonywane sa na serwerze/VM, niezaleznie od otwartej karty przegladarki. ## Start Wymagania: **Linux x86_64**, Docker Engine z wtyczka Docker Compose, minimum ok. 2 GB RAM (zalecane 4 GB podczas budowania), duzo miejsca na dane. ```bash unzip x360-web-queue-xbox.zip cd x360-web-queue # /xbox musi istniec i byc zapisywalny na hoscie Linux ./setup.sh ``` `setup.sh` przygotuje katalogi w `/xbox`, sam utworzy `.env` z mocnymi haslami i wykona `docker compose up -d --build`. Przy pierwszym starcie budowane sa `xdvdfs`, `iso2god-rs` i pomocniczy klient BitTorrent Go. Wirtualka potrzebuje dostepu do Docker Hub, GitHub, crates.io i proxy.golang.org. Na gospodarzu nie musisz instalowac Rusta ani Go. Otworz `http://IP_TWOJEJ_WIRTUALKI:8088` i zaloguj sie jako `admin` za pomoca hasla wypisanego przez `setup.sh` (takze w `.env`). Jesli Docker nie byl jeszcze zainstalowany, zainstaluj go, a pozniej: ```bash ./setup.sh # lub, po utworzeniu .env: docker compose up -d --build ``` Aktualny stan i logi: ```bash docker compose ps docker compose logs -f --tail=100 ``` ## Interfejs Plaski panel w ciemnych barwach, lokalne ikony SVG (bez CDN), filtrowanie kolejki i widok mobilny. Interfejs nie wymaga dodatkowych zaleznosci JS i zachowuje API dotychczasowej aplikacji. ## Zrodla - **HTTPS/HTTP**: wklej bezposredni adres pliku ISO/ZIP/7z/RAR, rowniez z serwisow umozliwiajacych normalny bezposredni transfer. - **Magnet**: panel automatycznie usuwa z wklejonego adresu HTML `&`, przypadkowe znaki `\` i lamanie linii, sprawdza hash, a nastepnie pobiera wylacznie metadane torrenta. Metadane pobiera klient Go (`anacrolix/torrent`, taki sam stos jak `minerva-pick`), bez pobierania plikow gry. Okno pokazuje czas, liczbe polaczen i znanych peerow. Po 5 minutach bez metadanych pojawia sie blad zamiast bezterminowego oczekiwania. Parametr `so=` ustawia wstepne zaznaczenie (od 0). Transfer danych rusza dopiero po wyborze plikow. - **Plik .torrent**: opcja `Wczytaj .torrent` w zakladce Link / magnet oraz w oknie podgladu. Pozwala natychmiast uzyskac liste plikow bez czekania na peerow. Maks. 32 MiB metadanych. Wczytanie .torrent *nie rozpoczyna* pobierania zawartosci, dopiero przycisk `Pobierz wybrane`. Dziala z duzymi katalogami Minerva (widok pokazuje maks. 500 plikow naraz, filtr pozwala wyszukac reszte). - **Internet Archive**: zakladka umozliwia zalogowanie e-mailem i haslem Archive.org (mechanizm xauthn stosowany w oficjalnych narzedziach), nastepnie wklej `https://archive.org/details/IDENTYFIKATOR` i wybierz pliki. Aplikacja przechowuje **tylko ciasteczka sesji**, a nie haslo. Pliki sa pobierane bezposrednio przez backend z sesja Archive.org, bez starego przekaznika aria2. **Wszystkie pliki jednego zadania sa pobierane rownolegle, maksymalnie 50 jednoczesnie**. Duze pliki sa dodatkowo dzielone na segmenty HTTP Range. Limit `ARCHIVE_CONNECTIONS=50` dotyczy **sumy polaczen HTTP wszystkich plikow zadania**, nie kazdego pliku osobno. Postep segmentow jest zachowywany po restarcie; pobieranie wznawia tylko brakujace bajty. Gdy serwer nie obsluguje Range albo zwraca niezgodne zakresy, aplikacja automatycznie przechodzi na jedno polaczenie. Dzialaja ponowienia HTTP 500/502/503/504/429 i kontrola wersji pliku za pomoca ETag / Last-Modified, jesli serwer je podaje. Ciasteczka sesji nie trafiaja do aria2 ani do logow. Logowanie nie zapewnia dostepu do plikow niedostepnych dla Twojego konta. Nie obchodzimy ograniczen serwisu. - **Vimm**: adres `https://vimm.net/vault/NUMER` przechodzi do **eksperymentalnego** adaptera uruchamiajacego Chromium. Wykorzystywany jest tylko faktycznie widoczny i dostepny przycisk `Download`. Brak omijania CAPTCHA, DRM, niedostepnych gier, antybota, limitow, kolejek i robots.txt. Gdy Vimm zmieni strone lub odrzuci automatyczny dostep, pobieranie nie bedzie dzialalo. Postep pobierania w trybie Vimm nie jest dostepny w % az do konca. Vimm uzywa jednej sesji naraz. Mozesz wylaczyc adapter w `.env`: `ENABLE_VIMM_BROWSER=false`. - **Import lokalny**: skopiuj plik do `/xbox/imports/`, odswiez karte Import i dodaj zadanie. Nie obslugujemy bypassowania zabezpieczen ani pobierania tresci wycofanych z serwisu. Uzywaj tylko plikow, do ktorych masz prawo. ## Przetwarzanie | Wejscie | Format XEX | Format GOD | |---|---|---| | `.iso` Xbox 360 | `xdvdfs unpack` | `iso2god` | | `.zip`, `.7z`, `.rar`, `.tar` zawierajace ISO | Rozpakuj, nastepnie XEX | Rozpakuj, nastepnie GOD | | Folder z `default.xex` spakowany w ZIP/7z | Kopia folderu | `xdvdfs pack`, potem `iso2god` | | Link magnet zawierajacy ISO | j.w. | j.w. | Archiwa wieloczesciowe: wybierz wszystkie czesci w **jednym** zadaniu (zakladka Archive.org), a nie osobno. Obsługiwane sa m.in. `.part1.rar`, `.7z.001`. Nie kazdy wariant kompresji RAR dziala w p7zip — wtedy zadanie zakonczy sie czytelnym bledem. Hasla do zaszyfrowanych archiwow nie sa obslugiwane. Dla XEX program sprawdza obecnosc `default.xex`. Dla GOD konwerter generuje katalogi TitleID/content type i pliki Data. Na dysku masz: ```text /xbox/ # katalog na hoscie VM downloads// # pobrane ISO, archiwa i torrenty (kontener: /data/raw) downloads//*.part # nieukonczone transfery HTTP downloads//*.part.segments/ # segmenty Archive.org do wznowienia work// # rozpakowywanie i ISO tymczasowe (kontener: /data/work) work/tmp/ # systemowe pliki tymczasowe (TMPDIR) work/cache/ # cache Chromium/narzedzi (XDG_CACHE_HOME) ready/xex// # wynik XEX ready/god// # wynik GOD imports/ # reczny import ISO lub archiwum torrents/.torrent # metadane do wznowienia metadata// # metadane magneta i engine.log private/archive-session.json # sesja Archive.org (0600) logs/.log # log konwersji logs/.bt.log # log BT logs/.download.log # log transferu Archive bt/.json # status klienta Go aria2/ # stan i sesje aria2 queue.sqlite3 # kolejka i historia zadan ``` Na Xbox przez FTP skopiuj **zawartosc** folderu `Gra` do `Hdd1:/Games/Nazwa/` i uruchom `default.xex` (albo wykonaj skan biblioteki Aurora). Dla GOD skopiuj `Content/0000000000000000/...` do `Hdd1:/Content/0000000000000000/...` z zachowaniem struktury. Gry wielodyskowe moga wymagac osobnej konfiguracji w Aurora. ## Przyspieszenie Internet Archive (HTTP Range) Nowe instalacje maja `ARCHIVE_CONNECTIONS=50` w `.env`. Przy aktualizacji istniejacego projektu dopisz lub zmien te ustawienie w `.env`, np.: ```dotenv ARCHIVE_CONNECTIONS=50 ``` Dozwolone jest **1-50**. `1` wylacza segmentowanie i ogranicza pobieranie do jednego pliku na raz. W zadaniu z 3 plikami przy limicie 50 przydzial wyniesie np. **17 + 17 + 16 polaczen**. Kazdy plik zaczyna sie pobierac od razu; kolejne pliki (pow. 50) uruchamiaja sie w zwolnionych slotach. Przydzial na plik jest ustalany na poczatku danej grupy plikow; gdy plik sie skonczy, pozostale zachowuja swoje segmenty i przydzielone sloty, a wolny slot moze rozpoczac nastepny plik. Mniejsze pliki oraz wczesniej podzielone na 8 segmentow moga wykorzystac mniej polaczen. Jesli Archive.org odrzuca zadania (np. HTTP 429) albo transfer zwalnia, ogranicz liczbe np. do 8, 16 lub 24. Po zmianie wykonaj `docker compose up -d --build`. Panel pokazuje liczbe plikow aktywnych, zbiorczy postep i sumaryczna predkosc, a w `/xbox/logs/.download.log` zapisany jest przydzial polaczen i bledy kazdego pliku. Segmenty uruchamiaja sie tylko dla plikow dostatecznie duzych (co najmniej dwa zakresy po 8 MiB; 50 segmentow wymaga minimum 400 MiB pozostalych do pobrania), po potwierdzeniu obslugi `HTTP 206 Content-Range` przez serwer. Program nie omija ograniczen konta ani zabezpieczen serwisu. Gdy Archive.org ogranicza polaczenia (np. `HTTP 429`) aplikacja uwzglednia `Retry-After` w sekundach; obniz `ARCHIVE_CONNECTIONS`, jezeli problem sie powtarza. Zadania, ktore maja juz zapisane segmenty z poprzedniej wersji, zachowuja pierwotna liczbe segmentow, aby mozna je bylo bezpiecznie wznowic. Po aktualizacji rownolegle rusza takze pobieranie pozostalych plikow z tego samego zadania. Nie trzeba kasowac pobranych czesci. Aby zastosowac nowy podzial 50 do juz podzielonego pliku, trzeba utworzyc nowe zadanie. Aktualizacja nie nadpisuje istniejacego `.env`: po podmianie projektu ustaw tam `ARCHIVE_CONNECTIONS=50` i zrestartuj kontener. **Dysk:** przed konwersja potrzebne jest miejsce na segmenty i kolejna pelna kopie skladanego pliku. Sprawdz wolne miejsce w VM, zwlaszcza przy obrazach ISO po kilka GB. ## Eksploatacja Aplikacja przechowuje kolejke SQLite, ma wznowienia HTTP i BitTorrent, jednego workera kolejki, do trzech podgladow magnet i przyciski stop/wznow/ponow. Wszystkie dane sa na hoscie w `/xbox` (domyslnie, bez wolumenow anonimowych), wiec pozostaja po restarcie kontenera. Zmiana lokalizacji jest mozliwa przez `XBOX_HOST_DIR` w `.env`. aria2 obsluguje zwykle linki HTTP/HTTPS, natomiast Go obsluguje magnety i pliki torrent. Czesciowo pobrane bloki torrenta sa weryfikowane po restarcie; Archive.org wznawia przez `.part` oraz katalog `.part.segments/` z oddzielnymi zakresami. Podczas koncowego laczenia czesci moze byc potrzebne dodatkowe miejsce na **jedna pelna kopie pliku**. Po poprawnym scaleniu czesci tymczasowe sa usuwane. **Bezpieczenstwo:** panel uzywa HTTP Basic Auth (haslo przesylane przy kazdym zadaniu HTTP). Formularz Archive.org rowniez przesyla haslo do lokalnego serwera. Zabezpiecz panel przed logowaniem poprzez HTTPS lub VPN; w lokalnym kontenerze haslo IA jest tylko przekazywane do `https://archive.org/services/xauthn/?op=login` i nie jest zapisywane. Sesja jest przechowywana w `/xbox/private` z uprawnieniami 0700/0600. Nie umieszczaj `/xbox/private` w publicznych kopiach projektu. Nie wystawiaj `8088` bezposrednio do internetu. Do dostepu z zewnatrz uzyj VPN (np. WireGuard/Tailscale) albo reverse proxy z TLS. Domyslnie port nasluchuje na LAN (`WEB_BIND=0.0.0.0`); aby ograniczyc dostep do maszyny lokalnej, ustaw `WEB_BIND=127.0.0.1` w `.env` i wykonaj `docker compose up -d`. ## Ograniczenia obecnej wersji - Brak bezposredniego FTP do konsoli i automatycznego rozpoznawania wszystkich wielodyskowych instalacji. - Brak wyszukiwarki gier — podajesz wlasne URL/magnet/item Archive. - Nie kazde konto Archive.org ma dostep do kazdego elementu. Nie ma gwarancji logowania, gdy serwis zmieni xauthn lub wymaga dodatkowej weryfikacji. Duzy transfer z Archive.org jest wielopolaczeniowy, jesli serwer akceptuje Range. Wieksza liczba polaczen nie gwarantuje wzrostu predkosci; zalezy to od serwera, trasy sieciowej i limitow konta. Jesli pojawiaja sie HTTP 429 albo 503, zmniejsz liczbe polaczen. Powtarzajacy sie HTTP 500 po 5 probach nadal oznacza blad po stronie serwera lub dostepu do pliku. - Odczyt metadanych magneta wymaga dostepnych peerow. Jezeli liczba polaczen i znanych peerow pozostaje 0, sprawdz DHT/UDP lub uzyj pliku .torrent. Plik .torrent eliminuje czekanie na metadane, ale nie gwarantuje dostepnosci zawartosci. Brak dostepnych peerow oznacza, ze zadne ustawienie interfejsu nie gwarantuje pobrania metadanych. Limit podgladu: 5 min. - W Docker Compose sa mapowane porty BitTorrent 6881/tcp i 6881/udp. Jezeli inna aplikacja uzywa 6881 na hoście, ustaw `BT_PORT=16881` w `.env` i przebuduj kontener. Przy NAT wirtualki moze byc potrzebne przekierowanie portow w hypervisorze/routerze. DHT wymaga dzialajacego ruchu UDP. - Brak gwarancji dla stron wymagajacych JS/autoryzacji poza obslugiwanymi integracjami; sam aria2 nie imituje przegladarki. - Uwaga na miejsce: w najgorszym przypadku podczas rozpakowania i konwersji potrzeba **2–4x** rozmiaru ISO. - Nie testowano pobierania rzeczywistych plikow z Archive.org na prywatnym koncie, odzyskiwania wskazanego magneta z DHT ani konwersji realnego ISO w tym srodowisku. Testy API, sesji, HTTP Range, ponawiania HTTP 500, nadzorcy klienta Go, parsera torrenta i kolejki mozna uruchomic `PYTHONPATH=. pytest -q` z zaleznosciami z requirements i pytest. Nie przetestowano obrazu Dockera ani transferu na zywej sieci; wymagaja testu na VM. ## Licencje i projekty Backend projektu: kod dostarczony tutaj. Zaleznosci i narzedzia sa instalowane niezaleznie na zasadach ich licencji: [aria2](https://aria2.github.io/), [anacrolix/torrent](https://github.com/anacrolix/torrent), [xdvdfs](https://github.com/antangelo/xdvdfs), [iso2god-rs](https://github.com/iliazeus/iso2god-rs), [Playwright](https://playwright.dev/), [FastAPI](https://fastapi.tiangolo.com/). ## Diagnostyka: magnet / torrent / Archive.org Po aktualizacji najpierw uruchom nowe zadanie `.torrent` lub magnet. Stare zadania moga miec zapisane `gid` aria2; nowszy backend przy pierwszym uruchomieniu zatrzymuje ich transfery. W razie bledu nacisnij **Log** w panelu, a dodatkowo sprawdz: ```bash docker compose ps docker compose logs --tail=120 x360-web # podstaw odpowiedni ID zadania z panelu lub katalogu /xbox/logs: ls -lt /xbox/logs/*.bt.log /xbox/logs/*.download.log 2>/dev/null | head # dla metadanych magnet: /xbox/metadata//engine.log ``` Oczekiwanie na metadane z 0 peerow oznacza brak osiagalnego zrodla w danym momencie lub problem z siecia BT w VM. Wczytanie `.torrent` omija wyłącznie etap metadanych, a nie potrzebe aktywnych peerow. Go używa TCP/UDP; sprawdz DNS i wyjscie UDP w wirtualce. Przy NAT czasem przydaje sie przekierowanie `BT_PORT` przez hypervisor i router. Archive.org **nie uzywa juz aria2** do plikow z `/download/`. Pliki jednego zadania ida rownolegle z lacznym limitem 1-50 polaczen HTTP (domyslnie 50), a HTTP 500 jest ponawiany maksymalnie 5 razy na probe/segment. Jesli nadal dostaniesz HTTP 500, oznacza to odpowiedz Archive.org lub posredniego serwera, nie samego panelu. Log pokazuje kazda probe, bez sesyjnych ciasteczek. ## Dane na dysku hosta: `/xbox` Compose montuje fizyczny katalog `/xbox` do `/data` w kontenerze. Dodatkowo `/xbox/downloads` jest montowany do `/data/raw`, dzieki czemu wszystkie stare sciezki w kolejce i sesjach aria2 pozostaja zgodne. Rowniez rozpakowywanie, konwersja i katalog tymczasowy (`TMPDIR`) korzystaja z tego samego katalogu hosta, a wynik trafia do `/xbox/ready/`. Nic z pobranych danych nie zalezy od dysku zapisywalnego kontenera. **Przed uruchomieniem musi istniec `/xbox`**. Jesli to podmontowany dysk lub udzial hosta, najpierw upewnij sie, ze jest dostepny i zapisywalny. Compose uzywa `bind.create_host_path: false`, zeby nie tworzyc po cichu brakujacej sciezki. **Jesli `/xbox` istnieje jako zwykly katalog pod niezamontowanym dyskiem, Compose nie rozpozna tego bledu** — w takim wypadku sprawdz `mountpoint /xbox` przed uruchomieniem. Przy nowej instalacji (jezeli katalog nie istnieje, utworz go najpierw): ```bash sudo mkdir -p /xbox # Tylko dla nowego katalogu na lokalnym dysku (nie zmieniaj wlasciciela udzialu SMB/NFS): sudo chown "$(id -un):$(id -gn)" /xbox # Dla udzialu/montowanego dysku zapewnij uprawnienia zapisu innym sposobem. cd x360-web-queue ./setup.sh ``` Jesli wolisz inna sciezke, dopisz do `.env` `XBOX_HOST_DIR=/sciezka/bezwzgledna`. Program nie zapisuje wtedy nic do `/xbox`, tylko do wybranej sciezki. Zmiana katalogu **nie przenosi** danych automatycznie. ### Aktualizacja istniejacej instalacji (migracja `./data`) Zachowaj `.env` i `./data` przed wypakowaniem tej wersji. Rozpakuj ZIP w katalogu nadrzednym starego `x360-web-queue/` i wykonaj: ```bash cd x360-web-queue # Upewnij sie, ze /xbox jest zamontowany i ma miejsce na dotychczasowe dane. ./migrate-to-xbox.sh docker compose up -d --build ``` Skrypt zatrzymuje stary kontener **przed kopiowaniem**, przenosi przez kopiowanie katalog `./data/raw/` do `/xbox/downloads/` oraz reszte `./data/` do `/xbox/`. **Nie usuwa starego `./data` ani nie nadpisuje istniejacej bazy / plikow**. Przerwana migracje mozna ponowic, o ile nie zostala uruchomiona nowa instancja. Jezeli brakuje `rsync`, zainstaluj go (`sudo apt install rsync`). Po sprawdzeniu dzialania i kompletności pobranych plikow mozesz samodzielnie usunac stary `./data`, zwalniajac miejsce. Weryfikacja: ```bash docker compose ps docker compose exec x360-web sh -c 'df -h /data/raw /data/work /data/ready; ls -ld /data/raw /data/work /data/ready' ls -lah /xbox/downloads /xbox/work /xbox/ready ``` **Uwaga:** dla SQLite i wznawiania pobierania najlepiej uzywac lokalnego systemu plikow z poprawnym blokowaniem (np. ext4 lub XFS). Przy montowaniu SMB/NFS sprawdz blokowanie plikow, uprawnienia i stabilnosc udzialu.