您自己的 App Center：把 QPKG 套件從 Git 發佈到每一台 NAS

Bucket & Code Server IDE 會在您的 NAS 上保存一個 App Center 儲存庫。用新專案建立的 QPKG 專案會在每次 Git 推送時建置，並把經過簽章的套件發佈到該儲存庫。您的其他 NAS 只要在 App Center 中加入一次這個儲存庫的位址，之後就能像其他應用程式一樣安裝和更新您的套件。Cloudflare Tunnel 可以把儲存庫放上網際網路，需要的話也能放上 Git，而且不必開放路由器的連接埠。

準備模組、QDK、憑證
專案新增專案、QPKG 套件
簽章Forgejo 中的兩個祕密值
儲存庫在 App Center 中的位址
網際網路套件主機名稱

截圖取自面板，每個欄位都照本指南填寫。位址屬於一台 IP 為 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 安裝套件時會檢查它的程式碼簽章，而套件頁面上的儲存庫只接受有程式碼簽章的套件。不支援存放在硬體權杖上的憑證。

「套件」頁面上的「程式碼簽署」卡片：1，以檔案形式提供的憑證，支援；2，位於硬體權杖上的憑證，不支援；3，沒有憑證，未簽署

02建立專案

從 Git 頁面或命令面板開啟 新專案（需要開發者角色）。

範本。在QTS 套件下選擇QPKG 套件，然後按下一步。
名稱與可見性。名稱同時用於儲存庫、資料夾與套件：1 到 20 個字元，可使用英文字母、數字、連字號或底線。擁有者是您的帳號或某個組織；專案保持私人。
服務。選擇套件的啟動與停止方式：命令列工具會把程式連結到 /usr/bin，背景服務會以其專屬帳號執行，網頁應用程式另外會提供 App Center 的「開啟」按鈕，空的則只有最基本的服務動作（啟動、停止等）。之後可以在專案檢視中更改這些區塊。
建置。選擇專案建置所在的環境，並保持建立後立即建置開啟。
發佈。開啟發佈到此 NAS 的 App Center 儲存庫。之後這個開關會留在專案的設定中，讓 CI 每次執行時都發佈。
檢查。確認將執行的步驟，然後按建立專案。

第一個工作會在 Forgejo 中建立儲存庫，以及資料夾 projects/<name> 與第一次提交：範本的檔案和工作流程 .forgejo/workflows/build.yml。首次建置時還沒有憑證，因此發佈步驟會停止，並表示套件沒有程式碼簽章。開關保持開啟，完成第 03 步後，每次推送都會發佈。

03為每次建置簽章

在 NAS 上，請把憑證檔案放進 projects/<name>，與 qpkg.cfg 放在一起。範本的 .gitignore 會讓這些檔案不被 git 追蹤。在該資料夾中建置時會為套件簽章，bvs qbuild 的第一行會顯示 case 1。若環境缺少 openssl 或 bsdextrautils，建置會停止，並指出可以補上它們的指令。

CI 檢出儲存庫時不含這些檔案，因此它會從兩個祕密值取得。在 Forgejo 中開啟儲存庫的設定 → 動作 → Secrets，並按兩次新增祕密值：QPKG_CERTIFICATE 的值為 base64 -w0 certificate 的輸出，QPKG_PRIVATE_KEY 的值為 base64 -w0 private_key 的輸出。當值的換行必須保留時，Forgejo 本身會要求 Base64。若憑證含有憑證鏈，需要第三個祕密值 QPKG_CA_CERTS，並且在第一個步驟中新增第三行，把它寫入 ca_certs。

Forgejo 的「新增祕密值」對話框：名稱 QPKG_CERTIFICATE，值為一行 Base64，以及「取消」與「確認」按鈕

接著在 .forgejo/workflows/build.yml 新增兩個步驟：一個在簽出（checkout）之後、建置之前寫入檔案，另一個放在清單最後，無論結果如何都會移除這些檔案。範本原有的步驟保持不變。

# .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 自己的 runner 上執行工作流程。它會建置套件，並以 --latest 發佈，因此 repo.xml 會立即列出新版本，App Center 在下次檢查時就會提供更新。未簽署的建置不會發佈：這次執行會以一則說明原因的警告結束。

專案頁面（專案，或編輯器的側邊欄）可以手動執行相同的步驟：建置、重新建置、測試部署（僅限管理員，且僅限已簽署的套件）以及發佈。

QPKG 專案的流程：在 ubuntu2404-builder 中以「建置」和「重新建置」進行建置；「測試部署」需要已簽署程式碼的套件；「發佈」會顯示建置未簽署、儲存庫只接受已簽署的套件，並說明 CI 也會發佈到 App Center 儲存庫；「發佈到網頁」無法在此執行

其設定卡片中有開關發佈到 App Center 儲存庫。開關關閉時，CI 執行會略過發佈，並顯示一則通知。

已開啟「發佈到 App Center 儲存庫」：專案的 CI 會把它的套件加入此 NAS 的 App Center 儲存庫

套件頁面列出每個套件的最新版本與簽署狀態。開發人員在這裡手動上傳的版本，會等到管理員把它設為最新版本。

05在其他 NAS 裝置上新增儲存庫

從套件頁面的 App Center 地址 卡片複製位址。
在另一台 NAS 上：App Center → ⚙ 設定 → App 儲存庫 → 新增。輸入名稱，貼上位址，然後按下新增。
您的套件會以該名稱列在 App Center 左側欄中，請在那裡安裝。當儲存庫列出較新的版本時，App Center 會將其提供為更新。

此區域網路位址適用於您網路中的 NAS 裝置。若 NAS 在您的網路之外，請把儲存庫發佈到網際網路。

06透過 Cloudflare Tunnel 連上網際網路

此套件內含 cloudflared，它會從 NAS 主動撥出連線到 Cloudflare：不需要開放路由器連接埠，名稱的憑證則由 Cloudflare 管理。您需要一個 DNS 託管在 Cloudflare 的網域，以及該區域的 API 權杖（dash.cloudflare.com，我的個人資料 → API 權杖），並具備四項權限：Account, Cloudflare Tunnel, Edit；Zone, DNS, Edit；Zone, Cache Rules, Edit；Zone, Cache Purge, Purge。若權杖具有用戶端 IP 位址篩選功能，請將 NAS 的兩個公開位址（IPv4 與 IPv6）都加入。

名稱	提供的內容
套件主機名稱 `qpkg.example.com`	只提供 `/repo/` 的 GET 與 HEAD，這正是其他 NAS 上的 App Center 所需要的全部內容
主要主機名稱 `code.example.com`	面板、位於 `/git/` 的 Forgejo（透過 HTTPS 進行 clone 與 push）、唯讀儲存庫、公開儲存庫的網頁檢視，以及使用指南

若要使用主要主機名稱，請先在 Git 頁面開啟 公開瀏覽，並按下 儲存並重新啟動 Forgejo：這個開關關閉時，「發佈」頁面會拒絕主要主機名稱。標記為私人的儲存庫仍會隱藏。
在管理功能下開啟發佈（僅限管理員）。輸入名稱與權杖，保持快取預設開啟，然後按下發佈。套件會先在 Cloudflare 檢查所有項目；若檢查失敗，不會在 Cloudflare 做任何變更，並會說明需要修正的內容。
接著它會建立通道、將各名稱指向該通道，並啟動 cloudflared。通道卡片會顯示連線狀態。
「套件」頁面上的 App Center 位址現在會指向套件主機名稱。請在您網路之外的 NAS 裝置上新增這個位址。
若使用主要主機名稱，請在網路頁面將 公開 URL 設為其位址，讓 Forgejo 的連結與 HTTPS 複製位址都使用此位址。

Git over SSH 不會經過通道。從外部請透過 HTTPS 進行 clone 與 push，或將路由器連接埠轉發到 Git over SSH 連接埠（9952），並在網路頁面設定複製 URL 中的 SSH 主機。
Cloudflare 接受最大 100 MB 的請求。若要推送或上傳更大的檔案，請透過區域網路位址進行。
每次發佈到儲存庫時，repo.xml 都會立即從 Cloudflare 的快取中清除，因此 App Center 會在下次檢查時看到新版本。

07網際網路可以存取的內容

「發佈」頁面會列出每個名稱提供的內容，以及旁邊的快取規則。

網際網路可存取的內容：主要主機名稱提供面板、Forgejo、網頁檢視與套件儲存庫，編輯器只在其開關開啟時提供，且絕不提供 WebDAV；套件主機名稱只提供 /repo/ 的 GET 與 HEAD。快取預設值：套件快取一年，圖示快取一天，repo.xml 快取 5 分鐘並在每次發佈時清除，API、Forgejo 與登入永不快取

在管理員開啟發佈編輯器之前，主要主機名稱對 /ide/ 會回應 404。編輯器的終端機是 NAS 上的 root 殼層，因此請先為開發人員與管理員帳號開啟兩步驟驗證。
在 CI 開啟期間，推送到任何儲存庫的工作流程都會以 root 身分在 NAS 上執行，無論來自網際網路或區域網路。請只把推送權限交給您放心告知 NAS 管理員密碼的人。
第一位管理員的密碼絕不會透過已發佈的名稱設定：首次執行畫面只接受區域網路上的用戶端。
停止會結束 cloudflared，且不會在 Cloudflare 做任何變更。從 Cloudflare 移除會刪除該套件建立的 DNS 記錄、快取規則與通道，並忘記權杖。