OpenShip 部署 AI Agent：2026 從程式碼到上線

原型在本機可以回答問題，部署後一重啟，對話紀錄、工作佇列和 API 設定卻全部消失。

最快解法是：先確認 Agent 屬於長駐 Web 服務還是需要特定 Serverless 執行時，再用 OpenShip 部署一個只有健康檢查與單一模型呼叫的最小版本；確認重啟、日誌與回滾都有效後，才加入資料庫、快取和工具服務。

本指南適合以下讀者：

想把本地 AI Agent 原型變成可公開存取服務的獨立開發者。
需要以 Git 推送觸發部署，並保留版本回滾能力的小型技術團隊。
正在比較雲端建置環境與遠端 Mac 控制端的 AI SaaS 工程師。

最後更新於 2026 年 8 月 1 日；部署流程核實自 OpenShip 官方首頁、官方下載與安裝文件及官方程式碼倉庫。若安裝指令、網路模型或回滾機制變更，應重新從全新環境驗證。

先判斷 Agent 的執行形態，再決定部署方式

OpenShip 可以處理標準容器化服務，但「能夠啟動」不等於「適合正式上線」。AI Agent 常見的執行形態至少有四種：

Web API：持續監聽 HTTP 連接埠，接收前端或其他服務請求。
長駐 Worker：持續讀取佇列，執行模型呼叫、工具操作或檔案處理。
定時任務：按照排程執行摘要、同步、清理或批次推論。
多服務應用：Web API、PostgreSQL、Redis 和物件儲存需要私有網路互通。

因此，OpenShip 部署 AI Agent 前，應先檢查以下限制：

程式是否能以容器方式啟動，且啟動命令不依賴開發者本機路徑。
應用是否明確監聽由環境變數提供的連接埠，而不是寫死在本機設定。
Agent 是否依賴某個特定 Serverless 執行時，例如請求必須在短時間內完成，或依賴平台專屬的暫存檔案。
長時間模型呼叫、串流回應和 WebSocket 是否需要長駐連線。
需要保留的資料是否寫入外部資料庫或持久化磁碟，而不是容器內的暫存目錄。

OpenShip 官方資料列出 Git 或本地目錄作為部署入口，並支援雲端或自有伺服器目標；同時也列出日誌、指標、資料庫、排程工作與版本回滾能力。這些屬於平台能力，不代表每個框架或複雜多服務拓撲都已完成生產環境驗證。

選雲端還是自有伺服器

判斷維度	OpenShip 雲端目標	自有伺服器目標
建置位置	由雲端環境或指定建置端執行	可在本機或遠端建置端完成
適合情況	想減少伺服器管理，快速建立公開服務	需要資料位置、網路政策或成本控制
主要風險	仍要確認區域、頻寬、資料備份責任	需要自行處理主機、SSH、磁碟與安全更新
回滾邊界	應用版本可回退，但資料庫資料仍需獨立恢復	應用與資料服務都要分開驗證
建議選擇	原型、預覽環境、短期測試	長期運行、敏感資料、既有基礎設施

這個選擇不應只看「哪一個比較快」。如果 Agent 會保存對話、任務狀態或客戶檔案，資料備份和恢復責任比首次部署時間更重要。

第一步：準備能被部署工具正確識別的專案

OpenShip 部署項目通常有兩個入口：本地資料夾，或已連接的 Git 儲存庫。官方下載頁列出的基本流程是安裝 CLI、執行 openship init 連結專案，再執行 openship deploy 發布。

本地專案可以先執行：

cd <PROJECT_DIR>
openship init
openship deploy

若使用 Git，建議先把以下內容提交到版本庫：

<PROJECT_DIR>/
├── README.md
├── package.json 或 requirements.txt
├── Dockerfile（如需固定建置環境）
├── .env.example
├── migrations/
├── src/
└── openship.json（如專案需要明確的部署設定）

不要把實際密鑰放進 .env.example、Git 記錄或 Dockerfile。模型供應商的 API Key、資料庫密碼、SSH 私鑰和 webhook 秘密，應在部署平台的環境變數或秘密管理功能中設定。

建置端也要先確認：

具備正確的 CPU 架構，避免在 ARM 建置後部署到只接受不同架構映像檔的環境。
能連線到套件倉庫、容器映像檔來源及模型 API。
憑據不會被寫入建置日誌。
不在正式伺服器上臨時編譯，避免依賴未鎖定的套件版本。

對於環境變數的設計，可參考十二因素應用程式的設定原則，把部署環境差異放在環境設定，而不是硬編碼在程式碼內。

第二步：先部署最小可用的 AI Agent

首次上線不要同時接入所有工具。建議先保留三個端點：

GET  /healthz
POST /api/chat
GET  /version

其中 /healthz 只檢查應用程式是否能回應，不要在這個端點執行模型呼叫；/api/chat 只接入一個模型 API；/version 回傳 Git commit 或部署版本，方便之後判斷實際服務是否已切換。

環境變數可以先使用占位符：

MODEL_API_KEY=<MODEL_API_KEY>
MODEL_BASE_URL=<MODEL_BASE_URL>
APP_ENV=production
PORT=<APP_PORT>

部署後依序檢查：

建置日誌沒有套件安裝錯誤或秘密內容。
服務狀態顯示為運行中。
/healthz 能從公開端點取得成功回應。
/api/chat 能完成一次模型呼叫。
/version 與預期的提交版本一致。
服務重啟後仍能完成健康檢查。

OpenShip 官方流程強調建置產物會以版本化形式發布，並可從 CLI、儀表板或桌面應用檢視日誌與執行回滾；但團隊仍應自行保存首次成功部署的版本識別碼，不能只依賴畫面上的「部署成功」。

第三步：接入資料庫、快取與背景工作

完成單一模型呼叫後，再依照以下順序擴充：

先接入 PostgreSQL 或其他主要資料庫。
執行 migration，建立 Agent 所需的使用者、對話和任務資料表。
重啟應用，確認資料仍然存在。
再加入 Redis 或其他快取與佇列服務。
最後部署 Worker 和定時任務，測試失敗重試與重複執行防護。

OpenShip 官方頁面列出 PostgreSQL、Redis、MongoDB、MySQL、物件儲存與排程工作等能力；也描述服務可在隔離的私有網路中互相連線。

不過，AI Agent 的資料生命週期仍要由團隊定義。至少要回答：

容器重建後，對話資料是否仍在資料庫內？
Worker 重啟時，未完成任務會重新排入佇列，還是直接遺失？
模型呼叫逾時後，是否會產生重複扣費或重複執行工具？
資料庫備份由誰負責，恢復測試多久執行一次？
物件儲存中的上傳檔案是否與應用版本分離？

Docker 官方入門文件對容器、映像檔與持久化資料的基本界線有清楚說明。實務上，第一次啟動成功只能證明服務能跑起來；只有完成「寫入資料、重啟服務、再次讀取」才算通過持久化驗收。

第四步：設定網域、HTTPS 和密鑰邊界

網域設定應拆成三個部分處理：

DNS 記錄指向 OpenShip 所使用的入口。
OpenShip 端設定應用網域與服務路由。
以 HTTPS 公開端點測試健康檢查、模型呼叫和串流回應。

官方資料提到自訂網域、TLS、自動憑證更新與邊緣路由能力；憑證實際是否成功簽發，仍應以部署日誌及瀏覽器 HTTPS 驗證為準。如需了解自動憑證的基本原理，可參考 Let's Encrypt 的官方說明。

密鑰邊界則應遵守以下規則：

模型 API Key 只放在正式環境秘密或環境變數。
日誌不得輸出完整 Authorization 標頭、請求內容或模型供應商回應中的敏感欄位。
前端不能直接持有高權限模型密鑰。
測試環境和正式環境使用不同 Key。
更換 Key 後，應確認舊 Key 已撤銷，而不是只覆蓋新的環境變數。

若使用 Git 推送觸發部署，還要檢查提交歷史；已經被提交過的密鑰，即使之後刪除檔案，也應視為已外洩並立即輪換。

第五步：用故障情境完成上線驗收

正式交付前，至少執行以下勾選清單：

[ ] 健康檢查在公開網域上可用。
[ ] 單一模型呼叫可完成，且錯誤訊息沒有洩露密鑰。
[ ] 資料庫寫入後重啟服務，資料仍可讀取。
[ ] Worker 能取出任務，失敗後有可追蹤的重試結果。
[ ] 模型 API 延遲或逾時時，Web API 不會永久佔用連線。
[ ] 新版本啟動失敗時，日誌能指出建置、環境變數或啟動命令問題。
[ ] 回滾後 /version 顯示舊版本，且健康檢查重新通過。
[ ] 回滾應用版本後，資料庫 migration 不會造成不可逆的結構錯誤。
[ ] 團隊已記錄部署版本、回滾指令、資料恢復責任與交接人。

模擬一次上游模型逾時，再模擬一次應用啟動失敗；如果團隊只能看到「服務離線」，卻無法從日誌判斷是哪一層出錯，就不應把服務標記為正式上線。OpenShip 官方資料列出即時日誌、指標和一鍵回滾，但回滾應用容器不必然等於恢復資料庫內容，兩者要分開測試。

OpenShip 部署 AI Agent 的常見判斷

OpenShip 部署項目需要準備哪些檔案？
至少要有可重現的依賴宣告、啟動命令、健康檢查端點和環境變數清單。若自動偵測不足，應補上 Dockerfile 或 openship.json，並把 migration、Worker 啟動方式和資料目錄寫清楚。

帶後端的 AI Agent 是否可以直接部署？
可以，但前提是後端能以長駐服務或標準容器方式運行。Web API、Worker、資料庫和快取應視為不同元件配置，不應把所有功能塞進一個只適合短請求的函式執行環境。

模型 API Key 應如何配置？
使用環境變數或秘密管理功能，不要放在 Git、前端程式碼、Dockerfile 或公開建置記錄中；部署後以一次成功呼叫和一次錯誤呼叫確認 Key 已生效且沒有被寫入日誌。

OpenShip 能否部署資料庫和背景任務？
官方資料列出資料庫、Redis 和排程工作能力，但團隊仍要確認備份、資料保留、重試、冪等性與重啟行為。對需要長時間執行的 Agent，Worker 和 Web API 分開部署通常更容易定位問題。

部署失敗後如何回滾？
先保留失敗版本的日誌與版本識別碼，再選擇上一個已通過健康檢查的不可變版本回退；回滾後要重新檢查 /healthz、/version、模型呼叫和資料庫讀寫，不能只看服務狀態變成正常。

上線前的方案取捨

若目前採用的是臨時本機服務、手寫 SSH 指令或只靠單一雲端函式，常見問題是部署步驟無法重現、資料持久化邊界不清楚、背景任務缺少可見度，以及新版本出錯後沒有可靠回退點。這些做法適合早期驗證，但不適合長期承擔帶模型 API、資料庫和工具呼叫的 AI SaaS。

OpenShip 部署 AI Agent 的優勢不在於省略所有運維工作，而在於把建置、發布、日誌、網域和版本切換放進同一條可檢查的流程。若團隊還需要持續在線的 macOS 建置端、遠端協作環境或隔離測試機，可按專案週期選擇 Vuncloud 遠端 Mac 環境，再用本文的健康檢查、重啟與回滾清單驗收整條部署鏈路；但長期高負載、需要固定實體介面或已有穩定自有建置機的團隊，直接維持現有硬體可能更合適。

若需要查閱帳戶、服務或連線設定，可再參考 Vuncloud 幫助中心。