x360-web-queue/README.md

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.

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:

./setup.sh
# lub, po utworzeniu .env:
docker compose up -d --build

Aktualny stan i logi:

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:

/xbox/                            # katalog na hoscie VM
  downloads/<JOB_ID>/             # pobrane ISO, archiwa i torrenty (kontener: /data/raw)
  downloads/<JOB_ID>/*.part       # nieukonczone transfery HTTP
  downloads/<JOB_ID>/*.part.segments/ # segmenty Archive.org do wznowienia
  work/<JOB_ID>/                  # rozpakowywanie i ISO tymczasowe (kontener: /data/work)
  work/tmp/                       # systemowe pliki tymczasowe (TMPDIR)
  work/cache/                     # cache Chromium/narzedzi (XDG_CACHE_HOME)
  ready/xex/<GRA>/                # wynik XEX
  ready/god/<GRA>/                # wynik GOD
  imports/                        # reczny import ISO lub archiwum
  torrents/<JOB_ID>.torrent       # metadane do wznowienia
  metadata/<PODGLAD_ID>/          # metadane magneta i engine.log
  private/archive-session.json   # sesja Archive.org (0600)
  logs/<JOB_ID>.log               # log konwersji
  logs/<JOB_ID>.bt.log            # log BT
  logs/<JOB_ID>.download.log      # log transferu Archive
  bt/<JOB_ID>.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.:

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/<JOB_ID>.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, anacrolix/torrent, xdvdfs, iso2god-rs, Playwright, FastAPI.

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:

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/<ID>/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):

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:

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:

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.