独自の App Center：Git から全 NAS へ QPKG パッケージを配布

Bucket & Code Server IDE は NAS 上に App Center リポジトリを保持します。新しいプロジェクト で作成した QPKG プロジェクトは、Git にプッシュするたびにビルドされ、署名済みパッケージをそのリポジトリに公開します。他の NAS は、リポジトリのアドレスを App Center に一度追加するだけで、他のアプリと同じようにパッケージをインストールおよび更新できます。Cloudflare Tunnel を使えば、ルーターのポートを開けずにリポジトリ（希望すれば Git も）をインターネットに公開できます。

1. 準備モジュール、QDK、証明書
2. プロジェクト新しいプロジェクト、QPKG パッケージ
3. 署名Forgejo の 2 つのシークレット
4. リポジトリApp Center でのアドレス
5. インターネットパッケージ用のホスト名

画像はパネルのもので、各項目は本ガイドの説明どおりに入力しています。アドレスは 192.168.1.20 の NAS のもので、公開する名前には、example.com 配下の例を使っています。

01始める前に

• Git、CI、エディターがオンになっている必要があります。オンにするのは管理者で、概要 にあるそれぞれのボタン（「Git」をオンにする、「Git」と「CI」をオンにする、「エディター」をオンにする）を使います。新しいプロジェクトのウィザードには Git とエディターが必要で、CI はプッシュのたびにプロジェクトのワークフローを実行します。
• QDK がインストールされている必要があります。ツールチェーン ページの QNAP タブで QNAP QDK 2.5.0 をインストールしてください。
• QNAP が発行したコード署名証明書が、ファイルの形で必要です。ファイル名は certificate、private_key、チェーン用の ca_certs です。App Center はインストール時にパッケージのコード署名を検証し、パッケージ ページのリポジトリはコード署名済みのパッケージのみを受け付けます。ハードウェアトークン上の証明書はサポートされていません。

02プロジェクトを作成する

Git ページまたはコマンドパレットから 新しいプロジェクト を開きます（開発者ロールが必要です）。

1. テンプレート。 QTS 用パッケージ の下で QPKG パッケージ を選び、次へ を押します。
2. 名前と公開範囲。 この名前はリポジトリ、フォルダー、パッケージの名前になります。使えるのは 1〜20 文字の英字、数字、ハイフン、アンダースコアです。所有者はご自身のアカウントまたは組織にします。プロジェクトは 非公開 のままにします。
3. サービス。 パッケージの起動と停止の方法を選びます。コマンドラインツール は、プログラムを /usr/bin にリンクします。バックグラウンドサービス は、専用のアカウントでプログラムを実行します。Web アプリ では、さらに App Center の「開く」ボタンが付きます。空 には、サービスの基本の操作 (起動、停止など) だけがあります。これらのブロックは、後からプロジェクトビューで変更できます。
4. ビルド。 プロジェクトをビルドする環境を選び、作成後すぐにビルド はオンのままにします。
5. 公開。 この NAS の App Center リポジトリに公開 をオンにします。同じスイッチがその後もプロジェクトの設定に残り、CI が実行のたびに公開できるようになります。
6. 確認。 実行される手順を確認し、プロジェクトを作成 を押します。

最初のジョブは、Forgejo にリポジトリを作成し、projects/<name> フォルダーを作って、最初のコミットを行います。コミットに含まれるのは、テンプレートのファイルと、ワークフロー .forgejo/workflows/build.yml です。最初のビルドにはまだ証明書がないため、公開ステップは停止し、パッケージにコード署名がないと表示します。スイッチはオンのままにしておき、ステップ 03 が終わると、以降のプッシュはすべて公開されます。

03すべてのビルドに署名する

NAS上では、証明書のファイルをqpkg.cfgの隣、projects/<name>に置きます。テンプレートの.gitignoreにより、これらはgitの管理対象から外れます。そのフォルダでビルドを実行すると、パッケージに署名されます。bvs qbuildの最初の行にcase 1と表示されます。環境にopensslまたはbsdextrautilsがない場合、ビルドは停止し、それらを追加するコマンドを表示します。

CI はこれらのファイルを含まずにリポジトリをチェックアウトするため、2 つのシークレットから取得します。Forgejo でリポジトリの 設定 → アクション → Secrets を開き、Add secret を 2 回押します。QPKG_CERTIFICATE には base64 -w0 certificate の出力を、QPKG_PRIVATE_KEY には base64 -w0 private_key の出力を設定します。値の改行を保たなければならない場合は Base64 を使うよう、Forgejo 自身が求めています。チェーン付きの証明書では 3 つ目のシークレット QPKG_CA_CERTS が必要です。最初のステップにも、それを ca_certs に書き出す 3 行目が必要です。

次に、.forgejo/workflows/build.yml に 2 つのステップを追加します。1 つはビルドの前 (チェックアウトの直後) にファイルを書き出すステップ、もう 1 つは一覧の最後に置き、結果にかかわらずそれらのファイルを削除するステップです。テンプレートの既存のステップはそのままにします。

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

04プッシュのたびに公開

リポジトリへのプッシュのたびに、NAS 自身のランナーでワークフローが実行されます。ワークフローはパッケージをビルドし、--latest 付きで公開します。そのため、repo.xml にはすぐに新しいバージョンが載り、App Center は次回の確認時にそれを提供します。署名のないビルドは公開されません。その場合、実行は警告で終わり、警告に理由が示されます。

プロジェクトのページ(プロジェクト、またはエディタのサイドバー)では、同じ手順を手動で実行できます: ビルド、再ビルド、テストデプロイ(管理者のみ、署名済みパッケージのみ)、公開。

その 設定 カードに、スイッチ App Center リポジトリに公開 があります。スイッチがオフの間、CI は公開を行わず、そのことを通知します。

パッケージ ページには、すべてのパッケージが最新バージョンと署名の状態とともに一覧表示されます。開発者が手動でアップロードしたバージョンは、管理者が最新のバージョンに指定するまで待機します。

05他の NAS にリポジトリを追加する

1. パッケージ ページの App Center 用アドレス カードからアドレスをコピーします。
2. 他の NAS で、App Center → ⚙ Settings → App Repository → 追加 の順に進みます。名前を付け、アドレスを貼り付けて 追加 を押します。
3. パッケージは、App Center の左側のリストでその名前の下に表示されます。そこからインストールしてください。リポジトリに新しいバージョンが載ると、App Center はそれをアップデートとして提案します。

この LAN アドレスは、同じネットワーク内の NAS で使えます。ネットワークの外にある NAS では、リポジトリをインターネットに公開してください。

06Cloudflare Tunnel でインターネット経由で公開

このパッケージには cloudflared が同梱されており、NAS から Cloudflare へ外向きに接続します。ルーターのポートは開放されず、名前の証明書は Cloudflare が管理します。DNS が Cloudflare にあるドメインと、そのゾーン用の API トークン(dash.cloudflare.com の My Profile → API Tokens)が必要です。トークンには次の 4 つの権限が必要です: Account, Cloudflare Tunnel, Edit、Zone, DNS, Edit、Zone, Cache Rules, Edit、Zone, Cache Purge, Purge。トークンで Client IP Address Filtering を使っている場合は、NAS の公開アドレスを IPv4 と IPv6 の両方とも登録してください。

1. メインのホスト名を公開する場合は、まず Git ページの 公開閲覧 をオンにし、保存して Forgejo を再起動 を押します。オフのままだと、公開ページはメインのホスト名を受け付けません。非公開のリポジトリは表示されません。
2. 管理者のみ: 管理メニューの 公開 を開きます。名前とトークンを入力し、キャッシュのプリセット をオンのままにして 公開 を押してください。パッケージはまず Cloudflare 側ですべてを確認し、確認に失敗した場合は Cloudflare 側を変更せず、何を直すべきかを示します。
3. 次に、パッケージがトンネルを作成し、各名前をそのトンネルに向けて、cloudflared を起動します。トンネル カードに接続状態が表示されます。
4. パッケージ ページの App Center 用アドレスは、これでパッケージ用のホスト名を指すようになります。ネットワーク外の NAS では、このアドレスを追加してください。
5. メインのホスト名を使う場合は、ネットワーク ページの 公開 URL をそのアドレスに設定します。こうすると、Forgejo のリンクと HTTPS のクローンアドレスがそのアドレスを使うようになります。

• Git over SSH はトンネルを通りません。外からは HTTPS でクローンとプッシュするか、ルーターのポートを Git over SSH のポート(9952)に転送し、ネットワーク ページで クローン URL の SSH ホスト を設定してください。
• Cloudflare は 100 MB までのリクエストを受け付けます。それより大きいものは、LAN アドレス経由でプッシュまたはアップロードしてください。
• リポジトリへの公開のたびに、repo.xml は Cloudflare のキャッシュからすぐに消去されるので、App Center は次回の確認時に新しいバージョンを認識します。

07インターネットから到達できるもの

公開ページには、各名前が提供する内容と、その横にあるキャッシュルールが一覧表示されます。

• メインのホスト名は、管理者が エディターを公開 をオンにするまで、/ide/ に 404 を返します。エディターのターミナルは NAS 上の root シェルなので、先に開発者と管理者のアカウントで 2 要素認証を有効にしてください。
• CI がオンの間は、どのリポジトリにプッシュされたワークフローも、NAS 上で root として実行されます。インターネットからのプッシュでも LAN からのプッシュでも同じです。プッシュ権限は、NAS の管理者パスワードを渡してもよい相手にだけ与えてください。
• 公開した名前を通して、最初の管理者パスワードを設定することはできません。最初の設定画面は、ローカルネットワーク上のクライアントからしか受け付けないためです。
• 停止 は cloudflared を終了させ、Cloudflare 側は何も変更しません。Cloudflare から削除 は、パッケージが作成した DNS レコード、キャッシュルール、トンネルを削除し、保存したトークンも消去します。