自訂容器映像檔

Cloud Workstations 提供的預先設定基本映像檔僅包含最低限度的環境，內含 IDE、基本 Linux 終端機、語言工具和 sshd 伺服器。如要加快特定開發用途的環境設定速度，您可以建立自訂容器映像檔，擴充這些基礎映像檔，預先安裝工具和依附元件，以及執行自動化指令碼。

如果是自訂容器映像檔，建議您設定管道，在 Cloud Workstations 基本映像檔更新時自動重新建構這些映像檔，並執行 Artifact Analysis 等容器掃描工具，檢查您新增的任何其他依附元件。您必須負責維護及更新新增至自訂映像檔的自訂套件和依附元件。

事前準備

1. 您需要一部機器，並安裝建構容器映像檔的工具 (例如 Docker)，以及使用 Google Cloud CLI 將映像檔推送至 Artifact Registry 的工具。您可以使用 Cloud Workstations 或 Cloud Shell 編輯器執行這些步驟，這些工具已預先安裝。

2. 從支援的基本映像檔清單中選取要使用的基本映像檔，例如 us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest。

   或者，您也可以按照使用自己的容器映像檔操作說明，使用自己的容器映像檔或外部容器映像檔。

3. 建立資料夾 (例如 CUSTOM_IMAGE_FOLDER)，並在這個資料夾中建立 Dockerfile，擴充所選的基本映像檔，如以下範例所示。

Cloud Workstations 基本映像檔結構

Cloud Workstations 基本映像檔共用下列定義結構：

• 基本映像檔進入點檔案設為 /google/scripts/entrypoint.sh。

• 啟動時，基礎映像檔會按照字典順序執行 /etc/workstation-startup.d/* 下的檔案，初始化工作站環境。

  檔案及其行為如下：

  • 000_configure-docker.sh：在工作站中設定及執行 Docker。

  • 010_add-user.sh：在 Cloud Workstations 中建立預設使用者。

    由於永久磁碟會動態附加至容器，因此必須在工作站啟動時新增使用者，而非在 Dockerfile 中新增。

  • 020_start-sshd.sh：在容器中啟動 sshd 服務。

  • 030_customize-environment.sh：以 user 身分執行 /home/user/.workstation/customize_environment。

  • 110_start-$IDE.sh：啟動映像檔的 IDE。

• Cloud Workstations 會將 Docker 映像檔儲存在主目錄 /home/.docker_data，以便在工作階段之間保留映像檔。

如要在工作站啟動期間新增其他功能，請在 /etc/workstation-startup.d/ 目錄中新增指令碼：

• 根據預設，這個目錄中的指令碼會以 root 身分執行。如要以其他使用者身分執行指令碼，請使用 runuser 指令。

• 由於指令碼會依字母順序執行，建議您在指令碼前面加上大於 200 的三位數。

或者，如果您不想擴充工作站映像檔，可以在主目錄中建立 customize_environment 指令碼。

主目錄修改

如果工作站設定指定永久主目錄 (預設行為)，系統會在執行階段，將支援主目錄的永久磁碟動態附加至容器。這項程序會覆寫建構容器映像檔時，對 /home 目錄所做的修改。

如要保留更新，請在容器執行階段修改 /home 目錄，方法是在 /etc/workstation-startup.d 目錄中新增指令碼，或在 /etc/profile.d 目錄中新增個別使用者的設定。如要加快程序，建議您將設定指令碼做為背景程序執行 (在指令結尾加上和號 &)，以免容器啟動作業遭到封鎖。

以下列舉一些應移至容器執行階段的建構階段設定：

• 每位使用者的git設定
• 已將 git 個存放區複製到主目錄
• 直接使用者設定，例如將檔案放在 $HOME/.config 目錄中
• 建立使用者

建立及修改使用者

由於永久磁碟會在執行階段動態附加至容器，因此必須在工作站啟動時新增使用者，而非在 Dockerfile 中新增。如要修改或建立其他使用者，建議您更新 /etc/workstation-startup.d/010_add-user.sh，或自行建立在啟動時執行的指令碼。

此外，您也可以更新 /etc/profile.d 中的檔案，修改使用者的預設 bash 設定檔。

更新預先設定的安全 APT 金鑰

Cloud Workstations 基本映像檔預先安裝了多項工具，這些工具是使用 Secure APT 從各種第三方存放區取得。在安裝過程中，系統會使用 gpg 匯入存放區擁有者提供的公開金鑰，並將其放入 /usr/share/keyrings/ 下的個別檔案中。這些檔案會從 /etc/apt/sources.list.d/ 下的對應 list 檔案參照。這樣一來，apt 就能在與特定存放區互動時，驗證存放區的完整性。

第三方存放區擁有者有時可能會決定變更用於驗證存放區完整性的公開金鑰，導致 apt 在與存放區互動時顯示錯誤。如要解決這個潛在問題，可以使用 /google/scripts/refresh-preinstalled-apt-keys.sh，取得最新版本的預先安裝公開金鑰，並重新匯入。

您也可以在 執行 apt-get update 之前，直接在自訂 Dockerfile 中執行這個指令碼：

# Refresh the preinstalled APT keys
RUN /google/scripts/refresh-preinstalled-apt-keys.sh

RUN apt-get update

列出已安裝的 IDE 版本

多個 Cloud Workstations 基本映像檔已預先安裝 IDE。為方便起見，請參閱隨附的 /google/scripts/preinstalled-ide-versions.sh 指令碼，其中列出映像檔中安裝的 IDE 名稱和版本資訊。

關閉 sudo 的超級使用者權限

預設工作站使用者在這些容器中擁有 sudo 根目錄存取權限。如要關閉 Docker 容器的根層級存取權，請在建立工作站設定時，將 CLOUD_WORKSTATIONS_CONFIG_DISABLE_SUDO 環境變數設為 true。

如要在建立工作站設定時，透過 Google Cloud 控制台設定這個環境變數，請按照下列步驟操作：

1. 建立工作站設定時，請完成「基本資訊」和「機器設定」的設定。
2. 在「Environment customization」(環境自訂) 對話方塊中，展開「Advanced container options」(進階容器選項) 部分，然後選取「Environment variables」(環境變數)。
3. 按一下「add 新增變數」。
4. 輸入 CLOUD_WORKSTATIONS_CONFIG_DISABLE_SUDO 和 true 做為值。

注意： 如果使用者能跳出 Docker 容器，就有可能取得基礎 VM 的根權限。

不擴充映像檔，直接自訂

為方便起見，所有 Cloud Workstations 基本映像檔都會檢查 /home/user/.workstation/customize_environment 是否有可執行的檔案，如果有的話，就會在背景以 user 的身分執行。這可讓您在啟動時執行任何指令碼或二進位檔。與 .profile 或 .bashrc 不同，指令碼只會在工作站啟動時執行一次，而不是每次殼層登入時執行一次。

由於 customize_environment 指令碼是以 user 身分執行，因此在編寫指令碼時，請務必視需要更新權限。舉例來說，如果您想在每次工作站啟動時安裝 Emacs，customize_environment 的內容可能類似下列內容：

#!/bin/bash
sudo apt-get update
sudo apt-get install -y emacs

customize_environment 的執行記錄檔位於容器中的 /var/log/customize_environment，也會寫入容器輸出記錄檔。成功執行 customize_environment 後，系統會在 /var/run/customize_environment_done 中建立檔案。由於 customize_environment 會與工作站啟動作業同時執行，因此工作站啟動後不久，指令碼安裝的套件就能使用。

防止閒置逾時

為方便起見，所有 Cloud Workstations 基礎映像檔都包含預先安裝的指令碼，位於 /google/scripts/keep_alive.sh。這個指令碼會定期傳送 keep-alive 訊息，防止工作站因閒置逾時而關閉，讓您在沒有直接互動的情況下執行背景程序。

使用 AI 代理防止閒置逾時

此外，Cloud Workstations 基本映像檔包含 /google/samples/agents/keepalive/ 下的範例代理程式設定指令碼。這些範例設定可讓您在工作站內設定 AI 程式設計代理 (例如 Claude Code 和 Antigravity CLI)，在工作站主動執行工作時，自動保持工作站運作。當代理完成工作或暫停等待使用者輸入時，指令碼會停止傳送連線維持訊息，讓工作站因閒置而逾時。如果工作站設定設為使用工作站暫停功能 (idleAction 設為 SUSPEND)，這些設定的效果最佳，可讓工作站儲存記憶體狀態，並在您返回時順暢恢復運作。

如要進一步瞭解如何設定代理輔助工作流程和 keep-alive 鉤子，請參閱「代理最佳化開發」。

使用自己的容器映像檔

您也可以使用自己的容器映像檔或外部容器映像檔，只要這些映像檔是以 Linux 為基礎，且在容器啟動時執行封鎖程序即可。

設定 Dockerfile 時，ENTRYPOINT 指令必須執行封鎖程序 (例如 sleep infinity)，讓容器繼續執行，而不是立即結束。或者，您也可以在工作站設定中設定 config.container.args 欄位，指定封鎖程序。

使用自己的容器映像檔時，請注意下列事項：

• Cloud Workstations 不需要 Cloud Workstations 基礎映像檔中的其他指令碼。

  不過，您可以在執行 Cloud Workstations 基礎映像檔的容器中，查看 /etc/workstation-startup.d/ 目錄中的指令碼。檔案名稱會指出各指令碼的作用。

• 建議您在容器中執行 SSH 伺服器。請參閱預設基礎映像檔中的 /etc/workstation-startup.d/020_start-sshd.sh，瞭解 Cloud Workstations 預設如何設定。

• 建議您在通訊埠 80 執行預設 IDE 或網路伺服器。

Google Cloud 提供標準基礎映像檔，可用於建構完全自訂的容器映像檔。

擴充 Cloud Workstations 基礎映像檔

擴充 Cloud Workstations 基本映像檔，為工作站環境建立自訂映像檔時，可以採取下列三種做法：

1. 更新 Dockerfile，加入要新增的其他靜態資產。
2. 在 /etc/workstation-startup.d/ 下方新增其他可執行的檔案，即可自訂執行中的容器。容器啟動時，這個目錄下的檔案會自動按照字典順序執行，因此您可以在檔案名稱加上前置字元，在工作站啟動時適時執行。
3. 覆寫 Dockerfile 中的 ENTRYPOINT，即可完全自訂容器啟動作業。

注意： 任何使用者修改作業都必須在容器執行階段完成，而非在 Dockerfile 中。這是因為 /home 會在啟動時動態掛接至容器。

自訂 Dockerfile 範例

本節提供範例情境和操作說明，協助您建立自己的 Dockerfile。

預先安裝 emacs 的容器映像檔

如要建立預先安裝 emacs 的容器映像檔，請執行下列指令：

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest

RUN sudo apt update
RUN sudo apt install -y emacs

使用者自訂的容器映像檔

如要自訂容器映像檔，請按照下列步驟操作：

1. 在 /etc/workstation-startup.d/* 中建立指令碼，並在 010_add-user.sh 之後執行，例如 011_customize-user.sh：

   #!/bin/bash
   # Create new group
   groupadd $GROUP
   # Add the user to a new group
   usermod -a -G $GROUP $USERNAME
   

   將 $GROUP 替換為新群組名稱，並將 $USERNAME 替換為使用者的使用者名稱。

2. 假設您將指令碼命名為 011_customize-user.sh，請在 Dockerfile 中將下列內容新增至映像檔，並設為可執行：

   FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest
   
   COPY 011_customize-user.sh /etc/workstation-startup.d/
   
   RUN chmod +x /etc/workstation-startup.d/011_customize-user.sh
   

在 SSH 工作階段中設定容器環境變數的容器映像檔

在工作站設定或工作站層級設定的環境變數，會透過進入點指令傳遞至直接子程序。包括預先設定的基本映像檔中的 IDE。不過，SSH 工作階段並非進入點的子程序，因此不會設定這些自訂環境變數。

如要在 SSH 工作階段中設定這些環境變數，請設定自訂容器映像檔，將這些環境變數從容器的進入點指令轉送至 /etc/environment 檔案。

步驟如下：

1. 在 /etc/workstation-startup.d/* 中建立指令碼，並在 010_add-user.sh 之後執行，例如 011_add-ssh-env-variables.sh：

   #!/bin/bash
   #
   echo "CUSTOM_ENV_VAR=$CUSTOM_ENV_VAR" >> /etc/environment
   

   將 CUSTOM_ENV_VAR 替換為預期的環境變數名稱。

2. 假設您將指令碼命名為 011_add-ssh-env-variables.sh，請在 Dockerfile 中將下列內容新增至映像檔，並設為可執行：

   FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest
   
   COPY 011_add-ssh-env-variables.sh /etc/workstation-startup.d/
   
   RUN chmod +x /etc/workstation-startup.d/011_add-ssh-env-variables.sh
   

為 SSH 工作階段啟用 X11 轉送功能的容器映像檔

X11 轉送功能可讓您啟動遠端應用程式，並將應用程式顯示畫面轉送至本機電腦。

如要建立可啟用 X11 轉送功能的容器映像檔，請修改 Cloud Workstations 基本映像檔提供的 OpenSSH daemon 設定檔 (/etc/ssh/sshd_config)，方法是附加 X11Forwarding yes (允許 X11 轉送) 和 AddressFamily inet (確保僅使用 IPv4)。如要進一步瞭解這些關鍵字，請參閱 OpenBSD 網頁中有關 AddressFamily 和 X11Forwarding 的說明。

以下是 Dockerfile 範例，其中包含必要修改：

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest

# Permit X11 forwarding using only IPv4
RUN cat >> /etc/ssh/sshd_config <<-EOF

AddressFamily inet
X11Forwarding yes
EOF

將 Code OSS for Cloud Workstations 複製到其他容器映像檔

多級式建構可讓您在 Dockerfile 中使用多個 FROM 陳述式。每個 FROM 指令都能使用不同的基礎，並可在建構階段之間複製構件。如要將 Code OSS for Cloud Workstations 新增至其他容器映像檔，請使用多級式建構，將應用程式資料夾 /opt/code-oss 複製到映像檔。如要在容器啟動時啟動 Code OSS for Cloud Workstations，請一併將指令碼 /etc/workstation-startup.d/110_start-code-oss.sh 複製到容器中。

以下是 Dockerfile 範例，可將 Code OSS 複製到 JetBrains IntelliJ Ultimate 映像檔。接著，您可以與任一 IDE 互動：

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest as code-oss-image

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/jetbrains-intellij:latest

# Copy Code OSS for Cloud Workstations and startup scripts into our custom image
COPY --from=code-oss-image /opt/code-oss /opt/code-oss
COPY --from=code-oss-image /etc/workstation-startup.d/110_start-code-oss.sh /etc/workstation-startup.d/110_start-code-oss.sh

# Use the existing entrypoint script which will execute all scripts in /etc/workstation-startup.d/
ENTRYPOINT ["/google/scripts/entrypoint.sh"]

容器映像檔，在 Code OSS for Cloud Workstations 中預先安裝 IDE 擴充功能，用於 Java 開發

如要建立容器映像檔，在建構時預先安裝 Code OSS for Cloud Workstations 的 IDE 擴充功能，以便開發 Java，請執行下列指令：

FROM us-central1-docker.pkg.dev/cloud-workstations-images/predefined/code-oss:latest

RUN wget https://open-vsx.org/api/vscjava/vscode-java-debug/0.40.1/file/vscjava.vscode-java-debug-0.40.1.vsix && \
unzip vscjava.vscode-java-debug-0.40.1.vsix "extension/*" &&\
mv extension /opt/code-oss/extensions/java-debug

RUN wget https://open-vsx.org/api/vscjava/vscode-java-dependency/0.19.1/file/vscjava.vscode-java-dependency-0.19.1.vsix && \
unzip vscjava.vscode-java-dependency-0.19.1.vsix "extension/*" &&\
mv extension /opt/code-oss/extensions/java-dependency

RUN wget https://open-vsx.org/api/redhat/java/1.6.0/file/redhat.java-1.6.0.vsix && \
unzip redhat.java-1.6.0.vsix "extension/*" &&\
mv extension /opt/code-oss/extensions/redhat-java

RUN wget https://open-vsx.org/api/vscjava/vscode-maven/0.35.2/file/vscjava.vscode-maven-0.35.2.vsix && \
unzip vscjava.vscode-maven-0.35.2.vsix "extension/*" &&\
mv extension /opt/code-oss/extensions/java-maven

RUN wget https://open-vsx.org/api/vscjava/vscode-java-test/0.35.0/file/vscjava.vscode-java-test-0.35.0.vsix && \
unzip vscjava.vscode-java-test-0.35.0.vsix "extension/*" &&\
mv extension /opt/code-oss/extensions/java-test

RUN chmod a+rwx -R /opt/code-oss/extensions/

如果您預先安裝擴充功能，系統會將其視為內建擴充功能。 您將無法更新這些擴充功能，而且這些擴充功能可能不會顯示在 Extensions Marketplace 的已安裝區段中。不過，您可以搜尋 @builtin 來找出內建擴充功能。

在啟動時安裝擴充功能的另一種方法是執行開機指令碼。例如，在 /etc/workstation-startup.d/120_install_extensions.sh 下加入下列開機指令碼：

sudo -u user /opt/code-oss/bin/codeoss-cloudworkstations --install-extension vscjava.vscode-java-debug@0.40.1 \
--install-extension vscjava.vscode-java-dependency@0.19.1  \
--install-extension redhat.java@1.6.0 \
--install-extension vscjava.vscode-maven@0.35.2 \
--install-extension vscjava.vscode-java-test@0.35.0

使用這個方法時，擴充功能會顯示在 Extensions Marketplace，您可以在該處更新。

注意： 您也可以在建構時預先下載 VSIX 檔案，並在執行階段使用這些檔案，進一步提升保護效果和啟動效能。

在基礎映像檔中安裝 JetBrains IDE 和外掛程式

為工作站設定自訂 Docker 映像檔時，您可以將 JetBrains IDE 和外掛程式 (例如 Cloud Code for IntelliJ) 安裝到基礎映像檔中。JetBrains 產品的 Cloud Workstations 基礎映像檔包含下列指令碼，可協助您：

• jetbrains-installer.sh：安裝 JetBrains IDE
• plugin-installer.sh：安裝外掛程式，例如 Cloud Code for IntelliJ

您可以視需要使用這些指令碼來自訂基本映像檔、透過開機指令碼呼叫這些指令碼，或是在啟動工作站後執行這些指令碼。

安裝程式指令碼

如要查看 jetbrains-installer.sh 和 plugin-installer.sh 指令碼的來源檔案，請使用採用 JetBrains 預先定義映像檔的工作站設定啟動工作站，透過 JetBrains Gateway 或 SSH 連線至工作站，然後瀏覽根目錄中 installer-scripts 目錄的指令碼檔案。

建議您在建構容器時執行這些指令碼。請勿在已啟動的工作站中執行這些指令。

使用外掛程式安裝指令碼

plugin-installer.sh 指令碼使用下列語法：

plugin-installer.sh [-v VERSION] [-d DESTINATION-DIRECTORY] [-c CHECKSUM] [-f] PLUGIN_ID

更改下列內容：

• VERSION：要安裝的外掛程式版本號碼 (選用)。
• DESTINATION-DIRECTORY：選用目錄，外掛程式應安裝至此。如未指定，則會使用目前使用的目錄。
• CHECKSUM：所要求外掛程式的 SHA-256 核對和 (選用)。
• -f：如果指定，系統會覆寫任何現有外掛程式。
• PLUGIN_ID：JetBrains Marketplace 的必要數值外掛程式 ID。舉例來說，如要新增 Dart，請使用 6351 做為 PLUGIN_ID。如要新增 Cloud Code for IntelliJ，請使用 8079 做為 PLUGIN_ID。

舉例來說，如要在 IntelliJ 中安裝最新版本的 Dart 外掛程式，請執行下列指令：

/installer-scripts/plugin-installer.sh -d /opt/ideaIU/plugins/ 6351

使用 JetBrains 安裝程式指令碼

擴充 JetBrains IDE 的預先設定基本映像檔時，建議使用 JetBrains 安裝程式指令碼。

jetbrains-installer.sh 指令碼使用下列語法：

jetbrains-installer.sh IDE [ pinned|latest ]

更改下列內容：

• IDE：要安裝的 JetBrains IDE。您必須使用下列其中一個 IDE 縮寫：

  IDE	已安裝產品
  cl	CLion
  clion	CLion
  go	GoLand
  goland	GoLand
  iiu	Intellij Ultimate
  intellij	Intellij Ultimate
  pcp	PyCharm Professional
  pycharm	PyCharm Professional
  ps	PHPStorm
  phpstorm	PHPStorm
  rd	Rider
  rider	Rider
  rm	RubyMine
  rubymine	RubyMine
  ws	WebStorm
  webstorm	WebStorm

• pinned|latest：選用 - 使用固定或最新版本的 IDE。預設值為 latest。

舉例來說，如要安裝最新版本的 Clion，請執行下列指令：

/installer-scripts/jetbrains-installer.sh clion

自訂 JetBrains IDE 設定檔

如果在工作站設定中指定永久主目錄，採用 JetBrains IDE 的 Cloud Workstations 基本映像檔會自動保留 $IDE.vmoptions 和 $IDE.properties 設定檔。如要覆寫這些檔案的預設位置，請指定 CLOUD_WORKSTATIONS_JETBRAINS_PERISTED_CONFIG_DIR 環境變數。

詳情請參閱任何 JetBrains 基本映像檔中的 /etc/workstation-startup.d/120_persist-jetbrains-configs.sh，瞭解 Cloud Workstations 預設如何設定。

使用 Cloud Code for IntelliJ 擴充基本 Docker 映像檔

下列 Dockerfile 程式碼片段會加入 8079 做為必要的 Plugin ID，使用 Cloud Code for IntelliJ 擴充基本 Docker 映像檔。這個範例也會視需要指定 version 22.9.3-222 做為版本號碼、/opt/ideaIU/plugins/ 做為目的地目錄，以及 89628279ed9042c526a81facc09bf53f8fb8b83b4595b0d329d94c1611e0c379 做為核對和：

...
# Install IDE and Plugins
RUN bash /installer-scripts/jetbrains-installer.sh intellij pinned && \
  # Install Cloud Code - https://plugins.jetbrains.com/plugin/8079-cloud-code
  bash /installer-scripts/plugin-installer.sh \
      -v 22.9.3-222 \
      -d /opt/ideaIU/plugins/ \
      -c 89628279ed9042c526a81facc09bf53f8fb8b83b4595b0d329d94c1611e0c379 \
      8079

# Register IDE with JetBrains Gateway
RUN echo 'runuser user -c "/opt/ideaIU/bin/remote-dev-server.sh registerBackendLocationForGateway"' > /etc/workstation-startup.d/110_register-intellij-with-gateway.sh \
    echo 'echo "IntelliJ-Ultimate ready for incoming gateway connection"' >> /etc/workstation-startup.d/110_register-intellij-with-gateway.sh
...

在 Code OSS for Cloud Workstations 安裝其他 IDE 擴充功能

如需其他 IDE 擴充功能，請前往 Open VSX Registry。您也可以複製任何擴充功能的「Download」(下載) 連結網址，找出 .vsix 檔案的網址。

如果從工作站開啟 Extensions Marketplace，系統會顯示「Install」(安裝)，而非「Download」(下載)。

Cloud Workstations 的預設 Code OSS 設定

如要進一步瞭解 Cloud Workstations 專用 Code OSS 的設定儲存空間，請參閱「自訂設定」。

如果您在工作站設定中指定永久主目錄，可以新增開機指令碼，將設定寫入 $HOME/.codeoss-cloudworkstations/data/Machine/settings.json，藉此設定 Code OSS for Cloud Workstations 的預設設定。

舉例來說，如要將預設色彩主題設為深色，請擴充基本編輯器映像檔，在 /etc/workstation-startup.d/150_default-ide-color-theme.sh 下方加入下列指令碼

cat <<< $(jq '. += {"workbench.colorTheme": "Default Dark Modern"}' settings.json) > settings.json

建構自訂容器映像檔

如要進一步瞭解 Docker 指令，請參閱 Docker 參考資料。輸入下列指令，建構容器：

docker build CUSTOM_IMAGE_FOLDER -t TARGET_IMAGE

請注意，如果取代「編輯」圖示前面的文字，本頁其他範例也會更新。

更改下列內容：

• CUSTOM_IMAGE_FOLDER：您建立用來儲存自訂映像檔的資料夾路徑。

• TARGET_IMAGE：Artifact Registry 中的映像檔路徑。

  舉例來說，TARGET_IMAGE 可能會指向與下列路徑類似的目標映像檔路徑：

  *.pkg.dev/cloud-workstations-external/customimage:latest
  

  視需要將 * 替換為區域名稱和任何其他 ID。

您也可以更新 CLOUD_WORKSTATIONS_CUSTOM_IMAGE 環境變數，指向存放區。

如要進一步瞭解如何在 Artifact Registry 中儲存 Docker 映像檔，請參閱下列各節：

• 如何使用 Artifact Registry 建立 Docker 存放區。
• 存放區和映像檔名稱的命名慣例。

託管自訂容器映像檔

如要託管自訂容器映像檔，建議使用 Artifact Registry，我們也支援這項服務。如果您使用 GitHub 或任何其他公開或私人存放區，Cloud Workstations 可能無法正常運作。詳情請參閱「使用自訂容器映像檔」一節中的重要注意事項。

測試自訂容器映像檔

容器建構完成後，您可以使用下列指令進行測試：

docker run --privileged -p LOCAL_PORT:CONTAINER_PORT TARGET_IMAGE

更改下列內容：

• LOCAL_PORT：本機通訊埠編號
• CONTAINER_PORT：容器通訊埠編號

舉例來說，將 LOCAL_PORT:CONTAINER_PORT 替換為 8080:80，會指派通訊埠 8080 供本機使用，並指派通訊埠 80 供容器使用。

如要擴充 Cloud Workstations 基本編輯器映像檔，請執行 docker 指令，然後透過本機瀏覽器連線至工作站 ，或執行 ssh 連線至容器，測試工作站映像檔：

• 如果透過瀏覽器連線，請務必將 -p 8080:80 傳遞至 docker run 指令，然後開啟 localhost:8080。
• 如要透過 SSH 連線，請務必將 -p 2222:22 傳遞至 docker run 指令，然後執行 ssh user@localhost -p 2222。

使用自訂容器映像檔

在本機建構及測試自訂容器映像檔後，如要使用該映像檔，請執行下列指令，將容器推送至 Artifact Registry：

docker push TARGET_IMAGE

現在，您可以使用剛建立並推送的容器映像檔，建立工作站設定。

重要事項： 如果映像檔託管於私人存放區，請務必在工作站設定中指定服務帳戶，且該帳戶須具備存放區的提取權限。

詳情請參閱「使用 Artifact Registry 建立 Docker 存放區」。

偵錯

如要找出並偵錯執行容器映像檔時發生的問題，請查看執行中工作站的容器輸出記錄。

建議：協助保護映像檔管道

您必須負責維護及更新自訂映像檔中新增的自訂套件和依附元件。

建立自訂映像檔時，建議您採取下列做法：

• 執行容器掃描工具 (例如 Artifact Analysis)，檢查您新增的其他依附元件。
• 排定建構作業，每週重新建構映像檔，或瞭解如何自動重新建構容器映像檔。

後續步驟

• 自動重新建構容器映像檔，使用 Cloud Build 和 Cloud Scheduler 同步處理基礎映像檔更新。
• 設定安全性最佳做法。
• 進一步瞭解 Artifact Analysis。