ccdi/docs/plans/2026-03-13-deploy-to-nas-bat-design.md

一键部署 BAT 入口设计

日期: 2026-03-13

目标: 在现有 PowerShell 与 Python 部署链路之上，新增一个 Windows 下可直接双击或命令行执行的 .bat 入口脚本，用于一键打包前后端并部署到 NAS。

背景

当前仓库已经有以下部署能力：

• deploy/deploy.ps1：负责本地打包、组装部署目录、上传到 NAS、远端执行 Docker Compose
• deploy/remote-deploy.py：负责 SSH/SFTP 上传与远端 Docker 部署

但 Windows 用户直接使用时仍需要显式调用 PowerShell，不够直观。

方案选择

方案一：薄封装 BAT 入口

新增一个 deploy/deploy-to-nas.bat，只做以下几件事：

• 定位仓库根目录
• 调用 PowerShell 执行 deploy.ps1
• 提供默认的 NAS 连接参数
• 原样透传退出码

优点：

• 复用现有稳定链路
• 维护成本最低
• 双击和命令行都能使用

缺点：

• 底层仍依赖 PowerShell、Python、Maven、npm

方案二：把所有逻辑都改写到 BAT

优点：

• 形式上只有一个入口文件

缺点：

• BAT 对目录处理、错误处理、网络部署支持差
• 可维护性明显下降

方案三：BAT + 独立配置文件

优点：

• 多环境切换更灵活

缺点：

• 对当前固定 NAS 场景偏重

最终方案

采用方案一。

设计细节

入口脚本

新增 deploy/deploy-to-nas.bat。

职责：

• 默认使用：
  • Host: 116.62.17.81
  • Port: 9444
  • Username: wkc
  • Password: wkc@0825
  • RemoteRoot: /volume1/webapp/ccdi
• 支持命令行覆盖参数
• 统一调用 powershell -ExecutionPolicy Bypass -File deploy.ps1

可验证性

为避免每次验证都真的触发完整部署，给 deploy/deploy.ps1 增加一个 -DryRun 开关：

• 打印将要使用的目标参数
• 不执行 Maven、npm、上传与远端部署
• 直接返回 0

这样 .bat 可以配合 --dry-run 做快速回归验证。

参数约定

BAT 入口参数顺序：

deploy-to-nas.bat [host] [port] [username] [password] [remoteRoot] [--dry-run]

如果不传，则使用默认值。

验证方式

1. cmd /c deploy\deploy-to-nas.bat --dry-run
2. 确认输出中的 NAS 地址、端口、路径与默认值一致
3. 可选：cmd /c deploy\deploy-to-nas.bat 116.62.17.81 9444 wkc wkc@0825 /volume1/webapp/ccdi --dry-run
4. 最终运行无 --dry-run 的真实部署

风险与处理

• 若用户机器禁止 PowerShell 脚本执行，BAT 通过 -ExecutionPolicy Bypass 绕过当前会话限制
• 若路径中存在空格，BAT 需统一用双引号包裹
• 若密码中存在特殊字符，BAT 只做原样透传，不自行拼接复杂 shell 表达式