今日开源[第37期]Openship

Openship 项目分析报告

分析日期：2026-07-24

一、项目介绍

1.1 项目概述

Openship 是一个开源、可自托管的零配置部署平台，内置 CI/CD。其核心理念是"指向一个代码仓库，自动检测技术栈、构建、配置一切并部署上线"——无需配置文件、无需 CI/CD 流水线、无需 YAML。它同时提供桌面应用（Electron）、Web Dashboard（Next.js + React 19）和 CLI 三种交互界面，支持将应用部署到 VPS、裸金属服务器或 Openship Cloud，是 Vercel/Netlify/Railway 等商业平台的开源自托管替代方案 $TRAE_REF。

1.2 项目信息

项目 详情
项目名称 Openship
项目地址 https://github.com/oblien/openship
项目官网 https://openship.io
文档站点 https://openship.io/docs
npm 包名 openship
作者/组织 oblien，主维护者 @Hydralerne
Stars 8,200+（截至 2026 年 7 月）
Forks 633
当前版本 v0.3.0（2026 年 7 月 23 日发布）
开源协议 Apache License 2.0
主要语言 TypeScript 89.4%、MDX 5.6%、Shell 2.5%、CSS 1.3%
提交数 357 commits
贡献者 30 人
Open Issues 35

1.3 项目示意图

README 和项目文档中提供了以下可视化资源：

  • Dashboard 截图（docs/screenshots/screen.png）：展示完整的部署管理界面，包括项目列表、构建日志、资源使用情况
  • Star History 图表：嵌入在 README 中的项目增长趋势图
  • 架构图（docs/diagrams/）：系统架构和部署流程的可视化说明
  • 多语言 README：支持 9 种语言（英文、阿拉伯文、简体中文、西班牙文、法文、日文、葡萄牙文、德文、土耳其文）

二、项目亮点

2.1 零配置自动检测

Openship 最核心的创新是零配置部署。通过 project-root-detector.ts（32KB 核心代码）自动检测项目技术栈：扫描项目中存在的特定文件（如 package.json、pyproject.toml、go.mod、Cargo.toml 等），并兼容读取 railway.toml、vercel.json 等第三方平台配置，自动决定构建策略。用户无需编写任何 Dockerfile、CI/CD 配置文件或 YAML 编排文件 $TRAE_REF。

2.2 全功能一体化平台

功能领域 详情
内置 CI/CD Push-to-deploy、预览环境、staging/prod 流程、一键回滚
多技术栈 Node.js、Python、Go、Rust、PHP、Ruby、Java、.NET、Docker、monorepos
全栈后端 PostgreSQL、MySQL、MongoDB、Redis、Workers、WebSockets、对象存储
域名与 SSL 自动 Let's Encrypt 证书、通配符域名、自动续期
CDN 边缘缓存、HTTP/3、Brotli 压缩、即时缓存清除
内置邮件服务器 自带 SMTP，支持 DKIM/SPF/DMARC，无需 Mailgun/SES 等第三方服务
备份系统 定时备份数据库+数据卷，一键恢复，支持随时导出
实时监控 构建日志、容器指标、资源使用情况实时流式展示
弹性伸缩 云端自动扩缩容，自托管多节点就绪
Docker Compose 可直接部署现有 docker-compose 文件
应用市场 15+ 一键安装应用：Convex、n8n、Ghost、Directus、NocoDB、Metabase、Grafana、Gitea、code-server、Uptime Kuma、Vaultwarden、FreshRSS、Stirling PDF、IT-Tools、Excalidraw

2.3 三种交互界面

界面 技术栈 特点
桌面应用 Electron 完整 GUI，实时日志，一键操作，通过 SSH 驱动远程服务器
Web Dashboard Next.js 16 + React 19 浏览器端，面向团队协作
CLI npm 包 openship 可脚本化，CI 友好，支持自动化

此外还提供 REST API + MCP 协议，支持 AI Agent 集成和自动化部署管理。

2.4 双模式运行

同一套代码通过 CLOUD_MODE 环境变量切换两种运行模式：

  • 自托管模式（CLOUD_MODE=false）：数据完全在自己服务器上，不依赖第三方平台
  • SaaS 云模式（CLOUD_MODE=true）：多租户、计费、GitHub App 集成

2.5 创新点

  1. 零配置自动检测：兼容第三方平台配置文件，降低迁移成本
  2. CLI 内嵌 API + Dashboard：一个命令启动全部服务，自动安装为后台服务并开机自启
  3. 桌面控制面：桌面应用通过 SSH 直接驱动远程服务器，Openship 自身不暴露在公网
  4. MCP 协议集成：原生支持 AI Agent 协议，可以通过 AI 工具自动化部署管理
  5. 内置邮件服务器：无需依赖 Mailgun、SendGrid、SES 等第三方邮件服务
  6. 标准 Docker 容器：可在不同服务商之间自由迁移，无厂商锁定

2.6 与同类工具的差异化优势

对比维度 Openship Vercel/Netlify Railway Coolify CapRover
自托管 ✅ ❌ ❌ ✅ ✅
桌面应用 ✅ ❌ ❌ ❌ ❌
内置邮件 ✅ ❌ ❌ ❌ ❌
MCP/AI 集成 ✅ ❌ ❌ ❌ ❌
零配置 ✅ 自动检测 ✅ 自动检测 ✅ 部分 ❌ 需配置 ❌ 需配置
应用市场 15+ 模板 模板 100+ 少数
开源协议 Apache 2.0 闭源 闭源 MIT Apache 2.0
多服务器 ✅ ❌ ❌ ✅ ✅

三、项目运行环境

3.1 开发环境要求

依赖 版本
Node.js >= 22.0.0
Bun 1.3.10（项目包管理器）
pnpm Workspace 管理
TypeScript 5.9.3
PostgreSQL 16（生产环境）
Redis 7（生产环境队列+缓存+限流）
Docker 用于容器化部署

3.2 安装与运行方式

方式一：CLI 一键安装（推荐）

# 全局安装
npm i -g openship

# 启动（自动安装为后台服务，开机自启）
openship up

# 打开 Dashboard
openship open

# 暂停服务
openship stop

# 升级
openship update

# 前台运行
openship up --foreground

方式二：Docker Compose

git clone https://github.com/oblien/openship.git && cd openship
cp .env.example .env   # 编辑必要的环境变量
docker compose up -d --build

Docker Compose 启动 5 个服务：

  • postgres:16-alpine — 内部端口 5432
  • redis:7-alpine — 内部端口 6379
  • api — 端口 4000
  • dashboard — 端口 3001
  • web — 端口 3000

方式三：桌面应用

openship install
# 或从 openship.io 下载 macOS/Linux/Windows 安装包

方式四：源码开发

git clone https://github.com/oblien/openship.git && cd openship
bun install
bun run dev:all    # 或 bun run dev 只启动 api + dashboard

3.3 核心依赖库

API 层（apps/api）：

依赖 用途
Hono 4.x 轻量级 Web 框架
better-auth 1.5.x 统一认证（GitHub/Google OAuth、设备码、PAT Token）
Drizzle ORM 0.45.x 数据库 ORM（兼容 PostgreSQL + PGlite）
BullMQ 5.x 基于 Redis 的任务队列
ioredis 5.x Redis 客户端
Stripe 20.x SaaS 支付集成
Pino 10.x 高性能日志
Zod 4.x + TypeBox 数据校验
nodemailer 9.x 邮件发送
maxmind GeoIP 定位

Dashboard 层（apps/dashboard）：

依赖 用途
Next.js 16.x React 全栈框架
React 19.x UI 框架
Tailwind CSS 4.x 样式框架
xterm.js 6.x Web 终端
Chart.js 4.x + Recharts 3.x 图表渲染
Lucide React 0.577.x 图标库

适配器层（packages/adapters）：

依赖 用途
dockerode 4.x Docker API 客户端
ssh2 1.17.x SSH 远程连接
AWS SDK S3 3.x 对象存储
oblien 2.x 云运行时

四、项目代码介绍

4.1 代码架构图

openship/
├── apps/                            # 应用层（Monorepo）
│   ├── api/                         # 后端 API 服务（Hono）
│   │   └── src/
│   │       ├── index.ts             # 入口
│   │       ├── app.ts               # 路由注册（17KB）
│   │       ├── config/              # 配置管理
│   │       ├── lib/                 # 核心库（~80+ 文件）
│   │       │   ├── auth.ts                  # 认证逻辑（35KB）
│   │       │   ├── project-root-detector.ts  # 技术栈检测（32KB）
│   │       │   ├── compose-parser.ts        # Docker Compose 解析（19KB）
│   │       │   ├── deployment-runtime.ts     # 部署运行时（16KB）
│   │       │   ├── routing-domains.ts       # 域名路由（17KB）
│   │       │   ├── mail.ts                  # 邮件服务（15KB）
│   │       │   ├── cloud-auth-proxy.ts      # 云认证代理（22KB）
│   │       │   ├── release-download.ts      # 发布下载（21KB）
│   │       │   ├── route-permission.ts      # 路由权限（21KB）
│   │       │   ├── public-endpoints.ts      # 公共端点（14KB）
│   │       │   ├── permission.ts            # 权限系统（18KB）
│   │       │   ├── job-runner/              # 任务调度器
│   │       │   ├── cache-store/             # 缓存存储
│   │       │   ├── rate-limit/              # 限流
│   │       │   └── git-forwarding/          # Git 转发
│   │       ├── middleware/          # 中间件
│   │       └── modules/            # 业务模块（20+ 模块）
│   │           ├── analytics/      # 分析
│   │           ├── apps/           # 应用管理
│   │           ├── audit/          # 审计日志
│   │           ├── auth/           # 认证
│   │           ├── backup-destinations/  # 备份目标
│   │           ├── backups/        # 备份
│   │           ├── billing/        # 账单（SaaS 模式）
│   │           ├── cloud/          # 云服务
│   │           ├── deployments/    # 部署管理
│   │           ├── domains/        # 域名管理
│   │           ├── github/         # GitHub 集成
│   │           ├── health/         # 健康检查
│   │           ├── images/         # 镜像管理
│   │           ├── jobs/           # 任务管理
│   │           ├── mail-server/    # 邮件服务器
│   │           ├── mail/           # 邮件
│   │           ├── mcp/            # MCP 协议
│   │           ├── migration/      # 迁移
│   │           ├── notices/        # 通知
│   │           └── notifications/  # 消息通知
│   │
│   ├── cli/                         # CLI 命令行工具
│   ├── dashboard/                   # Web Dashboard（Next.js 16 + React 19）
│   ├── desktop/                     # 桌面应用（Electron 40）
│   ├── email/                       # 邮件模板
│   └── web/                         # 官网/落地页
│
├── packages/                        # 共享包
│   ├── adapters/                    # 适配器层（Docker/SSH/S3）
│   ├── core/                        # 核心类型与工具
│   ├── db/                          # 数据库层（Drizzle ORM + PGlite）
│   ├── db-email/                    # 邮件数据库
│   ├── onboarding/                  # 新手引导
│   └── ui/                          # 共享 UI 组件
│
├── docs/                            # 文档
│   ├── diagrams/                    # 架构图
│   ├── i18n/                        # 多语言 README
│   └── screenshots/                 # 截图
│
├── fixtures/deploy/                 # 测试用的部署模板
├── scripts/                         # 构建/发布脚本
├── docker-compose.yml               # Docker 编排
├── turbo.json                       # Turborepo 配置
├── pnpm-workspace.yaml              # pnpm workspace
├── .env.example                     # 环境变量参考
└── package.json                     # 根配置（v0.3.0）

4.2 系统架构

┌──────────────────────────────────────────────────────┐
│                    用户交互层                          │
│  Desktop App (Electron) │ Web Dashboard │ CLI │ MCP  │
└──────────────────┬───────────────────────────────────┘
                   │
┌──────────────────┴───────────────────────────────────┐
│                  API 层 (Hono)                        │
│  ┌──────────────────────────────────────────────┐   │
│  │       路由注册 (app.ts, 17KB)                  │   │
│  │  认证 │ 权限 │ 限流 │ 审计 │ 中间件             │   │
│  └──────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────┐   │
│  │            20+ 业务模块 (modules/)             │   │
│  │  部署 │ 域名 │ 备份 │ 邮件 │ 应用市场 │ MCP    │   │
│  └──────────────────────────────────────────────┘   │
└──────────────────┬───────────────────────────────────┘
                   │
┌──────────────────┴───────────────────────────────────┐
│              核心引擎层 (lib/)                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐    │
│  │栈检测器   │ │部署运行时 │ │  路由系统         │    │
│  │(32KB)    │ │(16KB)    │ │  域名+SSL+CDN    │    │
│  └──────────┘ └──────────┘ └──────────────────┘    │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐    │
│  │认证系统   │ │邮件服务器 │ │  任务调度器       │    │
│  │(35KB)    │ │(15KB)    │ │  (BullMQ+Redis)  │    │
│  └──────────┘ └──────────┘ └──────────────────┘    │
└──────────────────┬───────────────────────────────────┘
                   │
┌──────────────────┴───────────────────────────────────┐
│              适配器层 (packages/adapters/)             │
│      Docker API │ SSH 远程 │ S3 对象存储 │ 云运行时     │
└──────────────────┬───────────────────────────────────┘
                   │
┌──────────────────┴───────────────────────────────────┐
│              基础设施层                                │
│   PostgreSQL 16 │ Redis 7 │ Docker │ 文件系统         │
└──────────────────────────────────────────────────────┘

4.3 核心模块介绍

模块 路径 大小 功能
技术栈检测器 lib/project-root-detector.ts 32KB 自动识别项目技术栈，兼容第三方平台配置
认证系统 lib/auth.ts 35KB 基于 better-auth 的统一认证，支持 GitHub/Google OAuth、设备码、PAT Token
部署运行时 lib/deployment-runtime.ts 16KB 管理部署生命周期：构建、打包、推送镜像、启动容器、健康检查、回滚
路由系统 lib/routing-domains.ts 17KB 域名解析、SSL 证书（Let's Encrypt）、反向代理配置生成
Docker Compose 解析器 lib/compose-parser.ts 19KB 完整的 Docker Compose 文件解析器，支持直接部署现有 compose 文件
邮件服务 lib/mail.ts 15KB 内置 SMTP 服务器，支持 DKIM/SPF/DMARC
云认证代理 lib/cloud-auth-proxy.ts 22KB SaaS 模式下的多租户认证代理
权限系统 lib/permission.ts 18KB 基于角色的访问控制（RBAC）
任务调度器 lib/job-runner/ — 基于 BullMQ 的异步任务调度
缓存存储 lib/cache-store/ — 多层缓存策略
限流 lib/rate-limit/ — API 请求频率限制
Git 转发 lib/git-forwarding/ — Git 仓库代理与加速

4.4 核心代码解析

4.4.1 技术栈自动检测（project-root-detector.ts）

// 技术栈检测的核心逻辑
// 通过扫描项目根目录中的特征文件，自动识别项目类型：
//
// 检测规则示例：
// - package.json 存在 → Node.js 项目
//   进一步检查：next.config.* → Next.js, vite.config.* → Vite
// - pyproject.toml 存在 → Python 项目
//   进一步检查：django 依赖 → Django, fastapi 依赖 → FastAPI
// - go.mod 存在 → Go 项目
// - Cargo.toml 存在 → Rust 项目
// - Gemfile 存在 → Ruby 项目
// - composer.json 存在 → PHP 项目
// - pom.xml / build.gradle → Java 项目
// - *.csproj / *.sln → .NET 项目
//
// 兼容读取第三方平台配置：
// - railway.toml → Railway 配置
// - vercel.json → Vercel 配置
// - openship.json → Openship 自定义配置

4.4.2 部署运行时（deployment-runtime.ts）

// 部署生命周期管理
// 核心流程：
// 1. 源码拉取 → 克隆仓库或拉取最新 commit
// 2. 技术栈检测 → 调用 project-root-detector 确定构建策略
// 3. 构建阶段 → 生成 Dockerfile，执行 docker build
// 4. 镜像推送 → 推送到内置或外部镜像仓库
// 5. 容器启动 → 配置端口映射、环境变量、数据卷
// 6. 健康检查 → 轮询应用端口，确认启动成功
// 7. 域名绑定 → 配置反向代理和 SSL 证书
// 8. 旧版本清理 → 停止旧容器，执行回滚（如需要）

4.4.3 认证系统（auth.ts）

// 基于 better-auth 的统一认证系统
// 支持的认证方式：
// - GitHub OAuth：开发者首选
// - Google OAuth：团队协作
// - 设备码登录（Device Code）：CLI 和桌面应用
// - PAT（Personal Access Token）：API 和 CI/CD
// - 内部 API Token：服务间认证
// - 会话管理：JWT + Refresh Token
// 安全特性：多因素认证、会话超时、IP 绑定

4.4.4 双模式运行机制

// 通过 CLOUD_MODE 环境变量切换运行模式
// CLOUD_MODE=false（自托管模式）：
//   - 单用户/单租户
//   - 数据完全本地存储
//   - 不需要 Stripe、GitHub App 等外部服务
//   - 开源免费，无功能限制
//
// CLOUD_MODE=true（SaaS 云模式）：
//   - 多租户支持
//   - 需要配置 GitHub App（OAuth + Webhook）
//   - 需要配置 Stripe（计费）
//   - 需要配置 Oblien 凭证（云运行时）
//   - 适合商业运营

4.4.5 适配器模式（packages/adapters）

// 适配器层封装基础设施操作，API 层不直接依赖底层实现
// Docker 适配器：dockerode 封装，容器生命周期管理
// SSH 适配器：ssh2 封装，远程服务器命令执行
// S3 适配器：AWS SDK 封装，对象存储操作
// 云运行时适配器：oblien SDK 封装，云服务管理
//
// 通过适配器模式，可在不同基础设施之间自由切换：
// - 开发环境：本地 Docker
// - 单服务器：Docker + 本地文件系统
// - 多服务器：SSH + S3 对象存储
// - 云环境：Oblien 云运行时

五、项目应用与评价

5.1 应用场景

场景 说明
独立开发者 零配置部署个人项目/SaaS 产品，桌面应用一键管理，无需学习 DevOps
小型团队 自托管在 VPS 上，低成本统一管理团队所有项目，无需第三方平台订阅费
家庭实验室 在自家 NAS/服务器上一键部署 Gitea、Vaultwarden、FreshRSS 等自托管应用
CI/CD 替代 不需要编写 GitHub Actions / GitLab CI 配置文件，Push-to-deploy 开箱即用
AI Agent 集成 通过 MCP 协议让 AI 代理自动管理部署和基础设施，实现智能运维
多项目统一管理 一个 Dashboard 管理所有项目，包括数据库、域名、SSL、备份、监控
企业内网部署 在内网服务器上部署私有实例，安全可控，数据不出企业
教学/培训 零配置特性适合编程教学，学生无需配置复杂环境即可部署项目

5.2 项目优点

  1. 真正的零配置：不需要写 Dockerfile、docker-compose.yml、CI/CD 配置文件，自动检测技术栈并构建部署。
  2. 全功能一体化：集成了 CI/CD、数据库、域名、SSL、CDN、邮件、备份、监控，无需额外配置第三方服务。
  3. 三种界面选择：桌面应用（Electron）、Web Dashboard（Next.js）、CLI（npm），覆盖不同使用习惯。
  4. 完全自托管：数据完全在自己服务器上，不依赖第三方平台，无厂商锁定风险。
  5. Apache 2.0 协议：对商业使用非常友好，可以闭源分发，无 GPL 限制。
  6. MCP 协议集成：前瞻性地支持 AI 代理自动化，可让 AI 助手管理部署和基础设施。
  7. 多语言支持：9 种语言的 README 翻译和界面国际化，覆盖全球用户。
  8. 内置邮件服务器：自带 SMTP，支持 DKIM/SPF/DMARC，无需 Mailgun/SES 等第三方邮件服务。
  9. 应用市场：15+ 一键安装的流行自托管应用，降低常用工具的部署门槛。
  10. 标准 Docker 容器：可在不同服务商之间自由迁移，保持可移植性。

5.3 项目不足

  1. 版本仍处于早期：v0.3.0，API 可能不稳定，文档标注为"仍在建设中"。
  2. 文档不完善：README 中明确标注"文档仍在积极填充中，某些内容可能缺失或不清晰"。
  3. 社区规模有限：30 名贡献者，35 个 open issues，生态尚未成熟，遇到问题可能缺乏社区支持。
  4. 功能尚未完成：计划中的多节点集群、负载均衡 UI、私有网络、高级监控、可视化 CI/CD 流水线均未实现。
  5. Node.js 版本要求高：要求 Node.js >= 22，对旧环境（如 LTS 发行版）的兼容性不佳。
  6. Bun 深度绑定：项目使用 Bun 作为包管理器和构建工具，对非 Bun 用户的开发体验不佳。
  7. 无官方中文文档：虽然 README 有中文翻译，但完整文档（openship.io/docs）仍以英文为主。
  8. SaaS 模式复杂度高：CLOUD_MODE 需要配置 GitHub App、Oblien 凭证、Stripe 等，自托管以外的云模式门槛较高。
  9. 无移动端支持：桌面应用仅支持 macOS/Linux/Windows，无 iOS/Android 客户端。

参考来源

posted @ 2026-07-25 00:06  zhang-yd  阅读(19)  评论(0)    收藏  举报