在 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 建構這個地端自動化環境由四個關鍵元件構成，所有服務皆能以容器形式整合執行。

元件名稱	系統角色	主要功能描述
QNAP Container Station	容器底層平台	提供 Docker 引擎環境與 Docker Compose 集中管理介面
Gitea	核心協作平台	提供輕量級 Git 儲存庫、專案權限管理與 Actions 排程控制
Gitea Actions Runner	自動化執行器	基於 act 引擎執行測試、靜態分析、安全掃描與映像檔建置任務
Gitea Container Registry	映像檔倉庫	內建支援 Docker 與 OCI 標準的私有容器映像檔儲存與版本控管

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 倉庫資料、資料庫以及設定檔定期加密備份至外接硬碟、異地設備或冷儲存空間，確保地端開發平台兼具高效率與高可靠度。