.gitea/workflows/cd.yaml

@@ -1,35 +1,81 @@
+# =============================================================================
+# 用途：這是 Gitea Actions 的 CD（持續部署）workflow。
+#       當有 commit push 到 master 分支時觸發，流程分兩個 job 依序執行：
+#       1. release-tag-version：釋出並標註成品版本，取得版本號。
+#       2. docker-build-push：依上一步取得的版本號 docker build 映像檔，
+#          並 push 到倉庫；倉庫主機由 vars.SERVER_DOMAIN 提供，
+#          登入帳密由 secrets.USERNAME / secrets.PASSWORD 提供。
+# 更新日期：2026/06/30 12:24:01
+# =============================================================================
+
+# 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
-    env:
+    # 此 job 的執行步驟清單
-      SERVER: gitea.jsc.idv.tw
-      USERNAME: jiantw83
-      PASSWORD: ${{ secrets.TOKEN }}
     steps:
+    # 步驟：取出原始碼到 runner 工作目錄，後續 docker build 需要 Dockerfile 等檔案
     - name: 取得存取庫
+      # 使用官方 checkout action；版本以變數 vars.ACTION_CHECKOUT_VERSION 釘選
       uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
+    # 步驟：登入 Docker 倉庫，取得推送映像檔的權限
     - name: 登入倉庫
-      run: echo $PASSWORD |  docker login $SERVER -u $USERNAME --password-stdin
+      # 登入指令直接以表達式注入認證資訊：
+      # secrets.PASSWORD 為倉庫密碼、vars.SERVER_DOMAIN 為倉庫主機位址、
+      # secrets.USERNAME 為登入帳號；
+      # 密碼透過管線餵給 docker login 的 --password-stdin，
+      # 避免密碼出現在指令參數中而被記錄於 log
+      run: echo ${{ secrets.PASSWORD }} |  docker login ${{ vars.SERVER_DOMAIN }} -u ${{ secrets.USERNAME }} --password-stdin
+      # 指定以 bash 執行此指令
       shell: bash
+    # 步驟：建置 Docker 映像檔
     - name: 建置映像檔
-      run: docker build -t $SERVER/${{ gitea.repository }}:${{ needs.release-tag-version.outputs.version }} .
+      # image 名稱由 vars.SERVER_DOMAIN（倉庫主機）與 gitea.repository（倉庫名稱）組成、
+      # 以 needs.release-tag-version.outputs.version（上一個 job 產生的版本號）為 tag，
+      # 對當前目錄（.）的 Dockerfile 進行 build
+      run: docker build -t ${{ vars.SERVER_DOMAIN }}/${{ gitea.repository }}:${{ needs.release-tag-version.outputs.version }} .
+      # 指定以 bash 執行此指令
       shell: bash
+    # 步驟：將建置完成的映像檔推送到倉庫
     - name: 推送映像檔
-      run: docker push $SERVER/${{ gitea.repository }}:${{ needs.release-tag-version.outputs.version }}
+      # push 與上一步相同名稱與 tag 的映像檔到 vars.SERVER_DOMAIN 指定的倉庫主機
+      run: docker push ${{ vars.SERVER_DOMAIN }}/${{ gitea.repository }}:${{ needs.release-tag-version.outputs.version }}
+      # 指定以 bash 執行此指令
       shell: bash

Dockerfile

@@ -1,15 +1,65 @@
-FROM ubuntu:latest
+# =============================================================================
+# 用途：本 Dockerfile 採「多階段建置（multi-stage build）」產出 codex CLI 映像。
+#       build 階段使用 node-slim 基底，透過 npm 全域安裝 @openai/codex CLI 套件；
+#       runtime 階段同樣改用較小的 node-slim 基底，只帶入 build 階段安裝好的 codex
+#       套件與其相依，並額外安裝 ca-certificates 以支援 HTTPS 連線，
+#       最終映像預設執行 `codex --version`。
+# 更新日期：2026/06/30 12:23:42
+# =============================================================================
 
+# syntax 指示詞：指定使用 dockerfile:1 前端語法，啟用 BuildKit 進階功能（必須置於檔首第一行有效指令）
+# syntax=docker/dockerfile:1
+
+# 1. 參數處理：可調參數集中於檔首，以 ARG 注入
+# ARG NODE_VERSION：node 基底映像的版本號，預設 22，可於 build 時以 --build-arg 覆寫
+ARG NODE_VERSION=22
+# ARG BUILD_IMAGE：build 階段的基底映像，預設為 node:<版本>-slim（slim 版較精簡）
+ARG BUILD_IMAGE=node:${NODE_VERSION}-slim
+# ARG RUNTIME_IMAGE：runtime 階段的基底映像，預設同樣為 node:<版本>-slim
+ARG RUNTIME_IMAGE=node:${NODE_VERSION}-slim
+# ARG CODEX_PACKAGE：要全域安裝的 npm 套件名稱，預設 @openai/codex（codex CLI）
+ARG CODEX_PACKAGE=@openai/codex
+
+# ---- build 階段：安裝 codex CLI 套件 ----
+# FROM ... AS build：以 BUILD_IMAGE 為基底開啟名為 build 的第一個建置階段（供後續 COPY --from 取用產物）
+FROM ${BUILD_IMAGE} AS build
+
+# 2. 安裝套件：以 npm 全域安裝 codex CLI（無本地相依描述檔，故無 manifest 先行 COPY 的 layer 快取最佳化空間）
+#    官方 node image 的全域安裝前綴為 /usr/local，套件與其相依落於 /usr/local/lib/node_modules，bin symlink 落於 /usr/local/bin
+# ARG CODEX_PACKAGE：在 build 階段內重新宣告 ARG，使檔首定義的值可在此階段被引用（ARG 作用域以 FROM 為界，跨階段需重新宣告）
+ARG CODEX_PACKAGE
+# RUN npm install -g：全域安裝指定的 codex 套件；接著 npm cache clean --force 清除 npm 快取，
+#     避免快取檔殘留於此層（雖然 build 階段產物不會整層帶入 runtime，仍維持乾淨並縮小該層）
+RUN npm install -g "${CODEX_PACKAGE}" \
+    && npm cache clean --force
+
+# 3. 複製檔案：本映像為純 CLI 工具安裝，無專案原始碼需複製（略）
+# 4. 執行程序：codex 為預編譯 npm 套件，無 build / compile / transpile 步驟（略）
+
+# ---- 5. 縮小映像檔：runtime 改用較小的 node-slim 基底，只帶執行所需產物 ----
+# FROM ... AS runtime：以 RUNTIME_IMAGE 為基底開啟名為 runtime 的最終階段；
+#     此階段為最終輸出映像，不含 build 階段的 npm 快取等中間產物，藉此縮小映像體積
+FROM ${RUNTIME_IMAGE} AS runtime
+
+# 保留原檔的 ENV 契約：DEBIAN_FRONTEND=noninteractive（並使下方 apt 安裝為非互動）
+# ENV DEBIAN_FRONTEND=noninteractive：設定 Debian 套件管理為非互動模式，避免 apt 安裝時跳出互動提示而卡住建置
 ENV DEBIAN_FRONTEND=noninteractive
 
-RUN apt update \
+# 保留原檔行為：安裝 ca-certificates 供 codex 進行 HTTPS 連線，安裝後清理 apt 快取縮小該層
-    && apt install -y --no-install-recommends \
+# RUN apt-get：更新套件索引後，以 --no-install-recommends 僅安裝 ca-certificates（不裝建議套件，減少體積）；
+#     安裝完成後 apt-get clean 並刪除 /var/lib/apt/lists/* 套件索引快取，將清理與安裝合併於同一層以縮小該層
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
         ca-certificates \
-        nodejs \
+    && apt-get clean \
-        npm \
-    && npm install -g @openai/codex \
-    && apt clean \
     && rm -rf /var/lib/apt/lists/*
 
-CMD ["codex", "--version"]
+# 只帶入執行所需產物：全域安裝的 codex 套件（含其相依）與 bin symlink
+# COPY --from=build node_modules：自 build 階段複製全域套件目錄（codex 套件本體與其所有相依）
+COPY --from=build /usr/local/lib/node_modules /usr/local/lib/node_modules
+# COPY --from=build codex：自 build 階段複製 codex 的可執行檔（bin symlink），使其可於 PATH 中直接呼叫
+COPY --from=build /usr/local/bin/codex /usr/local/bin/codex
 
+# 6. 設定入口：CMD 置於最後，語意與原檔一致
+# CMD：容器啟動時的預設執行指令，預設執行 `codex --version` 顯示版本（exec form，不經 shell）；可於 docker run 時覆寫
+CMD ["codex", "--version"]

README.md

@@ -0,0 +1,90 @@
+# codex
+
+> 更新時間（Asia/Taipei）：2026/06/30 12:29:20
+
+以多階段建置（multi-stage build）打包 [@openai/codex](https://www.npmjs.com/package/@openai/codex) CLI 的 Docker 映像檔專案。build 階段於 `node:<版本>-slim` 透過 npm 全域安裝 codex CLI，runtime 階段改用同樣精簡的 `node-slim` 基底，只帶入 codex 套件與其相依，並額外安裝 `ca-certificates` 以支援 HTTPS 連線，最終映像預設執行 `codex --version`。搭配 `.gitea/workflows/cd.yaml`，當 push 到 `master` 分支時，會自動釋出版本號、建置映像檔並推送到 Gitea 倉庫。
+
+## 專案列表
+
+### 專案描述
+
+| 專案名稱 | 專案描述 |
+| --- | --- |
+| [codex](https://gitea.jsc.idv.tw/images/codex/src/branch/develop) | 以多階段建置打包 @openai/codex CLI 的 Docker 映像檔專案，提供 `Dockerfile` 與 Gitea Actions CD 流程；此專案未公開可列入 README 的功能。 |
+
+### 參考專案
+
+| 專案名稱 | 參考專案列表 |
+| --- | --- |
+| [codex](https://gitea.jsc.idv.tw/images/codex/src/branch/develop) | 無 |
+
+### NuGet 套件
+
+| 專案名稱 | NuGet 套件列表 |
+| --- | --- |
+| [codex](https://gitea.jsc.idv.tw/images/codex/src/branch/develop) | 無 |
+
+## 功能列表
+
+本專案為 Docker 映像檔建置專案，未公開可列入 README 的程式方法（public method／constructor／extension method／operator）。實際交付內容為下列容器映像檔的建置與發佈設定，使用方式詳見「使用範例」。
+
+## 使用範例
+
+### 建置映像檔
+
+於專案根目錄（含 `Dockerfile`）執行：
+
+```bash
+docker build -t codex .
+```
+
+- 預設使用 `node:22-slim` 作為 build 與 runtime 基底，並全域安裝 `@openai/codex`。
+- 建議啟用 BuildKit（檔首已宣告 `# syntax=docker/dockerfile:1`）：`DOCKER_BUILDKIT=1 docker build -t codex .`。
+
+### 執行容器
+
+```bash
+# 顯示 codex 版本（映像檔預設 CMD）
+docker run --rm codex
+
+# 覆寫預設指令，改執行其他 codex 子指令
+docker run --rm codex codex --help
+```
+
+### 以 build 參數覆寫預設值
+
+`Dockerfile` 將可調參數集中於檔首 `ARG`，可於建置時覆寫：
+
+```bash
+# 指定 node 版本
+docker build --build-arg NODE_VERSION=20 -t codex:node20 .
+
+# 指定要安裝的 npm 套件（預設 @openai/codex）
+docker build --build-arg CODEX_PACKAGE=@openai/codex@latest -t codex:latest .
+```
+
+| 參數 | 預設值 | 說明 |
+| --- | --- | --- |
+| `NODE_VERSION` | `22` | node 基底映像版本（同時套用於 build 與 runtime 階段） |
+| `BUILD_IMAGE` | `node:${NODE_VERSION}-slim` | build 階段基底映像 |
+| `RUNTIME_IMAGE` | `node:${NODE_VERSION}-slim` | runtime 階段基底映像 |
+| `CODEX_PACKAGE` | `@openai/codex` | 要全域安裝的 npm 套件名稱 |
+
+### CI/CD 自動發佈（Gitea Actions）
+
+`.gitea/workflows/cd.yaml` 定義 CD 流程：當 push 到 `master` 分支時觸發，依序執行兩個 job：
+
+1. **Release Tag Version**：以共用 composite action 釋出並標註成品版本，輸出 `version`。
+2. **Docker Build & Push**：checkout 原始碼 → 登入倉庫 → 建置並推送映像檔。
+
+其中倉庫主機與登入認證皆由 Gitea 的 Actions 變數／密鑰提供：
+
+| 設定來源 | 用途 |
+| --- | --- |
+| `vars.SERVER_DOMAIN` | 倉庫主機位址（image 名稱前綴、`docker login` 目標） |
+| `secrets.USERNAME` | 登入倉庫的帳號 |
+| `secrets.PASSWORD` | 登入倉庫的密碼／權杖（以 `--password-stdin` 餵入，避免出現在指令參數） |
+| `vars.ACTION_RELEASE_TAG_VERSION` | 釘選 release-tag-version composite action 版本 |
+| `vars.ACTION_CHECKOUT_VERSION` | 釘選 checkout action 版本 |
+
+> 映像檔最終標籤格式為 `${vars.SERVER_DOMAIN}/${gitea.repository}:${version}`，其中 `version` 來自 Release Tag Version job 的輸出。