运维

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

介绍 OpenShip 自托管部署平台的定位、CLI 与 Docker 安装方法，以及项目初始化、自动部署、域名证书、数据库、备份和上线前安全检查。

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 服务器，并提前确认：

  1. 服务器可以访问代码仓库和镜像源；
  2. DNS 记录能够指向服务器公网地址；
  3. HTTP、HTTPS 以及平台实际要求的端口已在防火墙放行；
  4. 磁盘空间能够容纳镜像、数据库、持久卷和备份；
  5. 已规划管理员认证、密钥存放和异地备份。

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

需要特别检查：

  1. 不要把开发环境的绑定挂载直接带到生产环境；
  2. 数据库和缓存不要无认证暴露宿主机端口；
  3. Secret 不应硬编码进 compose.yaml；
  4. 服务应有合理的健康检查和重启策略；
  5. 持久卷应纳入备份与恢复测试。

本地 Compose 能启动，只能证明容器基本配置可用。域名、TLS、外部网络、资源限制和生产数据迁移仍需在 OpenShip 目标环境单独验证。

配置域名和 TLS

OpenShip 支持域名管理、Let’s Encrypt、通配符证书和自动续期。常规流程是：

  1. 在 DNS 服务商处把域名解析到部署服务器；
  2. 在 OpenShip 项目中绑定域名；
  3. 等待平台申请并配置证书；
  4. 验证 HTTP 到 HTTPS 的跳转；
  5. 从外部网络检查证书链和续期状态。

证书申请失败时，优先检查 DNS 是否已经生效、80 和 443 端口是否被其他反向代理占用，以及 CDN 代理模式是否影响 ACME 验证。通配符证书一般还涉及 DNS 验证，所需权限应限制在必要域名范围内。

数据库、存储和备份

平台列出的后端能力包括 Postgres、MySQL、MongoDB、Redis、Worker、WebSocket 和存储。创建数据库后，应通过平台的 Secret 或环境变量把连接信息注入应用，避免提交到 Git。

备份功能覆盖数据库和卷，但“已经设置计划任务”不等于“可以恢复”。上线前至少完成一次恢复演练：

  1. 创建一份测试数据；
  2. 手动或定时生成备份；
  3. 把备份导出到服务器之外；
  4. 在隔离项目或测试数据库中恢复；
  5. 验证数据、权限和应用版本一致。

如果备份只保存在同一台服务器的同一块磁盘上，硬盘故障或主机被入侵时仍可能全部丢失。生产环境应保留异地副本，并为备份文件配置加密和访问控制。

Push-to-deploy 与回滚

OpenShip 提供 Push-to-deploy、预览环境、staging/production 流程和回滚。接入代码仓库时，不要给部署令牌超出需要的组织或仓库权限。

建议把生产发布流程设置为：

  1. Pull Request 创建预览环境；
  2. 合并后部署 staging；
  3. 完成健康检查和必要测试；
  4. 经确认后发布 production；
  5. 监控错误率、资源和关键接口；
  6. 异常时回滚到上一个已验证制品。

数据库 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