Wasp 应用自托管部署实战从架构设计到服务器落地【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp本指南基于 Wasp 官方文档 self-hosted.md 展开系统讲解如何将 Wasp 全栈应用部署到自有或租用的服务器上。读完本文你将掌握 Wasp 自托管的三条捷径Caprover、Coolify、VPS Docker、手动部署的完整链路构建产物、环境变量、数据库、静态客户端、反向代理并能结合仓库源码理解wasp build生成物的实际形态。为什么选择自托管自托管意味着你把 Wasp 应用部署在自己拥有或租用的服务器上例如 AWS、DigitalOcean、OVH、Hetzner 等云厂商的 VPS而不是交给 PaaS 平台托管。完全控制权应用与数据的所有权、运行环境、版本升级节奏都由你决定成本更优一台服务器可以同时部署多个应用摊薄服务器成本代价是运维你需要自己管理服务器处理系统更新、安全补丁、数据库备份、故障恢复这需要一定的技术积累和持续的时间投入。如果既想要自动化部署又不想完全依赖云厂商仓库还提供了两条半托管路线Caprover自托管 PaaS和Coolify自托管部署平台详见下文。三种开箱即用的自托管指南Wasp 官方为最常见的自托管方式准备了逐步指南全部位于 web/docs/guides/deployment/self-hosted 目录指南技术栈适合场景Deploying Wasp with Docker on your serverUbuntu Git Caddy Docker想亲手掌控每一层学习完整部署原理Deploying Wasp with Caprover on your serverCaprover GitHub Actions GHCR想要 PaaS 体验但又自己持有服务器Deploying Wasp with Coolify on your serverCoolify GitHub Actions GHCR想要 Web UI 管理、自带部署 Webhook如果你的目标提供方不在列表中也不必担心——Wasp 应用本质上就是Node.js 服务器 静态前端 PostgreSQL 数据库三件套只要服务器/平台能承载这三者就一定能部署参见 cloud-providers.md。方案一VPS Docker Caddy最底层的自托管VPS 指南Wasp 0.24、Caddy 2.10.2、Ubuntu 24.04 LTS 验证完整演示了SSH 连接服务器安装 Caddy 与 Docker用 UFW 配置防火墙先ufw allow ssh再ufw enable避免把自己锁在门外配置 GitHub Deploy Key 并git clone私有仓库用 nvm 安装 Node.js、npm i -g wasp.sh/wasp-cli安装 Wasp CLI并把它加入~/.bashrc的 PATH项目内执行wasp install与wasp build创建 Docker 网络与 PostgreSQL 容器构建并运行 server 镜像用 Vite 构建静态客户端交给 Caddy 托管配置 Caddyfile让myapp.com服务前端、api.myapp.com反向代理到后端。方案二Caprover / Coolify自托管 PaaSCaprover 与 Coolify 两条路线的核心模式一致用 GitHub Actions 在 CI 里完成构建并推送镜像到 GitHub Container Registry再由平台拉取部署。两者的工作流文件几乎相同可在 caprover.md 与 coolify.md 中对照关键环节包括在平台上创建三个资源PostgreSQL 数据库、myapp-server暴露端口 3001、myapp-client暴露端口 8043客户端镜像使用pierrezemb/gostatic作为基础镜像用200.html作为 SPA 回退文件配置 GitHub SecretsCaprover 需要CAPROVER_SERVER与各 app tokenCoolify 需要两个 Deploy Webhook 与COOLIFY_TOKEN推送main分支即触发全自动构建、推送、部署。手动部署的架构总览不借助上述平台自己一步步部署时整体架构如下来自 web/static/img/deploying/self-hosting.png手动部署遵循六个一般步骤从应用源码出发让 Wasp 分别构建出服务器应用与客户端应用在服务器上配置服务器环境变量在服务器上运行数据库或使用托管数据库服务以 Docker或不以 Docker方式运行服务器应用用静态文件服务器托管客户端应用配置反向代理让应用通过域名 HTTPS 对外提供服务。这张图也揭示了一个要点自托管时反向代理是请求入口的核心它既要服务客户端的静态文件也要把 API 请求转发给后端同时还负责终止 TLS。手动部署分步实操前置准备一台具有公网 IP 的服务器任何主流云厂商的 VPS 均可一个域名例如myapp.comHTTPS 证书签发与浏览器安全提示都依赖域名纯 IP 无法获得受信任的证书。服务器环境搭建在服务器上依次安装三类工具Docker用于运行服务器应用和数据库容器Node.js建议用 nvm 安装版本需满足 Wasp 的最低 Node.js 版本要求Wasp CLInpm i -g wasp.sh/wasp-cli安装后确认wasp version可正常执行。获取应用源码推荐使用 Git克隆仓库后每次发布新版本只需git pull拉取最新代码再重新构建。构建应用产物wasp build 做了什么在项目根目录依次执行wasp install wasp buildwasp build会把整个应用的可部署代码生成到.wasp/out/目录该命令同样在 cloud-providers.md 中被定义。从源码结构看这个目录里包含两类关键产物服务器应用目录根部的Dockerfile定义了构建与运行 server 的多阶段镜像其中会执行待处理的数据库迁移客户端应用位于.wasp/out/web-app需要进一步用 Vite 构建成静态文件输出到.wasp/out/web-app/build。注意wasp build默认假设生产环境使用 PostgreSQL。如果项目还在使用默认的 SQLite需要在部署前先迁移到 PostgreSQL否则无法完成生产构建。如果需要查看可能被自定义内容合并后的最终 Dockerfile 长什么样可以运行wasp dockerfile预览详见 deployment overview。配置生产环境变量开发时使用的.env.server/.env.client在生产构建中会被忽略参见 deployment/env-vars.md必须显式提供。服务器应用所需的核心变量如下完整定义见 project/env-vars.md变量类型是否必填说明DATABASE_URLString是PostgreSQL 数据库连接串例如postgresql://postgres:mysecretpasswordmyapp-db:5432/myappJWT_SECRETString是至少 32 字符的随机字符串用于生成安全令牌开发环境默认DEVJWTSECRET生产必须更换PORTInteger是服务器监听的端口生产环境建议3001WASP_WEB_CLIENT_URLURL是客户端地址用于邮件内链接等场景例如https://myapp.comWASP_SERVER_URLURL是服务器地址OAuth 登录回调依赖它例如https://api.myapp.com缺任一必填变量服务器都会拒绝启动。此外若应用使用了 SMTP / SendGrid 邮件发送或 OAuth 社交登录还需按 project/env-vars.md 配置对应的SMTP_*、SENDGRID_API_KEY、OAuth 凭证等变量。客户端环境变量的处理方式完全不同它们会在构建期被内联注入到静态 JS 中因此任何人可见绝不能放密钥。构建客户端时必须通过命令行提供例如REACT_APP_API_URLhttps://api.myapp.com npx vite build构建产物位于.wasp/out/web-app/build/根部的200.html充当 SPA 回退文件。注意在托管平台/服务器上给静态文件设置环境变量是无效的——构建完成后代码里已经是写死的值。启动数据库自托管默认把数据库跑在服务器上有两种选择服务器本地 Docker 运行例如创建独立网络后启动 PostgreSQL 容器并把DATABASE_URL指向容器名如myapp-db:5432便于容器间通信托管数据库服务如 AWS RDS、DigitalOcean Managed Databases、Supabase备份、升级、扩缩容由服务商负责成本更高但省去运维。选择本地自管时必须自行负责备份——建议配置 PostgreSQL 周期性备份并/或对服务器磁盘做快照以防服务器故障时数据无法恢复。以 Docker 运行服务器应用进入.wasp/out目录构建镜像并启动容器cd .wasp/out docker build . -t myapp-server启动时通过--env-file传入生产环境变量文件并只绑定到回环地址确保后端不直接暴露公网docker run -d \ --name myapp-server \ --env-file .env.production \ -p 127.0.0.1:3001:3001 \ --network myapp-network \ myapp-server用curl -I http://localhost:3001验证应返回200 OK。也可以不借助 Docker 直接运行 Node 进程但需要自行复刻Dockerfile中的全部设置。构建并托管客户端静态文件在项目根目录执行REACT_APP_API_URLhttps://api.myapp.com npx vite build把.wasp/out/web-app/build/下的全部静态文件拷贝到 Web 服务器目录例如/var/www并确保 Web 服务器进程有读取权限。配置反向代理与域名反向代理是自托管链路的关键一环Nginx、Caddy、Traefik 都是成熟选择。域名建议按如下方式拆分myapp.com给客户端api.myapp.com给服务器并在 DNS 中把两条 A 记录都指向服务器 IP。以 Caddy 为例完整示例见 VPS 指南myapp.com { root * /var/www encode gzip try_files {path} /200.html file_server } api.myapp.com { reverse_proxy localhost:3001 }Caddy 会自动签发并续期 HTTPS 证书try_files {path} /200.html保证前端路由刷新时不 404。更新与降低停机时间手动部署的更新流程可以固化成脚本git pull→wasp build→ 重建镜像 → 停旧容器 → 起新容器 → 重新构建并拷贝客户端静态文件。为了让重启期间请求不报错可以让 Caddy 对后端做健康检查并等待其恢复api.myapp.com { reverse_proxy localhost:3001 { health_uri / lb_try_duration 15s } }这样 Caddy 会在服务器重启时最多等待 15 秒再恢复转发显著减少可见停机。进一步定制Dockerfile 扩展钩子如果默认生成的多阶段 Dockerfile 满足不了需求可以在项目根目录放一个自定义DockerfileWasp 会把它追加到默认多阶段 Dockerfile 的底部后定义者生效因此可以覆盖已有构建阶段。需要注意详见 deployment overview若覆盖了中间构建阶段后续阶段不会被使用除非你在自定义内容中重现它们生成内容随所用功能与 Wasp 版本动态变化应定期用wasp dockerfile核对最终阶段必须提供ENTRYPOINT否则改动不生效。小结Wasp 自托管的关键心法是三件套拆解wasp build产出 Node.js 服务器镜像.wasp/out/Dockerfile与可静态托管的客户端.wasp/out/web-app/build再配上 PostgreSQL 与反向代理即可上线。想要省心用 Caprover / Coolify 借助 GitHub Actions 实现推送即部署想要可控用 VPS Docker Caddy 逐层落地。无论哪条路线生产环境变量尤其是DATABASE_URL、JWT_SECRET、WASP_WEB_CLIENT_URL、WASP_SERVER_URL、PORT与数据库备份都是不可省略的底线配置。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考