RakeshSw/PulseGuard

# PulseGuard [](https://github.com/RakeshSW/PulseGuard/actions/workflows/docker-e2e.yml) **预测故障。保障可靠性。** PulseGuard 是一个 agentic 可靠性工程概念验证，它将实时的运维信号转化为受控的事件响应工作流。它生成真实的本地结账流量，观测服务遥测数据，检测运维风险，利用有限的证据调查事件，推荐响应措施，应用确定性策略，仅执行白名单内的操作，验证恢复情况，并在需要人工干预时准备支持移交。 ## 项目展示的内容 - Wikimedia EventStreams 控制**本地合成**结账流量的强度。 - 结账路径将请求路由到三个支付节点。 - Toxiproxy 和受控适配器注入延迟、超时、损坏、依赖、容量、身份验证、证书和磁盘压力场景。 - Prometheus 和 Grafana 暴露指标和运维状态。 - 确定性检测根据观测到的服务行为开启事件。 - 调查 agent 接收遥测、拓扑、事件事实、有界的自动化上下文以及透明的本地知识库。 - 可选的 OpenAI 或 Azure OpenAI provider 用于解释证据并推荐白名单内的操作。 - 确定性治理决定操作是自动执行、需要批准、仅限人工执行还是被拒绝。 - PulseGuard 在解决事件之前通过遥测验证恢复情况。 原始的 Wikimedia 事件内容不会发送到结账应用程序或模型。调查中仅可能包含聚合的流量指标。 ## Agentic 运维循环 ``` observe -> detect -> investigate -> decide -> govern -> act -> verify -> resolve or hand off ``` ## 架构 ``` flowchart LR W[Wikimedia EventStreams] --> WA[Wikimedia Adapter] WA --> LG[Locust Load Generator] LG --> CO[Checkout Service] CO --> PR[Payment Router] PR --> P1[Payment Node 1] PR --> P2[Payment Node 2] PR --> P3[Payment Node 3] CO --> PM[Prometheus] PR --> PM P1 --> PM P2 --> PM P3 --> PM PM --> DET[Detector and Predictor] DET --> CORE[Incident Console] CORE --> AGENT[Investigation Agent] KB[Local Knowledge Base] --> AGENT AGENT -. optional .-> LLM[OpenAI or Azure OpenAI] AGENT --> POLICY[Deterministic Policy] POLICY --> AUTO[Automation Service] AUTO --> VERIFY[Recovery Verification] VERIFY --> CORE POLICY --> SUPPORT[Support Handoff] ``` 公开的产品名称是 **PulseGuard**。以 `opsai-` 或 `OPSAI_` 开头的内部标识符将被保留，以保持跨 Docker 服务名称、镜像、指标、API、持久化卷和测试的兼容性。 ## 使用 GitHub Codespaces 的浏览器演示 PulseGuard 可以完全在浏览器托管的 GitHub Codespace 中运行，包括所有 18 个 Docker Compose 服务。Codespaces 配置安装了 Docker-in-Docker，私下转发演示端口，并支持确定性 mock 和可选的真实 AI 调查模式。 有关创建、启动、密钥配置、端口访问、关闭和清理说明，请参阅 [CODESPACES.md](CODESPACES.md)。 ## 前置条件 - Windows 10/11 或其他支持 Docker 的操作系统 - 带有 Docker Compose v2 的 Docker Desktop - 用于所提供脚本的 PowerShell 5.1 或更高版本 - 足够的 CPU 和内存来运行 18 个 Compose 服务；为 Docker 分配大约 8 GB 内存是一个实用的起点 - 用于真实 AI 调查路径的可选 OpenAI 或 Azure OpenAI 访问权限 ## Windows 快速开始 解压 ZIP 文件，在解压后的 `PulseGuard-1.0.1-poc` 目录中打开 PowerShell，然后运行： ``` Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force .\scripts\start.ps1 ``` 首次启动时，脚本将： 1. 从 `.env.example` 创建 `.env`。 2. 为数据库密码、Grafana 密码、自动化 token 和合作伙伴 token 生成本地随机值。 3. 构建并启动完整的环境。 4. 等待主要 endpoint 准备就绪。 生成的 `.env` 仅限本地使用，并被 `.gitignore` 排除。 详细的洁净室说明位于 [SETUP_WINDOWS.md](SETUP_WINDOWS.md) 中。 ## 主要 URL | 界面 | URL | |---|---| | 结账 API | http://localhost:8080/ | | 支付路由器 | http://localhost:8081/nodes | | Locust | http://localhost:8089/ | | 场景控制器 | http://localhost:8090/ | | Wikimedia 流量配置文件 | http://localhost:8093/profile | | 损坏适配器 | http://localhost:8094/profile | | PulseGuard 事件控制台 | http://localhost:8095/ | | PulseGuard 调查 | http://localhost:8096/ | | 自动化和支持 | http://localhost:8097/ | | 预测分析 | http://localhost:8098/ | | 外部身份验证演示 | http://localhost:8099/ | | Prometheus | http://localhost:9090/ | | Grafana | http://localhost:3000/ | Grafana 凭据将在首次启动时生成到本地 `.env` 中。 ## AI 模式 ### 确定性 Mock 模式 默认配置为： ``` LLM_PROVIDER=mock ``` 这将使用确定性回退分析来演练完整的工作流和 UI。这绝对不能作为真实的 AI 结果展示。 ### Azure OpenAI 在本地 `.env` 中设置这些值： ``` LLM_PROVIDER=azure_openai AZURE_OPENAI_ENDPOINT=https://YOUR-RESOURCE.openai.azure.com AZURE_OPENAI_API_KEY=YOUR_KEY AZURE_OPENAI_DEPLOYMENT=YOUR_DEPLOYMENT_NAME ``` 然后重新创建调查 agent： ``` docker compose up -d --build --force-recreate opsai-agent Invoke-RestMethod http://localhost:8096/health | ConvertTo-Json -Depth 6 ``` ### OpenAI ``` LLM_PROVIDER=openai OPENAI_API_KEY=YOUR_KEY OPENAI_MODEL=gpt-5-mini ``` 然后如上所示重新创建 `opsai-agent`。 ## 推荐演示 1. 从干净的基线和零事件开始。 2. 展示实时来自 Wikimedia 的流量配置文件和 Locust 目标。 3. 注入受控的支付节点延迟或超时场景。 4. 等待确定性检测确认症状。 5. 打开事件并审查证据、拓扑、调查路径、provider 响应、建议和置信度。 6. 审查治理决策。 7. 仅在策略需要操作员授权时批准该操作。 8. 展示操作结果和基于遥测的恢复验证。 9. 审查最终的解决方案或支持移交。 有关可直接发布的演练，请参阅 [docs/demo.html](docs/demo.html)。 ## 有用的命令 ``` # 启动或重新构建 .\scripts\start.ps1 # 状态与健康摘要 .\scripts\status.ps1 # Platform validation .\scripts\test-opsai-v06.ps1 # 停止但保留 volumes .\scripts\stop.ps1 # 重置 runtime data 并重新启动 .\scripts\reset.ps1 ``` ## 完整的破坏性清理 项目范围的清理脚本会移除 PulseGuard 容器、卷、PostgreSQL 数据、Prometheus 历史记录、Grafana 运行时数据、本地构建的 PulseGuard 镜像、日志和缓存。它不会运行全局 Docker 清理。 ``` .\scripts\clean-pulseguard-completely-for-transfer-v1.ps1 ` -ProjectRoot $PWD ` -ConfirmDataLoss ``` 仅在准备进行干净传输或公共仓库副本时添加 `-RemoveLocalSecrets -RemovePatchBackups`。 ## 安全边界 - 调查 agent 不具备对场景控制器真实数据的访问权限。 - 模型上下文限制在事件相关的证据内。 - 原始 Wikimedia payload 和密钥被排除在 AI 上下文之外。 - 只能执行白名单内的操作。 - 策略将结果划分为自动执行、需要批准、仅限人工执行和拒绝。 - 命令完成不等于恢复；必须通过遥测进行验证。 - 没有向 agent 暴露 Docker socket 或不受限制的 shell 访问权限。 - 故障注入和负载生成必须保留在您拥有或被授权测试的系统内。 在运行或发布项目之前，请阅读 [SECURITY.md](SECURITY.md)。 ## 仓库布局 ``` . |-- compose.yaml |-- load-generator/ |-- observability/ |-- services/ |-- scripts/ |-- docs/ |-- .env.example |-- README.md |-- SETUP_WINDOWS.md |-- SECURITY.md `-- LICENSE ``` ## 发布 在暂存仓库之前，删除本地运行时和密钥并运行发布验证器： ``` .\scripts\clean-pulseguard-completely-for-transfer-v1.ps1 ` -ProjectRoot $PWD ` -ConfirmDataLoss ` -RemoveLocalSecrets ` -RemovePatchBackups .\scripts\verify-public-release.ps1 -ProjectRoot $PWD ``` 有关最终的 Git 和 GitHub Pages 步骤，请参阅 [GIT_PUBLISH_CHECKLIST.md](GIT_PUBLISH_CHECKLIST.md)。 ## 最终 Docker 发布验证 在创建公共发布之前，请在支持 Docker 的 Windows 机器上运行破坏性洁净室验证器： ``` .\scripts\test-pulseguard-public-release-e2e.ps1 ` -ProjectRoot $PWD ` -ConfirmDataLoss ``` 验证器会创建新的本地密钥，移除之前的 PulseGuard 容器和卷，执行无缓存构建，启动所有服务，检查所有健康检查 endpoint，验证公共品牌和密钥安全响应，并执行针对检测、调查、治理、批准、自动修复和恢复验证的聚焦事件生命周期测试。 仅当替换现有的本地 `.env` 是安全的时候，才使用 `-ReplaceExistingEnv`。添加 `-CleanAfterTest` 以在报告写入后移除生成的 `.env`、容器、卷和本地镜像。结果将写入 `Downloads\PulseGuard-Docker-E2E-.txt`；失败会生成一个诊断 ZIP 文件。 ## 许可证 在 [MIT 许可证](LICENSE) 下发布。

标签：AIOps, AI合规, LLM代理, Petitpotam, 可靠性工程, 智能运维, 测试用例, 混沌工程, 版权保护, 自动化应急响应, 自定义请求头, 请求拦截, 逆向工具