升級自行託管的 Claude Managed Agents

本頁面說明如何在 Kubernetes 或 Docker Compose 上升級部署，以及如何回復。在 Kubernetes 上，停機時間取決於升級的幅度：

無論哪一種升級，Docker Compose 堆疊在重新啟動期間都會停止運作。

升級之前

請閱讀新版本在 CHANGELOG.md 中的章節，該檔案位於解壓縮後封存檔的最上層。該章節以該版本特有的升級步驟開頭。如果您跳過某些版本，請依照比您目前版本更新的每個章節進行，從最舊的開始。

接著，請逐一檢查要檢查的設定與路徑。

次要或主要升級包含資料庫備份。傾印檔以明文保存所有對話，因此本頁面上的指令會使用 age 加密工具將其加密。請建立一次金鑰組，並將私密金鑰 cma-backup.agekey 與備份分開存放：

age-keygen -o cma-backup.agekey
age-keygen -y cma-backup.agekey > cma-backup.agepub

在 Kubernetes 上升級

本頁面上的 kubectl 指令會從 shell 變數讀取伺服器 Deployment 的名稱。請在每個執行這些指令的終端機中執行下列兩行。第一行會查詢該名稱，第二行會將其印出：

server=$(kubectl -n cma-server get deployment -l anthropic.com/role=server -o jsonpath='{.items[*].metadata.name}')
echo "$server"

如果第二行印出 cma-server，請繼續。如果印出其他名稱，請在升級之前閱讀您的物件名稱。如果沒有印出任何內容，請確認 kubectl 指向正確的叢集，然後再次執行這兩行。

1. 1

   建置並推送新映像

   解壓縮新的封存檔。以新版本建置並推送其三個映像，如建置並推送映像中所述。如果您執行「egress gateway」（輸出閘道），也請建置並推送其映像。

   如果您自行建置沙箱映像，也請以新版本重新建置並推送該映像。請將其 Dockerfile 與新封存檔中的 kubernetes/sandbox/Dockerfile 進行比較，並參閱您自己的映像需要具備什麼。

2. 2

   在您的 values 檔案中設定新版本

   如果某個 values 檔案設定了 image.tag，請將其變更為新版本。

3. 3

   如果升級需要，請停止所有伺服器

   僅在下列情況下執行此步驟：

   • 您執行的某個伺服器落後新版本超過一個次要版本。
   • 第一個數字（即主要版本）增加。
   • CHANGELOG.md 中比您目前執行之版本更新的某個章節指出伺服器必須停止。

   從此步驟起直到新伺服器就緒為止，用戶端都無法連線到部署，因此請規劃維護時段。

   kubectl -n cma-server scale deployment/$server --replicas=0
   kubectl -n cma-server wait --for=delete pod -l anthropic.com/role=server --timeout=90s

   
4. 4

   備份資料庫

   在次要或主要升級之前，或如果您停止了伺服器，請執行此操作。如果舊版本無法在變更後的結構描述上執行，這份備份就是唯一的回復途徑。

   請使用與您資料庫伺服器相同 PostgreSQL 主要版本的 pg_dump。對於 <role> 與 <database>，請使用 cma-server-values.yaml 中 database.url 的 user 與 dbname 值。pg_dump 會提示輸入該角色的密碼。

   set -o pipefail
   PGSSLMODE=require pg_dump -h <database-host> -U <role> -d <database> -Fc \
     | age -r "$(cat cma-backup.agepub)" -o cma_server-<old-version>.dump.age

   

   如果任一指令印出錯誤，它留下的檔案就不是備份。請修正原因並重新執行該指令，然後再繼續。

   如果伺服器正在執行，備份只包含用戶端在傾印開始之前寫入的內容。

5. 5

   先升級伺服器，再升級沙箱

   請從新封存檔的最上層目錄執行這些指令，並使用您安裝時的 values 檔案：

   helm upgrade cma-server kubernetes/server/chart --namespace cma-server -f cma-server-values.yaml --wait
   helm upgrade cma kubernetes/chart --namespace cma -f cma-values.yaml --wait

   

   如果您執行多個環境，請針對每個沙箱 Helm release 執行第二個指令，並使用該 Helm release 的名稱、命名空間與 values 檔案。

   如果您停止了伺服器，第一個指令會遷移結構描述、恢復伺服器數量，並在新伺服器就緒後返回。

在伺服器執行時，Helm 會先啟動每個新伺服器，再停止舊伺服器，因此就緒伺服器的數量永遠不會減少。在次要升級中，第一個指令會在舊伺服器持續提供服務的同時變更結構描述，接著取代舊伺服器。正在被取代之伺服器上開啟的事件串流會正常結束，因此追蹤串流的用戶端必須重新連線。

如果某個指令失敗，請參閱如果升級失敗。

在 Docker Compose 上升級

每一種升級的步驟都相同。請從版本的 Compose 目錄執行每個 docker compose 指令，也就是存放 docker-compose.yml 的目錄。在解壓縮後的封存檔中，該目錄為 compose。請使用未設定 ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY 與 ANTHROPIC_AUTH_TOKEN 的終端機，因為 Compose 會將 shell 中這些變數的值傳遞給伺服器。

1. 1

   備份資料庫

   在次要或主要升級之前，請從舊版本的 Compose 目錄執行此操作：

   set -o pipefail
   docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
     | age -r "$(cat cma-backup.agepub)" -o cma_server-<old-version>.dump.age

   

   在指令中，請保留 $POSTGRES_USER 與 $POSTGRES_DB 原樣。單引號中的文字會在 postgres 容器內執行，該容器會在這些變數中保存其角色與資料庫的名稱。

   堆疊在備份期間會持續提供服務，因此傾印檔不會包含傾印開始後用戶端寫入的任何內容。如果任一指令印出錯誤，它留下的檔案就不是備份。請修正原因並重新執行該指令，然後再繼續。

2. 2

   解壓縮新的封存檔

   將新的封存檔放在新版本可以持續存放的目錄中，例如舊版本的上層目錄。這些指令會在該處解壓縮封存檔，而新的堆疊會從解壓縮後的檔案執行。

   如果您的 umask 比 022 更嚴格，請先執行 umask 022。接著從舊版本的 Compose 目錄執行下列指令。請以存放新封存檔之目錄的完整路徑取代 <directory>。請以封存檔的名稱（不含 .tar.gz）取代 <archive>。

   releases="<directory>"
   tar -xzf "$releases/<archive>.tar.gz" -C "$releases" && cp .env compose.config.yaml "$releases/<archive>/compose/"

   

   第二行還會將您的 .env 與 compose.config.yaml 複製到解壓縮後的 compose 目錄。在這兩行執行期間，舊的堆疊都會持續運作。如果某一行印出錯誤，請修正原因並重新執行這兩行。

3. 3

   重做您的其他變更

   只有 .env 與 compose.config.yaml 會被沿用。請在新版本的 Compose 目錄中再次進行您的其他變更：

   • 您新增的檔案： 複製該檔案。
   • 您編輯過的隨附檔案： 在新版本的副本中進行相同的編輯。請勿以舊檔案覆寫它，因為那會復原該版本對此檔案的變更。
   • 代理身分： 使用 cp -a 複製 agent-identity 目錄（如果該目錄由 root 擁有，請使用 sudo），並再次編輯 docker-compose.yml 的 volumes: 區塊。
   • 您自己的 Compose 檔案： 複製該檔案，並檢查其相對路徑。

   接著，進行要檢查的設定與路徑中的 Docker Compose 變更。

4. 4

   停止舊堆疊並啟動新堆疊

   請在您解壓縮封存檔的終端機中執行這幾行，因為它們會使用其 $releases 變數。請停留在舊版本的 Compose 目錄中，並以相同的名稱取代 <archive>。如果您曾為舊堆疊匯出 COMPOSE_FILE，請先匯出相同的值。

   ls "$releases/<archive>/compose/.env" && docker compose down
   cd "$releases/<archive>/compose" && docker compose up --build -d

   

   只有在新版本的 .env 已就位時，第一行才會停止舊堆疊。docker compose down 會保留資料庫。請勿加上 -v，那會將資料庫刪除。新的堆疊會沿用該資料庫，其 migrate 容器會在伺服器啟動前更新結構描述。

如果某個指令失敗，請參閱如果升級失敗。

如果升級失敗

在回復之前，請從記錄中找出原因：

• Kubernetes： 如果遷移 Job 失敗，helm upgrade 會在 Job 重試期間等待數分鐘，然後失敗。在等待期間，請在第二個終端機中執行 kubectl -n cma-server logs job/$server-migrate，並如在 Kubernetes 上升級中所述設定 $server。當 Job 停止重試時，Kubernetes 會刪除記錄。如果您錯過了，請再次執行 helm upgrade，這會再次啟動該 Job。
• Docker Compose： docker compose up --build -d 的輸出可能不會顯示原因。請執行 docker compose logs 找出原因。

遷移可能成功，但新伺服器沒有進入就緒狀態。若要找出原因，請閱讀伺服器的記錄：

• Kubernetes： kubectl -n cma-server logs -l anthropic.com/role=server --prefix --tail=20
• Docker Compose： docker compose logs cma-server

例如，在 Kubernetes 上，包含 has invalid keys 的一行會指出 server.config 底下新版本不接受的設定。請在考慮還原備份之前，先修正原因並再次執行升級指令，因為還原備份會遺失資料。在 Kubernetes 上，結構描述變更後，執行中的舊版本伺服器會持續提供服務，但若它停止，可能無法再次啟動。

回復

本節中的 kubectl 指令會使用在 Kubernetes 上升級中的 $server 變數。在回復之前，請檢查如果升級失敗。接著依升級類型進行回復：

• 修補升級之後： 再次部署舊版本。兩個版本使用相同的結構描述。
• 次要或主要升級之後： 請開啟新封存檔中的 CHANGELOG.md。閱讀您要回復到的版本之後每個版本的章節。
  • 如果某個章節指出舊版本無法在已遷移的資料庫上啟動，請還原備份。
  • 否則，請再次部署舊版本。如果這樣做失敗並顯示 cannot downgrade，請還原備份。

再次部署舊版本

• Kubernetes： 前往舊版本封存檔的頂層目錄。使用該版本當時的 values 檔案，執行在 Kubernetes 上升級中的兩個 helm upgrade 指令。例如，如果您為了升級而新增了 earlierNames，請將其移除。只有在第一個指令成功後，才執行第二個指令。
• Docker Compose： 在新版本的 Compose 目錄中執行 docker compose down，然後在舊版本的 Compose 目錄中執行 docker compose up --build -d。

如果舊版本無法在變更後的結構描述上執行，記錄會顯示 cannot downgrade：

• Kubernetes： 遷移 Job 會失敗，伺服器會維持原狀。如果升級失敗說明如何閱讀 Job 的記錄。
• Docker Compose： 伺服器不會啟動。請使用 docker compose logs migrate 閱讀記錄。

在 Docker Compose 上，docker compose logs 的輸出可能改為顯示 stored value is encrypted but no encryption key is configured。在此情況下，表示舊版本的 .env 沒有 CMA_STORE__CREDENTIALS_ENCRYPTION_KEY 這一行。請從新版本的 .env 複製該行，然後再次執行 docker compose up --build -d。

在 Kubernetes 上還原備份

您的資料庫伺服器需要有空間容納資料庫的第二份副本。對於 <role> 與 <database>，請使用 cma-server-values.yaml 中 database.url 的 user 與 dbname 值。

1. 1

   將備份還原到新資料庫

   以管理員身分連線到資料庫伺服器上的 postgres 資料庫，然後執行：

   CREATE DATABASE <database>_restored OWNER <role>;

   

   接著，在存放備份的機器上，以您的金鑰與備份檔案路徑執行下列指令。請使用與您資料庫伺服器相同主要版本的 pg_restore。它會提示您輸入該角色的密碼，成功時不會印出任何內容。

   age -d -i cma-backup.agekey cma_server-<old-version>.dump.age \
     | PGSSLMODE=require pg_restore -h <database-host> -U <role> -d <database>_restored --no-owner --exit-on-error

   

   如果這輸出錯誤，請停止。您的資料庫沒有變更。以管理員身分執行 DROP DATABASE <database>_restored;，然後重新開始此步驟。

2. 2

   停止所有伺服器

   kubectl -n cma-server scale deployment/$server --replicas=0
   kubectl -n cma-server wait --for=delete pod -l anthropic.com/role=server --timeout=90s

   
3. 3

   切換到還原的資料庫

   以管理員身分連線到 postgres 資料庫，然後執行：

   ALTER DATABASE <database> RENAME TO <database>_upgraded;
   ALTER DATABASE <database>_restored RENAME TO <database>;

   

   如果第一個陳述式表示有其他工作階段正在使用該資料庫，請關閉這些工作階段，然後再次執行這兩個陳述式。連線集區程式可能會持有這類工作階段。

4. 4

   部署舊版本

   依照再次部署舊版本中的 Kubernetes 項目進行。第一個指令也會恢復伺服器數量。如果它失敗，但 kubectl -n cma-server get pods 顯示舊伺服器已就緒，請參閱如果金鑰檢查失敗。

5. 5

   刪除您擱置的資料庫

   該資料庫仍保存著用戶端在備份之後寫入的內容。當舊版本正常運作後，使用 DROP DATABASE <database>_upgraded; 刪除該資料庫。

如果金鑰檢查失敗

在「部署舊版本」步驟中，第一個 helm upgrade 指令會等待舊伺服器就緒。接著它會檢查沙箱用來連線的金鑰。如果該指令失敗，但 kubectl -n cma-server get pods 顯示舊伺服器已就緒，表示該檢查失敗。

您的資料已還原且伺服器正常運作，但沙箱尚無法連線到伺服器。沙箱會使用其自身命名空間 cma 中 cma-environment Secret 的金鑰進行連線。該金鑰比您的備份更新，因此還原的資料庫無法辨識它。

若要確認原因，請再次執行第一個指令。在它等待期間，開啟第二個終端機，並在其中同樣設定 $server。接著執行 kubectl -n cma-server logs job/$server-environment-default（將 default 換成您環境的名稱）。尋找包含 Secret cma/cma-environment records key 的一行。如果記錄顯示其他錯誤，請修正其指出的問題。

如果記錄顯示該行，請使用 kubectl -n cma delete secret cma-environment 刪除該 Secret，然後再次執行第一個指令。它會以新的金鑰重新建立該 Secret。接著執行第二個指令。

在 Docker Compose 上還原備份

1. 1

   只啟動資料庫

   在新版本的 Compose 目錄中執行 docker compose down。然後在舊版本的 Compose 目錄中執行 docker compose up -d --wait postgres。在接下來的步驟中，請停留在該目錄。

2. 2

   將備份還原到新資料庫

   從舊版本的 Compose 目錄，以您的金鑰與備份檔案路徑執行此指令：

   docker compose exec -T postgres sh -c 'psql -U "$POSTGRES_USER" -d postgres \
       -c "DROP DATABASE IF EXISTS ${POSTGRES_DB}_restored" -c "CREATE DATABASE ${POSTGRES_DB}_restored"' \
     && age -d -i cma-backup.agekey cma_server-<old-version>.dump.age \
     | docker compose exec -T postgres sh -c 'pg_restore -U "$POSTGRES_USER" -d "${POSTGRES_DB}_restored" --no-owner --exit-on-error'

   

   如果它輸出 DROP DATABASE 與 CREATE DATABASE，且沒有錯誤，即表示成功。

   在此處及接下來的步驟中，請保留 $POSTGRES_USER 與 $POSTGRES_DB 原樣。單引號中的文字會在 postgres 容器內執行，該容器會在這些變數中保存其角色與資料庫的名稱。

   如果它輸出錯誤，您的資料庫沒有變更，因此您可以再次執行整個指令。如果無法還原備份，請在新版本的 Compose 目錄中執行 docker compose up --build -d，再次啟動該版本。

3. 3

   切換到還原的資料庫

   docker compose exec -T postgres sh -c 'psql -U "$POSTGRES_USER" -d postgres \
       -c "ALTER DATABASE $POSTGRES_DB RENAME TO ${POSTGRES_DB}_upgraded" \
       -c "ALTER DATABASE ${POSTGRES_DB}_restored RENAME TO $POSTGRES_DB"'

   
4. 4

   啟動舊版本

   執行 docker compose up --build -d。

5. 5

   刪除您擱置的資料庫

   該資料庫仍保存著用戶端在備份之後寫入的內容。舊版本正常運作後，刪除該資料庫：

   docker compose exec -T postgres sh -c 'psql -U "$POSTGRES_USER" -d postgres -c "DROP DATABASE ${POSTGRES_DB}_upgraded"'

   

還原之後

還原會使環境金鑰回到備份當時的狀態：

• 您在備份之後撤銷的金鑰： 它會再次生效。請再次撤銷。
• 您在備份之後建立的金鑰： 它會消失。請為使用它的 worker 建立新的金鑰。

為您自己的 worker 更換環境金鑰提供了相關指令，這些指令也適用於 Docker Compose。Docker Compose 堆疊啟動的沙箱不需要任何操作，因為堆疊會在啟動時更換其金鑰。

若要列出環境的金鑰（包括已撤銷的金鑰），請依下列方式執行 list-keys：

• 請使用您於在自行託管的伺服器上呼叫 API 中設定的終端機。請勿使用執行 docker compose 的終端機。
• 在 Kubernetes 上，請先在另一個終端機中執行 kubectl -n cma-server port-forward svc/$server 8400:8400，並在該終端機中同樣設定 $server。
• 請從封存檔的最上層目錄，針對每個環境執行一次此指令，並使用該環境的 ID。

echo "$ANTHROPIC_API_KEY" | ./cma-server-admin list-keys \
  -base-url http://127.0.0.1:8400 -env env_01595EKxaaTTGwwY3kyXdtbs \
  -key-file - -all

測試備份

若要證明傾印檔可以還原，請只執行「將備份還原到新資料庫」步驟。該步驟位於在 Kubernetes 上還原備份與在 Docker Compose 上還原備份中。該步驟不會變更使用中的資料庫。接著刪除新資料庫。在 Docker Compose 上，其名稱是您資料庫的名稱再加上結尾的 _restored。

要檢查的設定與路徑

請在執行升級指令之前閱讀本節。

請檢查您設定檔中的 web_tools 區段。如果該檔案沒有此區段，或該區段未設定任何鍵，升級後 web_search 與 web_fetch 工具會關閉。使用預設工具集的代理屆時會在沒有這些工具的情況下執行，且不會出現任何錯誤。工具集開啟任一工具的代理則無法啟動工作階段。若要保留這些工具，請參閱網頁工具需要伺服器設定。

在 Kubernetes 上，請確認每個沙箱 values 檔案（例如 cma-values.yaml）都設定了 egress.mode。若要保留沙箱對公用網際網路的存取，請在 egress 底下新增 mode: publicInternet。如果某個檔案未設定模式，chart 會套用其預設模式 closed。沙箱 chart 的 helm upgrade 指令接著會停止並顯示錯誤（例如 egress.mode is closed and egress.closed.hosts is empty），且不會變更任何內容。

請檢查相同檔案中的 sandbox.idleTimeout。如果某個檔案未設定此值，工作階段的 pod 會在代理的回合結束約 5 分鐘後消失。代理留下仍在執行的程序會隨 pod 一起停止。根據預設，/workspace 中的檔案會保留。若要將 pod 保留 30 分鐘，請在 sandbox 底下新增 idleTimeout: 30m。

請檢查設定檔中的 inference.attribution，以及伺服器環境中的 CMA_INFERENCE__ATTRIBUTION。如果找到，請刪除該行。您要升級到的版本沒有此設定，若設定了其中任一項，其伺服器就不會啟動。

當 Claude API 是您的推論提供者時，升級後每次模型呼叫都會攜帶其工作階段，以及該工作階段之代理與環境的 ID。請參閱伺服器傳送給其推論供應商的內容。

Kubernetes：您的物件名稱

cma-server-values.yaml 必須在其 earlierNames 設定中指出您的安裝使用哪些名稱。若要找出伺服器 Deployment 的名稱，請執行 kubectl -n cma-server get deployment -l anthropic.com/role=server。

如果該檔案沒有這一行，請在升級之前新增，並在之後的每次升級中保留。若沒有這一行，伺服器 chart 的 helm upgrade 指令會停止並顯示提及 earlierNames 的錯誤，且不會變更任何內容。

使用 earlierNames: true 時，chart 的物件會保留其 cma-onprem 名稱，伺服器仍會找到您以這些名稱建立的 Secret。這些頁面使用中間欄的名稱。使用 earlierNames: true 時，請改用最後一欄的名稱：

無論 earlierNames 的值為何，命名空間都名為 cma-server，伺服器的映像則名為 cma-server-image。

每個設定了 egress.mode: gateway 的沙箱 values 檔案，都必須在 egress.gateway 底下指出伺服器的兩個 Service。如果某個檔案沒有，請新增這兩行。此範例使用的是 earlierNames: true 安裝的名稱：

egress:
  gateway:
    serverService: cma-onprem
    serverEgressService: cma-onprem-egress

Docker Compose：封存檔的配置與路徑

如果您要升級的來源版本沒有 compose 目錄，其 docker-compose.yml 位於封存檔的最上層，與 bin 並列。在新的封存檔中，該檔案會深一層，位於 compose 中。

在「重做您的其他變更」步驟中，也請進行下列變更：

• 您自己的 Compose 檔案： 如果舊封存檔沒有 compose 目錄，您的檔案也會深一層。檔案中像 ./bin 這樣的路徑會變成 ../bin。如果該檔案提及 cma-onprem 服務，請將該名稱變更為 cma-server。
• 位於 /etc/cma-onprem/ 或 /run/cma-onprem/ 底下的路徑： 請將每個路徑變更為以 /etc/cma-server/ 或 /run/cma-server/ 開頭。請檢查新版本的 .env 與 compose.config.yaml、您自己的 Compose 檔案，以及您新增的每一行 volumes:。在 volumes: 行中，只變更第一個冒號之後的部分，也就是容器內的路徑。