# Deploy

> |

- **Type:** Skill
- **Install:** `agentstack add skill-aiyanjiu-git-claude-deploy-skill-claude-deploy-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aiyanjiu-git](https://agentstack.voostack.com/s/aiyanjiu-git)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aiyanjiu-git](https://github.com/aiyanjiu-git)
- **Source:** https://github.com/aiyanjiu-git/claude-deploy-skill

## Install

```sh
agentstack add skill-aiyanjiu-git-claude-deploy-skill-claude-deploy-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /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](https://github.com/aiyanjiu-git)
- **Source:** [aiyanjiu-git/claude-deploy-skill](https://github.com/aiyanjiu-git/claude-deploy-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aiyanjiu-git-claude-deploy-skill-claude-deploy-skill
- Seller: https://agentstack.voostack.com/s/aiyanjiu-git
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.