# 当前脚本情况总结

## 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. 失败时触发回滚
13. 输出最终部署报告

### 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`

## 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 `jq` 缺失问题

当前 `deploy.sh` 已做成：

- 有 `jq`：优先使用 `jq`
- 没有 `jq`：自动降级为 Bash 兼容 JSON 解析

已覆盖的 fallback 解析场景：

- `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
[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` 运行，但 fallback 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 状态码。