Ihr eigenes App Center: QPKG-Pakete von Git auf jedes NAS ausliefern

Bucket & Code Server IDE hält ein App-Center-Repository auf Ihrem NAS vor. Ein mit Neues Projekt angelegtes QPKG-Projekt wird bei jedem Git-Push gebaut, und das signierte Paket wird dort hineinveröffentlicht. Ihre anderen NAS-Geräte tragen die Adresse des Repositorys einmal im App Center ein und installieren und aktualisieren Ihre Pakete danach wie jede andere App. Cloudflare Tunnel bringt das Repository, und Git, falls Sie das wollen, ohne geöffneten Router-Port ins Internet.

1. VorbereitenModule, QDK, ein Zertifikat
2. ProjektNeues Projekt, QPKG-Paket
3. Signierenzwei Secrets in Forgejo
4. Repositoryseine Adresse im App Center
5. Internetein Paket-Hostname

Die Bilder zeigen das Panel; jedes Feld ist so ausgefüllt, wie dieser Leitfaden es beschreibt. Die Adressen gehören einem NAS unter 192.168.1.20, und die veröffentlichten Namen sind Beispiele unter example.com.

01Vor dem Start

• Git, CI und der Editor müssen eingeschaltet sein: Ein Admin schaltet jedes Modul mit seiner Schaltfläche auf der Seite Übersicht (Git einschalten, Git und CI einschalten, Editor einschalten) ein. Der Assistent Neues Projekt braucht Git und den Editor, und CI führt bei jedem Push den Workflow des Projekts aus.
• QDK muss installiert sein: Installieren Sie auf der Seite Toolchains, Reiter QNAP, QNAP QDK 2.5.0.
• Sie brauchen ein Code-Signing-Zertifikat, das QNAP Ihnen ausgestellt hat, in Form von Dateien: certificate, private_key und für die Kette ca_certs. Das App Center prüft beim Installieren die Code-Signatur eines Pakets, und das Repository auf der Seite Pakete nimmt nur code-signierte Pakete an. Ein Zertifikat auf einem Hardware-Token wird nicht unterstützt.

02Projekt anlegen

Öffnen Sie Neues Projekt auf der Seite Git oder über die Befehlspalette (Rolle developer).

1. Vorlage. Wählen Sie unter Pakete für QTS die Vorlage QPKG-Paket und drücken Sie Weiter.
2. Name und Sichtbarkeit. Der Name ist zugleich der des Repositorys, des Ordners und des Pakets: 1 bis 20 Buchstaben, Ziffern, Bindestriche oder Unterstriche. Besitzer ist Ihr Konto oder eine Organisation. Lassen Sie das Projekt auf Privat.
3. Dienst. Legen Sie fest, wie das Paket startet und stoppt: Kommandozeilenwerkzeug verlinkt das Programm nach /usr/bin, Hintergrunddienst führt es unter einem eigenen Konto aus, Web-App gibt ihm zusätzlich die Schaltfläche Öffnen im App Center, und Leer enthält nur die nackten Dienstbefehle (start, stop und so weiter). Diese Blöcke können Sie später in der Projektansicht ändern.
4. Build. Wählen Sie die Umgebung, in der das Projekt gebaut wird, und lassen Sie Direkt nach dem Anlegen bauen eingeschaltet.
5. Veröffentlichen. Schalten Sie Im App Center-Repository dieses NAS veröffentlichen ein. Derselbe Schalter bleibt danach in den Einstellungen des Projekts und lässt CI bei jedem Lauf veröffentlichen.
6. Überprüfen. Kontrollieren Sie die Schritte, die ausgeführt werden, und drücken Sie Projekt anlegen.

Der erste Job legt in Forgejo das Repository und den Ordner projects/<name> mit dem ersten Commit an: die Dateien der Vorlage und den Workflow .forgejo/workflows/build.yml. Der erste Build hat noch kein Zertifikat, daher bricht sein Veröffentlichungsschritt ab und meldet, das Paket trage keine Code-Signatur. Der Schalter bleibt an, und sobald Schritt 03 erledigt ist, veröffentlicht jeder Push.

03Jeden Build signieren

Legen Sie auf dem NAS die Dateien des Zertifikats neben qpkg.cfg im Ordner projects/<name> ab. Die .gitignore der Vorlage hält sie aus Git heraus. Ein Build in diesem Ordner signiert dann das Paket, und die erste Zeile von bvs qbuild lautet case 1. Fehlen in der Umgebung openssl oder bsdextrautils, bricht der Build ab und nennt den Befehl, der sie nachinstalliert.

CI checkt das Repository ohne diese Dateien aus und holt sie sich aus zwei Secrets. Öffnen Sie in Forgejo Einstellungen → Aktionen → Secrets des Repositorys und drücken Sie zweimal Add secret: QPKG_CERTIFICATE mit der Ausgabe von base64 -w0 certificate und QPKG_PRIVATE_KEY mit der von base64 -w0 private_key. Forgejo selbst verlangt Base64, wenn die Zeilenumbrüche eines Werts erhalten bleiben müssen. Ein Zertifikat mit Kette braucht ein drittes Secret, QPKG_CA_CERTS, und eine dritte Zeile im ersten Schritt, die es nach ca_certs schreibt.

Fügen Sie dann zwei Schritte zu .forgejo/workflows/build.yml hinzu: einen, der die Dateien direkt nach dem Checkout vor dem Build schreibt, und einen am Ende der Liste, der sie unabhängig vom Ergebnis wieder entfernt. Die eigenen Schritte der Vorlage bleiben unverändert.

# .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

04Jeder Push veröffentlicht das Paket

Jeder Push in das Repository startet den Workflow auf dem eigenen Runner des NAS. Er baut das Paket und veröffentlicht es mit --latest, sodass repo.xml die neue Version sofort auflistet und App Center sie bei der nächsten Prüfung anbietet. Ein nicht signierter Build wird nicht veröffentlicht: Der Lauf endet mit einer Warnung, die den Grund nennt.

Die Seite des Projekts (Projekte bzw. die Seitenleiste des Editors) startet dieselben Schritte von Hand: Bauen, Neu bauen, Testeinsatz (nur für Administratoren, nur signierte Pakete) und Veröffentlichen.

Die Karte Einstellungen enthält den Schalter Im App Center-Repository veröffentlichen. Solange er aus ist, überspringt ein CI-Lauf die Veröffentlichung mit einem Hinweis.

Die Seite Pakete listet jedes Paket mit seiner neuesten Version und Signatur auf. Eine Version, die ein Entwickler dort von Hand hochlädt, wartet, bis ein Administrator sie zur neuesten macht.

05Das Repository auf Ihren anderen NAS-Geräten hinzufügen

1. Kopieren Sie die Adresse aus der Karte Adresse für App Center auf der Seite Pakete.
2. Auf dem anderen NAS: App Center → ⚙ Settings → App Repository → Hinzufügen. Geben Sie einen Namen ein, fügen Sie die Adresse ein und drücken Sie Hinzufügen.
3. Ihre Pakete stehen unter diesem Namen in der linken Leiste von App Center. Installieren Sie sie dort. Wenn das Repository eine neuere Version auflistet, bietet App Center sie als Update an.

Diese LAN-Adresse funktioniert für NAS-Geräte in Ihrem Netzwerk. Für ein Gerät außerhalb müssen Sie das Repository im Internet veröffentlichen.

06Über das Internet mit Cloudflare Tunnel

Das Paket enthält cloudflared, das vom NAS aus eine ausgehende Verbindung zu Cloudflare aufbaut: Es wird kein Router-Port geöffnet, und Cloudflare verwaltet die Zertifikate für die Namen. Sie brauchen eine Domain, deren DNS bei Cloudflare liegt, und einen API-Token für diese Zone (dash.cloudflare.com, My Profile → API Tokens) mit vier Berechtigungen: Account, Cloudflare Tunnel, Edit; Zone, DNS, Edit; Zone, Cache Rules, Edit; Zone, Cache Purge, Purge. Hat der Token Client IP Address Filtering, tragen Sie beide öffentlichen Adressen des NAS ein, IPv4 und IPv6.

1. Für einen Haupt-Hostnamen aktivieren Sie zuerst Öffentliches Durchsuchen auf der Seite Git und drücken Speichern und Forgejo neu starten: Solange der Schalter aus ist, lehnt die Seite Veröffentlichen einen Haupt-Hostnamen ab. Als privat markierte Repositories bleiben verborgen.
2. Öffnen Sie Veröffentlichen unter Administration (nur Administratoren). Geben Sie die Namen und den Token ein, lassen Sie Cache-Vorgaben eingeschaltet und drücken Sie Veröffentlichen. Das Paket prüft zuerst alles bei Cloudflare, ändert dort nichts, wenn eine Prüfung fehlschlägt, und sagt, was Sie korrigieren müssen.
3. Danach legt das Paket den Tunnel an, leitet jeden Namen darauf und startet cloudflared. Die Karte Tunnel zeigt die Verbindungen.
4. Die Adresse für App Center auf der Seite Pakete nennt jetzt den Paket-Hostnamen. Fügen Sie diese Adresse auf NAS-Geräten außerhalb Ihres Netzwerks hinzu.
5. Bei einem Haupt-Hostnamen setzen Sie Öffentliche URL auf der Seite Netzwerk auf dessen Adresse, damit die Links von Forgejo und die HTTPS-Klonadressen darauf verweisen.

• Git über SSH läuft nicht über den Tunnel. Von außen klonen und pushen Sie über HTTPS, oder Sie leiten einen Router-Port an den Git-über-SSH-Port (9952) weiter und setzen auf der Seite Netzwerk SSH-Host in Klon-URLs.
• Cloudflare nimmt Anfragen bis 100 MB an. Pushen oder laden Sie alles, was größer ist, über die LAN-Adresse hoch.
• Eine Veröffentlichung in das Repository entfernt repo.xml sofort aus dem Cache von Cloudflare, sodass App Center die neue Version bei der nächsten Prüfung sieht.

07Was das Internet erreicht

Die Seite Veröffentlichen listet auf, was jeder Name ausliefert, und daneben die Cache-Regeln.

• Der Haupt-Hostname antwortet auf /ide/ mit 404, bis ein Administrator Den Editor veröffentlichen einschaltet. Das Terminal des Editors ist eine Root-Shell auf dem NAS, deshalb schalten Sie vorher die Zwei-Faktor-Authentifizierung für Entwickler- und Administratorkonten ein.
• Solange CI eingeschaltet ist, läuft jeder Workflow, den jemand in ein Repository pusht, als root auf dem NAS, egal ob aus dem Internet oder aus dem LAN. Geben Sie Push-Zugriff nur Personen, denen Sie auch das Admin-Passwort des NAS geben würden.
• Das erste Administratorpasswort lässt sich nie über einen veröffentlichten Namen setzen: Die Seite für die Ersteinrichtung nimmt nur Clients im lokalen Netzwerk an.
• Stoppen beendet cloudflared und ändert bei Cloudflare nichts. Bei Cloudflare entfernen löscht die DNS-Einträge, Cache-Regeln und den Tunnel, die das Paket angelegt hat, und vergisst den Token.