Własne App Center: wysyłaj pakiety QPKG z Gita na każde NAS

Bucket & Code Server IDE prowadzi na NAS-ie repozytorium App Center. Projekt QPKG utworzony przyciskiem Nowy projekt buduje się przy każdym wypchnięciu do Gita i publikuje podpisany pakiet w tym repozytorium. Pozostałe jednostki NAS dodają adres repozytorium w App Center raz, a potem instalują i aktualizują pakiety jak każdą inną aplikację. Cloudflare Tunnel udostępnia repozytorium, a jeśli chcesz, także Git, w internecie bez otwierania portu w routerze.

1. Przygotowaniemoduły, QDK, certyfikat
2. ProjektNowy projekt, pakiet QPKG
3. Podpisaniedwa sekrety w Forgejo
4. Repozytoriumjego adres w App Center
5. Internetnazwa hosta pakietów

Zrzuty ekranu pochodzą z panelu. Pola wypełniono tak, jak opisuje poradnik. Widoczne adresy należą do NAS-a 192.168.1.20, a opublikowane nazwy to przykłady w domenie example.com.

01Zanim zaczniesz

• Git, CI i Edytor muszą być włączone. Administrator włącza każdy z nich przyciskiem na stronie Przegląd (Włącz Git, Włącz Git i CI, Włącz Edytor). Kreator nowego projektu wymaga Gita i Edytora, a CI uruchamia workflow projektu przy każdym wypchnięciu zmian (git push).
• Potrzebny jest QDK: na stronie Toolchainy, na karcie QNAP, zainstaluj QNAP QDK 2.5.0.
• Potrzebny jest certyfikat do podpisywania kodu, wydany Ci przez QNAP, w postaci plików: certificate, private_key i, dla łańcucha, ca_certs. App Center sprawdza podpis pakietu przy instalacji, a repozytorium na stronie Pakiety przyjmuje tylko podpisane pakiety. Certyfikat na tokenie sprzętowym nie jest obsługiwany.

02Utwórz projekt

Kreator Nowy projekt otworzysz ze strony Git albo z palety poleceń (potrzebna rola developer).

1. Szablon. W sekcji Pakiety dla QTS wybierz Pakiet QPKG i naciśnij Dalej.
2. Nazwa i widoczność. Ta nazwa będzie nazwą repozytorium, folderu i pakietu: od 1 do 20 liter, cyfr, myślników lub podkreśleń. Właścicielem jest Twoje konto albo organizacja. Projekt zostaw jako Prywatne.
3. Usługa. Wybierz, jak pakiet się uruchamia i zatrzymuje: Narzędzie wiersza poleceń dowiązuje program do /usr/bin, Usługa w tle uruchamia go na osobnym koncie, Aplikacja WWW dodaje też przycisk Otwórz w App Center, a Pusty ma tylko puste polecenia skryptu usługi (takie jak start i stop). Te bloki możesz później zmienić w widoku projektu.
4. Budowanie. Wybierz środowisko, w którym projekt się buduje, i zostaw włączone Zbuduj zaraz po utworzeniu.
5. Publikowanie. Włącz Opublikuj w repozytorium App Center tego NAS-a. Ten sam przełącznik zostaje potem w ustawieniach projektu i pozwala CI publikować przy każdym przebiegu.
6. Podsumowanie. Sprawdź kroki, które się uruchomią, i naciśnij Utwórz projekt.

Pierwsze zadanie tworzy w Forgejo repozytorium i folder projects/<name> z pierwszym commitem: pliki szablonu oraz workflow .forgejo/workflows/build.yml. Przy pierwszym budowaniu nie ma jeszcze certyfikatu, więc krok publikacji się zatrzymuje i podaje, że pakiet nie ma podpisu kodu. Przełącznik zostaje włączony, a po kroku 03 każde wypchnięcie zmian publikuje nową wersję.

03Podpisz każdą zbudowaną wersję

Na NAS-ie skopiuj pliki certyfikatu do folderu projects/<name>, obok qpkg.cfg. Plik .gitignore z szablonu nie pozwala dodać ich do gita. Budowanie w tym folderze podpisuje wtedy pakiet, a pierwszy wiersz wyniku bvs qbuild to case 1. Gdy w środowisku brakuje openssl lub bsdextrautils, budowanie się zatrzymuje i podaje polecenie, które je doda.

CI pobiera repozytorium bez tych plików, więc bierze je z dwóch sekretów. W Forgejo otwórz Ustawienia → Działania → Sekrety repozytorium i dwa razy naciśnij Dodaj sekret: QPKG_CERTIFICATE z wynikiem polecenia base64 -w0 certificate i QPKG_PRIVATE_KEY z wynikiem base64 -w0 private_key. Forgejo sam zaleca Base64 dla wartości, w których trzeba zachować podziały wierszy. Certyfikat z łańcuchem wymaga trzeciego sekretu, QPKG_CA_CERTS, oraz trzeciego wiersza w pierwszym kroku, który zapisze go do ca_certs.

Następnie dodaj do .forgejo/workflows/build.yml dwa kroki. Pierwszy, zaraz po checkout, zapisuje pliki przed budowaniem. Drugi, na końcu listy, usuwa je bez względu na wynik. Kroków szablonu nie zmieniasz.

# .forgejo/workflows/build.yml: the two new steps, in the template's steps list
    steps:
      - uses: actions/checkout@v4
      - name: certificate from the secrets
        run: |
          printf '%s' "$CERT" | base64 -d > certificate
          printf '%s' "$KEY" | base64 -d > private_key
          chmod 600 private_key
        env:
          CERT: ${{ secrets.QPKG_CERTIFICATE }}
          KEY: ${{ secrets.QPKG_PRIVATE_KEY }}
      # the template's build and publish step follows here, unchanged
      - name: remove the certificate
        if: always()
        run: rm -f certificate private_key ca_certs

04Każde wypchnięcie publikuje

Każde wypchnięcie zmian do repozytorium uruchamia workflow na runnerze, który działa na samym NAS-ie. Workflow buduje pakiet i publikuje go z opcją --latest, więc repo.xml od razu podaje nową wersję, a App Center zaproponuje ją przy najbliższym sprawdzeniu. Wersja bez podpisu nie zostanie opublikowana: przebieg kończy się ostrzeżeniem z przyczyną.

Te same kroki uruchomisz ręcznie na stronie projektu (Projekty albo pasek boczny Edytora): Zbuduj, Zbuduj ponownie, Wdrożenie testowe (tylko administrator, tylko pakiety podpisane) i Opublikuj.

Na jej karcie Ustawienia jest przełącznik Opublikuj w repozytorium App Center. Gdy jest wyłączony, przebieg CI pomija publikację i wyświetla komunikat.

Strona Pakiety wymienia każdy pakiet z najnowszą wersją i podpisem. Wersja, którą developer wyśle tam ręcznie, czeka, aż administrator oznaczy ją jako najnowszą.

05Dodaj repozytorium na pozostałych NAS-ach

1. Skopiuj adres z karty Adres dla App Center na stronie Pakiety.
2. Na drugim NAS-ie: App Center → ⚙ Ustawienia → Repozytorium aplikacji → Dodaj. Podaj nazwę, wklej adres i naciśnij Dodaj.
3. Twoje pakiety znajdziesz pod tą nazwą w lewym panelu App Center. Instaluj je tam. Gdy repozytorium wymieni nowszą wersję, App Center zaoferuje ją jako aktualizację.

Ten adres działa tylko dla NAS-ów w Twojej sieci lokalnej. Dla NAS-a spoza niej opublikuj repozytorium w internecie.

06Przez internet z Cloudflare Tunnel

Pakiet zawiera program cloudflared, który sam łączy się z NAS-a do Cloudflare. Nie trzeba więc otwierać żadnego portu na routerze, a certyfikaty dla nazw ma Cloudflare. Potrzebujesz domeny, której DNS jest w Cloudflare, oraz tokenu API dla tej strefy (dash.cloudflare.com, My Profile → API Tokens) z czterema uprawnieniami: Account, Cloudflare Tunnel, Edit; Zone, DNS, Edit; Zone, Cache Rules, Edit; Zone, Cache Purge, Purge. Jeśli token ma włączone Client IP Address Filtering, dodaj w nim oba publiczne adresy NAS-a, IPv4 i IPv6.

1. Dla głównej nazwy hosta najpierw włącz Publiczne przeglądanie na stronie Git i naciśnij Zapisz i zrestartuj Forgejo: strona Publikowanie odrzuca główną nazwę hosta, gdy opcja jest wyłączona. Repozytoria oznaczone jako prywatne pozostają ukryte.
2. Otwórz Publikowanie w sekcji Administracja (tylko administratorzy). Wpisz nazwy i token, zostaw włączone Gotowe reguły pamięci podręcznej i naciśnij Opublikuj. Pakiet najpierw wszystko sprawdza w Cloudflare. Jeśli coś się nie zgadza, niczego tam nie zmienia i pokazuje, co poprawić.
3. Następnie tworzy tunel, kieruje na niego każdą nazwę i uruchamia cloudflared. Karta Tunel pokazuje połączenia.
4. Adres App Center na stronie Pakiety wskazuje teraz nazwę hosta pakietów. Dodaj ten adres na NAS-ach poza Twoją siecią.
5. Jeśli publikujesz główną nazwę hosta, na stronie Sieć wpisz jej adres w polu Publiczny URL. Wtedy linki Forgejo i adresy klonowania HTTPS będą prowadzić pod tę nazwę.

• Git przez SSH nie przechodzi przez tunel. Z zewnątrz klonuj i wypychaj przez HTTPS, albo przekieruj port routera na port Git przez SSH (9952) i ustaw Host SSH w adresach klonowania na stronie Sieć.
• Cloudflare przyjmuje żądania do 100 MB. Większe pliki wypychaj albo wysyłaj przez adres w sieci lokalnej.
• Publikacja do repozytorium natychmiast usuwa repo.xml z pamięci podręcznej Cloudflare, więc App Center widzi nową wersję przy najbliższym sprawdzeniu.

07Co widzi internet

Strona Publikowanie pokazuje, co obsługuje każda nazwa, a obok reguły pamięci podręcznej.

• Pod główną nazwą hosta /ide/ odpowiada 404, dopóki administrator nie włączy Opublikuj edytor. Terminal edytora to powłoka root na NAS-ie, więc najpierw włącz uwierzytelnianie dwuskładnikowe dla kont deweloperów i administratorów.
• Gdy CI jest włączone, workflow wypchnięty do dowolnego repozytorium działa na NAS-ie jako root, bez względu na to, czy wypchnięto go z internetu, czy z sieci lokalnej. Prawo zapisu dawaj tylko osobom, którym możesz powierzyć hasło administratora NAS-a.
• Hasła pierwszego administratora nie da się ustawić przez opublikowaną nazwę: ekran pierwszego uruchomienia przyjmuje tylko połączenia z sieci lokalnej.
• Zatrzymaj kończy cloudflared i nic nie zmienia w Cloudflare. Usuń z Cloudflare kasuje rekordy DNS, reguły pamięci podręcznej i tunel utworzone przez pakiet i usuwa zapisany token.