Deploy

/deploy — 服务器部署工作流

概览

这个 Skill 是项目部署的自动化流程，通过 MCP SSH Manager 连接远程服务器，完成构建、上传、部署、验证的完整闭环。

参数

| 参数 | 默认值 | 说明 | |------|--------|------| | target | 从项目记忆读取 | 服务器别名或 IP | | mode | full | check / build / full | | skip-build | false | 跳过本地构建，直接上传已有产物 | | backend-only | false | 只部署后端 | | frontend-only | false | 只部署前端 |

模式说明

| 模式 | 说明 | 执行范围 | |------|------|---------| | check | 仅连接服务器检查环境 | Phase 0 + Phase 1 | | build | 本地构建 + 上传，不重启 | Phase 0 ~ Phase 3 | | full | 完整部署流程 | Phase 0 ~ Phase 4 |

触发方式

/deploy                          # 完整部署（默认）
/deploy check                    # 仅检查服务器环境
/deploy build                    # 构建+上传，不重启
/deploy backend-only             # 只部署后端
/deploy frontend-only            # 只部署前端
/deploy skip-build               # 跳过构建，上传已有产物
/deploy target: your-server-ip   # 指定服务器

---

执行流程

Phase 0 — 上下文同步（必做，不可跳过）

□ 检查 git status，确认工作区状态
  → 有未提交变更 → 警告用户，询问是否继续
□ 读取项目记忆（CLAUDE.md、memory/ 目录）
□ 识别项目类型和结构：
  → 检查 package.json（前端/后端各自的）
  → 检查 Dockerfile、docker-compose.yml
  → 检查 deploy/ 目录下的已有部署脚本
  → 检查 DEPLOYMENT_GUIDE.md
□ 确定部署目标：
  → 优先读取项目记忆中的服务器信息
  → 其次检查 deploy/ 下的配置
  → 最后询问用户
□ 输出项目概况：
  - 项目名称和版本
  - 技术栈（前端框架、后端框架、数据库）
  - 目标服务器 IP 和部署路径
  - 已有部署脚本（如有）

铁律：

• 🔴 不可跳过上下文同步
• 🔴 不可在未确认目标服务器的情况下继续

---

Phase 1 — 连接服务器 & 环境检查

使用 MCP SSH Manager 的 ssh_execute 工具连接服务器。

□ 连接测试：ssh_execute(server, "echo OK")
□ 系统信息收集：
  - 操作系统版本
  - CPU / 内存 / 磁盘使用率
  - Node.js 版本（node -v）
  - npm 版本（npm -v）
  - PM2 版本和状态（pm2 status）
  - Nginx 状态（nginx -v && systemctl status nginx）
□ 检查目标部署目录：
  - 目录是否存在
  - 当前代码版本（git log -1 或 package.json version）
  - .env.production 是否存在
  - PM2 进程是否在运行
□ 检查磁盘空间是否充足（至少 1GB 可用）
□ 检查内存是否充足（至少 512MB 可用）

输出格式：

🖥️ 服务器环境报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
服务器: 
系统: Ubuntu 22.04 / CentOS 8.x
CPU: 4核 / 使用率 15%
内存: 4GB / 已用 1.2GB / 可用 2.8GB ✅
磁盘: 40GB / 已用 12GB / 可用 28GB ✅
Node.js: v20.11.0 ✅
PM2: 5.3.0 ✅
Nginx: 1.24.0 ✅
部署目录: /www/wwwroot/ ✅
当前版本: v1.0.0
PM2 状态: online (2 instances) ✅
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

如果 mode=check，到此结束，输出报告。

异常处理：

• 连接失败 → 检查 SSH 密钥、网络、防火墙，提示排查步骤
• Node.js 未安装 → 提供安装命令
• 磁盘/内存不足 → 提供清理建议
• PM2 未安装 → 提供安装命令

---

Phase 2 — 本地构建

根据项目类型执行构建。

Node.js 全栈项目（Vue/React + Express）

□ 后端构建（如非 frontend-only）：
  cd server/
  npm install
  npm run build
  → 验证 dist/ 目录生成

□ 前端构建（如非 backend-only）：
  cd client/
  npm install
  npm run build
  → 验证 dist/ 目录生成

Python 后端项目

□ 检查 requirements.txt 或 pyproject.toml
□ 无需本地构建，直接进入上传阶段

静态站点

□ 执行构建命令（从 package.json scripts 中读取）
□ 验证输出目录

构建失败处理：

• 输出完整错误日志
• 分析常见错误（依赖缺失、TypeScript 类型错误等）
• 中断部署流程

如果 skip-build 参数为 true，跳过此 Phase。

---

Phase 3 — 上传 & 部署

⚠️ 上传前必须向用户确认！显示将要上传的内容和目标路径。

方案 A：使用已有部署脚本（优先）

如果项目有 deploy/deploy-all.sh 或类似脚本：

□ 将脚本上传到服务器
□ 在服务器上执行脚本
□ 实时输出执行日志

方案 B：直接上传（无已有脚本时）

□ 前端部署（如非 backend-only）：
  - ssh_sync 上传 client/dist/ → 服务器目标目录/client/dist/
  - 或 ssh_upload 逐文件上传

□ 后端部署（如非 frontend-only）：
  - ssh_sync 上传 server/dist/ → 服务器目标目录/server/dist/
  - ssh_sync 上传 server/package.json → 服务器
  - ssh_execute: cd 目标目录/server && npm install --production

□ 环境变量检查：
  - 检查服务器上 .env.production 是否存在
  → 不存在 → 提示用户创建，列出需要的环境变量
  → 存在 → 跳过（不覆盖）

排除上传的文件/目录：

• node_modules/
• .git/
• .env.development
• *.log
• .vscode/
• uploads/（用户上传的文件不覆盖）

---

Phase 4 — 重启 & 验证

□ 重启后端服务：
  ssh_execute: pm2 restart  或 pm2 start dist/server.js --name 

□ 等待 5 秒让服务启动

□ 健康检查：
  - ssh_execute: curl -s http://localhost:/health 或 /api/health
  - 检查 PM2 状态：pm2 status
  - 检查是否有错误日志：pm2 logs --lines 10 --nostream

□ Nginx 检查（如有配置变更）：
  - ssh_execute: nginx -t
  - ssh_execute: systemctl reload nginx

□ 前端访问检查：
  - ssh_execute: curl -s -o /dev/null -w "%{http_code}" http://localhost
  - 期望返回 200

输出部署结果：

🚀 部署完成！
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
项目: 
版本: v1.0.0
服务器: 

前端: http:// ✅ (HTTP 200)
API:  http:///api/health ✅ (status: ok)
PM2:   online (2 instances) ✅

部署耗时: 2分30秒
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️ 回滚方法：
ssh root@
cd /www/wwwroot/ && git checkout 
pm2 restart 

---

安全原则

1. 🔴 不自动覆盖 .env.production — 仅提示用户手动配置
2. 🔴 上传前必须用户确认 — 显示文件列表和目标路径
3. 🔴 不删除服务器上的 uploads/ 或用户数据目录
4. 🔴 每个 Phase 失败都中断 — 不跳过错误继续执行
5. ✅ 输出回滚方法 — 每次部署完成后告知如何回退
6. ✅ 保留部署日志 — 记录本次部署的关键信息

---

首次部署 vs 更新部署

首次部署（服务器上无项目目录）

□ 创建项目目录
□ 上传全部代码
□ 安装依赖
□ 配置环境变量（引导用户填写）
□ 配置 PM2
□ 配置 Nginx（使用项目中的 nginx 配置模板或生成新的）
□ 启动服务

更新部署（服务器上已有项目）

□ 备份当前版本（记录 git commit 或打包）
□ 上传新版本代码/构建产物
□ 安装/更新依赖
□ 重启服务
□ 验证

---

项目类型自动识别

通过检查项目文件自动判断类型：

| 标识文件 | 项目类型 | 部署策略 | |---------|---------|---------| | client/package.json + server/package.json | 全栈 Node.js | 前后端分别构建部署 | | package.json (含 vue/react) | 纯前端 SPA | 构建 → 上传 dist/ | | package.json (含 express/nest) | 纯后端 API | 构建 → PM2 部署 | | requirements.txt / pyproject.toml | Python 项目 | 上传 → pip install → systemd/supervisor | | Dockerfile | Docker 项目 | docker build → docker-compose up | | deploy/ 目录 | 有已有脚本 | 优先使用已有脚本 |

---

边界

• 不处理：本地开发环境搭建、CI/CD 配置、Docker/K8s 编排、数据库迁移（仅提醒）
• 不处理：域名配置、SSL 证书申请（仅提示步骤）
• 与其他 Skill 的关系：
• /finalize 负责代码收尾和版本发布，/deploy 负责服务器部署
• 推荐流程：开发完成 → /finalize → /deploy

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aiyanjiu-git
• Source: aiyanjiu-git/claude-deploy-skill
• License: MIT

Install and usage instructions live in the source repository linked above.