VPS 部署

一次会话，即可将任意应用部署至任意 VPS —— 从裸机服务器直达生产环境（含 SSL）。

适用场景

• 用户已拥有 VPS（Ubuntu/Debian），希望部署一个应用
• 用户提出“部署到 VPS”、“配置我的服务器”、“上线生产环境”等需求
• 用户本地已有正在运行的应用，希望将其发布至服务器上运行
• 用户需要在 VPS 上配置 SSL、Nginx 和 Docker

不适用场景

• 部署至 Vercel、Netlify 或其他托管平台（请使用其官方 CLI）
• 部署至 Kubernetes（如存在 /k8s-deploy 技能，请改用该技能）
• 用户仅需推送代码（请使用 git push）

前置条件

• 具备 VPS 的 SSH 访问权限（IP 地址 + root 或具备 sudo 权限的凭证）
• 已将域名解析至该 VPS 的 IP 地址（用于申请 SSL；若无域名，可跳过 SSL 步骤）
• 应用必须包含 Dockerfile，或可通过 Docker 部署

执行流程

阶段 1：信息收集

向用户询问以下信息（已能自动检测的项可跳过）：

1. VPS IP 地址 及 SSH 凭据（root 密码或私钥路径）
2. 域名（可选 —— 仅 SSL 所需）
3. 应用类型 —— 若当前目录可识别，则自动检测：
   • 检查是否存在 package.json（Node.js / Next.js）
   • 检查是否存在 requirements.txt 或 pyproject.toml（Python）
   • 检查是否存在 go.mod（Go）
   • 检查是否存在 Dockerfile（任意语言）
4. 应用监听端口（优先从 Dockerfile 的 EXPOSE 指令中提取；否则向用户询问）
5. 所需环境变量（检查 .env.local、.env.example 等文件）
6. 数据库依赖（Postgres、MySQL、Redis、MongoDB —— 根据项目依赖自动识别）

阶段 2：服务器初始化（通过 SSH 登录 VPS 执行）

所有命令均通过 ssh root@ 执行。为确保安全，使用 && 连接命令链。

2a. 系统更新

apt update && apt upgrade -y

2b. 创建部署用户

adduser --disabled-password --gecos "" deploy
usermod -aG sudo docker deploy
echo "deploy ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/deploy

2c. SSH 安全加固

# 将 root 的 authorized_keys 复制给 deploy 用户
mkdir -p /home/deploy/.ssh
cp ~/.ssh/authorized_keys /home/deploy/.ssh/ 2>/dev/null || true
chown -R deploy:deploy /home/deploy/.ssh
chmod 700 /home/deploy/.ssh
chmod 600 /home/deploy/.ssh/authorized_keys 2>/dev/null || true

# 加固 SSH 配置
sed -i 's/#?PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config
sed -i 's/#?PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
sed -i 's/#?PubkeyAuthentication.*/PubkeyAuthentication yes/' /etc/ssh/sshd_config
systemctl restart sshd

关键提示： 在禁用 root 登录前，务必验证 deploy 用户能否成功 SSH 登录。请在另一独立连接中测试。若用户尚未配置 SSH 密钥，请先协助完成密钥配置。

2d. 防火墙（UFW）

apt install -y ufw
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp   # SSH
ufw allow 80/tcp   # HTTP
ufw allow 443/tcp  # HTTPS
ufw --force enable

2e. 安装 Docker

curl -fsSL https://get.docker.com | sh
usermod -aG docker deploy

2f. 安装 Docker Compose（v2）

apt install -y docker-compose-plugin
# 验证安装
docker compose version

阶段 3：应用部署

3a. 生成 Dockerfile（如不存在）

根据识别出的技术栈，生成合适的多阶段 Dockerfile：

Node.js / Next.js：

FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev

FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

Python（FastAPI / Flask）：

FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

请根据项目实际检测结果调整内容。

3b. 生成 docker-compose.yml

生成一份面向生产环境的 compose 文件。应包含以下要素：

services:
  app:
    build: .
    restart: unless-stopped
    ports:
      - "127.0.0.1:${APP_PORT:-3000}:${APP_PORT:-3000}"
    env_file: .env
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:${APP_PORT:-3000}/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '1.0'
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  # 根据检测结果添加数据库服务（示例）：
  # postgres:
  #   image: postgres:16-alpine
  #   restart: unless-stopped
  #   volumes:
  #     - pgdata:/var/lib/postgresql/data
  #   environment:
  #     POSTGRES_DB: ${DB_NAME:-app}
  #     POSTGRES_USER: ${DB_USER:-app}
  #     POSTGRES_PASSWORD: ${DB_PASSWORD}
  #   healthcheck:
  #     test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-app}"]
  #     interval: 10s
  #     timeout: 5s
  #     retries: 5

# volumes:
#   pgdata:

核心规范：

• 必须 将应用端口绑定至 127.0.0.1（由 Nginx 处理外部流量）
• 必须 包含健康检查（healthcheck）
• 必须 包含资源限制（memory / cpus）
• 必须 包含日志大小与数量限制
• 必须 使用 restart: unless-stopped
• 禁止 将数据库端口暴露至宿主机（即不可使用 ports: 直接映射）

3c. 向 VPS 传输文件

# 创建应用目录
ssh deploy@ "mkdir -p ~/apps/"

# 同步项目文件（排除 node_modules、.git、.next 等）
rsync -avz --exclude='node_modules' --exclude='.git' --exclude='.next' 
  ./ deploy@:~/apps//

3d. 构建并启动服务

ssh deploy@ "cd ~/apps/ && docker compose up -d --build"

阶段 4：Nginx 反向代理配置

apt install -y nginx

# 生成站点配置
cat > /etc/nginx/sites-available/ << 'EOF'
server {
    listen 80;
    server_name ;

    location / {
        proxy_pass http://127.0.0.1:;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400;
    }
}
EOF

ln -sf /etc/nginx/sites-available/ /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default
nginx -t && systemctl reload nginx

阶段 5：SSL 证书（Let’s Encrypt）

若未提供域名，则跳过此步骤。

apt install -y certbot python3-certbot-nginx
certbot --nginx -d  --non-interactive --agree-tos -m 
# certbot 会自动配置证书自动续期

阶段 6：部署验证

执行以下检查并汇总结果反馈给用户：

# 检查容器运行状态
docker compose ps

# 检查健康状态
docker inspect --format='{{.State.Health.Status}}' 

# 检查 Nginx 是否正常响应
curl -sI https:// | head -5

# 检查 SSL 证书有效期
echo | openssl s_client -servername  -connect :443 2>/dev/null | openssl x509 -noout -dates

向用户报告以下信息：

• 容器状态（是否运行中 / 是否健康）
• HTTP 响应状态码
• SSL 证书到期时间
• 可访问的 URL 地址

安全准则

• 严禁 未经确认擅自关闭防火墙
• 严禁 将数据库端口暴露至公网
• 必须 在禁用 root 登录前，确认 deploy 用户可正常 SSH 登录
• 必须 覆盖 Nginx 配置前，备份原有配置文件
• 必须 重载 Nginx 前执行 nginx -t 验证配置有效性
• 必须 执行破坏性命令（如 rm、drop 等）前征得用户明确许可
• 任一环节失败时，立即中止流程并向用户清晰说明错误原因；禁止盲目串联修复逻辑。

故障排查

• 端口已被占用： 使用 lsof -i : 查看占用进程
• Docker 构建失败： 检查 Dockerfile 内容，并展示构建日志
• SSL 申请失败： 确认域名 DNS 已正确解析至 VPS IP（执行 dig 验证）
• 应用崩溃： 使用 docker compose logs -f 实时查看日志
• 无法以 deploy 用户 SSH 登录： 暂勿禁用 root 登录，优先修复密钥配置

部署后检查清单

请提醒用户完成以下事项：

1. 配置监控系统（推荐 Uptime Kuma）
2. 为数据库卷配置自动化备份策略
3. 启用日志轮转（已在 docker-compose.yml 中预配置）
4. 考虑引入 CI/CD 流水线（推荐使用 /ci-gen 技能）
5. 如尚未完成，请将域名添加至 DNS 解析记录