# 并行版本使用指南

## 快速开始

```bash
# 基本使用（默认 20 个并行任务）
bash list-all-secrets-permissions-parallel.sh

# 指定项目和并行任务数
bash list-all-secrets-permissions-parallel.sh my-project-id 30
```

## 为什么需要并行版本？

### 问题场景

当你的项目有大量 Secret（如 350 个）时：

```
串行处理：
Secret 1 → Secret 2 → Secret 3 → ... → Secret 350
⏱️ 耗时：~35-70 分钟

并行处理：
Secret 1-20  ┐
Secret 21-40 ├→ 同时处理
Secret 41-60 ┘
...
⏱️ 耗时：~3-7 分钟
```

### 性能对比

| Secret 数量 | 串行版本 | 并行版本 (20 任务) | 速度提升 |
|------------|---------|-------------------|---------|
| 50 | 5 分钟 | 30 秒 | **10x** |
| 100 | 10 分钟 | 1 分钟 | **10x** |
| 200 | 20 分钟 | 2 分钟 | **10x** |
| 350 | 35 分钟 | 3.5 分钟 | **10x** |
| 500 | 50 分钟 | 5 分钟 | **10x** |

## 使用方法

### 1. 基本使用

```bash
# 使用当前项目，默认 20 个并行任务
bash list-all-secrets-permissions-parallel.sh

# 输出示例：
# =========================================
# GCP Secret Manager 权限审计 (并行版本)
# =========================================
# 项目 ID: my-project
# 并行任务数: 20
# 时间: 2024-11-14 10:30:00
# =========================================
#
# [1/5] 获取所有 Secret...
# 找到 350 个 Secret
#
# [2/5] 并行分析 Secret 权限...
# 使用 20 个并行任务
# [进度条显示]
# ✓ 完成！耗时: 210 秒
```

### 2. 指定项目

```bash
bash list-all-secrets-permissions-parallel.sh my-project-id
```

### 3. 调整并行任务数

```bash
# 保守配置（10 任务）
bash list-all-secrets-permissions-parallel.sh my-project 10

# 推荐配置（20 任务）
bash list-all-secrets-permissions-parallel.sh my-project 20

# 激进配置（50 任务）
bash list-all-secrets-permissions-parallel.sh my-project 50
```

## 并行任务数选择指南

### 决策表

| Secret 数量 | 推荐任务数 | 预期耗时 | 说明 |
|------------|-----------|---------|------|
| < 50 | 10 | < 1 分钟 | 小规模，保守配置 |
| 50-100 | 10-20 | 1-2 分钟 | 中等规模 |
| 100-300 | 20-30 | 2-5 分钟 | 大规模 |
| 300-500 | 30-40 | 3-7 分钟 | 超大规模 |
| > 500 | 40-50 | 5-10 分钟 | 极大规模 |

### 影响因素

**增加并行任务数的好处：**
- ✅ 处理速度更快
- ✅ 更快完成审计

**增加并行任务数的风险：**
- ⚠️ 可能触发 API 限流
- ⚠️ 占用更多系统资源
- ⚠️ 网络不稳定时失败率增加

**推荐策略：**
1. 首次使用：从 10 开始
2. 观察成功率和耗时
3. 逐步增加到 20-30
4. 找到最佳平衡点

## 输出文件

### 生成的文件

```
secret-audit-parallel-20241114-103000/
├── summary.txt                    # 📄 汇总报告
├── secrets-permissions.csv        # 📊 CSV 数据
├── secrets-permissions.json       # 📦 JSON 数据
├── report.md                      # 📝 Markdown 报告
└── report.html                    # 🌐 HTML 可视化报告
```

### 文件格式

**与串行版本完全相同！**

- CSV 格式相同
- JSON 格式相同
- 报告格式相同
- 可以使用相同的工具处理

## 依赖要求

### 必需依赖

- ✅ `gcloud` CLI
- ✅ `jq` (JSON 处理)
- ✅ `bash` 4.0+

### 可选依赖

- 🔧 `GNU parallel` (推荐，提供进度条)

### 安装 GNU Parallel

```bash
# macOS
brew install parallel

# Ubuntu/Debian
sudo apt-get install parallel

# CentOS/RHEL
sudo yum install parallel

# 验证安装
parallel --version
```

**如果不安装：**
- 脚本会自动使用 `xargs` 替代
- 功能完全相同
- 只是没有进度条显示

## 性能测试

### 运行基准测试

```bash
# 测试 10 个 Secret 的性能
bash benchmark-comparison.sh my-project 10

# 输出示例：
# =========================================
# 性能对比测试
# =========================================
# 项目 ID: my-project
# 测试样本: 10 个 Secret
# =========================================
#
# 测试 1: 串行处理
# 串行处理耗时: 60 秒
#
# 测试: 并行处理 (10 任务)
# 并行处理耗时: 6 秒
# 速度提升: 10.00x
#
# 测试: 并行处理 (20 任务)
# 并行处理耗时: 3 秒
# 速度提升: 20.00x
```

### 解读测试结果

```
全量处理预估 (350 个 Secret):
  串行处理: ~2100 秒 (~35 分钟)
  并行处理 (10 任务): ~210 秒 (~3.5 分钟)
  并行处理 (20 任务): ~105 秒 (~1.75 分钟)
```

## 常见问题

### Q1: 并行版本和串行版本有什么区别？

**A:** 只有处理速度不同，其他完全相同：

| 特性 | 串行版本 | 并行版本 |
|------|---------|---------|
| 输出格式 | ✅ 相同 | ✅ 相同 |
| 数据准确性 | ✅ 相同 | ✅ 相同 |
| API 调用次数 | ✅ 相同 | ✅ 相同 |
| 处理速度 | 慢 | **快 10-20 倍** |

### Q2: 会不会触发 API 限流？

**A:** 使用推荐配置（20 任务）通常不会：

```
Secret Manager API 配额:
- 读取操作: 60,000 次/分钟
- 并发请求: 1,000

20 个并行任务远低于配额限制
```

**如果遇到限流：**
```bash
# 减少并行任务数
bash list-all-secrets-permissions-parallel.sh my-project 10
```

### Q3: 需要安装额外的软件吗？

**A:** 可选安装 GNU parallel：

```bash
# 不安装 GNU parallel
✅ 功能完全正常
✅ 使用 xargs 替代
❌ 没有进度条

# 安装 GNU parallel
✅ 功能完全正常
✅ 有进度条显示
✅ 更好的性能监控
```

### Q4: 如何选择合适的并行任务数？

**A:** 使用决策流程：

```
1. 首次使用 → 10 任务
2. 观察耗时和成功率
3. 如果成功 → 增加到 20
4. 如果仍然成功 → 增加到 30
5. 找到最佳平衡点
```

### Q5: 并行版本更消耗资源吗？

**A:** 略微增加，但可以接受：

```
资源使用对比:
- CPU: 略微增加（多进程）
- 内存: 略微增加（临时文件）
- 网络: 相同（API 调用次数相同）
- 磁盘: 相同（输出文件相同）

对于现代计算机，影响可以忽略
```

## 故障排查

### 问题 1: 脚本提示 "jq: command not found"

**解决方案：**
```bash
# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# CentOS/RHEL
sudo yum install jq
```

### 问题 2: API 限流错误

**错误信息：**
```
ERROR: (gcloud.secrets.get-iam-policy) RESOURCE_EXHAUSTED: Quota exceeded
```

**解决方案：**
```bash
# 减少并行任务数
bash list-all-secrets-permissions-parallel.sh my-project 10

# 或等待几分钟后重试
```

### 问题 3: 内存不足

**错误信息：**
```
bash: fork: Cannot allocate memory
```

**解决方案：**
```bash
# 减少并行任务数
bash list-all-secrets-permissions-parallel.sh my-project 5

# 或增加系统内存限制
ulimit -v unlimited
```

### 问题 4: 进度条不显示

**原因：**
- 未安装 GNU parallel
- 脚本自动使用 xargs

**解决方案：**
```bash
# 安装 GNU parallel（可选）
brew install parallel  # macOS
sudo apt-get install parallel  # Ubuntu

# 或继续使用 xargs（功能相同）
```

## 最佳实践

### 1. 首次使用

```bash
# 使用保守配置
bash list-all-secrets-permissions-parallel.sh my-project 10

# 检查结果
cat secret-audit-*/summary.txt

# 如果成功，下次可以增加并行任务数
```

### 2. 定期审计

```bash
# 每周一早上 9 点运行
# crontab -e
0 9 * * 1 /path/to/list-all-secrets-permissions-parallel.sh my-project 20
```

### 3. 大规模审计

```bash
# 对于 500+ Secret
bash list-all-secrets-permissions-parallel.sh my-project 30

# 监控执行情况
tail -f secret-audit-*/summary.txt
```

### 4. 结果分析

```bash
# 使用 Excel 打开 CSV
open secret-audit-*/secrets-permissions.csv

# 使用浏览器查看 HTML
open secret-audit-*/report.html

# 使用 jq 查询 JSON
jq '.[] | select(.summary.groups > 0)' secret-audit-*/secrets-permissions.json
```

## 性能优化技巧

### 1. 网络优化

```bash
# 启用 HTTP/2
export CLOUDSDK_CORE_USE_HTTP2=true

# 运行脚本
bash list-all-secrets-permissions-parallel.sh my-project 20
```

### 2. 缓存优化

```bash
# 预热 gcloud 缓存
gcloud secrets list --project=my-project > /dev/null

# 运行脚本
bash list-all-secrets-permissions-parallel.sh my-project 20
```

### 3. 资源限制调整

```bash
# 增加文件描述符限制
ulimit -n 4096

# 运行脚本
bash list-all-secrets-permissions-parallel.sh my-project 20
```

## 与串行版本对比

### 何时使用并行版本？

✅ **推荐使用并行版本：**
- Secret 数量 > 50
- 需要快速完成审计
- 网络连接稳定
- 有充足的 API 配额

✅ **使用串行版本：**
- Secret 数量 < 50
- 需要实时详细输出
- 网络不稳定
- API 配额有限

### 功能对比

| 功能 | 串行版本 | 并行版本 |
|------|---------|---------|
| 输出格式 | ✅ | ✅ |
| 数据准确性 | ✅ | ✅ |
| 实时输出 | ✅ | ⚠️ 批量输出 |
| 处理速度 | ⚠️ 慢 | ✅ 快 10-20 倍 |
| 进度显示 | ✅ 详细 | ✅ 进度条 |
| 资源占用 | ✅ 低 | ⚠️ 略高 |
| 依赖要求 | ✅ 少 | ⚠️ 需要 jq |

## 总结

### 关键要点

1. **速度提升 10-20 倍** - 对于 350 个 Secret，从 35 分钟降到 3.5 分钟
2. **输出格式相同** - 可以使用相同的工具和流程处理结果
3. **推荐配置 20 任务** - 平衡速度和稳定性
4. **可选安装 GNU parallel** - 获得进度条显示
5. **API 调用次数相同** - 不会增加成本

### 快速决策

```
Secret 数量 < 50  → 使用串行版本
Secret 数量 > 50  → 使用并行版本（20 任务）
Secret 数量 > 300 → 使用并行版本（30 任务）
```

### 下一步

1. 运行基准测试了解性能
2. 选择合适的并行任务数
3. 定期运行审计
4. 分析结果并优化权限

---

**相关文档：**
- [性能优化指南](./PERFORMANCE-OPTIMIZATION.md)
- [基准测试脚本](./benchmark-comparison.sh)
- [原版使用指南](../README-audit-scripts.md)

**更新日期:** 2024-11-14  
**版本:** 1.0
