使用自訂鏡像部署服務 - Platform For AI

當EAS提供的官方鏡像無法滿足特定業務或環境需求時，可通過自訂鏡像來封裝完整的運行環境，實現靈活、可靠的模型服務部署。

鏡像倉庫規劃

EAS部署服務時需要從鏡像倉庫拉取鏡像，推薦使用阿里雲Container RegistryACR儲存鏡像。拉取鏡像時使用VPC地址，以獲得更好的效能和安全性。

重要

公網拉取鏡像存在安全風險，且速度會特別慢，不建議使用。

ACR個人版

免費提供，但只能在一個地區內開通使用，跨地區拉取鏡像只能通過公網地址。
建議僅在測試情境使用ACR個人版，並確保與EAS服務同地區。

ACR企業版

提供更強的安全、效能和全球同步能力，可實現EAS服務在同一地區或跨地區通過內網安全、高速地拉取鏡像。
推薦在生產環境中使用。

自建鏡像倉庫

如果在阿里雲VPC中使用Harbor等自建鏡像倉庫，地址僅支援在VPC中訪問，與ACR企業版類似，需要為EAS服務配置VPC，讓鏡像倉庫與EAS服務處於同一VPC中。

鏡像倉庫身份認證

使用需要認證的私人鏡像倉庫，需在服務部署時提供使用者名稱密碼資訊。

在JSON設定檔中通過dockerAuth參數指定認證資訊，值為username:password的Base64編碼形式。

例如，對於abcd:abcde12345，執行命令echo -n "abcd:abcde12345" | base64得到YWJjZDphYmNkZTEy****，即為dockerAuth的取值。

{"dockerAuth": "YWJjZDphYmNkZTEy****"}

說明

使用同一阿里雲帳號下同地區的ACR鏡像倉庫時，EAS可免密拉取鏡像，無需填寫使用者名稱密碼。

快速開始：製作並部署自訂鏡像

本節將在阿里雲ECS執行個體上構建一個基於Gunicorn和Flask的生產級Web服務鏡像，將其推送至ACR鏡像倉庫，並最終部署為EAS線上服務。

步驟一：環境準備

在開始之前，請確保您已準備好以下環境和資源：

Virtual Private Cloud：EAS服務、ECS執行個體與ACR鏡像倉庫之間需要通過VPC進行網路通訊，以確保鏡像推送拉取的穩定性和安全性。
容器鏡像倉庫 (ACR)：用於儲存和管理您的自訂鏡像。參見使用企業版執行個體推送和拉取鏡像準備一個ACR企業版執行個體，並建立好所需的命名空間和鏡像倉庫。
開發環境：建立一個配置如下的ECS執行個體來製作鏡像。
- 執行個體規格：ecs.u1-c1m2.large
- 鏡像：Alibaba Cloud Linux 3.2104 LTS 64位
- 擴充程式：Docker社區版
- 網路：選擇的VPC需在ACR企業版執行個體的“存取控制”中添加，否則將無法推送鏡像到ACR鏡像倉庫。詳情請參見為ACR配置專用網路的存取控制。
說明
也可以使用本地或其他開發環境。
- 本地開發環境：安裝並運行 Docker，用於在本地構建鏡像。
- 使用DSW開發環境：在DSW執行個體的操作列中單擊制作镜像，系統將構建Docker鏡像並儲存到阿里雲Container RegistryACR中，部署時選擇自定义镜像即可下拉選擇。詳情請參見製作DSW執行個體鏡像。

步驟二：準備應用檔案

建立一個專案檔夾（例如 my-app），並包含以下三個檔案：

requirements.txt （應用依賴）
```
flask
gunicorn
```

app.py（Web應用代碼）

from flask import Flask

app = Flask(__name__)

@app.route('/hello/model')
def hello_world():
    # 此處可以整合您的模型推理或其他商務邏輯
    return 'Hello World from Gunicorn!'

# 注意：無需 app.run()，應用將由 Gunicorn 啟動

Dockerfile（鏡像構建指令）

# 1. 使用輕量級的官方Python鏡像作為基礎
FROM python:3.9-slim

# 2. 設定工作目錄
WORKDIR /app

# 3. 複製依賴檔案並安裝，利用Docker緩衝機制加速後續構建
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

# 4. 複製應用代碼
COPY app.py .

# 5. 聲明服務連接埠
EXPOSE 8000

# 6. 定義容器預設啟動命令（可被EAS控制台的“運行命令”覆蓋）
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:app"]

步驟三：構建並推送鏡像

開啟終端，進入專案檔夾（my-app）。

登入到您的ACR執行個體。請將命令中的預留位置替換為您的實際資訊。

# 樣本: docker login --username=your_user my-registry.cn-hangzhou.aliyuncs.com
docker login --username=<使用者名稱> <ACR倉庫網域名稱>

構建Docker鏡像並為其打上完整的標籤。

# 樣本: docker build -t my-registry.cn-hangzhou.aliyuncs.com/my-namespace/flask-app:v1 .
docker build -t <ACR倉庫網域名稱>/<命名空間>/<鏡像倉庫名>:<版本號碼> .

將構建好的鏡像推送到ACR。

# 樣本: docker push registry.cn-hangzhou.aliyuncs.com/my-namespace/flask-app:v1
docker push <ACR倉庫網域名稱>/<命名空間>/<鏡像倉庫名>:<版本號碼>

步驟四：部署服務

登入PAI控制台，在頁面上方選擇目標地區，並在右側選擇目標工作空間，然後單擊進入EAS。
單擊部署服务，選擇自定义模型部署 > 自定义部署。
配置以下關鍵參數：
- 部署方式：選擇镜像部署。
- 镜像配置：選擇镜像地址，填寫上一步中推送的完整鏡像地址。
  由於本樣本使用同一阿里雲帳號下的ACR，EAS可免密拉取鏡像，無需提供使用者名稱和密碼。
- 运行命令：gunicorn -w 4 -b 0.0.0.0:8000 app:app
  邏輯說明：EAS控制台填寫的運行命令會覆蓋 Dockerfile中的CMD指令。建議將啟動命令填寫在此處，便於後續調試和修改。
- 端口号：8000。
- 部署资源：本樣本使用CPU資源即可。如選擇公共资源下的ecs.c6.large。
- 专有网络配置：選擇一個VPC、交換器和安全性群組。
  請確保此處選擇的VPC已在ACR執行個體的“存取控制”中添加，否則將因網路不通導致鏡像拉取失敗（常見錯誤為ImagePullBackOff）。
單擊部署，當服務狀態變為运行中，表示部署成功。

步驟五：服務測試

服務部署成功後，擷取訪問地址和Token，使用以下命令測試Flask服務：

# <endpoint>和<token>替換為服務的實際調用地址和Token
curl <endpoint>/hello/model -H "Authorization: <token>"

如果返回 Hello World from Gunicorn!，則表示服務已成功部署並可正常訪問。

關於服務調用的更多資訊，請參見服務調用方式。

核心概念與限制

網路限制：EAS 服務通過VPC地址訪問內網資源，通常需要為其配置VPC。如果需要訪問公網資源（例如，使用 pip 從公用源安裝依賴、調用外部 API 或通過公網拉取鏡像），還需為VPC配置NAT Gateway。詳情請參見EAS訪問公網或內網資源。
成本提示：NAT Gateway是付費服務，會產生額外費用。
連接埠限制：EAS服務引擎會佔用 8080 和 9090 連接埠。您的應用程式監聽的連接埠必須避開這兩個連接埠，否則服務將因連接埠衝突而啟動失敗。
Sidecar注入：為實現認證、鑒權和監控，EAS會以Sidecar模式在您的服務執行個體中注入一個代理容器。這個代理是透明的，但會佔用少量資源，並負責將外部請求安全地轉寄到您配置的服務連接埠。
API協議支援：鏡像部署支援在鏡像中以HTTP、WebSocket、gRPC（HTTP2）三種協議提供API服務。

生產應用建議

鏡像與模型分離：始終將代碼和模型檔案分離。代碼打包進鏡像，模型存放在Object Storage Service或Apsara File Storage NAS上，在EAS部署頁面，通過儲存掛載功能將模型掛載到容器內使用。這能極大縮短服務更新和擴容時的鏡像拉取時間。
使用內網拉取鏡像：為了安全和效能，務必為服務配置專用網路，使其能通過 VPC 地址從 ACR 拉取鏡像。
註冊鏡像為AI資產：如果您的自訂的鏡像可在其他多種情境下應用，可使用PAI AI資產的鏡像功能，將其沉澱為對應的AI資產進行統一管理。
配置健全狀態檢查：為您的服務配置健全狀態檢查，EAS 會據此自動重啟不健康的執行個體，保障服務穩定性。詳情請參見健全狀態檢查。
啟用自動擴縮容：當業務負載有明顯波動時，開啟水平自動擴縮容功能，以彈性、經濟的方式應對流量變化。

常見問題

Q：鏡像拉取失敗（ImagePullBackOff）

原因1：網路不通。最常見的原因。請檢查EAS服務配置的VPC是否已添加到ACR執行個體的存取控制白名單中。如跨地區，需通過CEN打通VPC，參見跨地區或從IDC訪問ACR企業版執行個體。如通過公網地址拉取鏡像，請確認已為EAS配置能訪問公網的VPC專用網路，且為ACR開通公網訪問。
原因2：認證失敗。如果使用需要認證的私人鏡像倉庫（非本帳號下ACR），請檢查在鏡像配置中填寫的認證資訊是否正確。
原因3：鏡像不存在。請檢查鏡像地址、命名空間和版本號碼（Tag）是否完全正確，且鏡像已成功推送到倉庫。
原因4：系統硬碟空間不足。請擴容系統硬碟。

更多問題，請參見EAS常見問題。