在阿里云 ECS 上部署 Vue、Spring Boot、Python 和 MySQL 组成的项目，经常会遇到运行环境不一致、依赖冲突、Nginx 配置错误等问题。尤其是服务器已经运行其他网站时，一次错误修改可能影响多个服务。
为提高部署效率，作者开发了开源 Agent Skill：aliyun-fullstack-deploy，将环境检查、版本兼容性分析、发布包构建、灰度测试与回滚操作整理为可复用的部署规范。
当前版本：v0.6.0 。（100+ star）
一、Skill 的核心功能
该 Skill 面向阿里云 ECS 及类似的 Linux 服务器，支持 Vue、React、Java、Python 等常见项目的部署检查。
它重点处理四类问题 ：第一，检查本地项目与云服务器的运行环境，提前识别版本冲突；第二，根据发布清单自动整理程序文件，避免漏传模型、依赖说明或前端资源；第三，在独立端口验证新版本，降低正式发布风险；第四，保存历史版本和部署信息，便于发生故障时恢复。【版本冲突识别、自动整理文件、独立端口验证、保存历史信息】
整个过程由 Skill 文档提供操作规则，具体检查与打包由 Python、Shell 脚本完成。对于数据库迁移、系统升级等高风险操作，需要结合实际服务器情况进行验证与授权。
二、部署前如何检查版本兼容性？
以某项目为例，本地开发使用 Java 17、Python 3.11、Vue 3 和 MySQL 8。云服务器可能已经安装其他版本，因此需要先检查两端的环境。
首先，在本地项目根目录执行：
python
python scripts/preflight_local.py .这里的 scripts 指 Skill 内的脚本目录。命令会识别 Java、Python 和前端项目结构，检查必要文件、开发环境路径及潜在敏感信息。
接着，通过 SSH 登录 ECS，使用 preflight_remote.sh 检查操作系统、内存、磁盘、端口、Java、Python、Nginx 和现有服务。
v0.6.0 新增了 probe_runtime.py，可以进一步记录服务器运行环境。例如：
python
python3 probe_runtime.py \
--python-bin /usr/bin/python3.11 \
--packages flask,numpy,catboost \
--json-out ecs-runtime.json将生成的 JSON 安全传回本地，再使用 runtime_matrix.py 与项目的版本配置进行比较：
python
python runtime_matrix.py . \
--contract deploy/runtime-contract.json \
--server ecs-runtime.json \
--gate plan其中，runtime-contract.json 记录项目要求的 Java、Python、数据库版本和依赖文件位置。
检查结果分为 PASS、ACTION_REQUIRED、REVIEW 和 BLOCK，分别表示满足当前检查、需要调整、需要进一步核实以及存在阻断问题。
例如，服务器使用 Java 11，而项目要求 Java 17，检查器会提示安装兼容的 JRE，并重新验证。数据库是否真正兼容仍需检查实际运行实例和业务 SQL。
三、如何自动生成发布包？
完成依赖检查和本地构建后，需要把程序整理为可上传的发布文件。
Skill 提供 build_release.py，根据 JSON 配置选择文件。下面是一个简化示例：
json
{
"project_name": "hnblue",
"version": "v1",
"includes": [
"frontend/dist",
"backend/target/app.jar",
"flask_model"
],
"excludes": [
"node_modules",
"__pycache__",
".venv"
]
}其中，includes 指定需要上传的内容，excludes 指定排除的目录。实际项目应使用真实的 JAR 路径，并补充模型文件、检索索引和部署配置模板。
随后执行：
python
python scripts/build_release.py . \
--config deploy/release.json
python scripts/inspect_release.py \
release/hnblue-v1.zip第一条命令生成 ZIP，并记录文件清单及 SHA-256。第二条命令检查归档完整性和常见敏感内容。打包前仍需检查实际文件，避免遗漏生产环境必需的数据或意外包含密码。
四、灰度发布与回滚
发布包上传 ECS 后，先解压至独立目录，例如：
bash
/opt/hnblue/
├── releases/
│ ├── v1/
│ └── v2/
├── current -> releases/v2
└── shared/其中，releases 保存不同版本，current 指向当前运行版本，shared 保存独立于版本的配置和持久化数据。
新版本可以先在临时端口运行，例如 Java 使用
28088，Python 使用28880。检查登录、数据库查询、模型预测和实际页面，全部通过后再切换正式版本。
如果新版本出现严重错误，可以把 current 切回上一版本，并恢复相应服务。数据库变更需要单独备份和恢复，不能依赖代码版本切换撤销。
需要注意，当前 Skill 的通用灰度脚本主要适配 Python/Uvicorn。Spring Boot 与 Flask/Gunicorn 需要提供项目专用的启动和验证命令。
五、适用范围与实际价值
aliyun-fullstack-deploy 已经包含环境检查、版本兼容性分析、归档校验和部署验证规则。v0.6.0 通过了相应 GitHub Actions 自动化测试。
目前版本能够识别多类兼容性问题并提供修复建议。实际依赖安装、模型加载和业务验证仍需要在目标服务器上执行。
对于需要反复发布的中小型项目，使用 Skill 可以减少重复排查工作，并保存版本、检查结果和回滚依据，提升部署过程的可重复性。