Openship CI/CD完全指南：GitHub Webhook推送即部署实战（新手友好）
【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship
Openship是一款自托管（Self-hosted）部署平台，支持从 GitHub 仓库一键发布应用，并内置GitHub Webhook能力：开启自动部署后，每次git push都会自动触发重新构建与上线，让自托管 CI/CD 像 PaaS 一样简单。本文用大白话带你跑通"连接仓库 → 首次部署 → 推送即部署"的完整实战流程，零 Docker 经验也能上手。
为什么选 Openship 做自托管 CI/CD？
传统 CI/CD 要自己搭流水线、写 YAML、管理构建机器。而 Openship 把这件事压缩成三步：
| 能力 | 说明 |
|---|---|
| 🔗 自动识别框架 | Next.js、Nuxt、Go、Python 等，自动填好构建命令 |
| 🚀 推送即部署 | 绑定 GitHub Webhook，push 到部署分支自动重新发布 |
| 🏠 自托管 | 部署到你自己的服务器，数据和代码都在自己手里 |
| 📡 统一 Webhook 入口 | 所有外部事件（GitHub、备份触发等）走同一条安全通道 |
核心原理：Webhook 推送即部署是怎么回事？
一句话：GitHub 主动打电话告诉 Openship"代码变了"，Openship 收到后立即重新构建上线。
流程如下：
- 首次部署时，Openship 自动在你的仓库上注册一个push Webhook，指向自己；
- 每次你
git push，GitHub 把事件签名后 POST 到/api/webhooks/github； - Openship 用HMAC-SHA256校验签名，确认是 GitHub 发来的合法请求；
- 匹配"仓库 + 分支"，命中已开启自动部署的项目，立即触发重新构建；
- 构建完成后自动切换流量，你的新代码就上线了。
这套入口的安全细节（签名验证、防重放、防重复部署）都在 webhook.controller.ts 与 github.webhook.ts 中实现，每个项目的 Webhook 密钥独立加密存储，伪造请求会被直接拒绝。
快速上手：三步跑通推送即部署
第一步：连接 GitHub 账号（只需一次）
进入仪表盘Settings → Git，选择 GitHub 连接方式。自托管实例有三种选择（详见 deploy-from-github.mdx）：
- Openship Cloud GitHub App：托管式 App，适合远程服务器部署；
- 自建 GitHub App：一键注册，不依赖云服务；
- 手动方式：用本机
ghCLI 登录、OAuth 设备码登录，或添加一个 Clone Token。
授权完成后，你的仓库列表就会出现在Library → Repositories页面中。
第二步：选择仓库并首次部署
点击目标仓库，选择运行位置（Local / Server / Cloud三选一，新手选默认即可），检查右侧摘要面板：检测到的框架、构建命令、域名（如mdx-portfolio.oshp.io）都自动配好了。
点击Deploy，构建日志会实时流式输出，完成后直接给出线上地址。相关配置逻辑源码见 project.controller.ts，API 定义见 github.mdx。
第三步：打开自动部署开关
进入项目 →Source标签页 → 打开Auto-deploy。从此每次 push 到部署分支，都会自动重新构建并发布——这就是推送即部署的核心体验。
进阶：Webhook 事件背后的"聪明"细节
1. 只部署你关心的分支
Webhook 处理器会先过滤掉 tag 推送、分支删除等无关事件，只处理refs/heads/*分支推送，再把"仓库 + 分支"与项目里配置的部署分支做匹配（webhook-push.ts）。没匹配上的推送会被静默忽略，不会误触发构建。
2. Monorepo 智能路由：只重建受影响的服务
如果你的仓库是多服务/Compose 项目，Openship 会分析这次 push改了哪些文件，只重新部署受影响的服务，而不是全量重建。这个"变更加路由"的逻辑在 webhook-changed-files.ts 中实现，能大幅节省服务器资源。
3. 签名安全与多密钥校验
每收到一个 push 事件，Openship 会收集该仓库所有关联项目的 Webhook 密钥逐一尝试验签——因为同一个仓库可能被多个项目（不同环境/分支）引用，任一密钥匹配成功即放行，全部失败则返回 401 拒绝。HMAC 工具函数见 webhook.service.ts。
4. 部署失败也有通知
自动部署若在建单前就失败，系统会以组织所有者身份发出deployment.failed通知，确保你不会"push 了却没上线还毫不知情"。
顺手一学：CLI 也能触发 CI/CD
偏好终端的读者可以用官方 CLI 完成同样操作，命令与构建命令一览见 cli-commands.mdx，源码入口在 apps/cli/src/commands/。
常见问题 FAQ
Q1：不开自动部署，还能用 Webhook 吗？可以。Webhook 主要用于自动部署；你也可以单独用POST /api/webhooks/backup（Bearer Token 鉴权）从外部系统触发备份，见 backups.mdx。
Q2：伪造的 Webhook 请求会触发部署吗？不会。所有请求必须通过 HMAC-SHA256 签名校验，密钥按项目加密存储；且处理过程中即使内部出错也返回 200，避免 GitHub 重试造成重复部署。
Q3：本地仓库没有 GitHub 也能部署吗？可以。不连 GitHub 时，直接点 Deploy 手动发布即可，只是少了"推送即部署"的自动化。
总结
- ✅Openship把自托管 CI/CD 简化为：连 GitHub → 点 Deploy → 打开 Auto-deploy；
- ✅ 统一 Webhook 入口 + 按项目加密的签名密钥，安全不输商业 PaaS；
- ✅ Monorepo 智能路由、失败通知、CLI 支持，细节拉满；
- ✅ 代码、域名、数据全部留在自己的服务器上。
按照 installation.md 把 Openship 部署到自己的机器上，然后照着上面的三步走，今晚就能拥有"push 即上线"的私人 PaaS。
【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
