企业 GCP 部署指南 - Energent.ai

Energent.ai 提供 AI 驱动的虚拟桌面代理，能够为企业用户自动化复杂的多应用工作流程。本指南提供了使用现代云原生架构（包括 GKE、多租户设计和企业级安全控制）在 Google Cloud Platform 上进行全面部署的规范。

• 文档分类: 公开
• 版本: 3.0
• 最后更新: 2025-05-28
• 架构: GCP GKE + 无服务器混合
• 合规性: SOC 2，Google Cloud 安全最佳实践

目录

1. 架构概述
2. GCP 基础设施要求
3. GKE 集群规范
4. 数据层架构
5. 无服务器组件
6. 安全与合规
7. 网络架构
8. CI/CD 流水线
9. 监控与可观测性
10. 部署流程
11. 运营与维护
12. 支持与升级

1. 架构概述

1.1 云原生多租户架构

Energent.ai 部署在 Google Cloud Platform 上，采用现代化、可扩展的架构，将 Kubernetes 编排与无服务器组件相结合，以实现最佳性能和成本效率。

┌──────────────────────────────────────────────────────────────────┐
│                        GCP 云环境                                │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐   │
│  │   GKE 集群      │  │   无服务器      │  │   数据层         │   │
│  │                 │  │                 │  │                 │   │
│  │ • 多租户        │  │ • 函数认证      │  │ • Firestore      │   │
│  │ • n2-standard-4 │  │ • 函数计费      │  │ • Cloud Storage  │   │
│  │ • 自动扩展      │  │ • API 网关      │  │ • Filestore      │   │
│  │ • Flux GitOps   │  │ • Pub/Sub       │  │ • 密钥管理器     │   │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘   │
│           │                     │                    │           │
│           └─────────────────────┼────────────────────┘           │
│                                 │                                │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    VPC 安全边界                             │ │
│  │  • 私有子网      • Cloud NAT    • 防火墙规则                │ │
│  │  • IAP 隧道      • VPC 端点     • 负载均衡                 │ │
│  └─────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘

1.2 部署模型

2. GCP 基础设施要求

2.1 最低基础设施规范

2.2 GCP 服务依赖

3. GKE 集群规范

3.1 集群配置

# GKE 集群 Terraform 配置
resource "google_container_cluster" "energent_cluster" {
name     = "energent-production"
location = var.gcp_region

remove_default_node_pool = true
initial_node_count       = 1

network    = google_compute_network.vpc.name
subnetwork = google_compute_subnetwork.subnet.name

networking_mode = "VPC_NATIVE"
ip_allocation_policy {
cluster_secondary_range_name  = "k8s-pod-range"
services_secondary_range_name = "k8s-service-range"
}

private_cluster_config {
enable_private_nodes    = true
enable_private_endpoint = false
master_ipv4_cidr_block  = "172.16.0.0/28"
}

master_auth {
client_certificate_config {
issue_client_certificate = false
}
}

workload_identity_config {
workload_pool = "${var.project_id}.svc.id.goog"
}

addons_config {
gcp_filestore_csi_driver_config {
enabled = true
}

network_policy_config {
disabled = false
}
}

cluster_telemetry {
type = "ENABLED"
}

logging_config {
enable_components = [
"SYSTEM_COMPONENTS",
"WORKLOADS",
"API_SERVER"
]
}

monitoring_config {
enable_components = [
"SYSTEM_COMPONENTS",
"WORKLOADS"
]
}
}

3.2 节点池配置

# 主节点池
resource "google_container_node_pool" "energent_nodes" {
name       = "energent-node-pool"
location   = var.gcp_region
cluster    = google_container_cluster.energent_cluster.name
node_count = 3

autoscaling {
min_node_count = 2
max_node_count = 20
}

node_config {
preemptible  = false
machine_type = "n2-standard-4"
disk_size_gb = 100
disk_type    = "pd-ssd"

service_account = google_service_account.gke_service_account.email
oauth_scopes = [
"https://www.googleapis.com/auth/logging.write",
"https://www.googleapis.com/auth/monitoring",
"https://www.googleapis.com/auth/cloud-platform"
]

workload_metadata_config {
mode = "GKE_METADATA"
}

labels = {
env = "production"
app = "energent-ai"
}

taint {
key    = "workload"
value  = "energent-ai"
effect = "NO_SCHEDULE"
}
}

management {
auto_repair  = true
auto_upgrade = true
}
}

3.3 多租户资源分配

4. 数据层架构

4.1 存储架构

4.1.1 Cloud Storage 配置

# 云存储桶用于对象存储
resource "google_storage_bucket" "energent_storage" {
  name     = "energent-${var.environment}-storage-${random_id.bucket_suffix.hex}"
  location = var.gcp_region

  uniform_bucket_level_access = true

  versioning {
    enabled = true
  }

  encryption {
    default_kms_key_name = google_kms_crypto_key.storage_key.id
  }

  lifecycle_rule {
    condition {
      age = 90
    }
    action {
      type          = "SetStorageClass"
      storage_class = "NEARLINE"
    }
  }

  retention_policy {
    retention_period = 2592000  # 30 天
  }

  labels = {
    environment = var.environment
    purpose     = "energent-object-storage"
  }
}

resource "google_storage_bucket_iam_member" "storage_admin" {
  bucket = google_storage_bucket.energent_storage.name
  role   = "roles/storage.admin"
  member = "serviceAccount:${google_service_account.gke_service_account.email}"
}

4.1.2 Firestore 配置

# Firestore 数据库用于元数据和配置
resource "google_firestore_database" "energent_metadata" {
  project     = var.project_id
  name        = "energent-metadata-${var.environment}"
  location_id = var.gcp_region
  type        = "FIRESTORE_NATIVE"

  concurrency_mode = "OPTIMISTIC"
  app_engine_integration_mode = "DISABLED"

  point_in_time_recovery_enablement = "POINT_IN_TIME_RECOVERY_ENABLED"
  delete_protection_state = "DELETE_PROTECTION_ENABLED"
}

# Firestore 安全规则
resource "google_firestore_database" "security_rules" {
  depends_on = [google_firestore_database.energent_metadata]

  # 此处定义安全规则内容
  # 实现租户隔离和访问控制
}

4.1.3 Filestore 共享存储

# Filestore 用于共享文件系统
resource "google_filestore_instance" "energent_shared" {
name     = "energent-shared-${var.environment}"
location = var.gcp_zone
tier     = "BASIC_HDD"

file_shares {
capacity_gb = 1024
name        = "energent-share"
}

networks {
network = google_compute_network.vpc.name
modes   = ["MODE_IPV4"]
}

labels = {
environment = var.environment
purpose     = "shared-storage"
}
}

5. 无服务器组件

5.1 云函数

5.1.1 认证服务

# 用于认证的云函数
resource "google_cloudfunctions2_function" "auth_service" {
name     = "energent-auth-${var.environment}"
location = var.gcp_region

build_config {
runtime     = "python311"
entry_point = "auth_handler"
source {
storage_source {
bucket = google_storage_bucket.functions_source.name
object = google_storage_bucket_object.auth_source.name
}
}
}

service_config {
max_instance_count = 100
min_instance_count = 1
available_memory   = "512Mi"
timeout_seconds    = 60

environment_variables = {
FIRESTORE_PROJECT = var.project_id
SECRET_MANAGER_PROJECT = var.project_id
ENVIRONMENT = var.environment
}

vpc_connector = google_vpc_access_connector.connector.id
vpc_connector_egress_settings = "ALL_TRAFFIC"

service_account_email = google_service_account.functions_service_account.email
}

event_trigger {
trigger_region = var.gcp_region
event_type     = "google.cloud.pubsub.topic.v1.messagePublished"
pubsub_topic   = google_pubsub_topic.auth_events.id
}

labels = {
environment = var.environment
service     = "authentication"
}
}

5.1.2 计费服务

# 用于计费的云函数
resource "google_cloudfunctions2_function" "billing_service" {
name     = "energent-billing-${var.environment}"
location = var.gcp_region

build_config {
runtime     = "python311"
entry_point = "billing_handler"
source {
storage_source {
bucket = google_storage_bucket.functions_source.name
object = google_storage_bucket_object.billing_source.name
}
}
}

service_config {
max_instance_count = 50
min_instance_count = 0
available_memory   = "1Gi"
timeout_seconds    = 300

environment_variables = {
FIRESTORE_PROJECT = var.project_id
STORAGE_BUCKET = google_storage_bucket.energent_storage.name
}

service_account_email = google_service_account.functions_service_account.email
}
}

5.2 API 网关配置

# 用于无服务器函数的 API 网关
resource "google_api_gateway_api" "energent_api" {
provider = google-beta
api_id   = "energent-api-${var.environment}"
project  = var.project_id

labels = {
environment = var.environment
service     = "api-gateway"
}
}

resource "google_api_gateway_api_config" "energent_api_config" {
provider      = google-beta
api           = google_api_gateway_api.energent_api.api_id
api_config_id = "energent-config-${var.environment}"
project       = var.project_id

openapi_documents {
document {
path     = "spec.yaml"
contents = base64encode(templatefile("${path.module}/api-spec.yaml", {
project_id = var.project_id
region     = var.gcp_region
}))
}
}

lifecycle {
create_before_destroy = true
}
}

resource "google_api_gateway_gateway" "energent_gateway" {
provider   = google-beta
gateway_id = "energent-gateway-${var.environment}"
api_config = google_api_gateway_api_config.energent_api_config.id
location   = var.gcp_region
project    = var.project_id

labels = {
environment = var.environment
service     = "api-gateway"
}
}

6. 安全与合规

6.1 网络安全

6.1.1 VPC 配置

# VPC 网络和防火墙规则
resource "google_compute_network" "vpc" {
name                    = "energent-vpc-${var.environment}"
auto_create_subnetworks = false
mtu                     = 1460
}

resource "google_compute_subnetwork" "subnet" {
name          = "energent-subnet-${var.environment}"
ip_cidr_range = "10.0.0.0/16"
region        = var.gcp_region
network       = google_compute_network.vpc.id

secondary_ip_range {
range_name    = "k8s-pod-range"
ip_cidr_range = "10.1.0.0/16"
}

secondary_ip_range {
range_name    = "k8s-service-range"
ip_cidr_range = "10.2.0.0/16"
}

private_ip_google_access = true
}

resource "google_compute_firewall" "allow_internal" {
name    = "energent-allow-internal"
network = google_compute_network.vpc.name

allow {
protocol = "tcp"
ports    = ["0-65535"]
}

allow {
protocol = "udp"
ports    = ["0-65535"]
}

allow {
protocol = "icmp"
}

source_ranges = ["10.0.0.0/8"]
}

resource "google_compute_firewall" "allow_https" {
name    = "energent-allow-https"
network = google_compute_network.vpc.name

allow {
protocol = "tcp"
ports    = ["443"]
}

source_ranges = ["0.0.0.0/0"]
target_tags   = ["https-server"]
}

6.1.2 防火墙规则

6.2 加密标准

6.3 IAM 和服务账户

6.3.1 GKE 服务账户

# GKE 服务账户
resource "google_service_account" "gke_service_account" {
  account_id   = "energent-gke-${var.environment}"
  display_name = "Energent GKE 服务账户"
  project      = var.project_id
}

resource "google_project_iam_member" "gke_permissions" {
  for_each = toset([
    "roles/logging.logWriter",
    "roles/monitoring.metricWriter",
    "roles/monitoring.viewer",
    "roles/storage.objectViewer"
  ])

  project = var.project_id
  role    = each.value
  member  = "serviceAccount:${google_service_account.gke_service_account.email}"
}

# 工作负载身份绑定
resource "google_service_account_iam_member" "workload_identity" {
  service_account_id = google_service_account.gke_service_account.name
  role               = "roles/iam.workloadIdentityUser"
  member             = "serviceAccount:${var.project_id}.svc.id.goog[energent-ai/energent-platform]"
}

7. 网络架构

7.1 VPC 设计

┌─────────────────────────────────────────────────────────────────┐
│                         VPC (10.0.0.0/16)                       │
│                                                                 │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐  │
│  │  公共子网       │    │  公共子网       │    │ 公共子网    │  │
│  │   (10.0.1.0/24) │    │   (10.0.2.0/24) │    │(10.0.3.0/24)│  │
│  │                 │    │                 │    │             │  │
│  │   Cloud NAT     │    │   Cloud NAT     │    │ Cloud NAT   │  │
│  │   负载均衡器    │    │   负载均衡器    │    │负载均衡器   │  │
│  └─────────────────┘    └─────────────────┘    └─────────────┘  │
│           │                       │                     │       │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐  │
│  │ 私有子网        │    │ 私有子网        │    │私有子网     │  │
│  │  (10.1.0.0/16)  │    │  (10.1.0.0/16)  │    │(10.1.0.0/16)│  │
│  │                 │    │                 │    │             │  │
│  │  GKE 节点       │    │  GKE 节点       │    │ GKE 节点    │  │
│  │  Functions VPC  │    │  Functions VPC  │    │ Functions   │  │
│  └─────────────────┘    └─────────────────┘    └─────────────┘  │
│           │                       │                     │       │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐  │
│  │ 服务子网        │    │ 服务子网        │    │服务子网     │  │
│  │  (10.2.0.0/16)  │    │  (10.2.0.0/16)  │    │(10.2.0.0/16)│  │
│  │                 │    │                 │    │             │  │
│  │   Firestore     │    │   Firestore     │    │ Firestore   │  │
│  │   Cloud Storage │    │   Cloud Storage │    │Cloud Storage│  │
│  └─────────────────┘    └─────────────────┘    └─────────────┘  │
└─────────────────────────────────────────────────────────────────┘

7.2 私有服务连接

8. CI/CD 流水线

8.1 基础设施即代码 (Terraform)

8.1.1 Terraform 结构

terraform/
├── environments/
│   ├── dev/
│   ├── staging/
│   └── production/
├── modules/
│   ├── gke/
│   ├── networking/
│   ├── security/
│   └── storage/
├── shared/
│   └── backend.tf
└── global/
    └── iam.tf

8.1.2 Terraform 流水线 (Cloud Build)

# cloudbuild.yaml
steps:
  # Terraform Init
  - name: 'hashicorp/terraform:1.6.0'
    entrypoint: 'sh'
    args:
      - '-c'
      - |
        cd terraform/environments/${_ENVIRONMENT}
        terraform init -backend-config="bucket=${_TF_STATE_BUCKET}"

  # Terraform Plan
  - name: 'hashicorp/terraform:1.6.0'
    entrypoint: 'sh'
    args:
      - '-c'
      - |
        cd terraform/environments/${_ENVIRONMENT}
        terraform plan -var-file="${_ENVIRONMENT}.tfvars" -out=tfplan

  # Terraform Apply (仅在主分支上)
  - name: 'hashicorp/terraform:1.6.0'
    entrypoint: 'sh'
    args:
      - '-c'
      - |
        if [ "${BRANCH_NAME}" = "main" ]; then
          cd terraform/environments/${_ENVIRONMENT}
          terraform apply -auto-approve tfplan
        else
          echo "Skipping apply for non-main branch"
        fi

substitutions:
  _ENVIRONMENT: 'production'
  _TF_STATE_BUCKET: 'energent-terraform-state'

options:
  logging: CLOUD_LOGGING_ONLY
  machineType: 'E2_HIGHCPU_8'

timeout: 1200s

8.2 Kubernetes GitOps (Flux)

8.2.1 Flux 配置

# flux-system/gotk-sync.yaml
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: GitRepository
metadata:
  name: energent-k8s
  namespace: flux-system
spec:
  interval: 1m
  ref:
    branch: main
  url: https://github.com/energent-ai/k8s-manifests
---
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: energent-apps
  namespace: flux-system
spec:
  interval: 10m
  path: './apps'
  prune: true
  sourceRef:
    kind: GitRepository
    name: energent-k8s
  validation: client

8.3 无服务器部署 (Cloud Build)

8.3.1 函数部署配置

# cloudbuild-functions.yaml
steps:
  # 部署认证函数
  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk:latest'
    entrypoint: 'bash'
    args:
      - '-c'
      - |
        cd functions/auth
        gcloud functions deploy energent-auth-${_ENVIRONMENT} \
          --runtime python311 \
          --trigger-http \
          --entry-point auth_handler \
          --memory 512MB \
          --timeout 60s \
          --region ${_REGION} \
          --vpc-connector ${_VPC_CONNECTOR} \
          --set-env-vars ENVIRONMENT=${_ENVIRONMENT}

  # 部署计费函数
  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk:latest'
    entrypoint: 'bash'
    args:
      - '-c'
      - |
        cd functions/billing
        gcloud functions deploy energent-billing-${_ENVIRONMENT} \
          --runtime python311 \
          --trigger-topic billing-events \
          --entry-point billing_handler \
          --memory 1024MB \
          --timeout 300s \
          --region ${_REGION}

substitutions:
  _ENVIRONMENT: 'production'
  _REGION: 'us-central1'
  _VPC_CONNECTOR: 'energent-vpc-connector'

options:
  logging: CLOUD_LOGGING_ONLY

9. 监控与可观测性

9.1 Cloud Monitoring 配置

9.1.1 GKE 监控

# GKE 的 Cloud Monitoring
resource "google_monitoring_dashboard" "gke_dashboard" {
  dashboard_json = jsonencode({
    displayName = "Energent GKE Dashboard"
    mosaicLayout = {
      tiles = [
        {
          width = 6
          height = 4
          widget = {
            title = "GKE 集群 CPU 利用率"
            xyChart = {
              dataSets = [{
                timeSeriesQuery = {
                  timeSeriesFilter = {
                    filter = "resource.type=\"k8s_cluster\" AND metric.type=\"kubernetes.io/container/cpu/core_usage_time\""
                  }
                }
              }]
            }
          }
        }
      ]
    }
  })
}

# 基于日志的指标
resource "google_logging_metric" "error_rate" {
  name   = "energent_error_rate"
  filter = "resource.type=\"k8s_container\" AND resource.labels.namespace_name=\"energent-ai\" AND severity=\"ERROR\""

  metric_descriptor {
    metric_kind = "GAUGE"
    value_type  = "INT64"
    display_name = "Energent 错误率"
  }
}

9.2 应用程序指标

9.3 审计日志

# Cloud Audit Logs 配置
resource "google_project_iam_audit_config" "project_audit" {
  project = var.project_id
  service = "allServices"

  audit_log_config {
    log_type = "ADMIN_READ"
  }

  audit_log_config {
    log_type = "DATA_READ"
  }

  audit_log_config {
    log_type = "DATA_WRITE"
  }
}

# 安全事件的日志接收器
resource "google_logging_project_sink" "security_sink" {
  name        = "energent-security-sink"
  destination = "storage.googleapis.com/${google_storage_bucket.audit_logs.name}"

  filter = "protoPayload.serviceName=\"container.googleapis.com\" OR protoPayload.serviceName=\"iam.googleapis.com\""

  unique_writer_identity = true
}

10. 部署流程

10.1 部署时间表

10.2 部署命令

10.2.1 基础设施部署

# 使用 Terraform 部署基础设施
cd terraform/environments/production
terraform init -backend-config="bucket=energent-terraform-state"
terraform plan -var-file="production.tfvars"
terraform apply -auto-approve

# 验证 GKE 集群
gcloud container clusters get-credentials energent-production --region us-central1
kubectl get nodes

10.2.2 应用程序部署

# 安装 Flux GitOps
flux bootstrap github \
  --owner=energent-ai \
  --repository=k8s-manifests \
  --branch=main \
  --path=./clusters/production

# 部署无服务器组件
gcloud builds submit --config cloudbuild-functions.yaml \
  --substitutions _ENVIRONMENT=production,_REGION=us-central1

# 验证部署
kubectl get pods -n energent-ai
kubectl get ingress -n energent-ai

10.3 部署验证

# 健康检查端点
curl -k https://api.energent.example.com/health
curl -k https://api.energent.example.com/metrics

# Kubernetes 验证
kubectl top nodes
kubectl get hpa -n energent-ai
kubectl logs -n energent-ai -l app=energent-platform

11. 操作与维护

11.1 备份与灾难恢复

11.1.1 备份策略

11.1.2 灾难恢复程序

# 使用 Velero 备份 GKE 集群
velero backup create energent-cluster-backup \
  --include-namespaces energent-ai \
  --storage-location gcp

# Firestore 时间点恢复
gcloud firestore databases restore \
  --source-database=energent-metadata-production \
  --destination-database=energent-metadata-restored \
  --backup-time=2025-05-28T10:00:00Z

11.2 扩展与性能

11.2.1 自动扩展配置

# 水平 Pod 自动扩展器
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: energent-platform-hpa
  namespace: energent-ai
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: energent-platform
  minReplicas: 3
  maxReplicas: 50
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

11.3 更新与维护

11.3.1 滚动更新

# GKE 集群更新
gcloud container clusters upgrade energent-production \
  --master \
  --cluster-version 1.30 \
  --region us-central1

# 使用 Flux 进行应用滚动更新
git commit -am "Update energent-platform to v2.1.0"
git push origin main
# Flux 自动检测并应用更改

12. 支持与升级

12.1 支持等级

12.2 24/7 支持覆盖

企业支持：

• 📧 邮件: support@energent.ai

紧急升级：

• 📧 紧急邮件: emergency@energent.ai

12.3 服务级别协议

附录

附录 A: GCP 服务成本

附录 B: 安全合规检查表

• 部署了具有私有子网的 VPC
• 最小权限访问的防火墙规则
• 所有静态数据使用 Cloud KMS 加密
• 所有传输数据使用 TLS 1.3
• 最小权限的 IAM 配置
• 启用了 Cloud 审计日志
• 启用了安全指挥中心
• 启用了组织策略约束
• 所有凭证使用 Secret Manager
• 定期进行安全扫描和评估

附录 C: 故障排除指南

常见问题：

1. GKE 节点未加入集群

   • 验证服务账户权限
   • 检查子网路由和 Cloud NAT

2. 应用 Pods 崩溃循环

   • 检查资源限制和请求
   • 验证持久卷声明

3. 网络连接问题

   • 验证 VPC 连接器配置
   • 检查防火墙规则

• 文档分类: 公共
• 版本: 3.0
• 最后更新: 2025-05-28
• 下次审查: 2025-08-28
• 联系人: support@energent.ai