neo4j-aura-provisioning-skill

适用场景

• 创建 Aura 实例（CLI、REST API、Python、Terraform）
• 暂停、恢复、调整大小或删除实例
• 从创建响应中下载初始凭据
• 轮询实例状态：creating → running
• 设置 CI/CD 配置或拆除流水线
• 选择实例层级（Free、Professional、Business Critical 或 VDC）

不适用场景

• 对运行中的数据库执行 Cypher 查询 → neo4j-cypher-skill
• 在 Aura 上运行 GDS 算法 → neo4j-gds-skill（Pro 搭配插件）或 neo4j-aura-graph-analytics-skill（无服务器）
• neo4j-admin / cypher-shell → neo4j-cli-tools-skill
• 应用程序驱动设置 → 使用相应语言的驱动技能（python、javascript、java、go、dotnet）

---

实例层级决策表

层级	API 类型代码	内存	GDS	副本	适用场景
AuraDB Free	free-db	1 GB	❌	❌	开发/演示；≤200k 个节点/400k 条关系
AuraDB Professional	professional-db	2–64 GB	可使用插件	❌	生产工作负载
AuraDB Business Critical	business-critical	4–384 GB	可使用插件	✅	高可用、多可用区、SLA
AuraDB VDC	enterprise-db	自定义	✅	✅	专用基础设施、合规要求
AuraDS Professional	professional-ds	2–64 GB	✅ 内置	❌	数据科学/GDS
AuraDS Enterprise	enterprise-ds	自定义	✅	✅	企业级 GDS

AuraDB Free 限制：200k 个节点、400k 条关系；闲置 72 h 后自动暂停；暂停超过 30 天后删除；无法调整大小。

---

身份验证设置

CLI（aura-cli v1.7+）

安装（使用二进制文件，而非 pip）：

# macOS
curl -L https://github.com/neo4j/aura-cli/releases/latest/download/aura-cli-darwin-amd64.tar.gz | tar xz
sudo mv aura-cli /usr/local/bin/
aura-cli -v          # verify

添加凭据（来自 console.neo4j.io → Account Settings → API Credentials）：

aura-cli credential add \
  --name "my-creds" \
  --client-id "$AURA_CLIENT_ID" \
  --client-secret "$AURA_CLIENT_SECRET"
aura-cli credential use --name "my-creds"

验证：

aura-cli instance list --output table

REST API — 获取 Bearer 令牌

令牌端点：POST https://api.neo4j.io/oauth/token 令牌有效期：3600 s（1 h）。收到 403 时 → 刷新令牌。

TOKEN=$(curl -s --request POST 'https://api.neo4j.io/oauth/token' \
  --user "${AURA_CLIENT_ID}:${AURA_CLIENT_SECRET}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  | jq -r '.access_token')
echo "Token: ${TOKEN:0:20}..."

在后续所有调用中使用：--header "Authorization: Bearer $TOKEN"

---

第 1 步 — 列出租户（项目）

CLI：

aura-cli tenants list --output table
# Copy TENANT_ID for create operations

REST：

curl -s https://api.neo4j.io/v1/tenants \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {id, name}'

---

第 2 步 — 创建实例

重要：立即捕获输出。 初始密码只会显示一次，之后无法再次获取。 如果丢失：删除并重新创建。先保存 aura-creds.json，再进行其他操作。

CLI

aura-cli instance create \
  --name "my-instance" \
  --cloud-provider gcp \
  --region europe-west1 \
  --type professional-db \
  --tenant-id "$TENANT_ID" \
  --output json | tee aura-creds.json

# Extract for .env
INSTANCE_ID=$(jq -r '.id' aura-creds.json)
PASSWORD=$(jq -r '.password' aura-creds.json)

REST API（完整创建）

RESPONSE=$(curl -s -X POST https://api.neo4j.io/v1/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":           "my-instance",
    "cloud_provider": "gcp",
    "region":         "europe-west1",
    "type":           "professional-db",
    "tenant_id":      "'"$TENANT_ID"'",
    "memory":         "4GB",
    "version":        "5"
  }')
echo "$RESPONSE" | tee aura-creds.json
INSTANCE_ID=$(echo "$RESPONSE" | jq -r '.data.id')
PASSWORD=$(echo "$RESPONSE"   | jq -r '.data.password')

实例创建请求正文字段：

字段	必填	值
name	✅	任意字符串
cloud_provider	✅	gcp aws azure
region	✅	参见区域表
type	✅	参见层级表
tenant_id	✅	来自租户列表
memory	✗	1GB 2GB 4GB 8GB … 384GB
version	✗	5（默认值）

---

第 3 步 — 轮询直到状态为 RUNNING（重要 — 所有操作均为异步）

所有生命周期操作（创建、暂停、恢复、调整大小）均为异步。在状态变为 running 之前，不要尝试连接或进行下一步操作（暂停操作则需等待状态变为 paused）。

poll_status() {
  local INSTANCE_ID=$1 TARGET=$2 MAX_WAIT=${3:-600}
  local ELAPSED=0 STATUS
  echo "Polling for status=$TARGET (max ${MAX_WAIT}s)..."
  while [ $ELAPSED -lt $MAX_WAIT ]; do
    STATUS=$(aura-cli instance get --instance-id "$INSTANCE_ID" --output json \
             | jq -r '.status' 2>/dev/null)
    echo "  [${ELAPSED}s] status=$STATUS"
    [ "$STATUS" = "$TARGET" ] && echo "Ready." && return 0
    [ "$STATUS" = "destroying" ] && echo "ERROR: instance is being destroyed" && return 1
    sleep 10; ELAPSED=$((ELAPSED + 10))
  done
  echo "TIMEOUT after ${MAX_WAIT}s — last status: $STATUS" && return 1
}

poll_status "$INSTANCE_ID" "running" 600

REST 等效操作：

while true; do
  STATUS=$(curl -s "https://api.neo4j.io/v1/instances/$INSTANCE_ID" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.data.status')
  [ "$STATUS" = "running" ] && break
  sleep 10
done

状态生命周期：

creating → running → pausing → paused → resuming → running
                  ↘ destroying → (gone)

---

第 4 步 — 写入 .env 并验证

CONNECTION_URI="neo4j+s://${INSTANCE_ID}.databases.neo4j.io"

cat > .env <<EOF
NEO4J_URI=${CONNECTION_URI}
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=${PASSWORD}
NEO4J_DATABASE=neo4j
AURA_INSTANCE_ID=${INSTANCE_ID}
EOF

# Ensure .env never committed
grep -q '^\.env$' .gitignore 2>/dev/null || echo '.env' >> .gitignore

# Verify connectivity
cypher-shell -a "$CONNECTION_URI" -u neo4j -p "$PASSWORD" "RETURN 'connected' AS status"

---

第 5 步 — 生命周期操作

所有操作都要求实例处于正确状态。状态不正确的操作会返回 4xx 错误。

暂停

所需状态：running

aura-cli instance pause --instance-id "$INSTANCE_ID"
poll_status "$INSTANCE_ID" "paused" 600

恢复

所需状态：paused

aura-cli instance resume --instance-id "$INSTANCE_ID"
poll_status "$INSTANCE_ID" "running" 900   # resume can take longer

调整大小（仅限 Professional 及以上层级 — Free 不支持）

所需状态：running；调整大小期间实例仍可用。

# REST only — CLI resize not available in v1.7
curl -s -X PATCH "https://api.neo4j.io/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memory": "8GB"}'
poll_status "$INSTANCE_ID" "running" 600
# Cannot reduce below current usage level

删除

不可撤销。如果需要数据，请先导出快照。

aura-cli instance delete --instance-id "$INSTANCE_ID"
# No poll needed — immediate

REST：

curl -s -X DELETE "https://api.neo4j.io/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $TOKEN"

---

Python CI/CD 配置脚本

import os, time, requests

CLIENT_ID     = os.environ["AURA_CLIENT_ID"]
CLIENT_SECRET = os.environ["AURA_CLIENT_SECRET"]
BASE          = "https://api.neo4j.io/v1"

def get_token() -> str:
    r = requests.post(
        "https://api.neo4j.io/oauth/token",
        auth=(CLIENT_ID, CLIENT_SECRET),
        data={"grant_type": "client_credentials"},
    )
    r.raise_for_status()
    return r.json()["access_token"]

def auth_headers(token: str) -> dict:
    return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

def create_instance(token: str, tenant_id: str, **kwargs) -> dict:
    payload = {"tenant_id": tenant_id, "version": "5", **kwargs}
    r = requests.post(f"{BASE}/instances", headers=auth_headers(token), json=payload)
    r.raise_for_status()
    return r.json()["data"]   # contains id, password, connection_url

def poll_status(token: str, instance_id: str, target: str, timeout: int = 600) -> None:
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{BASE}/instances/{instance_id}", headers=auth_headers(token))
        r.raise_for_status()
        status = r.json()["data"]["status"]
        print(f"  status={status}")
        if status == target:
            return
        if status == "destroying":
            raise RuntimeError("Instance destroyed unexpectedly")
        time.sleep(10)
    raise TimeoutError(f"Instance {instance_id} did not reach '{target}' in {timeout}s")

# --- usage ---
token    = get_token()
instance = create_instance(
    token,
    tenant_id = os.environ["AURA_TENANT_ID"],
    name           = "ci-test-instance",
    cloud_provider = "aws",
    region         = "us-east-1",
    type           = "professional-db",
    memory         = "2GB",
)
# SAVE CREDENTIALS IMMEDIATELY — password never retrievable again
print(f"ID:       {instance['id']}")
print(f"URI:      neo4j+s://{instance['id']}.databases.neo4j.io")
print(f"Password: {instance['password']}")   # log to secure vault NOW

poll_status(token, instance["id"], "running", timeout=600)
print("Instance ready.")

---

区域代码

AWS

区域代码	位置
us-east-1	美国弗吉尼亚州北部
us-east-2	美国俄亥俄州
us-west-2	美国俄勒冈州
eu-west-1	爱尔兰
eu-west-3	巴黎
eu-central-1	法兰克福
ap-southeast-1	新加坡
ap-southeast-2	悉尼
ap-south-1	孟买
sa-east-1	圣保罗

GCP

区域代码	位置
europe-west1	比利时
europe-west3	法兰克福
europe-west4	荷兰
us-central1	爱荷华州
us-east1	南卡罗来纳州
us-east4	北弗吉尼亚州
asia-east1	台湾
asia-northeast1	东京
asia-southeast1	新加坡
australia-southeast1	悉尼

Azure

区域代码	位置
eastus	美国东部
eastus2	美国东部 2
westeurope	荷兰
northeurope	爱尔兰
uksouth	伦敦
southeastasia	新加坡
brazilsouth	巴西
koreacentral	韩国

企业层级（Business Critical、VDC）会为每个提供商增加 20 多个区域。请查看控制台获取完整列表。 免费层级：仅限 GCP；可用区域有限。

---

Terraform 提供商

terraform {
  required_providers {
    neo4jaura = {
      source  = "neo4j-labs/neo4jaura"
    }
  }
}

provider "neo4jaura" {
  client_id     = var.aura_client_id       # or AURA_CLIENT_ID env var
  client_secret = var.aura_client_secret   # or AURA_CLIENT_SECRET env var
}

resource "neo4jaura_instance" "db" {
  name           = "prod-db"
  type           = "professional-db"
  cloud_provider = "gcp"
  region         = "europe-west1"
  memory         = "4GB"
  project_id     = var.aura_project_id   # Terraform uses project_id (REST API: tenant_id)
}

output "neo4j_uri" {
  value     = neo4jaura_instance.db.connection_url
  sensitive = false
}
output "neo4j_password" {
  value     = neo4jaura_instance.db.password
  sensitive = true
}

执行 terraform apply 后：将基础设施标记为就绪前，先轮询状态——Terraform 资源创建会在 API 调用完成时返回，而不是在数据库进入 running 状态时返回。

---

常见错误

错误	原因	解决方法
正常工作后出现 403 Forbidden	令牌已过期（TTL 为 1 小时）	重新运行 get_token()
创建时出现 409 Conflict	租户中已存在同名项	更改名称或删除现有项
暂停时出现 422	实例未处于 running 状态	检查状态；等待正在进行的操作完成
恢复时出现 422	实例未处于 paused 状态	检查状态
调整大小时出现 422	小于当前用量	先减少数据；不能缩小到低于当前用量
未找到区域	层级不支持该区域	仅在 GCP 上使用 Free 层级；Pro/BC 支持全部 3 个云平台
创建后凭据丢失	密码仅在创建时返回	删除并重新创建——无法重置
429 Too Many Requests	触发速率限制（Free 为 25 次/分钟，Pro+ 为 125 次/分钟）	在轮询调用之间添加 time.sleep(2)
instance list 返回空结果	当前凭据不正确	aura-cli credential use --name <name>

---

API 速率限制

层级	请求数/分钟
Free / Pro Trial（无账单）	25
Pro（启用账单）、BC、VDC	125

轮询间隔：Free 至少为 10 秒，以遵守速率限制；Pro+ 使用 5 秒即可。 对于 5xx 响应中的 Retry-After 标头：等待相应秒数后再重试。

---

安全规则

• 将初始凭据写入 .env；继续操作前，确认 .env 已列在 .gitignore 中
• 切勿在 CI 日志中打印 PASSWORD——应将其写入密钥保管库（AWS Secrets Manager、GitHub secret、Vault）
• 使用 from_env() / os.environ——切勿将凭据硬编码
• 如果 .env 不存在：python-dotenv 的 load_dotenv() 会自动加载；除非加载失败，否则不要提示用户

---

WebFetch — 当前文档

需求	URL
REST API 规范（OpenAPI）	https://neo4j.com/docs/aura/platform/api/specification/
CLI 参考	https://neo4j.com/docs/aura/aura-cli/
区域列表	https://neo4j.com/docs/aura/managing-instances/regions/
身份验证详情	https://neo4j.com/docs/aura/api/authentication/
实例操作	https://neo4j.com/docs/aura/managing-instances/instance-actions/

---

检查清单

• 已创建包含 URI/用户名/密码的 .env；.env 已列在 .gitignore 中
• 创建后立即将初始凭据保存到安全存储中
• 创建后已调用 poll_status——状态为 running 前不要连接
• 暂停/恢复后已调用 poll_status
• 已选择正确的层级（开发使用 Free，生产使用 Pro+，高可用使用 BC）
• 已确认所选层级和云提供商支持该区域
• 所有创建/列表操作均已提供租户 ID（多租户组织必需）
• 令牌超过 1 小时或收到 403 时已刷新
• 已由用户确认删除——数据丢失不可逆，无法恢复