OpenShip 自託管部署教程：用 CLI 和 Docker 搭建 CI/CD 平臺

OpenShip 是一個開源、自託管的應用部署平臺，內建 CI/CD，並提供桌面應用、Web 控制檯和 CLI。它的目標是讓開發者把程式碼倉庫連線到伺服器後，自動識別技術棧、構建容器、配置服務並完成釋出，減少手寫流水線和部署 YAML 的工作。

專案覆蓋 Node.js、Python、Go、Rust、PHP、Ruby、Java、.NET、Docker 與 monorepo，也把資料庫、域名、TLS 證書、CDN、郵件、備份和監控放在同一套介面中。它既可以連線 OpenShip Cloud，也可以部署到自己的 Linux VPS 或獨立伺服器。

快速答案

使用 npm 安裝 CLI：

1

npm i -g openship

啟動 OpenShip 後臺服務：

1

openship up

開啟管理介面：

1

openship open

進入要部署的專案目錄，初始化併發布：

1
2
3


cd your-project
openship init
openship deploy

openship init 用於把當前目錄連線到 OpenShip 專案，openship deploy 觸發構建與部署。第一次在生產伺服器使用前，建議先拿一個非關鍵專案驗證持久化目錄、域名解析、證書、備份與回滾流程。

OpenShip 解決什麼問題

手工部署一個 Web 專案通常需要分別處理 Git 拉取、映象構建、反向代理、TLS、環境變數、資料庫、日誌、備份和釋出回滾。OpenShip 把這些任務集中到一個部署平臺中。

能力	用途
內建 CI/CD	Push-to-deploy、預覽環境、測試與生產流程、回滾
多技術棧	自動處理常見語言、Docker 與 monorepo 專案
後端服務	管理 Postgres、MySQL、MongoDB、Redis、Worker 和儲存
域名與 TLS	配置域名、Let’s Encrypt、萬用字元證書和自動續期
備份	定時備份資料庫與卷，並提供恢復和匯出入口
監控	檢視實時構建日誌、容器指標和資源佔用

它更接近輕量 PaaS 或自託管部署控制面板，而不是單獨的 CI Runner。部署結果使用標準 Docker 容器，便於在不同伺服器和供應商之間遷移。

安裝前準備

如果只是本地體驗，可以在開發機安裝 CLI。準備長期自託管時，建議使用獨立 Linux 伺服器，並提前確認：

伺服器可以訪問程式碼倉庫和映象源；
DNS 記錄能夠指向伺服器公網地址；
HTTP、HTTPS 以及平臺實際要求的埠已在防火牆放行；
磁碟空間能夠容納映象、資料庫、持久卷和備份；
已規劃管理員認證、金鑰存放和異地備份。

OpenShip 會接觸原始碼、部署憑據、環境變數和資料庫，因此不應把未經保護的控制檯直接暴露到公網。正式上線前應閱讀當前版本文件和安全說明，並先在隔離環境驗證升級與恢復。

方法一：透過 CLI 安裝

官方快速開始使用 npm 全域性安裝：

1

npm i -g openship

官方還提供 Shell 安裝入口：

1

curl -fsSL https://get.openship.io | sh

在伺服器執行遠端指令碼前，建議先下載並審查指令碼內容。安裝完成後啟動後臺服務：

1

openship up

這個命令會把 OpenShip 安裝為後臺服務，並配置開機啟動和異常自動重啟。需要在前臺觀察啟動日誌時執行：

1

openship up --foreground

開啟控制檯：

1

openship open

停止後臺服務：

1

openship stop

前臺執行更適合首次排錯；確認配置和資料目錄正確後，再切換到後臺服務模式。

方法二：使用 Docker Compose

希望明確控制容器、網路和卷時，可以從官方倉庫啟動 Compose 棧：

1
2
3
4


git clone https://github.com/oblien/openship.git
cd openship
cp .env.example .env
docker compose up -d

不要在複製 .env.example 後立即面向公網啟動。先開啟 .env，檢查所有密碼、金鑰、外部地址、埠和持久化配置，替換示例值，再執行 Compose。

檢視服務狀態和日誌：

1
2


docker compose ps
docker compose logs -f

停止服務但保留卷資料：

1

docker compose down

不要在沒有備份的情況下隨意新增 -v，因為它會刪除 Compose 管理的卷。升級前應記錄當前映象或版本、匯出資料庫並備份持久卷，確保可以回到已驗證版本。

部署第一個專案

進入本地專案目錄：

1
2


cd your-project
openship init

初始化過程用於建立或選擇 OpenShip 專案，並把當前目錄與專案關聯。完成後觸發部署：

1

openship deploy

平臺會嘗試識別技術棧、構建應用並配置執行環境。即使官方強調減少配置檔案，部署前仍應明確以下資訊：

應用監聽的埠和健康檢查路徑；
構建命令、啟動命令與執行時版本；
必需的環境變數和 Secret；
需要持久儲存的目錄；
資料庫遷移應該在何時執行。

自動檢測適合常規專案，但不應代替對應用啟動過程的理解。遇到構建失敗時，先從實時構建日誌確認檢測出的語言、版本和命令是否正確。

部署 Docker Compose 專案

OpenShip 官方說明可以原樣部署已有 Compose 檔案。對包含 Web 服務、Worker、資料庫和 Redis 的專案，這通常比把所有服務重新配置一遍更直接。

提交部署前檢查 Compose 檔案：

1

docker compose config

本地啟動驗證：

1
2


docker compose up -d
docker compose ps

需要特別檢查：

不要把開發環境的繫結掛載直接帶到生產環境；
資料庫和快取不要無認證暴露宿主機埠；
Secret 不應硬編碼進 compose.yaml；
服務應有合理的健康檢查和重啟策略；
持久卷應納入備份與恢復測試。

本地 Compose 能啟動，只能證明容器基本配置可用。域名、TLS、外部網路、資源限制和生產資料遷移仍需在 OpenShip 目標環境單獨驗證。

配置域名和 TLS

OpenShip 支援域名管理、Let’s Encrypt、萬用字元證書和自動續期。常規流程是：

在 DNS 服務商處把域名解析到部署伺服器；
在 OpenShip 專案中繫結域名；
等待平臺申請並配置證書；
驗證 HTTP 到 HTTPS 的跳轉；
從外部網路檢查證書鏈和續期狀態。

證書申請失敗時，優先檢查 DNS 是否已經生效、80 和 443 埠是否被其他反向代理佔用，以及 CDN 代理模式是否影響 ACME 驗證。萬用字元證書一般還涉及 DNS 驗證，所需許可權應限制在必要域名範圍內。

資料庫、儲存和備份

平臺列出的後端能力包括 Postgres、MySQL、MongoDB、Redis、Worker、WebSocket 和儲存。建立資料庫後，應透過平臺的 Secret 或環境變數把連線資訊注入應用，避擴音交到 Git。

備份功能覆蓋資料庫和卷，但“已經設定計劃任務”不等於“可以恢復”。上線前至少完成一次恢復演練：

建立一份測試資料；
手動或定時生成備份；
把備份匯出到伺服器之外；
在隔離專案或測試資料庫中恢復；
驗證資料、許可權和應用版本一致。

如果備份只儲存在同一臺伺服器的同一塊磁碟上，硬碟故障或主機被入侵時仍可能全部丟失。生產環境應保留異地副本，併為備份檔案配置加密和訪問控制。

Push-to-deploy 與回滾

OpenShip 提供 Push-to-deploy、預覽環境、staging/production 流程和回滾。接入程式碼倉庫時，不要給部署令牌超出需要的組織或倉庫許可權。

建議把生產釋出流程設定為：

Pull Request 建立預覽環境；
合併後部署 staging；
完成健康檢查和必要測試；
經確認後釋出 production；
監控錯誤率、資源和關鍵介面；
異常時回滾到上一個已驗證製品。

資料庫 Schema 變化可能無法隨容器回滾自動撤銷。設計遷移時應優先採用向後相容步驟，並把資料庫恢復流程與應用回滾分開驗證。

三種管理方式怎麼選

介面	適合場景
Desktop App	單人開發、本地管理、檢視實時日誌
Web Dashboard	團隊共享、瀏覽器遠端管理
CLI	自動化、指令碼、CI 環境和快速操作

專案還提供 REST API 和 MCP 介面，可供自動化工具或 AI Agent 整合。給自動化客戶端建立憑據時，應使用獨立身份、最小許可權和可撤銷令牌；對部署、刪除、恢復等高影響操作保留人工確認或審批。

當前狀態與路線圖要分清

官方 README 將核心功能描述為可用於生產並持續開發，同時明確說明文件仍在完善。多節點叢集、負載均衡介面、私有網路、高階監控和視覺化 CI/CD 流水線被列在後續計劃中。

因此，評估時應以當前釋出版本實際可用的功能為準，不要把路線圖當成已經交付。對於生產遷移，先驗證自己真正需要的能力，例如單節點故障恢復、升級相容性、備份匯出、許可權隔離和審計日誌。

常見問題

`openship up` 啟動後打不開控制檯

先使用前臺模式觀察錯誤：

1

openship up --foreground

再檢查埠占用、防火牆、服務狀態和日誌。如果是在遠端伺服器執行，openship open 開啟的地址還需要從管理端網路可達。

自動識別的構建方式不正確

檢查專案根目錄、鎖檔案、Dockerfile、Compose 檔案和執行時版本宣告。monorepo 還要確認實際應用子目錄與構建上下文，避免平臺在倉庫根目錄選擇錯誤入口。

域名已經解析但證書籤發失敗

確認 DNS 返回目標伺服器地址，80/443 埠沒有被其他服務佔用，雲防火牆允許外部訪問，並檢查 CDN 或反向代理是否攔截驗證請求。

可以立刻替換現有生產平臺嗎？

不建議直接整體遷移。先選擇一個可回滾的低風險專案，驗證部署、日誌、監控、備份恢復、版本升級和故障處理，再逐步擴大使用範圍。

OpenShip 適合誰

OpenShip 適合希望在自己的 Linux 伺服器上獲得一體化部署體驗，又不想為每個專案分別維護 CI、反向代理、證書和資料庫指令碼的個人開發者或小團隊。它也適合希望透過 Docker 保留基礎可遷移性的環境。

如果組織已經有成熟的 Kubernetes、GitOps、身份治理和可觀測性體系，引入新的部署控制面可能增加重複管理。此時應先比較許可權模型、審計、叢集能力和現有流水線整合成本。

總結

OpenShip 把程式碼構建、容器部署、域名證書、資料庫、備份和監控集中到同一平臺，並允許透過桌面端、Web、CLI、API 和 MCP 管理。最快的體驗方式是安裝 CLI 後執行 openship up，生產自託管則更適合從隔離測試專案開始，重點驗證 Secret、持久化、備份恢復、升級和回滾。

專案地址：oblien/openship

官方文件：openship.io/docs