内容
# FinSavant: Dazbo 的谷歌云财务运营智能
由 [Dazbo](https://dazbo.co.uk) 创建的，用于谷歌云平台（GCP）的财务运营智能代理解决方案，旨在帮助云平台工程师和财务运营实践者管理、理解和优化整个组织云支出。
## 目录
- [功能](#功能)
- [相关文章](#相关文章)
- [目标受众](#目标受众)
- [成功指标](#成功指标)
- [项目结构](#项目结构)
- [需求](#需求)
- [快速入门](#快速入门)
- [命令](#命令)
- [本地开发和测试流程](#本地开发和测试流程)
- [作为独立服务运行（热加载）](#作为独立服务运行热加载)
- [步骤 1：初始化依赖项](#步骤-1初始化依赖项)
- [步骤 2：运行应用程序](#步骤-2运行应用程序)
- [作为单个 Docker 容器运行](#作为单个-docker-容器运行)
- [步骤 3：运行测试和质量检查](#步骤-3运行测试和质量检查)
- [交互式笔记本原型设计](#交互式笔记本原型设计)
- [CI/CD 和部署流程](#cicd-和部署流程)
- [GitHub Actions 工作流](#github-actions-工作流)
- [IAM 权限和验证](#iam-权限和验证)
- [技术架构](#技术架构)
- [有用链接和参考](#有用链接和参考)
- [许可证](#许可证)
## 功能
- **BigQuery 计费集成**：直接访问 BigQuery 计费导出，进行跨项目成本分析。
- **BigQuery ADK 集成**：使用 ADK 的原生 `BigQueryToolset`，具有本地查询缓存，实现原生数据集和表架构感知。
- **自然语言聊天界面**：基于 React 的用户界面，允许用户用纯英文查询计费数据和基础设施状态。
- **财务运营仪表盘**：成本趋势、异常报告和优化进度的集中视图。
- **僵尸资源检测和审计**：主动识别成本浪费，例如未附加的持久磁盘，使用云资产库存。将计费峰值与历史配置更改相关联。
- **多项目分析**：能够将分析范围限定为特定项目、计费账户或整个谷歌云组织。
- **人工智能驱动的预测**：使用历史数据预测未来的云消耗和预算需求。
- **自动异常检测**：主动识别不寻常的计费峰值和成本低效。
- **可行的建议**：将计费洞察与架构最佳实践相结合，实现高影响力的成本优化。
[](https://youtu.be/zs_IRUxIx4E)
## 相关文章
本存储库与一系列多部分文章相关联，记录了 FinSavant 的设计、实现和部署：
1. 目标、架构和技术栈：能力、项目目标、目标架构、技术栈和设计决策。
2. 使用谷歌 Antigravity、ADK、Agents CLI、MCP 和技能设置开发环境
3. 使用 A2UI 构建动态用户界面
4. 使用 IAP、Terraform 和 CI/CD 进行身份验证
5. 使用 Gemini Enterprise Agent 平台观察、评估和调整我们的代理
## 目标受众
- **云平台工程师**：管理基础设施和资源生命周期。
- **财务运营实践者**：专门的团队负责云财务治理。
- **GCP 组织管理员**：监督大规模云足迹的成本和合规性。
## 成功指标
- **支出减少百分比**：目标是减少未优化的支出。
- **异常检测速度**：最小化计费异常的平均检测时间（MTTD）。
- **预测准确性**：项目预算与实际实现的准确性。
## 项目结构
```
smart-gcp-finops/
├── app/ # 独立代理运行时包（ADK 代理）
│ ├── finops_agent/ # 核心 ADK 代理 Python 包
│ │ ├── app_utils/ # CAI、BQ 工具、凭证和缓存助手
│ │ ├── agent.py # 根代理定义和工具路由
│ │ ├── deploy_to_agent_runtime.py # 将代理部署到代理运行时
│ │ ├── agent_runtime_app.py # 远程代理运行时的启动器
│ │ └── requirements.txt # 部署时动态生成
│ ├── .env # 代理特定环境变量
│ ├── agents-cli-manifest.yaml # ADK 代理 CLI 清单，支持生命周期
│ ├── Dockerfile # 将代理部署到代理运行时
│ └── pyproject.toml # 代理运行时依赖项
├── bff/ # 前端后端（FastAPI 网络应用）
│ ├── Dockerfile # 仅限 UI/BFF 的 Dockerfile（待定）
│ └── fast_api_app.py # 为 UI 提供服务，代理查询和管理 SSE 流
├── deployment/ # 基础设施和 CI/CD（Terraform IaC）
│ └── terraform/ # 生产和暂存的集中式 IaC
├── docs/ # 系统范围的架构和设计文档
│ ├── images/ # 图表和架构视觉资产
│ ├── DESIGN.md # 视觉身份、组件和设计令牌
│ ├── architecture-and-walkthrough.md # 解决方案蓝图、ADR 和组件数据流
│ └── testing.md # 测试策略和验证指令
├── frontend/ # 单页应用（React + Vite + Stitch）
│ ├── src/ # 应用源代码
│ └── index.html # 首页
├── notebooks/ # Jupyter 笔记本，用于原型设计和评估
│ └── adk_app_testing.ipynb # 用于测试本地和远程运行的交互式游乐场
├── scripts/ # 环境设置和其他实用脚本
├── tests/ # 单元和集成测试套件
├── .gemini/ # Gemini 配置（MCP 设置）
├── .github/ # GitHub Actions 工作流和 CI/CD
├── Dockerfile # 统一开发镜像配置
├── Makefile # 集中式开发者命令管道
├── GEMINI.md # 开发者上下文和指南
├── pyproject.toml # 根开发者环境配置
├── README.md # 开发者文档首页
└── TODO.md # 待办事项列表
```
## 需求
开始前，请确保您已具备：
- **uv**：Python 包管理器（Python 3.13+）
- **谷歌云 SDK**：已通过身份验证您的 GCP 项目
- **Terraform**：用于基础设施部署
- **make**：构建自动化工具
## 快速入门
安装所需包并启动本地开发环境：
```bash
make install && make playground
```
## 命令
| 命令 | 描述 |
| -------------------- | ----------------------------------------------------------------- |
| `make install` | 使用 `uv` 安装依赖项 |
| `make playground` | 启动本地开发环境（ADK 开发界面） |
| `make run-backend` | 在本地运行后端 BFF 服务器（在未设置 `AGENT_RUNTIME_ID` 时本地运行代理） |
| `make run-frontend` | 启动 React UI 的 Vite 开发服务器 |
| `make lint` | 运行后端代码质量检查（`ruff`、`codespell`、`ty`） |
| `make test-ui` | 运行前端编译器和 lint 检查（TypeScript、ESLint） |
| `make test` | 运行单元和集成测试（`pytest`） |
| `make build` | 在本地构建统一的生产容器镜像 |
| `make docker-build` | 在本地构建统一的生产容器镜像（React + FastAPI） |
| `make docker-run` | 在本地运行构建的容器（默认本地运行代理；设置 `DOCKER_AGENT_RUNTIME_ID` 进行代理） |
| `make run` | `make docker-run` 的快捷方式，在本地运行容器 |
| `make tf-plan` | 初始化 Terraform 并计划基础设施部署 |
| `make tf-apply` | 初始化 Terraform 并应用部署配置 |
| `make deploy-agent-runtime` | 将后端代理代码部署到 Gemini Enterprise 代理运行时 |
| `make get-agent-runtime-id` | 检索已部署的代理运行时 ID（资源 URN） |
| `make deploy-cloud-run` | 使用 Cloud Build 将 BFF 容器部署到 Cloud Run。传递 `LOG_LEVEL=DEBUG` 以启用调试 |
## 本地开发和测试流程
应用程序可以在本地以两种不同的方式运行：
1. **独立服务**（推荐用于主动开发）：分别运行 React 前端和 FastAPI 后端，作为单独的热加载进程。
2. **统一 Docker 容器**：在单个本地 Docker 容器中运行整个应用程序（编译的 React 资产 + FastAPI 后端），复制生产环境。
### 作为独立服务运行（热加载）
要在本地作为独立服务运行 React 前端和 FastAPI 后端，请遵循此开发工作流：
### 步骤 1：初始化依赖项
在一步中自动安装后端 Python 包依赖项（`uv sync`）和 React 前端包依赖项（`npm install`）：
```bash
make install
```
### 步骤 2：运行应用程序
您需要两个单独的终端会话来同时运行两个服务器：
* **终端 1（后端）**：在 `http://localhost:8000` 上启动 FastAPI 后端 BFF：
```bash
make run-backend
```
* **终端 2（前端）**：在 `http://localhost:5173` 上启动 Vite 开发服务器：
```bash
make run-frontend
```
在浏览器中导航到 `http://localhost:5173`。前端会自动将所有 `/api` 和 `/events` 查询代理到后端。
### 作为单个 Docker 容器运行
或者，您可以使用 Docker 在本地运行整个统一容器（捆绑编译的 React 前端和 FastAPI 后端）：
```bash
# 在本地构建统一容器镜像
make docker-build
# 在本地以回退模式运行容器（在容器内本地执行代理）
make docker-run
# 在本地以远程代理模式运行容器（连接到远程代理运行时）：
make docker-run DOCKER_AGENT_RUNTIME_ID=$(AGENT_RUNTIME_ID)
```
这将应用程序启动在 `http://localhost:8000` 上，与在 Cloud Run 上完全相同。
### 步骤 3：运行测试和质量检查
在将更改提交到 git 之前，请验证后端和前端是否健康：
* **后端 Linting 和类型**：运行 `ruff` linting/formatting 和 `ty` 静态类型检查：
```bash
make lint
```
* **前端 Linting 和编译**：运行 `eslint` 检查并编译生产包以验证零 TypeScript 错误：
```bash
make test-ui
```
* **单元和集成测试**：执行后端 pytest 覆盖率检查：
```bash
make test
```
### 交互式笔记本原型设计
交互式笔记本位于 [adk_app_testing.ipynb](notebooks/adk_app_testing.ipynb)，用于在沙箱环境中测试代理：
- **本地测试**：在项目虚拟环境中实例化代理逻辑。
- **远程测试（代理运行时）**：与已部署的 Gemini Enterprise 代理运行时交互。
- **远程测试（Cloud Run）**：触发已部署的 uvicorn 服务器/SSE 流式接口。
有关完整使用说明，请参阅 [测试指南](docs/testing.md#交互式测试通过-jupyter-笔记本).
## CI/CD 和部署流程
FinSavant 使用解耦的 GitHub Actions 工作流，在发布到生产环境之前强制执行严格的质量检查。架构将应用程序分为两个部署目标：
1. **代理逻辑（Gemini Enterprise 代理运行时）**：托管代理的 Python 代码、回调和工具的无服务器环境。
2. **BFF + UI（Cloud Run）**：托管静态 React 资产和 FastAPI 薄代理层的轻量级容器。
### GitHub Actions 工作流
* **持续集成（暂存）**：
- **触发器**：在推送或合并到 `main` 分支时自动。
- **操作**：[.github/workflows/staging.yaml](.github/workflows/staging.yaml) 工作流自动打包并将代理逻辑部署到暂存代理运行时 (`finops-admin-dev`)，提取生成的 `AGENT_RUNTIME_ID`，构建统一容器镜像，并将镜像部署到暂存 Cloud Run BFF，并使用正确的引擎 ID。
* **验证**：验证暂存环境以确保所有代理工具、BigQuery MCP 连接和 React 组件渲染正确。
* **手动门控（生产）**：
- **触发器**：GitHub Actions 中的手动触发（“工作流调度”）。
- **操作**：[.github/workflows/deploy-to-prod.yaml](.github/workflows/deploy-to-prod.yaml) 工作流将代理部署到生产代理运行时 (`finops-admin-prd`)，提取生产 ID，并将 BFF 容器部署到生产 Cloud Run。
有关网络变量、服务帐户和 Terraform 变量传播的详细信息，请参阅 [部署 README](deployment/README.md)。
## IAM 权限和验证
对于代理和执行仪表板发现 GCP 资源和项目，查询开发人员的帐户（和已部署的应用程序服务帐户）必须具有适当的云资产库存权限。
请参阅部署 README 中的 [IAM 权限和验证](deployment/README.md#iam-权限和验证) 部分，获取：
- 验证用户权限的验证命令。
- 在组织、文件夹或项目级别授予缺少角色的 `gcloud` 命令。
- 用于将权限绑定到所有项目或独立（孤立）项目的帮助性 bash 脚本，这些项目链接到您的计费账户。
## 技术架构
- **编排**：使用 **Google ADK** 进行强大的多代理编排、会话上下文管理和遥测。
- **API**：谷歌云助手 API、谷歌开发者知识 API 和云资产库存。
- **数据层**：通过原生 ADK `BigQueryToolset` 和缓存 SQL 查询直接访问 BigQuery 的语义模式。
- **基础设施**：GCS 支持的远程状态，用于通过 Terraform 管理的一致性多环境管理。
- **前端**：使用 **Stitch** 构建的 React（TypeScript），具有高信息密度，利用 **Agent-to-UI（A2UI）** 动态渲染表和图表等丰富组件。
- **安全边界和行级过滤**：**Identity-Aware Proxy（IAP）** 与 Cloud Run 原生集成，用于企业级身份验证。FastAPI BFF 从 `x-goog-authenticated-user-email` 头部提取用户身份，解析项目/组织 IAM 权限，并将所有 BigQuery 查询包装在子查询中，以强制执行严格的行级安全。
- **混合执行**：支持两种运行模式：
- *远程执行模式*：BFF 充当无状态代理，连接到 Google 代理运行时上的远程代理。
- *本地回退模式*：如果未配置远程运行时 ID，BFF 在容器内本地加载代理，使用开发人员的应用默认凭证（ADC）运行 ADK 引擎。
- **部署**：**统一容器** 架构（捆绑编译的 React 资产 + FastAPI），托管在 **Google Cloud Run** 上。
## 有用链接和参考
### Dazbo 的作品集和出版物
- [Dazbo 的作品集](https://dazbo.co.uk)
- [在没有负载均衡器的情况下在 Cloud Run 上使用 Google IAP（Dazbo 在 Medium 上的文章）](https://medium.com/google-cloud/using-google-identity-aware-proxy-iap-with-cloud-run-without-a-load-balancer-27db89b9ed49?sharedUserId=derailed.dash)
- [FinSavant 视频演示（YouTube）](https://youtu.be/zs_IRUxIx4E)
### Gemini Enterprise 代理平台和 ADK
- [Gemini Enterprise 代理平台概述](https://docs.cloud.google.com/gemini-enterprise-agent-platform/overview?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [代理运行时（ADK 主机）](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/runtime?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [ADK 代理构建指南](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/adk?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [代理 CLI 文档](https://google.github.io/agents-cli/?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [ADK BigQuery 工具集成](https://adk.dev/integrations/bigquery/?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [代理注册表概述](https://docs.cloud.google.com/agent-registry/overview?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [GEAP 内存库](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/memory-bank?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [代理网关文档](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-overview?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [模型护甲安全概述](https://docs.cloud.google.com/model-armor/overview?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [GEAP 可观察性和遥测](https://docs.cloud.google.com/gemini-enterprise-agent-platform/optimize/observability/overview?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [代理评估](https://docs.cloud.google.com/gemini-enterprise-agent-platform/optimize/evaluation/agent-evaluation?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
### 谷歌云服务和 API
- [Cloud Run 概述](https://docs.cloud.google.com/run/docs/overview/what-is-cloud-run?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [Identity-Aware Proxy（IAP）概述](https://docs.cloud.google.com/iap/docs/concepts-overview?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [谷歌云助手](https://docs.cloud.google.com/cloud-assist/overview?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [云资产库存（CAI）API](https://docs.cloud.google.com/asset-inventory/docs/overview?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [开发者知识 MCP 服务器](https://developers.google.com/knowledge/mcp?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
### GCP 计费和财务运营
- [谷歌云财务运营中心](https://docs.cloud.google.com/billing/docs/how-to/finops-hub?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
- [BigQuery 计费导出设置](https://docs.cloud.google.com/billing/docs/how-to/export-data-bigquery?utm_campaign=DEVECO_GDEMembers&utm_source=deveco)
## 许可证
该项目使用 MIT 许可证 - 参见 [LICENSE](LICENSE) 文件以获取详细信息。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器