349 lines
8.5 KiB
Markdown
349 lines
8.5 KiB
Markdown
# 当前脚本情况总结
|
||
|
||
## 1. 当前文件说明
|
||
|
||
当前目录下与部署直接相关的脚本如下：
|
||
|
||
- `deploy.sh`
|
||
- Shell 主部署脚本
|
||
- 适合 Git Bash / Linux / macOS 环境
|
||
- `test_deploy.sh`
|
||
- Shell 测试脚本
|
||
- 默认执行全接口测试
|
||
- `deploy.ps1`
|
||
- PowerShell 主部署脚本
|
||
- Windows 下的实际实现入口
|
||
- `test_deploy.ps1`
|
||
- PowerShell 测试脚本
|
||
- 支持 `smoke` / `full` 两种模式
|
||
- `deploy.bat`
|
||
- Windows 包装入口
|
||
- 实际调用 `deploy.ps1`
|
||
- `test_deploy.bat`
|
||
- Windows 测试包装入口
|
||
- 实际调用 `test_deploy.ps1`
|
||
- `config.txt.example`
|
||
- 配置示例文件
|
||
|
||
## 2. 当前能力
|
||
|
||
### 2.1 主部署脚本
|
||
|
||
`deploy.sh` / `deploy.ps1` 当前都覆盖以下流程：
|
||
|
||
1. 获取 Token
|
||
2. 新建版本记录
|
||
3. 上传软件包
|
||
4. 发布版本
|
||
5. 获取 Target Node
|
||
6. 获取在线工作站 IP 列表
|
||
7. 下载软件包到 Node
|
||
8. 逐台执行升级
|
||
9. 启动应用
|
||
10. 健康检查
|
||
11. 下载日志
|
||
12. 失败时标记回滚待确认，由 Agent 与用户确认后再执行手动回滚
|
||
13. 输出最终部署报告
|
||
|
||
同时，两个主脚本都已提供 `action` 入口，适合由 Agent 按步骤调用，而不是只能整条主流程一把执行。
|
||
|
||
当前接口约定补充：
|
||
|
||
- `/api/mcp/version/upgrade` 使用 query 参数，不再使用 body 表单。
|
||
- `/api/mcp/version/upgrade/start-stop` 使用 query 参数，不再使用 body 表单，且参数名使用 `runStart`。
|
||
- `download-cloud` 固定传 `timeOut=0`，仅用于创建下载任务；后续进度通过 `download-cloud/progress` 异步查询。
|
||
|
||
### 2.2 测试脚本
|
||
|
||
`test_deploy.sh` / `test_deploy.ps1` 当前支持：
|
||
|
||
- `smoke`
|
||
- 仅测试配置、Token、Node、在线 IP 查询
|
||
- `full`
|
||
- 按完整部署顺序测试全部接口
|
||
|
||
`full` 模式会测试到：
|
||
|
||
1. `oauth/token`
|
||
2. `api/version/upgrade`
|
||
3. `api/version/upgrade/upload`
|
||
4. `api/version/upgrade/profile`
|
||
5. `api/mcp/airport/target-node`
|
||
6. `api/mcp/version/upgrade/ips`
|
||
7. `api/mcp/version/upgrade/download-cloud`
|
||
8. `api/mcp/version/upgrade/download-cloud/progress`
|
||
9. `api/mcp/version/upgrade`
|
||
10. `api/mcp/version/upgrade/start-stop`
|
||
11. `api/mcp/version/upgrade/verify`
|
||
12. `api/mcp/version/upgrade/log-download`
|
||
13. `api/mcp/version/upgrade/rollback`
|
||
|
||
正式部署脚本当前不会自动执行 `rollback`，而是输出待确认状态；需要实际回滚时，应由 Agent 与用户确认后，再调用手动回滚入口：
|
||
|
||
```bash
|
||
bash ./deploy.sh --config ./config.txt --rollback-ip 192.168.1.10 --rollback-stop-first
|
||
```
|
||
|
||
```powershell
|
||
powershell -File .\deploy.ps1 -ConfigPath .\config.txt -RollbackIp 192.168.1.10 -RollbackStopFirst
|
||
```
|
||
|
||
常见的 Agent 调用方式示例：
|
||
|
||
```bash
|
||
bash ./deploy.sh --config ./config.txt --action get-online-ips
|
||
bash ./deploy.sh --config ./config.txt --action upgrade-ip --ip 192.168.1.10
|
||
```
|
||
|
||
```powershell
|
||
powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action GetOnlineIps
|
||
powershell -File .\deploy.ps1 -ConfigPath .\config.txt -Action UpgradeIp -Ip 192.168.1.10
|
||
```
|
||
|
||
## 3. 当前运行方式
|
||
|
||
### 3.1 Windows
|
||
|
||
正式部署：
|
||
|
||
```bat
|
||
deploy.bat -ConfigPath .\config.txt
|
||
```
|
||
|
||
全接口测试：
|
||
|
||
```bat
|
||
test_deploy.bat -ConfigPath .\config.txt
|
||
```
|
||
|
||
只做轻量测试：
|
||
|
||
```bat
|
||
test_deploy.bat -ConfigPath .\config.txt -Mode smoke
|
||
```
|
||
|
||
不测回滚：
|
||
|
||
```bat
|
||
test_deploy.bat -ConfigPath .\config.txt -SkipRollback
|
||
```
|
||
|
||
限制只测前 N 台在线 IP：
|
||
|
||
```bat
|
||
test_deploy.bat -ConfigPath .\config.txt -MaxIps 1
|
||
```
|
||
|
||
### 3.2 Shell / Git Bash
|
||
|
||
正式部署：
|
||
|
||
```bash
|
||
bash ./deploy.sh --config ./config.txt
|
||
```
|
||
|
||
全接口测试：
|
||
|
||
```bash
|
||
bash ./test_deploy.sh --config ./config.txt --mode full
|
||
```
|
||
|
||
轻量测试：
|
||
|
||
```bash
|
||
bash ./test_deploy.sh --config ./config.txt --mode smoke
|
||
```
|
||
|
||
跳过回滚：
|
||
|
||
```bash
|
||
bash ./test_deploy.sh --config ./config.txt --mode full --skip-rollback
|
||
```
|
||
|
||
限制 IP 数量：
|
||
|
||
```bash
|
||
bash ./test_deploy.sh --config ./config.txt --mode full --max-ips 1
|
||
```
|
||
|
||
## 4. 已处理的问题
|
||
|
||
### 4.1 Windows Batch 中 `!` 被吞掉
|
||
|
||
之前的核心问题是：
|
||
|
||
- `setlocal EnableDelayedExpansion` 打开后
|
||
- `CLIENT_SECRET` 中如果有 `!`
|
||
- 传给 `curl` 时会被 Batch 吞掉
|
||
|
||
当前处理方式：
|
||
|
||
- `deploy.bat` / `test_deploy.bat` 只做包装
|
||
- 真实逻辑全部转给 `deploy.ps1` / `test_deploy.ps1`
|
||
- 不再在 Batch 中直接拼接敏感参数
|
||
|
||
### 4.2 PowerShell 对 JSON 解析兼容问题
|
||
|
||
之前测试环境里出现过：
|
||
|
||
- 接口已经返回 `access_token`
|
||
- 但脚本仍报 `Invalid token response`
|
||
|
||
当前处理方式：
|
||
|
||
- `PowerShell 6+` 使用 `ConvertFrom-Json -Depth 100`
|
||
- `Windows PowerShell 5.x` 使用兼容写法 `ConvertFrom-Json`
|
||
|
||
### 4.3 Git Bash 对 `[[ ... =~ ... ]]` 和进程替换兼容问题
|
||
|
||
之前 Shell 侧出现过：
|
||
|
||
- 正则匹配语法在 Git Bash 下报错
|
||
- `done < <(...)` 在当前环境下报错
|
||
|
||
当前处理方式：
|
||
|
||
- 改成更兼容的正则变量写法
|
||
- 改成 here-string 方式读取解析结果
|
||
|
||
### 4.4 Shell 原生 JSON 解析
|
||
|
||
当前 `deploy.sh` 已完全去除 `jq` 依赖，统一使用 Bash 原生兼容解析。
|
||
|
||
当前已覆盖的解析场景：
|
||
|
||
- `access_token`
|
||
- `status`
|
||
- `success`
|
||
- `message`
|
||
- `hashCode`
|
||
- `data.hashCode`
|
||
- 顶层对象首个 key
|
||
- 顶层字符串数组
|
||
|
||
注意：
|
||
|
||
- 这不是完整 JSON 解析器
|
||
- 目前是针对当前 PAM 接口返回结构做的兼容处理
|
||
|
||
### 4.5 日志接口 `401` 仍显示通过
|
||
|
||
之前 Shell 测试脚本里：
|
||
|
||
- `LOG_DOWNLOAD` 只看文件是否存在
|
||
- 即使接口返回 `401`
|
||
- 也可能被误判成 `PASS`
|
||
|
||
当前处理方式：
|
||
|
||
- `http_request` 和 `upload_file` 已增加 HTTP 状态码校验
|
||
- 只有 `2xx` 才算成功
|
||
- `download_log` 也会校验 HTTP 状态码
|
||
- `test_deploy.sh` 的 `LOG_DOWNLOAD` 现在按返回码判定，不再只按文件存在判定
|
||
|
||
### 4.6 `Target-Node` 未校验
|
||
|
||
之前如果 `target-node` 接口返回的 key 不是合法 URL：
|
||
|
||
- 后续所有 Node 相关接口都会异常
|
||
- 但问题源头不够直观
|
||
|
||
当前处理方式：
|
||
|
||
- `get_node_url` 已加入 `Target-Node` 校验
|
||
- 必须是 `http://` 或 `https://` 开头
|
||
- 不允许包含空格、制表符、换行等非法空白字符
|
||
|
||
## 5. 当前日志能力
|
||
|
||
### 5.1 业务日志
|
||
|
||
正式部署脚本与手动回滚入口当前会输出统一流程日志，例如：
|
||
|
||
```text
|
||
[FLOW][START] Get-Token
|
||
[FLOW][DONE] Get-Token
|
||
[FLOW][FAIL] Verify-Ip[192.168.1.10] | ...
|
||
```
|
||
|
||
测试脚本当前会在控制台边跑边打印：
|
||
|
||
```text
|
||
[PASS] TOKEN | ...
|
||
[FAIL] VERIFY [ip] | ...
|
||
[SKIP] ROLLBACK | ...
|
||
```
|
||
|
||
最后还会输出汇总报告：
|
||
|
||
- `PASS`
|
||
- `FAIL`
|
||
- `SKIP`
|
||
|
||
### 5.2 接口跟踪日志
|
||
|
||
`deploy.sh` 当前已经加入接口级 trace 日志。
|
||
|
||
日志特点：
|
||
|
||
- 位置：`logs/api_trace_YYYYMMDD_HHMMSS_PID.log`
|
||
- 自动记录每个请求
|
||
- 自动生成请求编号，如 `REQ-0001`
|
||
|
||
当前已记录内容：
|
||
|
||
- 请求时间
|
||
- 请求方法
|
||
- 请求 URL
|
||
- 请求头
|
||
- 请求体
|
||
- `curl` 退出码
|
||
- HTTP 状态码
|
||
- 响应体
|
||
|
||
已做脱敏：
|
||
|
||
- `client_secret`
|
||
- `Authorization`
|
||
- `access_token`
|
||
|
||
## 6. 当前已知限制
|
||
|
||
1. Shell 侧已去除 `jq` 依赖，但当前原生 JSON 解析只针对现有接口结构，不适合复杂 JSON。
|
||
2. 回滚测试默认会真实调用回滚接口，会改变测试环境状态；如不希望改变状态，需要显式加 `--skip-rollback`。
|
||
3. `full` 模式会真实创建版本、上传包、发布、升级、启动、回滚，因此它不是只读检查。
|
||
4. PowerShell 与 Shell 两套脚本逻辑大体对齐，但最新的一些 Shell 侧 trace 和兼容修复，后续仍建议同步到 PowerShell 版本。
|
||
|
||
## 7. 当前建议
|
||
|
||
1. 在测试环境优先使用测试脚本，不要直接先跑正式部署脚本。
|
||
2. 第一次联调建议先跑：
|
||
|
||
```bash
|
||
bash ./test_deploy.sh --config ./config.txt --mode smoke
|
||
```
|
||
|
||
3. 基础联通没问题后再跑：
|
||
|
||
```bash
|
||
bash ./test_deploy.sh --config ./config.txt --mode full --skip-rollback
|
||
```
|
||
|
||
4. 如果要排查具体接口问题，优先查看：
|
||
|
||
- 控制台 `[PASS] / [FAIL]`
|
||
- `logs/api_trace_*.log`
|
||
|
||
5. 如果某一台 IP 的 `verify`、`log-download` 或 `rollback` 异常，建议把对应 `REQ-xxxx` 的 trace 片段单独摘出来分析。
|
||
|
||
## 8. 后续可继续优化的方向
|
||
|
||
1. 把 PowerShell 脚本里的帮助文本、输出文案进一步统一为中文。
|
||
2. 把 Shell 侧新增的接口 trace 能力同步到 PowerShell 版本。
|
||
3. 给接口 trace 再拆分摘要视图，例如：
|
||
- `summary.log`
|
||
- `request.log`
|
||
- `response.log`
|
||
4. 给测试脚本增加“只测试指定接口”的模式，方便单点排障。
|
||
5. 给 `download_log` 增加更明确的响应内容校验，而不只是 HTTP 状态码。
|