docs(README 與 CD workflow): 重建 README 並為 cd.yaml 補逐行註解

.gitea/workflows/cd.yaml

@@ -1,35 +1,83 @@
+# =============================================================================
+# 用途：這是 Gitea Actions 的 CD（持續部署）workflow。
+#       當有 commit push 到 master 分支時觸發，流程分兩個 job 依序執行：
+#       1. release-tag-version：釋出並標註成品版本，取得版本號。
+#       2. docker-build-push：依上一步取得的版本號 docker build 映像檔，
+#          並 push 到 gitea.jsc.idv.tw 倉庫。
+# 更新日期：2026/06/30 12:00:23
+# =============================================================================
+
+# workflow 名稱，會顯示在 Gitea Actions 介面上，方便辨識此流程
 name: CD
+# 觸發條件區塊，定義哪些事件會啟動此 workflow
 on:
+  # 監聽 push 事件（有提交被推送到倉庫時）
   push:
+    # 限定只有 push 到下列分支時才觸發，避免其他分支誤觸發部署
     branches:
+    # 僅針對 master 分支（正式主線）觸發 CD
     - master
+# 工作（job）區塊，定義此 workflow 包含的所有 job
 jobs:
+  # 第一個 job：負責釋出並標註成品版本，產出版本號供後續 job 使用
   release-tag-version:
+    # job 的顯示名稱，呈現在 Actions 介面
     name: Release Tag Version
+    # 指定執行此 job 的 runner 標籤（自架的 ubuntu runner）
     runs-on: ubuntu
+    # 定義此 job 對外輸出的值，供其他 job 透過 needs 引用
     outputs:
+      # 將下方 id 為 release-tag-version 的 step 所輸出的 version
+      # 暴露為此 job 的 version 輸出，後續 docker-build-push 會用到
       version: ${{ steps.release-tag-version.outputs.version }}
+    # 此 job 的執行步驟清單
     steps:
+    # 步驟：執行外部 composite action 來釋出並標註成品版本
     - name: 釋出並標註成品版本
+      # 設定 step 的 id，讓 outputs 能以 steps.release-tag-version 引用其輸出
       id: release-tag-version
+      # 使用 Gitea 上的共用 composite action 取得版本號；
+      # 版本以變數 vars.ACTION_RELEASE_TAG_VERSION 釘選，便於統一管理 action 版本
       uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }}
+  # 第二個 job：建置 Docker 映像檔並推送到倉庫
   docker-build-push:
+    # job 的顯示名稱
     name: Docker Build & Push
+    # 指定執行此 job 的 runner 標籤（自架的 ubuntu runner）
     runs-on: ubuntu
+    # 宣告此 job 相依於 release-tag-version；
+    # 確保版本號先產生完成才執行，並可透過 needs 取得其 outputs
     needs: release-tag-version
+    # 此 job 範圍內的環境變數，供下方 steps 的 run 指令使用
     env:
+      # 目標倉庫主機（Gitea container registry 位址）
       SERVER: gitea.jsc.idv.tw
+      # 登入倉庫所使用的帳號
       USERNAME: jiantw83
+      # 登入倉庫所使用的密碼／權杖，從 Gitea secrets 取得，避免明文外洩
       PASSWORD: ${{ secrets.TOKEN }}
+    # 此 job 的執行步驟清單
     steps:
+    # 步驟：取出原始碼到 runner 工作目錄，後續 docker build 需要 Dockerfile 等檔案
     - name: 取得存取庫
+      # 使用官方 checkout action；版本以變數 vars.ACTION_CHECKOUT_VERSION 釘選
       uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
+    # 步驟：登入 Docker 倉庫，取得推送映像檔的權限
     - name: 登入倉庫
+      # 將密碼透過管線餵給 docker login 的 --password-stdin，避免密碼出現在指令參數中
       run: echo $PASSWORD |  docker login $SERVER -u $USERNAME --password-stdin
+      # 指定以 bash 執行此指令
       shell: bash
+    # 步驟：建置 Docker 映像檔
     - name: 建置映像檔
+      # 以倉庫名稱（gitea.repository）為 image 名稱、上一個 job 產生的 version 為 tag，
+      # 對當前目錄（.）的 Dockerfile 進行 build
       run: docker build -t $SERVER/${{ gitea.repository }}:${{ needs.release-tag-version.outputs.version }} .
+      # 指定以 bash 執行此指令
       shell: bash
+    # 步驟：將建置完成的映像檔推送到倉庫
     - name: 推送映像檔
+      # push 與上一步相同名稱與 tag 的映像檔到 SERVER 指定的倉庫
       run: docker push $SERVER/${{ gitea.repository }}:${{ needs.release-tag-version.outputs.version }}
+      # 指定以 bash 執行此指令
       shell: bash