在 QNAP NAS 上打造地端 CI/CD：從 Git、Runner 到 Docker 自動部署

許多開發者在規劃持續整合與部署時，最先想到的通常是 GitHub Actions、GitLab CI 等公有雲服務。對於個人開發者、家庭實驗室（Homelab）、小型團隊或具備機密原始碼保護需求的企業而言，將整套建置管線移至內部網路是兼顧效能與資安的理想方案。

QNAP NAS 本身提供 Container Station，完整支援 Docker 容器與 Docker Compose 多容器應用程式管理。結合開源的 Gitea，單一系統即可同時扮演 Git 儲存庫、CI/CD 控制中心以及 OCI / Docker 容器映像檔倉庫（Container Registry）。透過這套整合架構，原始碼、建置任務、測試環境與最終產出的映像檔都能完整保留在區域網路內部。

Developer
    │
    │ git push
    ▼
┌──────────────────────────────────────────────────────────┐
│                         QNAP NAS                         │
│                                                          │
│  Gitea                                                   │
│   ├── Git Repository                                     │
│   ├── Actions (CI/CD Controller)                         │
│   └── Container Registry                                 │
│          │                                               │
│          ▼ Job Trigger                                   │
│      Gitea Actions Runner (act_runner)                   │
│          │                                               │
│          ├─► Unit Test                                   │
│          ├─► Security Scan (Trivy)                       │
│          ├─► Docker Build & Push to Registry             │
│          └─► Automated Deploy                            │
│                                                          │
│  Production Environment                                  │
│   └── Running Application Container                      │
└──────────────────────────────────────────────────────────┘

為什麼選擇在 QNAP NAS 上建構 CI/CD？

QNAP NAS 原生具備全年無休持續運作、大容量儲存空間、高速區域網路介面以及快照（Snapshot）備份能力。用來託管內部網站、API 服務、外掛程式或各類自動化工具時，不需要額外添購專用伺服器。

這套架構最關鍵的優勢在於資料完全自主掌控。原始碼不需要上傳至第三方雲端平台，CI/CD 的建置運算完全由內部處理，建置完畢的容器映像檔直接儲存在 NAS 本機，能徹底避免網路傳輸瓶頸與機密資料外洩風險。

系統架構與核心元件

CyberQ 建構這個地端自動化環境由四個關鍵元件構成，所有服務皆能以容器形式整合執行。

Gitea 內建的 Actions 架構能高度相容 GitHub Actions 的語法定義，開發者不需為了地端環境重新學習複雜的配置邏輯，也省去了另外架設與維護 Jenkins 伺服器的系統負擔。

Docker Compose 集中化部署

在 QNAP NAS 上可透過 SSH 終端機或 Container Station 的應用程式介面，使用 Docker Compose 同步啟動 Gitea 服務與 Actions Runner 執行器。

在啟動前，請先於 QNAP 檔案總管建立好對應的共用資料夾，例如 /share/Container/gitea，並在初次啟動 Gitea 後至管理後台取得 Runner 註冊權杖（Registration Token）。

YAML

version: ‘3.8’ services: gitea: image: gitea/gitea:latest container_name: gitea environment: – USER_UID=1000 – USER_GID=1000 – GITEA__database__DB_TYPE=sqlite3 – GITEA__packages__ENABLED=true – GITEA__actions__ENABLED=true restart: always volumes: – /share/Container/gitea/data:/data – /etc/timezone:/etc/timezone:ro – /etc/localtime:/etc/localtime:ro ports: – “3000:3000” – “2222:22” networks: – ci-net runner: image: gitea/act_runner:latest container_name: gitea-runner restart: always environment: – GITEA_INSTANCE_URL=http://gitea:3000 – GITEA_RUNNER_REGISTRATION_TOKEN=your_registration_token_here – GITEA_RUNNER_NAME=qnap-act-runner – GITEA_RUNNER_LABELS=ubuntu-latest:docker://catthehacker/ubuntu:act-latest volumes: – /var/run/docker.sock:/var/run/docker.sock – /share/Container/gitea/runner:/data networks: – ci-net depends_on: – gitea networks: ci-net: driver: bridge

自動化管線配置：測試、弱點掃描與發布

專案儲存庫建立後，在專案根目錄新增 .gitea/workflows/deploy.yaml 即可定義完整的自動化生命週期。這套流程涵蓋程式碼檢核、單元測試、Trivy 資安弱點掃描、建置 Docker 映像檔並推送至 Gitea Container Registry，最後觸發目標容器更新。

YAML

name: CI/CD Pipeline on: push: branches: – main jobs: pipeline: runs-on: ubuntu-latest steps: – name: 檢核原始碼 uses: actions/checkout@v4 – name: 執行單元測試 run: | npm ci npm test – name: 執行 Trivy 檔案系統資安弱點掃描 uses: aquasecurity/trivy-action@master with: scan-type: ‘fs’ ignore-unfixed: true format: ‘table’ severity: ‘CRITICAL,HIGH’ – name: 登入 Gitea 私有映像檔倉庫 uses: docker/login-action@v3 with: registry: gitea:3000 username: ${{ gitea.actor }} password: ${{ secrets.GITEA_TOKEN }} – name: 建置並推送容器映像檔 uses: docker/build-push-action@v5 with: context: . push: true tags: gitea:3000/${{ gitea.repository }}:latest – name: 執行地端生產環境更新 run: | docker pull gitea:3000/${{ gitea.repository }}:latest docker compose -f /data/deploy/docker-compose.yml up -d –force-recreate

資安防護機制與資料備份策略

CyberQ 建議，地端環境雖然隔絕了公有雲的外部暴露風險，但內部防護依然是維持系統穩定的核心重點。

將宿主機的 /var/run/docker.sock 直接掛載給 Runner 存在潛在的權限提升威脅。在嚴格管制的環境中，建議透過 docker-socket-proxy 設定存取白名單，僅允許容器建立、日誌讀取等必要 API，阻斷危險的特權呼叫。

網路設定方面，建議將 CI/CD 執行網路與 NAS 的管理介面（QTS / QuTS hero）進行隔離，避免測試流程中的不受信任程式碼存取核心儲存節點。

資料保存層面，建議結合 QNAP 原生的儲存池快照功能，針對 /share/Container 設定定時快照任務。搭配 Hybrid Backup Sync（HBS 3）套件，可將 Gitea 的 Git 倉庫資料、資料庫以及設定檔定期加密備份至外接硬碟、異地設備或冷儲存空間，確保地端開發平台兼具高效率與高可靠度。

推薦閱讀

Gitea 官方文件 以及 Gitea Actions 說明指南。

Gitea Container Registry 映像檔發布與驗證機制 Gitea Packages 文件。

容器弱點檢測與安全性掃描工具配置 Trivy 官方技術文件。

QNAP 容器化應用管理與儲存組態 QNAP Container Station 官方說明。