tollingvision/sar-cluster
GitHub: tollingvision/sar-cluster
一套基于 AWS Serverless 的 SAR 模板，用于部署具备高可用与安全特性的自动车牌/车型识别基础设施。
Stars: 2 | Forks: 0
# Tolling Vision SAR 基础设施
[](https://serverlessrepo.aws.amazon.com/)
[](https://opensource.org/licenses/MIT)
[](template.yaml)
[](https://github.com/tollingvision/sar-cluster/releases)
[](https://github.com/tollingvision/sar-cluster/stargazers)
完整的 AWS Serverless Application Repository (SAR) 模板，用于部署安全、可扩展的 **Tolling Vision ANPR/MMR**（自动车牌识别/车型识别）处理基础设施。
## 🏗️ 架构概述
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ API Clients │───▶│ Public ALB │───▶│ VPC │
│ │ │ (HTTPS:443) │ │ │
└─────────────────┘ └──────────────────┘ │ ┌─────────────────┐│
│ │ │ Auto Scaling ││
┌────────▼────────┐ │ │ Group ││
│ Optional WAF │ │ │ (Lambda Created)││
│ Protection │ │ └─────────────────┘│
└─────────────────┘ │ │ │
│ ┌─────────▼───────┐ │
┌─────────────────┐ ┌──────────────────┐ │ │ EC2 Instances │ │
│ Optional Route53│───▶│ Custom Domain │ │ │ (Private IPs) │ │
│ DNS Records │ │ (Optional) │ │ │ │ │
└─────────────────┘ └──────────────────┘ │ │ Container JWT │ │
│ │ Auth (Optional) │ │
│ └─────────────────┘ │
└─────────────────────┘
```
## ✨ 关键特性
### 🔒 **安全优先**
- **私有基础设施**：所有计算资源位于私有子网，无公网 IP
- **公共 ALB 入口**：单一面向互联网的负载均衡器，终止 HTTPS
- **容器级 JWT 认证**：可选的 Cognito 基础 JWT 验证
- **可选 WAF 保护**：第 7 层过滤与 IP 允许列表及 AWS 受管规则
- **IAM 最小权限**：所有组件所需权限最小化
### 🚀 **简化架构**
- **Lambda 自定义资源**：为 SAR 兼容性创建 Auto Scaling 组和 WAF 资源
- **协议支持**：HTTP/1.1 与 gRPC-Web（端口 443）
- **可选 DNS 管理**：Route53 集成自定义域名
### 🧩 **实现说明**
- 活动 Lambda 自定义资源处理程序直接嵌入在 [template.yaml](template.yaml) 中的内联 `ZipFile` 代码。
- 目前使用的 SAR 自定义资源无需单独的 Python 源码包进行构建。
- 部署与发布辅助脚本位于 `scripts/` 目录下。
### 📈 **可扩展性与性能**
- **自动伸缩**：可配置容量，支持按需/竞价实例
- **多可用区部署**：跨可用区的高可用性
- **架构支持**：ARM64（默认）与 x86-64 容器
- **负载均衡**：应用负载均衡器与健康检查
### 💰 **成本优化**
- **竞价实例**：可配置比例以节省成本
- **合理尺寸实例**：根据 ProcessCount 自动选择
- **ARM64 默认**：更优的价格/性能比
- **灵活伸缩**：空闲时缩容至零
## 📋 先决条件
### 必需资源
1. **Tolling Vision 许可证密钥**：来自 tollingvision.com 的有效许可证密钥（`LicenseKey` 参数）
2. **最大实例数**：必须指定最大实例数量（`MaxSize` 参数）
### 可选资源（增强功能）
1. **SSL 证书**：HTTPS 所需的 ACM 证书（生产环境推荐）
2. **自定义域名**：用于 Route53 DNS 管理的域名
3. **Cognito 用户池**：用于 JWT 认证的现有用户池
4. **Route53 托管区域**：用于自动 DNS 记录创建
### AWS 权限
- CloudFormation 堆栈创建
- Lambda 函数执行
- VPC 与网络资源创建
- IAM 角色与策略管理
## 🔧 仓库布局
### 活动源码
- [template.yaml](template.yaml)：规范 SAR 模板，包含当前部署的内联自定义资源 Lambda 代码。
- [scripts/publish-sar.sh](scripts/publish-sar.sh)：主要 SAR 发布工作流。
### 保留的支持文件
- [scripts/fix-sar-s3-permissions.sh](scripts/fix-sar-s3-permissions.sh)：可选的 S3 存储桶策略修复助手（用于 SAR 托管工件）
- [scripts/s3-bucket-policy-for-sar.json](scripts/s3-bucket-policy-for-sar.json)：SAR 故障排除工作流使用的存储桶策略模板
### 当前使用说明
- 主要的发布路径是 [scripts/publish-sar.sh](scripts/publish-sar.sh)。
- 除发布外，仅保留 SAR S3 权限修复助手作为已记录的支持路径。
## ⚙️ 配置参数
### 🔑 **必需配置**
| 参数 | 说明 | 示例 |
|------|------|------|
| `LicenseKey` | Tolling Vision 许可证密钥 | `your-license-key` |
| `MaxSize` | 最大实例数量 | `10` |
### 🐳 **容器配置**
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `ConcurrentRequestCount` | `1` | 每个进程的并发请求数 |
| `ProcessCount` | `1` | 处理线程（1-64） |
| `MaxRequestSize` | `6291456` | 最大请求大小（6MB） |
| `ImageArchitecture` | `arm64` | 容器架构 |
| `ImageTag` | `arm64` | 容器镜像标签 |
| `Backlog` | `10` | 请求队列大小 |
| `BacklogTimeout` | `60` | 队列超时（秒） |
| `RequestTimeout` | `30` | 请求超时（秒） |
### 🔧 **自动伸缩配置**
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `MinSize` | `0` | 最小实例数 |
| `DesiredCapacity` | `0` | 初始实例数 |
| `OnDemandPercentage` | `100` | 按需与竞价比例 |
| `KeyPairName` | 空 | EC2 密钥对（可选） |
| `EnableDetailedMonitoring` | `false` | 启用详细的 CloudWatch 监控 |
### 🌐 **网络与域名与 SSL 配置（可选）**
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `VpcCidr` | `10.0.0.0/16` | VPC CIDR 块 |
| `PrivateSubnet1Cidr` | `10.0.1.0/24` | 私有子网 1 CIDR |
| `PrivateSubnet2Cidr` | `10.0.2.0/24` | 私有子网 2 CIDR |
| `PublicSubnet1Cidr` | `10.0.101.0/24` | 公共子网 1 CIDR |
| `PublicSubnet2Cidr` | `10.0.102.0/24` | 公共子网 2 CIDR |
| `DomainName` | 空 | 自定义域名 |
| `CertificateArn` | 空 | HTTPS 的 ACM 证书 ARN |
| `EnableDNS` | `false` | 创建 Route53 DNS 记录 |
### 🔐 **容器级 JWT 认证（可选）**
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `CognitoUserPoolId` | 空 | 现有 Cognito 用户池 ID |
| `CognitoRegion` | 空 | Cognito 用户池的 AWS 区域 |
| `CognitoAppClientId` | 空 | Cognito 应用客户端 ID |
| `CognitoRequiredScope` | 空 | 访问所需的 JWT 范围 |
### 🛡️ **安全与日志（可选）**
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `EnableWAF` | `false` | 在 ALB 上启用 WAF 保护 |
| `AllowedIpCidrs` | 空 | WAF 规则的 IP CIDR 范围 |
| `EnableAWSManagedRules` | `true` | 启用 AWS 受管规则组 |
| `CloudWatchLogRetentionDays` | `7` | CloudWatch 日志保留天数 |
| `EnableSNSNotifications` | `false` | 启用 SNS 通知 |
| `SNSNotificationEmail` | 空 | 通知电子邮件地址 |
| `EnableCustomMetrics` | `true` | 启用自定义应用指标 |
| `EnableALBAccessLogs` | `false` | 启用 ALB 访问日志到 S3 |
| `ALBAccessLogsBucketName` | 空 | S3 存储桶用于 ALB 日志 |
##🔌 API 端点
部署后，您的 Tolling Vision API 将可通过以下地址访问：
### 使用自定义域名（启用 DNS 管理时）
```
# HTTP/1.1 Endpoint
https://DOMAIN_NAME/
```
### 使用 ALB DNS 名称（默认）
```
# HTTP/1.1 Endpoint
https://GENERATED_LB_NAME-AWS_ACCOUNT_ID.REGION.elb.amazonaws.com/
```
### ℹ️ 如何查找 ALB DNS 名称
如果未启用自定义域名的 DNS 管理，**应用负载均衡器（ALB）DNS 名称**可在 **CloudFormation 堆栈 Outputs** 中找到。查找键名：`ALBEndpoint`。
### 协议详情
- **HTTP/1.1 + gRPC-Web**：端口 443（HTTPS）→ 容器端口 80（HTTP）
- **健康检查**：`/` 端点（状态码：200）
## 🔑 认证
### 容器级 JWT 认证（可选）
启用 JWT 认证后，容器将使用提供的 Cognito 配置在内部验证 JWT 令牌。
#### 先决条件
1. **现有 Cognito 用户池**：必须单独创建
2. **应用客户端**：配置为客户端凭证流
3. **资源服务器**：定义自定义范围
### JWT 令牌生成
```
# 获取客户端凭据（来自您的 Cognito 设置）
CLIENT_ID="your-app-client-id"
CLIENT_SECRET="your-app-client-secret"
USER_POOL_DOMAIN="your-user-pool-domain"
# 生成 JWT 令牌
curl -X POST https://your-cognito-domain.auth.region.amazoncognito.com/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=$CLIENT_SECRET&scope=api/m2m"
```
## 📊 增强型监控与可观测性
### 🎯 **综合仪表板**
- **实时指标**：ALB、自动伸缩组、Lambda 性能
- **自定义应用指标**：容器启动、许可证验证、处理请求/错误
- **健康概览**：单值小部件快速状态概览
- **日志分析**：近期错误与故障排查信息
### 🚨 **关键告警与通知**
- **SNS 电子邮件通知**：关键问题的可配置邮件告警
- **CloudWatch 告警**：Lambda 错误、ALB 不健康目标、自动伸缩组问题、容器错误
- **升级路径**：生产关键故障的即时通知
### 📈 **自定义应用指标**
- **命名空间**：`TollingVision/Application`
- **容器生命周期**：启动事件、许可证验证状态
- **处理性能**：请求吞吐量、错误率、响应时间
- **业务指标**：ANPR/MMR 处理统计与成功率
### 📋 **CloudWatch 资源**
- **容器日志**：`/aws/ec2/tolling-vision/[stack-name]`
- **Lambda 日志**：`/aws/lambda/[stack-name]-custom-resource-handler`
### 🎛️ **监控配置**
```
# 启用增强监控功能
EnableSNSNotifications: 'true'
SNSNotificationEmail: 'admin@example.com'
EnableCustomMetrics: 'true'
```
### 📊 **仪表板访问**
访问您的操作仪表板：
```
https://[region].console.aws.amazon.com/cloudwatch/home?region=[region]#dashboards:name=[stack-name]-operational-dashboard
```
有关监控设置的详细说明与故障排查，请参阅 [增强监控指南](docs/ENHANCED-MONITORING-GUIDE.md)。
## 🛠️ 故障排查
### 🔧 **基础设施问题**
#### 容器启动失败
**问题**：无效的许可证密钥或资源不足
**解决方案**：检查容器日志与许可证验证
#### JWT 认证错误
**问题**：无效令牌或范围配置错误
**解决方案**：验证 Cognito 配置与令牌生成
### 📚 **详细故障排查**
完整的故障排查指南请参考：
- [SAR 故障排除指南](docs/SAR-TROUBLESHOOTING-GUIDE.md) - SAR 部署问题
- [增强监控指南](docs/ENHANCED-MONITORING-GUIDE.md) - 监控与告警问题
### 支持资源
- **CloudFormation 事件**：监控堆栈部署进度
- **Lambda 日志**：自定义资源执行详情
- **容器日志**：应用级故障排查
- **ALB 健康检查**：后端连接状态
## 📄 许可证
本项目根据 MIT 许可证授权 - 详见 [LICENSE](LICENSE) 文件。
### 重要声明
**本模板启动的 Docker 容器镜像不受 MIT 许可证覆盖。**
它们是 Smart CFloud Solutions Inc. 提供的商业软件，受单独的
最终用户许可协议（EULA）约束：https://tollingvision.com/eula/
运行容器镜像需要有效的 Tolling Vision 许可证密钥和活跃的注册/订阅。
## 📞 支持
技术问题与支持请咨询：
- **问题**：GitHub Issues
- **文档**：本 README 与内联模板注释
- **AWS 支持**：AWS 相关问题请使用 AWS 支持渠道
**注意**：本模板使用 Lambda 自定义资源以克服 AWS SAR 限制，同时保持完整功能与市场兼容性。
标签：ALB, ANPR, API 网关, AppImage, Auto Scaling, AWS, CloudFormation, DPI, HTTPS, ITS, JWT, Lambda, Make Model Recognition, MMR, SAR, Serverless, Serverless Application Repository, Tolling Vision, VPC, WAF, Web应用防火墙, 交通, 保护, 安全, 应用负载均衡器, 开源, 收费系统, 智能交通, 模板, 漏洞利用检测, 物联网, 自动扩展, 自动车牌识别, 自定义资源, 视频分析, 认证, 请求拦截, 超时处理, 车型识别, 车牌识别, 边缘计算, 部署模板