单台 VPS 部署 API（上）：环境准备与 Docker Hub 镜像发布

本方案的技术链路为：Mac + OrbStack 本地开发与构建 → Docker Hub 保存版本化镜像 → Ubuntu VPS 使用 Docker Compose 运行。VPS 只保留部署配置、环境变量、Nginx 配置和数据卷，不上传 Git 仓库或 src 源码目录。

注意：多阶段镜像不等同绝对源码保护。最终镜像可没有 TypeScript 源码，但编译后的 JavaScript 仍可被分析。密码、令牌和私钥永远不能写进镜像。

---

一、环境说明

本地需要 macOS、OrbStack、Node.js LTS、npm、Git 和 Docker Hub 账号。PostgreSQL 通过 OrbStack 容器运行。

VPS 建议使用：

• 系统：Ubuntu 24.04 LTS（或仍受支持的 LTS）
• 配置：2 vCPU、4 GB RAM、40 GB 以上 SSD/NVMe
• 网络：公网 IPv4，开放 TCP 80/443
• 安全：SSH 仅对可信 IP 开放

1 GB 内存可试验，但 API、PostgreSQL 与 Docker 共用资源时余量很少。

---

二、本地 PostgreSQL

创建 compose.dev.yml：

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: app_user
      POSTGRES_PASSWORD: change-this-local-password
      POSTGRES_DB: app_db
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - postgres_dev_data:/var/lib/postgresql/data
volumes:
  postgres_dev_data:

启动并验证：

docker compose -f compose.dev.yml up -d
docker compose -f compose.dev.yml exec postgres psql -U app_user -d app_db

本机运行 API 时的数据库连接字符串：

DATABASE_URL=postgresql://app_user:***@localhost:5432/app_db

绑定 127.0.0.1 代表数据库只供本机开发使用。

---

三、构建生产 Docker 镜像

假设 npm run build 输出 dist，入口为 dist/server.js：

FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig*.json ./
COPY src ./src
RUN npm run build

FROM node:22-alpine AS production
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

创建 .dockerignore：

node_modules
dist
.git
.env
.env.*
npm-debug.log*
compose*.yml

本地验证构建与运行：

docker build -t YOUR_DOCKERHUB_USER/backend-api:1.0.0 .
docker run --rm -p 3000:3000 YOUR_DOCKERHUB_USER/backend-api:1.0.0

Prisma、原生模块等可能需要额外生成步骤，应以项目实际依赖为准。

---

四、Docker Hub 如何选择

Docker Hub 镜像格式为 docker.io/<用户名>/<镜像名>:<标签>，例如 docker.io/alice/backend-api:1.0.0。它最通用、入门简单，业务 API 通常应使用私有仓库。

各容器仓库选型对比：

仓库	适用场景
Docker Hub	最通用，入门简单，业务建议使用私有仓库
GHCR	适合 GitHub Actions 工作流
GitLab Container Registry	适合 GitLab CI
云厂商仓库	适合长期部署在同一家云

私有仓库和拉取额度会变化，以各平台官网当前政策为准。

---

五、推送镜像

在 Docker Hub 创建 backend-api 私有仓库，使用 Personal Access Token 登录：

docker login
docker build -t YOUR_DOCKERHUB_USER/backend-api:1.0.0 .
docker push YOUR_DOCKERHUB_USER/backend-api:1.0.0

可附加 latest 标签：

docker tag YOUR_DOCKERHUB_USER/backend-api:1.0.0 YOUR_DOCKERHUB_USER/backend-api:latest
docker push YOUR_DOCKERHUB_USER/backend-api:latest

发布前检查清单：

• ✅ API 已连接本地 PostgreSQL 通过关键测试
• ✅ 存在 GET /health 健康检查端点
• ✅ 机密没有进入镜像
• ✅ 每次发布都有新标签

生产 Compose 应固定使用 1.0.0 之类的明确版本，便于回滚。

---

总结

本文完成了「单台 VPS 部署 API」的上半部分：从本地开发环境搭建、PostgreSQL 配置、多阶段 Docker 镜像构建，到 Docker Hub 镜像推送。下一篇文章将介绍如何在 Ubuntu VPS 上拉取镜像、配置 Nginx 反向代理，并完成 HTTPS 证书的申请与自动续期。