Phiên bản
Ngôn ngữ
Người đóng góp Sửa (16/07/2026)
Avatar

Hướng Dẫn Cấu Hình Biến Môi Trường (.env)

Tệp .env (được tạo từ tệp mẫu .env.example) là Single Source of Truth (Nguồn cấu hình duy nhất) chứa toàn bộ API Keys nhạy cảm và thông số phân phối (Deploy) cho hệ thống SEO Kit.

Để bảo đảm an toàn thông tin, tệp .env này được cấu hình mặc định trong .gitignore để không bao giờ bị đẩy lên các kho lưu trữ công cộng (GitHub, GitLab...).

🛠️ Quy Trình Thiết Lập

  1. Tại thư mục gốc của dự án của bạn, tìm tệp .env.example.
  2. Sao chép và đổi tên tệp này thành .env: 
    cp .env.example .env
  3. Mở tệp .env bằng trình chỉnh sửa mã nguồn và điền các giá trị cấu hình tương ứng dưới đây.
  4. Khởi động lại Antigravity để hệ thống nhận diện các biến môi trường mới nạp.

📋 Chi Tiết Các Biến Cấu Hình

1. API Keys & Credentials (Thông Tin Xác Thực)

GSC_SERVICE_ACCOUNT_KEY

  • Mô tả: Khóa của tài khoản dịch vụ (Google Service Account Key) dùng để kết nối với Google Search Console API và Google Analytics 4.
  • Giá trị: Có thể điền ở 2 dạng:
    • Chuỗi JSON thô của tệp khóa (ví dụ: {"type": "service_account", ...}).
    • Đường dẫn tuyệt đối đến tệp tin JSON được lưu trữ cục bộ trên máy tính của bạn (ví dụ: C:\Users\Username\.config\seo-kit\service-account.json).
  • Cách lấy: Tạo Service Account trong Google Cloud Console, cấp quyền truy cập vào dự án Search Console của bạn, và tải khóa dưới dạng tệp JSON.

BING_API_KEY

  • Mô tả: API Key kết nối với công cụ quản trị trang web Bing (Bing Webmaster Tools).
  • Giá trị: Chuỗi API Key cá nhân.
  • Cách lấy: Đăng nhập vào Bing Webmaster Tools, truy cập Settings -> API Access -> API Key để sao chép.

GA_PROPERTY_ID

  • Mô tả: Mã định danh thuộc tính Google Analytics 4 để chạy các công cụ phân tích GA4 (Sessions, Engagement, Conversions...).
  • Giá trị: ID dạng số (ví dụ: 123456789).
  • Cách lấy: Vào trang Quản trị GA4 -> Cài đặt Thuộc tính (Property Settings) -> lấy Property ID ở góc trên bên phải.

SOLANN_API_KEY

  • Mô tả: API Key kết nối dịch vụ dữ liệu từ khóa của Solann (dùng cho harvesting, clustering, và topical map). Đây là data provider mặc định (#1) của hệ thống.
  • Giá trị: Chuỗi API Key cá nhân.
  • Cách lấy: Đăng ký và nhận key tại app.solann.io.

SERPER_API_KEY

  • Mô tả: API Key kết nối dịch vụ Serper.dev dùng để cào kết quả tìm kiếm Google SERPs theo thời gian thực (hỗ trợ phân tích đối thủ cạnh tranh).
  • Giá trị: Chuỗi API Key cá nhân.
  • Cách lấy: Đăng ký nhận API Key miễn phí tại serper.dev.

2. WordPress WSP MCP (Tích hợp WordPress)

Để xuất bản bài viết tự động trực tiếp lên website WordPress của bạn thông qua giao thức MCP, thiết lập các biến sau:

  • SEO_WP_MCP_ENABLED: Đặt thành true để kích hoạt WordPress MCP (Mặc định là false).
  • WSP_MCP_SERVER_URL: Đường dẫn Endpoint API của WSP MCP Server trên trang WordPress của bạn (ví dụ: https://your-wordpress-site.com/index.php?rest_route=/wsp-mcp/v1/mcp).
  • WSP_MCP_TOKEN: Bearer token bảo mật được tạo từ plugin WordPress để xác thực quyền đăng tải bài viết.

3. Deploy Configurations (Cấu Hình Xuất Bản)

Các thông số chỉ định cách thức và nơi lưu trữ/xuất bản các tệp nội dung, sửa lỗi sau khi hoàn thành Phase 4 (Execute):

SEO_DEPLOY_METHOD

  • Mô tả: Phương thức xuất bản bài viết sau khi được duyệt.
  • Các giá trị hỗ trợ:
    • local (Mặc định): Chỉ xuất ra thư mục cục bộ của bạn.
    • wordpress: Tự động đẩy lên site WordPress qua MCP.
    • google-docs: Đẩy lên Google Docs của Google Workspace.
    • git: Tạo commit và đẩy lên nhánh Git cấu hình.

SEO_WP_MCP_SERVER

  • Mô tả: Tên định danh của WordPress MCP Server được định nghĩa trong hệ thống. Mặc định là wsp-wordpress.

SEO_GWORKSPACE_MCP_SERVER

  • Mô tả: Tên định danh của Google Workspace MCP Server. Mặc định là workspacemcp.

SEO_LOCAL_DEPLOY_DIR

  • Mô tả: Thư mục cục bộ đích để lưu trữ các bài viết/file sửa lỗi nếu chọn phương thức deploy là local. Mặc định là output/.

🔒 Cơ Chế Nạp Động Dynamic Placeholder

SEO Kit được thiết kế theo nguyên tắc bảo mật tối đa. Tệp cấu hình các MCP Server tại .agents/mcp_config.json sử dụng các placeholder để ánh xạ động: 

"search-console": {
  "command": "npx",
  "args": ["-y", "@nicholasharrigan/search-console-mcp@latest"],
  "env": {
    "GSC_SERVICE_ACCOUNT_KEY": "${GSC_SERVICE_ACCOUNT_KEY}",
    "BING_API_KEY": "${BING_API_KEY}",
    "GA_PROPERTY_ID": "${GA_PROPERTY_ID}"
  }
}

Khi Antigravity khởi chạy MCP Server, nó sẽ tự động đọc tệp .env của bạn, lấy giá trị thực tế của BING_API_KEY, GSC_SERVICE_ACCOUNT_KEY,... và truyền an toàn vào môi trường chạy của Server. Điều này giúp ngăn chặn hoàn toàn việc lưu trữ cứng API key trong các file JSON cấu hình hệ thống.

Trong tài liệu này