本文件提供逐步說明，協助您在 Google Distributed Cloud (GDC) 實體隔離環境中，部署 Open WebUI，這是一種自行託管、以瀏覽器為基礎的對話介面。Open WebUI 會透過 Ollama 和 OpenAI 相容 API，連線至使用 Ollama 和 vLLM 使用手冊部署的推論後端，因此開發人員和使用者不必編寫 API 呼叫，就能與開放權重模型互動。
架構
Open WebUI 會在標準叢集的專屬命名空間中，以單一副本 Deployment 的形式運作。其狀態 (使用者帳戶、即時通訊、設定) 儲存在 ReadWriteOnce PersistentVolumeClaim。ConfigMap 包含推論後端的連線設定，可透過叢集內 Service 名稱存取，而 Secret 則包含工作階段簽署金鑰。LoadBalancer 類型的 Kubernetes Service 會公開網頁介面，而 NetworkPolicy/ProjectNetworkPolicy 物件則會保護該介面的存取權。
事前準備
請確認您已按照使用 Ollama 部署 Gemma 模型的使用手冊、使用 vLLM 部署 Gemma 模型的使用手冊，或使用 vLLM 部署 Mistral 模型的使用手冊，部署至少一個推論後端，且您有權存取工作站上對應參考實作項目的 ${HOME}/gdcag-solutions 目錄。
Identity and Access Management
請確認已正確設定必要的 IAM 帳戶、角色和權限。
組織的 GDC 使用者角色：
- 選用：標準叢集管理員 (透過控制台查看叢集)
專案的 GDC 使用者角色：
- 標準叢集管理員 (
standard-cluster-admin)
標準叢集的 GDC 使用者角色：
StandardClusterRoleBinding至StandardClusterRolecluster-admin(由專案 IAM 管理員建立，請參閱參考實作的「Identity and Access Management」一節)
工作站
除非步驟另有說明，否則請在工作站執行本指南中的所有指令，並確保工作站具備必要工具，且可連線至環境和網際網路。
建立使用手冊目錄架構：
mkdir -p ${HOME}/gdcag-solutions/open-weight-models/open-webui/env.d mkdir -p ${HOME}/gdcag-solutions/open-weight-models/open-webui/secrets chmod u=rwx,go= ${HOME}/gdcag-solutions/open-weight-models/open-webui/secrets建立工作階段簽署金鑰：
openssl rand -hex 32 > ${HOME}/gdcag-solutions/open-weight-models/open-webui/secrets/open_webui_secret_key chmod u=rw,go= ${HOME}/gdcag-solutions/open-weight-models/open-webui/secrets/open_webui_secret_key建立使用手冊環境設定檔：
cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/open-webui/env.d/open-webui.sh && echo "Successfully created." || echo "Failed to create!" # Open WebUI export GDCS_OPEN_WEBUI_IMAGE_TAG="v0.11.3" export GDCS_OPEN_WEBUI_NAME="open-webui" export GDCS_OPEN_WEBUI_PVC_SIZE="20Gi" export GDCS_OPEN_WEBUI_SECRET_KEY="$(cat ${GDCS_USER_GUIDE_HOME}/secrets/open_webui_secret_key)" # Inference backends (in-cluster Service addresses, several backends separated by ';'). # The user guides name the Service after the model: Ollama uses GDCS_OLLAMA_MODEL_KUBERNETES # (gemma4:e4b -> gemma4-e4b) and vLLM uses GDCS_HF_MODEL_KUBERNETES (such as vllm-gemma or vllm-mistral) # (mistralai/Mistral-7B-Instruct-v0.2 -> mistralai-mistral-7b-instruct-v0-2); kubectl get service # in the workload namespace (ollama-gemma, vllm-gemma or vllm-mistral) lists them. export GDCS_OPEN_WEBUI_ENABLE_OLLAMA_API="OPEN_WEBUI_ENABLE_OLLAMA_API" export GDCS_OPEN_WEBUI_OLLAMA_BASE_URLS="OPEN_WEBUI_OLLAMA_BASE_URLS" export GDCS_OPEN_WEBUI_ENABLE_OPENAI_API="OPEN_WEBUI_ENABLE_OPENAI_API" export GDCS_OPEN_WEBUI_OPENAI_API_BASE_URLS="OPEN_WEBUI_OPENAI_API_BASE_URLS" export GDCS_OPEN_WEBUI_OPENAI_API_KEYS="none" # vLLM does not check API keys unless started with --api-key # Workload export GDCS_WORKLOAD_NAMESPACE="open-webui" # CPU resources export GDCS_WORKLOAD_CPU_LIMIT="2" export GDCS_WORKLOAD_CPU_REQUEST="1" # Memory resources export GDCS_WORKLOAD_MEMORY_LIMIT="4Gi" export GDCS_WORKLOAD_MEMORY_REQUEST="2Gi" EOF更改下列內容：
OPEN_WEBUI_ENABLE_OLLAMA_API：如果您部署了 Ollama 後端，則為true，否則為false。OPEN_WEBUI_OLLAMA_BASE_URLS：Ollama 服務的叢集內網址，以;分隔，例如http://gemma4-e4b.ollama-gemma.svc.cluster.local。如果未部署 Ollama 後端，請留空。OPEN_WEBUI_ENABLE_OPENAI_API：如果您部署了 vLLM 後端，則為true，否則為false。OPEN_WEBUI_OPENAI_API_BASE_URLS：vLLM 服務的叢集內網址，路徑為/v1，並以;分隔，例如http://mistralai-mistral-7b-instruct-v0-2.vllm-mistral.svc.cluster.local/v1或http://google-gemma-4-e2b-it.vllm-gemma.svc.cluster.local/v1。如果未部署 vLLM 後端，請留空。
建立使用手冊環境載入器檔案：
cat << 'EOF' > ${HOME}/gdcag-solutions/open-weight-models/open-webui/env.sh && echo "Successfully created." || echo "Failed to create!" source "${HOME}/gdcag-solutions/open-weight-models/IMPLEMENTATION/env.sh" export GDCS_USER_GUIDE_HOME="${HOME}/gdcag-solutions/open-weight-models/open-webui" echo "GDCS_USER_GUIDE_HOME=${GDCS_USER_GUIDE_HOME}" # Sourced in dependency order source "${GDCS_USER_GUIDE_HOME}/env.d/open-webui.sh" EOF更改下列內容：
IMPLEMENTATION：ollama或vllm，也就是您在這個工作站上完成的參考實作。
使用偏好的編輯器編輯及查看環境檔案：
${EDITOR:-vi} ${HOME}/gdcag-solutions/open-weight-models/open-webui/env.d/open-webui.sh提供環境檔案來源：
source ${HOME}/gdcag-solutions/open-weight-models/open-webui/env.sh輸出結果會與下列內容相似：
GDCS_ROOT_HOME=HOME_DIRECTORY_PATH/gdcag-solutions GDCS_IMPLEMENTATION_HOME=HOME_DIRECTORY_PATH/gdcag-solutions/open-weight-models/IMPLEMENTATION GDCS_USER_GUIDE_HOME=HOME_DIRECTORY_PATH/gdcag-solutions/open-weight-models/open-webui
叢集
設定
gdcloud：gdcloud config set core/account "default-user" gdcloud config set core/organization_console_url "${GDC_ZONAL_CONSOLE_URL}" gdcloud config set core/project "${GDC_PROJECT}" gdcloud config set core/zone "${GDC_ZONE}"向 GDC 環境進行驗證：
gdcloud auth login擷取叢集憑證：
gdcloud clusters get-credentials "${GDC_STANDARD_CLUSTER_NAME}" \ --project="${GDC_PROJECT}" \ --standard \ --zone="${GDC_ZONE}"確認環境檔案中參照的推論後端
Service存在：for url in $(echo "${GDCS_OPEN_WEBUI_OLLAMA_BASE_URLS};${GDCS_OPEN_WEBUI_OPENAI_API_BASE_URLS}" | tr ';' ' '); do host=$(echo "${url}" | sed -E 's#https?://([^/:]+).*#\1#') kubectl get service "${host%%.*}" --namespace="$(echo "${host}" | cut -d. -f2)" --output=wide done
實作
構件遷移
定義解決方案所需的容器映像檔清單：
declare -a GDCS_REGISTRY_IMAGES=( "ghcr.io/open-webui/open-webui:${GDCS_OPEN_WEBUI_IMAGE_TAG}" ) export SERIALIZED_IMAGES=$(declare -p GDCS_REGISTRY_IMAGES)使用參考實作指令碼，將必要的容器映像檔植入 Artifact Registry：
${GDCS_IMPLEMENTATION_HOME}/seed_registry.sh
命名空間
建立命名空間：
kubectl create namespace "${GDCS_WORKLOAD_NAMESPACE}"新增
imagePullSecret：kubectl create secret docker-registry "${GDCS_HARBOR_K8S_PULL_SECRET}" \ --dry-run=client \ --from-file=.dockerconfigjson=${GDCS_HARBOR_K8S_DOCKER_CONFIG}/config.json \ --namespace="${GDCS_WORKLOAD_NAMESPACE}" \ --output=yaml | kubectl apply -f -使用工作階段簽署金鑰建立
Secret：kubectl create secret generic "${GDCS_OPEN_WEBUI_NAME}" \ --dry-run=client \ --from-literal=WEBUI_SECRET_KEY="${GDCS_OPEN_WEBUI_SECRET_KEY}" \ --namespace="${GDCS_WORKLOAD_NAMESPACE}" \ --output=yaml | kubectl apply -f -
儲存空間
為 Open WebUI 資料建立
PersistentVolumeClaim資訊清單：cat <<EOF > "${GDCS_USER_GUIDE_HOME}/${GDCS_OPEN_WEBUI_NAME}-rwo-pvc.yaml" && echo "Successfully created." || echo "Failed to create!" apiVersion: v1 kind: PersistentVolumeClaim metadata: name: ${GDCS_OPEN_WEBUI_NAME}-rwo spec: accessModes: - ReadWriteOnce resources: requests: storage: ${GDCS_OPEN_WEBUI_PVC_SIZE} storageClassName: standard-rwo volumeMode: Filesystem EOF套用
PersistentVolumeClaim的資訊清單：kubectl apply \ --filename="${GDCS_USER_GUIDE_HOME}/${GDCS_OPEN_WEBUI_NAME}-rwo-pvc.yaml" \ --namespace="${GDCS_WORKLOAD_NAMESPACE}"
網頁介面
為 Open WebUI
ConfigMap、Deployment和Service建立資訊清單。Open WebUI 會在離線模式 (OFFLINE_MODE) 下執行，並將ConfigMap視為可靠資料來源 (ENABLE_PERSISTENT_CONFIG=false)，同時停用需要網路連線能力的功能：cat <<EOF > "${GDCS_USER_GUIDE_HOME}/${GDCS_OPEN_WEBUI_NAME}-deployment.yaml" && echo "Successfully created." || echo "Failed to create!" apiVersion: v1 kind: ConfigMap metadata: name: ${GDCS_OPEN_WEBUI_NAME} data: DATA_DIR: "/app/backend/data" ENABLE_COMMUNITY_SHARING: "false" ENABLE_IMAGE_GENERATION: "false" ENABLE_OLLAMA_API: "${GDCS_OPEN_WEBUI_ENABLE_OLLAMA_API}" ENABLE_OPENAI_API: "${GDCS_OPEN_WEBUI_ENABLE_OPENAI_API}" ENABLE_PERSISTENT_CONFIG: "false" ENABLE_SIGNUP: "true" ENABLE_VERSION_UPDATE_CHECK: "false" ENABLE_WEB_SEARCH: "false" OFFLINE_MODE: "true" OLLAMA_BASE_URLS: "${GDCS_OPEN_WEBUI_OLLAMA_BASE_URLS}" OPENAI_API_BASE_URLS: "${GDCS_OPEN_WEBUI_OPENAI_API_BASE_URLS}" OPENAI_API_KEYS: "${GDCS_OPEN_WEBUI_OPENAI_API_KEYS}" PORT: "8080" --- apiVersion: apps/v1 kind: Deployment metadata: labels: app: ${GDCS_OPEN_WEBUI_NAME} name: ${GDCS_OPEN_WEBUI_NAME} spec: replicas: 1 selector: matchLabels: app: ${GDCS_OPEN_WEBUI_NAME} strategy: type: Recreate template: metadata: labels: app: ${GDCS_OPEN_WEBUI_NAME} spec: containers: - envFrom: - configMapRef: name: ${GDCS_OPEN_WEBUI_NAME} - secretRef: name: ${GDCS_OPEN_WEBUI_NAME} image: ${GDCS_HARBOR_PROJECT_URI}/open-webui/open-webui:${GDCS_OPEN_WEBUI_IMAGE_TAG} imagePullPolicy: IfNotPresent livenessProbe: failureThreshold: 3 httpGet: path: /health port: 8080 periodSeconds: 30 timeoutSeconds: 10 name: open-webui ports: - containerPort: 8080 name: http readinessProbe: failureThreshold: 3 httpGet: path: /health port: 8080 periodSeconds: 10 successThreshold: 1 timeoutSeconds: 5 resources: limits: cpu: "${GDCS_WORKLOAD_CPU_LIMIT}" memory: "${GDCS_WORKLOAD_MEMORY_LIMIT}" requests: cpu: "${GDCS_WORKLOAD_CPU_REQUEST}" memory: "${GDCS_WORKLOAD_MEMORY_REQUEST}" securityContext: allowPrivilegeEscalation: false startupProbe: failureThreshold: 60 httpGet: path: /health port: 8080 periodSeconds: 10 timeoutSeconds: 5 volumeMounts: - mountPath: /app/backend/data name: data imagePullSecrets: - name: ${GDCS_HARBOR_K8S_PULL_SECRET} volumes: - name: data persistentVolumeClaim: claimName: ${GDCS_OPEN_WEBUI_NAME}-rwo --- apiVersion: v1 kind: Service metadata: name: ${GDCS_OPEN_WEBUI_NAME} spec: ports: - name: http port: 80 protocol: TCP targetPort: 8080 selector: app: ${GDCS_OPEN_WEBUI_NAME} type: LoadBalancer EOF為 Open WebUI
ConfigMap、Deployment和Service套用資訊清單：kubectl apply \ --filename="${GDCS_USER_GUIDE_HOME}/${GDCS_OPEN_WEBUI_NAME}-deployment.yaml" \ --namespace="${GDCS_WORKLOAD_NAMESPACE}"為 Open WebUI
NetworkPolicy建立資訊清單：cat <<EOF > "${GDCS_USER_GUIDE_HOME}/${GDCS_OPEN_WEBUI_NAME}-netpol.yaml" && echo "Successfully created." || echo "Failed to create!" apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: allow-${GDCS_OPEN_WEBUI_NAME}-ingress namespace: ${GDCS_WORKLOAD_NAMESPACE} spec: ingress: - from: - ipBlock: cidr: 0.0.0.0/0 - namespaceSelector: {} ports: - port: 8080 protocol: TCP podSelector: {} policyTypes: - Ingress EOF套用 Open WebUI
NetworkPolicy的資訊清單：kubectl apply \ --filename="${GDCS_USER_GUIDE_HOME}/${GDCS_OPEN_WEBUI_NAME}-netpol.yaml"
等待
Pod進入「執行中」狀態：watch --color --interval 5 --no-title \ "kubectl get pods --selector=app=${GDCS_OPEN_WEBUI_NAME} \ --namespace=${GDCS_WORKLOAD_NAMESPACE} | GREP_COLORS='mt=01;92' grep -E --color=always -e '^' -e 'Running'"等待
Deployment準備就緒：watch --color --interval 5 --no-title \ "kubectl get deployment/${GDCS_OPEN_WEBUI_NAME} \ --namespace=${GDCS_WORKLOAD_NAMESPACE} | GREP_COLORS='mt=01;92' grep -E --color=always -e '^' -e '1/1 1 1'"選用：串流容器記錄，監控啟動進度：
kubectl logs deployment/${GDCS_OPEN_WEBUI_NAME} \ --follow \ --namespace="${GDCS_WORKLOAD_NAMESPACE}"
驗證
擷取 Open WebUI 的 LoadBalancer IP 位址：
export OPEN_WEBUI_LB_IP=$(kubectl get service/${GDCS_OPEN_WEBUI_NAME} --namespace="${GDCS_WORKLOAD_NAMESPACE}" --output=jsonpath='{.status.loadBalancer.ingress[*].ip}') echo "OPEN_WEBUI_LB_IP=${OPEN_WEBUI_LB_IP}"使用負載平衡器檢查健康狀態和版本端點：
curl --show-error --silent http://${OPEN_WEBUI_LB_IP}/health && echo curl --show-error --silent http://${OPEN_WEBUI_LB_IP}/api/version && echo輸出結果會與下列內容相似：
{"status":true} {"version":"0.11.3"}使用通訊埠轉送功能，檢查健康狀態和版本端點：
kubectl port-forward service/${GDCS_OPEN_WEBUI_NAME} \ --namespace="${GDCS_WORKLOAD_NAMESPACE}" 8080:80 & PF_PID=$! sleep 2 curl --show-error --silent http://127.0.0.1:8080/health && echo curl --show-error --silent http://127.0.0.1:8080/api/version && echo kill ${PF_PID}確認 Open WebUI 可連至推論後端：
kubectl exec deployment/${GDCS_OPEN_WEBUI_NAME} \ --namespace="${GDCS_WORKLOAD_NAMESPACE}" \ -- sh -c 'for url in $(echo "${OLLAMA_BASE_URLS};${OPENAI_API_BASE_URLS}" | tr ";" " "); do case "${url}" in *"/v1") echo "${url}/models"; curl --max-time 10 --show-error --silent "${url}/models" | head -c 300; echo;; *) echo "${url}/api/tags"; curl --max-time 10 --show-error --silent "${url}/api/tags" | head -c 300; echo;; esac; done'在瀏覽器中開啟
http://${OPEN_WEBUI_LB_IP}並建立第一個帳戶，這個帳戶會成為管理員。在對話檢視畫面中選取模型，然後傳送提示。
作業
新增或變更推論後端
更新
env.d/open-webui.sh中的GDCS_OPEN_WEBUI_OLLAMA_BASE_URLS或GDCS_OPEN_WEBUI_OPENAI_API_BASE_URLS，取得環境檔案，然後再次執行網頁介面中的資訊清單步驟。接著套用資訊清單並重新啟動 Open WebUI。由於永久設定已停用，Open WebUI 每次啟動時都會讀取ConfigMap：kubectl apply \ --filename="${GDCS_USER_GUIDE_HOME}/${GDCS_OPEN_WEBUI_NAME}-deployment.yaml" \ --namespace="${GDCS_WORKLOAD_NAMESPACE}" kubectl rollout restart deployment/${GDCS_OPEN_WEBUI_NAME} \ --namespace="${GDCS_WORKLOAD_NAMESPACE}"
升級
在環境檔案中設定新的
GDCS_OPEN_WEBUI_IMAGE_TAG、擷取來源、植入新映像檔，並推出Deployment：source ${HOME}/gdcag-solutions/open-weight-models/open-webui/env.sh declare -a GDCS_REGISTRY_IMAGES=( "ghcr.io/open-webui/open-webui:${GDCS_OPEN_WEBUI_IMAGE_TAG}" ) export SERIALIZED_IMAGES=$(declare -p GDCS_REGISTRY_IMAGES) ${GDCS_IMPLEMENTATION_HOME}/seed_registry.sh kubectl set image deployment/${GDCS_OPEN_WEBUI_NAME} \ open-webui="${GDCS_HARBOR_PROJECT_URI}/open-webui/open-webui:${GDCS_OPEN_WEBUI_IMAGE_TAG}" \ --namespace="${GDCS_WORKLOAD_NAMESPACE}"
備份
建立資料磁碟區的
VolumeSnapshot(standardVolumeSnapshotClass適用於 GDC 標準叢集)：cat <<EOF | kubectl apply --namespace="${GDCS_WORKLOAD_NAMESPACE}" -f - apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshot metadata: name: ${GDCS_OPEN_WEBUI_NAME}-$(date +%Y%m%d-%H%M) spec: source: persistentVolumeClaimName: ${GDCS_OPEN_WEBUI_NAME}-rwo volumeSnapshotClassName: standard EOF
疑難排解
| 問題 | 可能原因 | 動作 |
|---|---|---|
| 對話檢視畫面中未提供模型 | 後端 Service 位址有誤、後端未就緒，或後端 NetworkPolicy 不接受 Open WebUI 命名空間 |
在「驗證」中執行後端驗證步驟；檢查後端 Deployment 和其 NetworkPolicy |
啟動期間重新啟動 Pod 次 |
PersistentVolume首次啟動速度緩慢 |
請查看 kubectl describe pod；startupProbe允許 10 分鐘 |
| 文件上傳 (RAG) 失敗 | 離線模式會禁止下載預設嵌入模型 | 使用 Ollama 提供的嵌入模型設定 RAG_EMBEDDING_ENGINE=ollama，或停用 RAG |
LoadBalancer IP 保持 <pending> 或無法連線 |
環境中沒有負載平衡器，或缺少 ProjectNetworkPolicy |
請使用通訊埠轉送驗證步驟，向專案 NetworkPolicy 管理員索取 ProjectNetworkPolicy |
Pod重新啟動後，工作階段失效 |
已變更「WEBUI_SECRET_KEY」 |
保持 Secret 穩定；從 secrets/open_webui_secret_key 還原 |
清除所用資源
刪除 Open WebUI 資源：
kubectl delete namespace "${GDCS_WORKLOAD_NAMESPACE}"刪除本機檔案：
rm -rf ${HOME}/gdcag-solutions/open-weight-models/open-webui