mcpField
T
troubleshooting

troubleshooting

github.com/acquia云与 DevOps10123 次安装1 天前更新
代码仓库

关于 troubleshooting

troubleshooting 是用于诊断 Acquia CLI 问题的指南，涵盖安装、身份验证、IDE、SSH 和命令错误。它列出可能原因、修复命令，以及联系支持前应收集的信息。

主要功能

  1. 01诊断安装和 PATH 问题
  2. 02解决身份验证及访问错误
  3. 03排查 IDE 和 SSH 问题
  4. 04调查应用及命令故障
  5. 05收集版本和调试信息

适用场景

  1. 01修复 acli 登录失败
  2. 02调查 IDE 无法启动的问题
  3. 03解决 SSH 公钥错误
  4. 04准备联系支持所需的诊断信息

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/acquia/acquia-skills --skill troubleshooting

安装后在 Claude Code 中输入/troubleshooting确认已加载。

详细介绍

Acquia CLI 故障排查

适用于：

  • 诊断 acli 身份验证失败
  • 解决命令错误或意外输出
  • 联系支持团队前收集信息

常见问题

“Command not found: acli”

原因： 二进制文件不在系统 PATH 中。

解决方案：

# Check if it's installed
which acli

# If nothing, add to PATH
export PATH="/usr/local/bin:$PATH"

# Test
acli --version

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
运行 acli 时出现“Permission denied”

原因： 二进制文件不可执行。

解决方案：

chmod +x /usr/local/bin/acli
acli --version
更新后出现“acli: command not found”

原因： 更新未完成，或 PATH 已更改。

解决方案：

# Reinstall
curl -fsSL https://github.com/acquia/cli/releases/latest/download/acli \
  -o /usr/local/bin/acli
chmod +x /usr/local/bin/acli

# Verify
acli --version

身份验证问题

“Error: Failed to authenticate”

原因： 身份验证令牌已过期或无效。

解决方案：

# Re-authenticate
acli auth:login

# This opens your browser to authorize again
“Error: Access Denied”

原因： 你的帐户无权访问此资源。

解决方案：

  1. 确认你使用的是正确的帐户登录：

    acli auth:me

  2. 在 Acquia Cloud UI 中确认你拥有访问权限：

  3. 退出后重新登录：

    acli auth:logout
acli auth:login
“Invalid JSON in credentials.json”

原因： 凭据文件已损坏。

解决方案：

# Remove the corrupted file
rm -rf ~/.acquia/cloud_api/

# Re-authenticate
acli auth:login

IDE 问题

IDE 无法启动

症状： IDE 一直显示“Starting...”，或无法加载。

解决方案：

  1. 尝试重启 IDE 服务：

    acli ide:service-stop
acli ide:service-start

  2. 检查 IDE 状态：

    acli ide:info

  3. 如果是新建的 IDE，请稍等： 新 IDE 需要 2-3 分钟才能启动。请稍后再检查。

  4. 尝试新建 IDE：

    acli ide:create
IDE 运行很慢

原因： 正在从休眠状态唤醒、进程卡住或资源限制

解决方案：

  1. 如果 IDE 正从休眠状态唤醒，请稍等： IDE 唤醒需要 30-60 秒，请耐心等待。

  2. 清除 Drupal 缓存：

    acli remote:drush cr

  3. 重启 IDE：

    acli ide:service-restart

  4. 新建一个 IDE：

    acli ide:create --label "Fresh IDE"
打开 IDE 时出现“Access Denied”

原因： 尚未设置 SSH 密钥。

解决方案：

# Create an SSH key
acli ssh-key:create

# Try accessing IDE again
acli ide:open
IDE 看似已删除，但仍然存在

原因： IDE 处于休眠状态，或列表已缓存。

解决方案：

# Clear cache and list again
acli self:clear-caches
acli ide:list

SSH 密钥问题

“Permission denied (publickey)”

原因： SSH 密钥尚未设置，或未正确使用。

解决方案：

  1. 确认 SSH 密钥存在：

    ls -la ~/.ssh/id_rsa

  2. 如果没有，请创建一个：

    acli ssh-key:create

  3. 检查权限（必须为 600）：

    chmod 600 ~/.ssh/id_rsa

  4. 确认密钥已添加到 Acquia 帐户：

    acli ssh-key:list
“创建 IDE 时找不到 SSH 密钥”

原因： 创建 IDE 需要 SSH 密钥以确保安全访问。

解决方案：

# Create SSH key first
acli ssh-key:create

# Then create IDE
acli ide:create
“有多个 SSH 密钥，该用哪一个？”

解决方案：

添加到 ~/.ssh/config：

Host ide-*.ides.acquia.com
  IdentityFile ~/.ssh/my_custom_key

应用程序和环境问题

“No applications found”

原因： 你目前无权访问任何应用程序。

解决方案：

  1. 确认你是否属于某个团队：

    acli auth:me

  2. 请团队管理员将你添加到某个应用程序

“Error: Application not found”

原因： 应用程序 UUID 错误，或你无权访问。

解决方案：

  1. 列出应用程序以找到正确的应用程序：

    acli api:applications:list

    MEO (V3) 订阅： api:applications:list 不会返回任何结果——请改用 acli api:v3:sites:list 或 acli api:v3:codebases:list 列出你的资源（参见 MEO 概览）。

  2. 使用正确的应用程序：

    acli ide:create --application=<correct-uuid>

命令执行问题

“Error: Drush command failed”

原因： Drupal 站点中的 Drush 出错。

解决方案：

  1. 查看 Drush 输出以了解详情：

    acli remote:drush status

  2. 清除缓存：

    acli remote:drush cr
“Error: Could not connect to remote server”

原因： 网络连接问题或 SSH 密钥问题。

解决方案：

  1. 检查 SSH 密钥设置：

    acli ssh-key:list

  2. 尝试使用详细输出查看详情：

    acli -vvv <command>

性能问题

命令执行时间过长

解决方案：

  1. 重试（问题可能是暂时的）

  2. 检查网络连接：

    ping acquia.com

  3. 尝试设置较短的超时时间：

    acli <command> --no-wait
缓存导致数据过时

原因： CLI 会缓存 API 响应。

解决方案：

# Clear cache
acli self:clear-caches   # aliases: acli cc, acli cr

# Try the command again
acli <command>

# Or run with --no-cache if supported
acli <command> --no-cache

获取帮助

检查 acli 版本
acli --version
启用调试输出
# Run any command with verbose output
acli -vvv <command>

# Save to a log file
acli -vvv <command> > debug.log 2>&1
查看所有帮助信息
# General help
acli --help

# List all commands
acli list

# Help for a specific command
acli <command> --help

获取支持帮助

联系支持团队前，请收集相关信息
# Your version
acli --version

# Your account info
acli auth:me

# Your applications (ACE / V2). On MEO (V3), use: acli api:v3:sites:list
acli api:applications:list

# Your IDEs
acli ide:list

# Your SSH keys
acli ssh-key:list

# Debug output of the problem command
acli -vvv <command> 2>&1 | tee debug.log
联系 Acquia Support

常见错误消息

错误含义解决方案
"Error: Access Denied"你没有权限检查账户访问权限和团队成员资格
"Command not found"二进制文件不在 PATH 中检查安装情况，并确认 PATH 设置
"Failed to authenticate"令牌已过期或无效重新运行 acli auth:login
"SSH Key not found"IDE 需要 SSH 密钥使用 acli ssh-key:create 创建密钥
"IDE not starting"IDE 配置速度较慢或失败等待 2-3 分钟后重启，或创建新的 IDE
"Permission denied (publickey)"SSH 密钥问题验证密钥设置：acli ssh-key:list
"No applications found"无团队访问权限请管理员将你添加到团队

高级故障排除

检查 API 响应
# See what the API is returning
acli -vvv <command> 2>&1 | grep -A 5 "Response:"
重置所有配置
# CAUTION: This clears everything
rm -rf ~/.acquia

# Re-authenticate
acli auth:login

最佳实践

  1. 保持更新 — 定期运行 acli self:update；许多错误已在较新版本中修复。
  2. 先检查身份验证 — 在怀疑其他命令之前，先运行 acli auth:me。
  3. 使用详细模式 — 在任何失败的命令后添加 -vvv，以查看详细的错误输出。

仍然无法解决？ 联系 Acquia Support

评论

支持 Markdown