این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

مشکلات برنامه را با Gemini Cloud Assist پیدا کنید و برطرف کنید

۱. مقدمه

Gemini Cloud Assist یک عامل کاملاً برجسته است که از بارهای کاری Google Cloud شما پشتیبانی می‌کند. این عامل، شریک شما برای طراحی برنامه‌های جدید یا به‌روزرسانی برنامه‌های موجود، استقرار و اجرای بارهای کاری در Google Cloud، عیب‌یابی بارهای کاری و بهینه‌سازی آنها از نظر هزینه و عملکرد است.

Gemini Cloud Assist توانایی شما را در پاسخگویی به خطاهای غیرمنتظره و خرابی‌ها بهبود می‌بخشد.

آنچه یاد خواهید گرفت

استقرار: نحوه استقرار یک backend و پایگاه داده اولیه در Google Cloud.
اشکال‌زدایی: چگونه Gemini Cloud Assist تحقیقات و تحلیل ریشه‌ای مشکلات ابری و کد را خودکار می‌کند.
اصلاح: چگونه Gemini Cloud Assist به شناسایی اصلاحات بر اساس علت اصلی کمک می‌کند.

۲. راه‌اندازی پروژه

حساب گوگل

اگر از قبل حساب گوگل شخصی ندارید، باید یک حساب گوگل ایجاد کنید .

به جای حساب کاری یا تحصیلی از حساب شخصی استفاده کنید .

با استفاده از یک حساب کاربری شخصی گوگل، وارد کنسول ابری گوگل شوید.

فعال کردن صورتحساب

یک حساب پرداخت شخصی تنظیم کنید

اگر صورتحساب را با استفاده از اعتبارهای Google Cloud تنظیم کرده‌اید، می‌توانید از این مرحله صرف نظر کنید.

برای تنظیم یک حساب پرداخت شخصی، به اینجا بروید تا پرداخت را در کنسول ابری فعال کنید .

برخی نکات:

تکمیل این آزمایشگاه باید کمتر از ۱ دلار آمریکا از طریق منابع ابری هزینه داشته باشد.
شما می‌توانید مراحل انتهای این آزمایش را برای حذف منابع دنبال کنید تا از هزینه‌های بیشتر جلوگیری شود.
کاربران جدید واجد شرایط استفاده از دوره آزمایشی رایگان ۳۰۰ دلاری هستند.

ایجاد پروژه (اختیاری)

اگر پروژه فعلی ندارید که بخواهید برای این آزمایشگاه استفاده کنید، اینجا یک پروژه جدید ایجاد کنید .

۳. ویرایشگر Cloud Shell را باز کنید

برای دسترسی مستقیم به ویرایشگر Cloud Shell ، روی این لینک کلیک کنید.
اگر امروز در هر مرحله‌ای از شما خواسته شد که مجوز دهید، برای ادامه روی تأیید کلیک کنید.
اگر ترمینال در پایین صفحه نمایش داده نشد، آن را باز کنید:
- روی مشاهده کلیک کنید
- روی ترمینال کلیک کنید
در ترمینال، پروژه خود را با این دستور تنظیم کنید:
```
gcloud config set project [PROJECT_ID]
```
- مثال:
```
gcloud config set project lab-project-id-example
```
- اگر نمی‌توانید شناسه پروژه خود را به خاطر بیاورید، می‌توانید تمام شناسه‌های پروژه خود را با استفاده از دستور زیر فهرست کنید:
```
gcloud projects list
```
شما باید این پیام را ببینید:
```
Updated property [core/project].
```
اگر یک WARNING مشاهده کردید و از شما پرسیده شد Do you want to continue (Y/n)? احتمالاً شناسه پروژه را اشتباه وارد کرده‌اید. n را فشار دهید، Enter را بزنید و دوباره سعی کنید دستور gcloud config set project اجرا کنید.

۴. فعال کردن APIها

API های زیر را برای استقرار اجزای برنامه و استفاده از Google Cloud Assist فعال کنید:

در ترمینال ، APIها را فعال کنید:

```bash
gcloud services enable \
  container.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  alloydb.googleapis.com \
  run.googleapis.com
```
<br>
When the command finishes, you should see an output like the following: 
<br>

```console
Operation "operations/acf.p2-176675280136-b03ab5e4-3483-4ebf-9655-43dc3b345c63" finished successfully.
```

۵. پروژه را آماده کنید

شما برنامه اولیه و استقرار را برای آزمایش Cloud Assist ایجاد خواهید کرد.

دایرکتوری ایجاد کنید

ویرایشگر Cloud Shell یا محیط توسعه‌دهنده‌ی مورد نظر خود را باز کنید.

یک پوشه جدید ایجاد کنید:

mkdir -p ~/gemini-cloud-assist-debug
mkdir -p ~/gemini-cloud-assist-debug/auth_issue_demo
mkdir -p ~/gemini-cloud-assist-debug/terraform
cd ~/gemini-cloud-assist-debug

در ترمینال ، دستور زیر را برای باز کردن فضای کاری ویرایشگر Cloud Shell اجرا کنید:

cloudshell open-workspace ~/gemini-cloud-assist-debug

فایل‌ها را ایجاد کنید

اکنون فایل‌های آغازین لازم برای برنامه را ایجاد خواهید کرد.

با اجرای دستور زیر در ترمینال، فایل Docker را ایجاد کنید. این فایل، ایجاد کانتینر برنامه را مدیریت می‌کند.

cat <<EOF > ~/gemini-cloud-assist-debug/auth_issue_demo/Dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY main.py .

CMD ["gunicorn", "--bind", "0.0.0.0:8080", "main:app"]
EOF

با اجرای دستور زیر در ترمینال، فایل main.py را ایجاد کنید. این فایل حاوی برنامه نوشته شده با پایتون است.

cat <<EOF > ~/gemini-cloud-assist-debug/auth_issue_demo/main.py
import os
import logging
from flask import Flask
from google.cloud.alloydb.connector import Connector
import sqlalchemy

app = Flask(__name__)

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Configuration from Environment Variables
# The fully qualified instance URI: projects/<PROJECT>/locations/<REGION>/clusters/<CLUSTER>/instances/<INSTANCE>
ALLOYDB_URI = os.environ.get("ALLOYDB_URI") 
DB_USER = os.environ.get("DB_USER", "auth-debug")
DB_PASS = os.environ.get("DB_PASS", "debug-auth")
DB_NAME = os.environ.get("DB_NAME", "postgres")
USE_PUBLIC_IP = os.environ.get("USE_PUBLIC_IP", "false").lower() == "true"

# Initialize Connector lazily
_connector = None

def get_connector():
    global _connector
    if _connector is None:
        _connector = Connector()
    return _connector

def getconn():
    connector = get_connector()
    ip_type = "PUBLIC" if USE_PUBLIC_IP else "PRIVATE"
    
    conn = connector.connect(
        ALLOYDB_URI,
        "pg8000",
        user=DB_USER,
        password=DB_PASS,
        db=DB_NAME,
        ip_type=ip_type
    )
    return conn

@app.route("/")
def index():
    return "AlloyDB Auth Demo. /connect to test.", 200

@app.route("/connect")
def connect_db():
    if not ALLOYDB_URI:
        return "FAILURE: ALLOYDB_URI env var is not set.", 500

    try:
        logger.info(f"Attempting connection to {ALLOYDB_URI} with user {DB_USER}...")
        
        # Create connection pool
        pool = sqlalchemy.create_engine(
            "postgresql+pg8000://",
            creator=getconn,
        )
        
        with pool.connect() as db_conn:
            # Simple query to validate connection
            result = db_conn.execute(sqlalchemy.text("SELECT NOW()")).fetchone()
            timestamp = result[0]
            
        msg = f"SUCCESS: Connected to AlloyDB! DB Time: {timestamp}"
        logger.info(msg)
        return msg, 200

    except Exception as e:
        logger.exception("Connection failed")
        # Return the error to the caller to visualize the auth failure
        return f"FAILURE: Connection Error.\nDetails: {str(e)}", 500

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
EOF

با اجرای دستور زیر در ترمینال ، فایل requirements.txt را ایجاد کنید. این فایل، نیازمندی‌های بسته پایتون را مدیریت می‌کند.

cat <<EOF > ~/gemini-cloud-assist-debug/auth_issue_demo/requirements.txt
flask==3.1.3
gunicorn==25.3.0
google-cloud-alloydb-connector[pg8000]==1.12.1
sqlalchemy==2.0.49
EOF

با اجرای دستور زیر در ترمینال ، فایل main.tf را ایجاد کنید. این فایل، منابع Google Cloud که قرار است ایجاد شوند را مدیریت می‌کند.

cat <<EOF > ~/gemini-cloud-assist-debug/terraform/main.tf
provider "google" {
  project = var.project_id
  region  = var.region
}

# Enable APIs
locals {
  apis = [
    "alloydb.googleapis.com",
    "run.googleapis.com",
    "artifactregistry.googleapis.com",
    "compute.googleapis.com",
    "geminicloudassist.googleapis.com",
    "monitoring.googleapis.com",
    "cloudasset.googleapis.com",
    "cloudbuild.googleapis.com",
    "recommender.googleapis.com",
    "appoptimize.googleapis.com"
  ]
}

resource "random_password" "db_pass" {
  count            = var.db_password == null ? 1 : 0
  length           = 16
  special          = true
  override_special = "!#$%&*()-_=+[]{}<>:?"
}

locals {
  db_password = var.db_password != null ? var.db_password : random_password.db_pass[0].result
}

resource "google_project_service" "apis" {
  for_each           = toset(local.apis)
  service            = each.value
  disable_on_destroy = false
}

# Service Account
resource "google_service_account" "auth_demo_sa" {
  account_id   = var.service_account_name
  display_name = "Auth Demo SA"
}

# AlloyDB Cluster
resource "google_alloydb_cluster" "rma_cluster" {
  cluster_id = var.cluster_id
  location   = var.region

  # Initial password, managed via variable or generated randomly
  initial_user {
    password = local.db_password
  }

  # Use default network as in the manual setup
  network_config {
    network = "projects/${var.project_id}/global/networks/default"
  }

  depends_on = [google_project_service.apis["alloydb.googleapis.com"]]
}

# AlloyDB Instance
resource "google_alloydb_instance" "rma_instance_1" {
  cluster       = google_alloydb_cluster.rma_cluster.name
  instance_id   = var.instance_id
  instance_type = "PRIMARY"

  machine_config {
    cpu_count = 2
  }

  network_config {
    enable_public_ip = true
  }

  depends_on = [google_alloydb_cluster.rma_cluster]
}

# Cloud Run Service
resource "google_cloud_run_service" "auth_issue_demo" {
  name     = var.cloud_run_service_name
  location = var.region

  template {
    spec {
      containers {
        image = var.cloud_run_image
        env {
          name  = "ALLOYDB_URI"
          value = "projects/${var.project_id}/locations/${var.region}/clusters/${var.cluster_id}/instances/${var.instance_id}"
        }
        env {
          name  = "DB_USER"
          value = "postgres"
        }
        env {
          name  = "DB_PASS"
          value = local.db_password
        }
        env {
          name  = "USE_PUBLIC_IP"
          value = "true"
        }
      }
      service_account_name = google_service_account.auth_demo_sa.email
    }
  }

  traffic {
    percent         = 100
    latest_revision = true
  }

  depends_on = [google_project_service.apis["run.googleapis.com"], google_alloydb_instance.rma_instance_1]
}

# Allow unauthenticated access to Cloud Run service (matching --allow-unauthenticated)
resource "google_cloud_run_service_iam_member" "public_access" {
  location = google_cloud_run_service.auth_issue_demo.location
  project  = google_cloud_run_service.auth_issue_demo.project
  service  = google_cloud_run_service.auth_issue_demo.name
  role     = "roles/run.invoker"
  member   = "allUsers"
}
EOF

با اجرای دستور زیر در ترمینال، فایل variables.tf را ایجاد کنید. این فایل، متغیرهای Terraform را برای منابع Google Cloud مدیریت می‌کند.

cat <<EOF > ~/gemini-cloud-assist-debug/terraform/variables.tf
variable "project_id" {
  description = "The ID of the Google Cloud project."
  type        = string
}

variable "region" {
  description = "The region to deploy resources in."
  type        = string
  default     = "us-central1"
}

variable "cluster_id" {
  description = "The ID of the AlloyDB cluster."
  type        = string
  default     = "rma-cluster"
}

variable "instance_id" {
  description = "The ID of the AlloyDB instance."
  type        = string
  default     = "rma-instance-1"
}

variable "service_account_name" {
  description = "The name of the service account."
  type        = string
  default     = "auth-demo-sa"
}

variable "cloud_run_service_name" {
  description = "The name of the Cloud Run service."
  type        = string
  default     = "auth-issue-demo"
}

variable "cloud_run_image" {
  description = "The container image for the Cloud Run service."
  type        = string
}

variable "db_password" {
  description = "The database password. If not provided, a random one will be generated."
  type        = string
  sensitive   = true
  default     = null
}
EOF

با اجرای دستور زیر در ترمینال، فایل setup_via_tf.sh را ایجاد کنید. این فایل، الزامات بسته پایتون را مدیریت می‌کند.

cat <<EOF > ~/gemini-cloud-assist-debug/setup_via_tf.sh
#!/bin/bash
set -e

# Get script directory and change to project root
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
cd "$SCRIPT_DIR"

# Load configuration from .env
if [ -f .env ]; then
    set -a
    source .env
    set +a
else
    echo "ERROR: .env file not found. Please create one with PROJECT_ID."
    exit 1
fi

if [ -z "$PROJECT_ID" ]; then
    echo "ERROR: PROJECT_ID is not set in .env file."
    exit 1
fi

REGION="us-central1"
CLUSTER_ID="rma-cluster"
INSTANCE_ID="rma-instance-1"
SA_NAME="auth-demo-sa"
SERVICE_NAME="auth-issue-demo"

echo "--- Terraform Setup for Auth Demo ---"
echo "Using Project: $PROJECT_ID"

# Get current Cloud Run image
echo "Fetching current Cloud Run image..."
IMAGE=$(gcloud run services describe $SERVICE_NAME --region=$REGION --project=$PROJECT_ID --format="value(spec.template.spec.containers[0].image)" 2>/dev/null || true)

if [ -z "$IMAGE" ]; then
    echo "WARNING: Could not find existing Cloud Run service image."
    echo "Using a placeholder image (gcr.io/cloudrun/hello) for initial Terraform apply."
    IMAGE="gcr.io/cloudrun/hello"
fi

echo "Found Image: $IMAGE"

cd terraform

# Initialize Terraform
echo "Initializing Terraform..."
terraform init

echo "Formatting Terraform files..."
terraform fmt

echo "Validating Terraform configuration..."
terraform validate

echo "------------------------------------------------"
echo "Applying changes..."
echo "------------------------------------------------"

terraform apply -var="project_id=$PROJECT_ID" -var="cloud_run_image=$IMAGE" -auto-approve

echo "------------------------------------------------"
echo "Building and deploying updated Cloud Run service..."
echo "------------------------------------------------"

gcloud run deploy $SERVICE_NAME \
  --source ../auth_issue_demo \
  --region $REGION \
  --project $PROJECT_ID \
  --service-account $SA_NAME@$PROJECT_ID.iam.gserviceaccount.com \
  --quiet
EOF

دستور زیر را اجرا کنید تا اسکریپت shell قابل اجرا شود:

chmod +x ~/gemini-cloud-assist-debug/setup_via_tf.sh

یک فایل .env حاوی شناسه پروژه Google Cloud خود برای استقرار ایجاد کنید. فیلد YOUR_PROJECT_ID را به‌روزرسانی کنید:

cat <<EOF > ~/gemini-cloud-assist-debug/.env
PROJECT_ID=YOUR_PROJECT_ID
USE_PUBLIC_IP=true
EOF

۶. برنامه را مستقر کنید

کد برنامه و منابع Google Cloud آماده‌ی استقرار هستند. این کار می‌تواند تا ۱۵ دقیقه طول بکشد.

دستور زیر را از ترمینال اجرا کنید:

cd ~/gemini-cloud-assist-debug
./setup_via_tf.sh

در حین استقرار اجزا، برای کسب اطلاعات بیشتر، فایل‌های موجود در Cloud Shell Editor را مرور کنید.

۷. ایجاد و اشکال‌زدایی یک خطا

حالا، ما یک خطا از برنامه ایجاد خواهیم کرد. Cloud Run را در پنل سمت چپ باز کنید. سپس، روی سرویس auth-issue-demo کلیک کنید.

در بالای صفحه جزئیات سرویس، یک URL وجود دارد. URL را کپی کنید و یک تب جدید مرورگر باز کنید. URL را جایگذاری کنید و /connect به آن اضافه کنید. URL شما چیزی شبیه به این خواهد بود:

https://auth-issue-demo- .us-central1.run.app/connect

به آدرس اینترنتی (URL) بروید. ممکن است چند ثانیه طول بکشد تا نمونه Cloud Run شروع شود. در این صورت با خطا مواجه خواهید شد.
به صفحه جزئیات سرویس Cloud Run برگردید. روی Observability و سپس روی Logs کلیک کنید. گزارش‌های مربوط به کانتینر شامل خطا را مشاهده خواهید کرد. اگر گزارش خطا هنوز در دسترس نیست، چند ثانیه صبر کنید و صفحه را با استفاده از نماد سمت راست بالا رفرش کنید.
برای مطالعه بیشتر، روی گزارش خطا کلیک کنید. روی آیکون Investigate در خط اصلی گزارش کلیک کنید. سپس، روی Investigate Log کلیک کنید.

صفحه چت Cloud Assist باز خواهد شد. تکمیل بررسی ۲ تا ۳ دقیقه طول می‌کشد.

پس از تکمیل تحقیقات، می‌توانید نتایج و توصیه‌ها را مطالعه کنید. توصیه‌ای برای افزودن کمک‌هزینه مناسب به حساب سرویس Cloud Run جهت دسترسی به نمونه AlloyDB وجود دارد.

۸. خطا را اصلاح کنید

خطای مجوز حساب سرویس را برطرف کنید.

به Cloud IAM بروید.
روی دکمه‌ی اعطای دسترسی (Grant Access) کلیک کنید. در پنل اصلی (Principal)، با تایپ auth-demo شروع کنید و منتظر بمانید تا حساب کاربری سرویس نمایش داده شود.
در مرحله بعد، نقش AlloyDB Client را به حساب سرویس اضافه کنید، سپس روی ذخیره کلیک کنید.

انتشار این مقدار تا یک دقیقه طول می‌کشد.

پس از صبر کردن، برگردید و برنامه را رفرش کنید. اکنون یک پیام موفقیت از پایگاه داده AlloyDB مشاهده خواهید کرد.

۹. تبریک

تبریک! شما با موفقیت این مقدمه در مورد تحقیقات ابری و فرآیند اشکال‌زدایی مجوزهای یک برنامه در Google Cloud را به پایان رساندید.

بعدش چی؟

راهنماها و مثال‌های دیگری را که نحوه استفاده از Gemini Cloud Assist را برای سناریوهای مختلف نشان می‌دهند، بررسی کنید:
- عیب‌یابی مشکلات Gemini در Google Cloud
- طراحی و استقرار یک برنامه جدید با Gemini در Google Cloud
برای کسب اطلاعات بیشتر در مورد ویژگی‌ها و قابلیت‌های Gemini Cloud Assist، مستندات آن را مرور کنید.