1. 为什么我又折腾了一个自托管部署平台第一次接触 Vercel 那种「push 代码就自动上线、每个分支都有独立预览地址」的体验时我确实被惯坏了。后来手上项目变多有些是公司内网服务有些是客户要求数据必须落在自己机房还有些纯粹是我自己想省点托管费于是「把 Vercel 的体验搬回自己服务器」这件事就反复被提上日程。Openship 就是我在这个背景下挖到的一个自托管部署平台它的定位很直接你有一台自己的服务器装好 Docker它帮你把 Git 仓库到线上服务的整条链路管起来包括构建、部署、域名、HTTPS、回滚这些琐事。这篇文章不是官方文档的搬运而是我把它从零跑起来、踩了几个坑、又拿它部署了两三个真实项目之后的一份实操记录。我会讲清楚它到底解决了什么问题、核心链路是怎么设计的、Docker 和 OpenResty 在里面各扮演什么角色、以及那些文档里不会写但实际一定会遇到的坑。适合谁看如果你已经会用 Docker、懂一点 Linux 和 Nginx/OpenResty又想给自己的项目搞一套「私有版 Vercel」那这篇基本可以照着抄。如果你连 Docker 都没装过建议先把 Docker 基础过一遍再回来不然中间很多环节会卡住。先说结论性的判断Openship 这类自托管部署平台的价值不在于它比 Vercel 功能更强而在于控制权。代码、构建产物、运行环境、数据全在你自己手里代价是你得自己维护服务器、自己处理证书续期、自己扛住流量。这笔账划不划算取决于你的项目性质而不是平台本身好不好。2. Openship 到底是个什么东西2.1 一句话拆解它的核心能力把 Openship 拆开看它本质上是一个「Git 驱动的部署编排器」。你给它一个仓库地址它负责拉代码、识别项目类型、跑构建命令、把产物打成镜像或静态文件、再通过反向代理暴露出去。整个过程和你熟悉的 Vercel 工作流几乎一致连仓库、配环境变量、点部署、拿域名。它和纯 CI/CD 工具比如 Jenkins、GitLab CI的区别在于抽象层级。Jenkins 给你的是「流水线原语」你得自己写每一步Openship 给你的是「部署原语」构建、发布、路由、证书这些它已经封装好了你只需要填几个关键参数。这也是为什么它敢说自己「把 Vercel 的体验搬过来」——它卖的是开箱即用的部署体验不是无限灵活的流水线。2.2 它和 Vercel、Netlify 的本质差异很多人第一反应是「这不就是个开源的 Vercel 吗」。功能层面确实像但底层逻辑完全不同。Vercel 是托管服务你的代码跑在它的边缘网络上构建也在它的机器上完成Openship 是自托管所有东西都跑在你自己那台机器上。这个差异带来几个直接后果。第一构建资源由你决定你服务器 CPU 强、内存大构建就快反之就慢没有平台帮你弹性扩容。第二网络位置由你决定用户访问速度取决于你服务器所在机房和带宽而不是全球边缘节点。第三数据合规由你掌控这对很多有数据落地要求的场景是刚需。第四成本模型变了从按量付费变成固定服务器成本流量小的项目反而更贵流量大的项目可能省很多。所以别把 Openship 当成「免费 Vercel」它更像是「用一台服务器换一套部署体验」。想清楚这个前提后面的取舍就顺了。2.3 技术栈里 Docker 和 OpenResty 的分工Openship 的运行时底座是 Docker这点很关键。每个部署单元最终都会变成一个或多个容器构建在容器里跑运行也在容器里跑隔离性和可复现性都靠它。你服务器上装好 Docker 和 Docker Compose基本就满足了运行前提。反向代理层用的是 OpenResty也就是 Nginx 加 Lua 的那套组合。为什么不用裸 Nginx因为动态路由、证书自动签发、按域名分流这些逻辑用 Lua 在 OpenResty 里处理比反复改 Nginx 配置文件优雅得多。你访问服务时看到的 443、80 端口背后就是 OpenResty 在转发。顺带提一句很多人搜「403 forbidden openresty」就是因为代理配置里目录权限或 root 路径写错了这个后面排查章节会细讲。3. 部署前的环境准备与关键决策3.1 服务器规格怎么选才不踩坑这是最容易被低估的一步。Openship 本身不重但你的项目构建可能很吃资源。我的经验是构建峰值内存至少按项目最重的那次构建来估。一个中等规模的 Node 前端项目构建时 Node 进程吃到 1.5G 到 2G 内存很常见如果你服务器只有 2G 内存构建大概率被 OOM Killer 干掉表现为「构建莫名其妙失败日志里啥也没有」。我的推荐配置分三档。个人玩具项目、纯静态站2 核 2G 够用但要开 swap。中小型全栈项目2 核 4G 是舒适区。要跑多个项目、还带数据库的直接上 4 核 8G别省这个钱。磁盘方面Docker 镜像和构建缓存很占空间40G 起步建议 80G 以上否则跑几个月就得手动清镜像。提示如果你在 Windows 上用 Docker Desktop 做本地测试遇到「virtualization support not detected」或「failed to start because virtualization support wasnt detected」先去 BIOS 里把虚拟化VT-x / AMD-V打开这是最常见的原因和 Openship 本身无关。3.2 Docker 安装与几个必调参数Linux 上装 Docker 现在很省事官方脚本一把梭curl -fsSL https://get.docker.com | sh sudo systemctl enable --now docker装完别急着往下走有几个参数必须调。第一日志驱动和大小限制。Docker 默认的 json-file 日志会无限增长跑久了能把磁盘吃满。在/etc/docker/daemon.json里加上{ log-driver: json-file, log-opts: { max-size: 50m, max-file: 3 } }第二镜像加速。国内拉镜像慢是常态配好镜像源能省大量时间。第三把当前用户加进 docker 组否则每条命令都要 sudosudo usermod -aG docker $USER改完记得重新登录生效。这里有个高频坑很多人改完没重登然后一直报 docker 权限错误以为是配置没生效其实是会话没刷新。3.3 域名与证书的前置规划Openship 要接管域名和 HTTPS所以你得提前把 DNS 规划好。我的做法是准备一个泛解析记录比如*.deploy.example.com指向服务器 IP这样每个项目分配一个子域名不用每次手动加解析。证书方面Openship 一般走 ACME 自动签发前提是 80 端口能被外部访问到用于域名验证。这里有个容易忽略的点如果你的服务器前面还有一层云厂商的负载均衡或 CDN80 端口的验证请求可能到不了 Openship。要么把验证路径透传要么改用 DNS 验证方式。我一开始就是卡在这证书一直签不下来排查半天才发现是上游把 80 端口拦了。4. 核心链路拆解从 Git 到线上服务4.1 构建阶段识别项目类型与产物Openship 拿到仓库后第一件事是判断这是个什么项目。常见类型有静态站、Node 服务、Python 服务、Dockerfile 项目等。判断逻辑一般基于仓库里的标志文件比如有package.json就当 Node 项目有Dockerfile就优先用 Dockerfile 构建。这一步的实操要点是构建命令和环境变量。以 Node 项目为例构建命令通常是npm ci npm run build注意用ci而不是install前者严格按 lock 文件装依赖可复现性更好。环境变量分两类构建时变量和运行时变量。前端项目里NEXT_PUBLIC_或VITE_开头的变量是在构建时被「烧」进产物的改了必须重新构建后端服务的数据库连接串这类是运行时注入的改了重启即可。搞混这两类会出现「我明明改了配置怎么没生效」的经典问题。4.2 镜像与容器部署单元的落地构建完成后产物会被打成镜像或直接作为静态文件挂载。Dockerfile 项目的流程最直观docker build出镜像docker run起容器。非 Dockerfile 项目Openship 会用内置的模板生成镜像比如 Node 服务用官方 node 基础镜像加你的产物。这里我强烈建议自己写 Dockerfile哪怕平台能自动生成。原因有三一是多阶段构建能把镜像从几百兆压到几十兆二是你能精确控制基础镜像版本避免某天平台模板升级导致构建行为变化三是排查问题时你对自己的镜像结构心里有数。一个典型的多阶段 Node 构建长这样FROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build FROM node:20-alpine WORKDIR /app COPY --frombuilder /app/dist ./dist COPY --frombuilder /app/node_modules ./node_modules EXPOSE 3000 CMD [node, dist/server.js]4.3 路由与代理OpenResty 怎么把请求送对地方容器起来后监听的是内部端口外部访问要靠 OpenResty 转发。Openship 会为每个部署生成一段路由配置把域名映射到对应的容器端口。这块的核心是域名到服务的映射关系和证书绑定。实际使用中我建议给每个项目分配独立子域名而不是用路径前缀区分。原因很简单路径前缀会让前端资源引用、Cookie 作用域、CORS 配置都变复杂子域名则天然隔离。OpenResty 处理子域名转发时server_name写具体域名proxy_pass指向容器地址即可。如果你遇到 403 forbidden八成是root指向的目录权限不对或者index文件不存在先查这两处。4.4 发布与回滚怎么做到「一键切回上一版」这是自托管平台最容易被做砸的地方。好的发布流程应该是原子切换新版本容器先起来、健康检查通过、再把流量切过去旧容器保留一段时间以便回滚。Openship 的思路基本是这个但具体实现依赖它怎么管理容器和路由。我的实操建议是永远保留最近两到三个版本的镜像别让清理策略把旧镜像全删了。回滚时如果镜像还在切回去就是秒级的事如果镜像没了就得重新构建那回滚就变成了「重新部署一个旧 commit」体验差很多。另外数据库迁移这类有状态操作要单独考虑回滚代码不等于回滚数据这点必须提前想清楚。5. 完整实操从零部署一个真实项目5.1 服务器初始化与 Openship 安装假设你有一台干净的 Ubuntu 22.04 服务器第一步装 Docker按前面 3.2 的步骤来。装完验证docker --version docker compose version两个命令都有输出说明环境 OK。接着拉 Openship 的部署文件。这类自托管平台通常提供 docker compose 方式安装大致流程是下载 compose 文件和配置模板改几个关键变量然后docker compose up -d。关键变量一般包括管理后台的访问域名、管理员账号密码、数据存储路径、以及 ACME 证书用的邮箱。数据存储路径一定要挂到宿主机上别用容器内的匿名卷否则容器重建数据就没了。我一般挂到/opt/openship/data这种固定路径方便备份。5.2 接入 Git 仓库与首次部署进管理后台添加 Git 仓库。这里有两种方式公开仓库直接填地址私有仓库需要配访问凭证。私有仓库建议用部署密钥或访问令牌别用账号密码令牌权限也尽量收窄到只读。添加仓库后Openship 会让你选分支、配构建命令、填环境变量。第一次部署我建议先用最简单的项目试水比如一个纯静态 HTML 站确认整条链路通了再上复杂项目。这样出问题时变量少好排查。首次部署的日志要盯紧。构建阶段看依赖装没装上、构建命令有没有报错运行阶段看容器起没起来、健康检查过没过路由阶段看域名解析对不对、证书签没签下来。这三段任何一段出问题表现都是「部署失败」但原因完全不同。5.3 环境变量与密钥管理环境变量是部署里最容易出事的地方。我的原则是敏感信息只放运行时变量绝不进代码仓库。数据库密码、API 密钥、JWT secret 这些全部通过平台的环境变量功能注入。还有个细节环境变量里的特殊字符要转义。比如密码里带$或#在某些 shell 解析场景下会被当成变量或注释导致实际注入的值和你以为的不一样。我踩过一次数据库密码里有个$结果连接一直失败排查半天才发现是变量被提前展开了。解决办法是用单引号包裹或者干脆避免在密码里用这些字符。5.4 绑定域名与 HTTPS 生效域名绑定分两步DNS 解析和平台配置。DNS 那边加一条 A 记录或泛解析指向服务器 IP平台这边填上域名等证书签发。证书签发通常几十秒到几分钟取决于 ACME 服务的响应速度。验证 HTTPS 是否生效别只看浏览器绿锁用命令行更靠谱curl -I https://your-app.example.com看返回头里有没有正常的 200以及证书信息对不对。如果返回 403回到 4.3 那节查 OpenResty 配置如果连接超时查防火墙和安全组有没有放行 443。6. 常见问题与排查技巧实录6.1 构建失败类问题速查构建失败是最常见的一类表现是日志里报错然后流程中断。我整理了一张速查表覆盖我实际遇到过的几种现象可能原因排查方向构建进程被杀死无明确报错内存不足触发 OOM加 swap 或升配看dmesg有无 oom 记录依赖安装超时镜像源慢或网络不通换镜像源检查服务器出网构建命令找不到基础镜像里没这个命令换基础镜像或自己写 Dockerfile构建成功但产物为空构建输出目录配错核对dist/build等输出路径OOM 这个特别隐蔽因为日志里往往只有一句「Killed」没有任何堆栈。判断方法是在构建时另开一个终端跑dmesg -T | tail如果看到 oom-killer 相关记录基本就实锤了。6.2 运行与网络类问题排查容器起来了但访问不通这类问题排查顺序很重要。我的习惯是从内到外先进容器看服务本身通不通再看容器端口映射最后看 OpenResty 转发。# 进容器 docker exec -it container sh # 容器内自测 curl localhost:3000容器内能通、外部不通问题就在代理层或防火墙。容器内就不通问题在应用本身看应用日志。这个顺序能帮你快速定位问题在哪一层避免瞎猜。6.3 证书与域名类问题证书签不下来最常见三个原因80 端口不通、DNS 没生效、域名被上游拦截。排查时先dig一下域名看解析对不对再curl一下 80 端口看能不能通。如果服务器前面有 CDN 或负载均衡记得验证请求要能透传到 Openship。还有个坑是证书续期失败。ACME 证书一般 90 天有效期自动续期依赖定时任务。如果续期任务因为某种原因挂了某天你会突然发现网站证书过期。建议加个监控证书剩余天数少于 15 天就告警。6.4 我踩过的几个真实坑第一个坑是磁盘被镜像撑满。跑了两三个月某天部署突然失败一查磁盘 100%。原因是旧镜像和构建缓存没清理。解决办法是配定期清理策略docker system prune要慎用会删掉所有未使用资源最好用带过滤条件的版本保留最近几个版本。第二个坑是环境变量改了没生效。前端项目改了VITE_变量重新部署还是旧值。原因是这类变量在构建时被烧进产物必须触发重新构建光重启容器没用。这个坑我踩了不止一次后来养成习惯改前端环境变量一定手动触发一次完整构建。第三个坑是回滚时发现旧镜像没了。有次线上出问题想回滚结果清理策略把旧镜像删了只能重新构建旧 commit多花了好几分钟。从那以后我把镜像保留数量调到 5宁可多占点磁盘。7. 自托管部署的取舍与我的实际体会用了一段时间 Openship我对「自托管部署平台」这件事有了更清醒的认识。它确实能把 Vercel 那套体验搬回来但搬回来的只是体验不是 Vercel 背后的基础设施。你的构建速度取决于你的服务器你的可用性取决于你的运维水平你的访问速度取决于你的机房。这些是自托管的固有代价不是 Openship 的锅。反过来说如果你需要数据落地、需要成本可控、需要完全掌控运行环境那这套方案的价值就体现出来了。我现在把几个内部工具和客户项目都放在上面日常 push 代码自动部署体验和用 Vercel 差别不大但数据全在自己手里心里踏实。最后分享一个我一直在用的小技巧给每个项目配一个健康检查端点比如/healthz返回 200 就行。Openship 发布时可以用它判断新版本是否真的起来了避免把流量切到一个起不来的容器上。这个端点实现成本极低但能挡掉很多「部署成功但服务不可用」的尴尬情况。另外服务器上的 Docker 和 Openship 本身也要定期更新安全补丁这东西平时不觉得出事就晚了。