dark/agent_deply
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
agent_deply/doc_scripts/当前脚本情况总结.md
dark 143cd76c6a 1、新增action给agent使用 
2、新增SKILL描述
2026-05-20 16:58:01 +08:00

8.5 KiB
Raw Blame History

当前脚本情况总结

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 ./deploy.sh --config ./config.txt --rollback-ip 192.168.1.10 --rollback-stop-first

powershell -File .\deploy.ps1 -ConfigPath .\config.txt -RollbackIp 192.168.1.10 -RollbackStopFirst

常见的 Agent 调用方式示例：

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

正式部署：

deploy.bat -ConfigPath .\config.txt

全接口测试：

test_deploy.bat -ConfigPath .\config.txt

只做轻量测试：

test_deploy.bat -ConfigPath .\config.txt -Mode smoke

不测回滚：

test_deploy.bat -ConfigPath .\config.txt -SkipRollback

限制只测前 N 台在线 IP：

test_deploy.bat -ConfigPath .\config.txt -MaxIps 1

3.2 Shell / Git Bash

正式部署：

bash ./deploy.sh --config ./config.txt

全接口测试：

bash ./test_deploy.sh --config ./config.txt --mode full

轻量测试：

bash ./test_deploy.sh --config ./config.txt --mode smoke

跳过回滚：

bash ./test_deploy.sh --config ./config.txt --mode full --skip-rollback

限制 IP 数量：

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 业务日志

正式部署脚本与手动回滚入口当前会输出统一流程日志，例如：

[FLOW][START] Get-Token
[FLOW][DONE] Get-Token
[FLOW][FAIL] Verify-Ip[192.168.1.10] | ...

测试脚本当前会在控制台边跑边打印：

[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 ./test_deploy.sh --config ./config.txt --mode smoke
  1. 基础联通没问题后再跑：
bash ./test_deploy.sh --config ./config.txt --mode full --skip-rollback
  1. 如果要排查具体接口问题，优先查看：
  • 控制台 [PASS] / [FAIL]
  • logs/api_trace_*.log
  1. 如果某一台 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 状态码。