Azure Cosmos DB Shell 故障排除指南

解决 Azure Cosmos DB Shell 安装、身份验证、连接和命令执行的常见问题。

安装问题

问题：“找不到命令”（NuGet 安装）

错误：

cosmosdbshell: command not found

原因：

  • 未安装 .NET SDK
  • 工具未正确安装
  • PATH 未更新
  • 安装后未重启终端

解决方案：

  1. 验证 .NET SDK 安装

    dotnet --version

  2. 重新安装工具

    dotnet tool uninstall --global CosmosDBShell
dotnet tool install --global CosmosDBShell --prerelease

  3. 验证安装位置

    dotnet tool list --global | grep CosmosDBShell
    • 应显示： cosmosdbshell 1.0.213-preview

  4. 重启终端

    • 关闭并重新打开终端
    • 终端可以缓存 PATH 信息

  5. 手动添加到 PATH （如果需要）

    • Windows：将 %USERPROFILE%\.dotnet\tools添加到 PATH
    • macOS/Linux： ~/.dotnet/tools 应已位于 PATH 中

问题：“找不到文件”（二进制安装）

错误：

cosmosdbshell: No such file or directory

原因：

  • 压缩包未完全解压
  • 文件不可执行（Linux/macOS）
  • 文件路径错误

解决方案：

  • 验证提取

    • 检查是否已提取所有文件
    • 查找 cosmosdbshell 可执行文件（在 Windows 上则为 .exe）

  • 设为可执行（Linux/macOS）

    chmod +x ~/cosmosdbshell/cosmosdbshell

  • 使用完整路径

    /full/path/to/cosmosdbshell

  • 添加到 PATH

    export PATH="$PATH:~/cosmosdbshell"

问题：下载期间“文件已损坏”

错误：

Archive is corrupted or incomplete

原因：

  • 不完整的下载
  • 网络中断
  • 文件格式错误

解决方案：

  • 再次下载

    • 删除损坏的文件
    • 从官方源重新下载
    • 验证文件大小是否符合预期

  • 校验 MD5/SHA 哈希

    • 比较已下载文件的哈希
    • 与发布页面提供的哈希值匹配

  • 使用不同的浏览器

    • 尝试替代下载方法
    • 尝试不同的网络连接

身份验证问题

问题：“身份验证失败”

错误：

Authentication failed. Please check your credentials.

原因：

  • 过期的令牌
  • 凭据错误
  • 无 Internet 连接
  • 帐户密钥不正确

解决方案：

  • 试用 Entra ID（推荐）

    • Cosmos DB Shell 应提示进行浏览器身份验证
    • 使用 Azure 帐户登录
    • 最可靠的方法

  • 检查 Internet 连接

    ping azure.microsoft.com
    • 确保网络连接

  • 验证帐户密钥

    • 转到Azure门户
    • 导航到 Cosmos DB 帐户
    • 复制主连接字符串
    • 验证格式是否正确

  • 清除缓存凭据

    • Windows：credman （凭据管理器）
    • macOS：密钥链
    • Linux：检查 ~/.config 目录

问题：“未授权 - 权限不足”

错误：

Authorization failed. Your user does not have permission to perform this operation.

原因：

  • 用户缺少所需的 RBAC 角色
  • 未分配给账户的角色
  • 订阅上下文错误

解决方案：

  1. 检查 RBAC 角色

    • 转到 Azure 门户 > Cosmos DB 帐户
    • 访问控制（IAM）
    • 确认你的用户拥有“Cosmos DB Account Reader”或更高权限的角色

  2. 请求角色分配

  3. 验证订阅

    az account show
    • 确保处于正确的订阅中
    • 根据需要切换： az account set --subscription <ID>

问题：“令牌已过期”

错误：

Token has expired. Please re-authenticate.

原因：

  • 会话超时
  • 令牌在长时间处于非活动状态后过期
  • 时间同步问题

解决方案：

  1. 重新进行身份验证

    • 退出shell：exit
    • 重新启动：cosmosdbshell
    • 再次登录

  2. 检查系统时间

    • 确保系统时钟已同步
    • Windows：设置>时间和语言> 日期和时间
    • macOS/Linux：使用 date 检查系统时间

  3. 检查令牌刷新设置

    • 令牌应会自动刷新
    • 如果问题仍然存在，请联系Azure 支持

连接问题

问题：“连接被拒绝”

错误：

Connection refused to Cosmos DB account

原因：

  • 终结点 URL 错误
  • 防火墙阻止连接
  • 网络连接问题
  • 帐户终结点不正确

解决方案：

  1. 验证终结点 URL

    • Azure 门户 > Cosmos DB 帐户
    • 复制正确的终结点 URL
    • 格式：https://<account>.documents.azure.cn:443/

  2. 检查防火墙

    • 验证 Cosmos DB 防火墙规则中的允许 IP 地址
    • Azure门户> Cosmos DB 帐户>防火墙和虚拟网络
    • 如有需要，请添加您的 IP

  3. 测试网络连接

    ping <account>.documents.azure.cn
    • 应使用 IP 地址进行响应

  4. 检查 VPN/代理

    • 如果使用 VPN，请确保它已连接
    • 如果使用代理，请验证代理设置

问题：“无法解决终结点”

错误：

Cannot resolve host: account.documents.azure.cn

原因：

  • DNS 解析失败
  • 终结点名称错误
  • 网络连接
  • 防火墙阻止 DNS

解决方案：

  1. 验证终结点拼写

    • 仔细检查帐户名称
    • 格式正确： https://<account>.documents.azure.cn:443/

  2. 检查 DNS

    nslookup <account>.documents.azure.cn
    • 应返回 IP 地址

  3. 尝试备用 DNS

    • 使用公共 DNS（8.8.8.8、1.1.1.1.1）
    • 检查 ISP DNS 设置

  4. 测试直接连接

    telnet <account>.documents.azure.cn 443
    • 应该能够成功连接

问题：“连接到 Cosmos DB 时超时”

错误：

Connection timeout. Could not connect to Cosmos DB account.

原因：

  • 网络延迟
  • Internet 连接速度缓慢
  • Cosmos DB 服务问题
  • 防火墙阻止流量

解决方案：

  1. 增加超时时间

    • 在设置中修改连接超时时间
    • 默认为 30 秒

  2. 检查网络速度

    • 通过测速测试带宽
    • 确保有足够的带宽

  3. 尝试不同的网络

    • 切换到不同的 Wi-Fi 或移动热点
    • 测试问题是否特定于网络

  4. Check Azure Status

命令问题

问题：“命令无法识别”

错误：

Unknown command. Type 'help' for available commands.

原因：

  • 命令名称中的拼写错误
  • 此命令在当前版本中不受支持
  • 使用错误的语法

解决方案：

  1. 检查命令语法

    • 使用 help 列出可用命令
    • 使用 help <command> 获取特定命令的帮助信息

  2. 验证命令拼写

    > help query
    • 正确： query，不是 select 或 find

  3. 查看您的版本

    > version
    • 确保你拥有最新版本

问题：“查询中的语法错误”

错误：

Syntax error in SQL query

原因：

  • 无效的 SQL 语法
  • 缺少引号
  • JSON 路径不正确
  • 不支持的 SQL 函数

解决方案：

  1. 查看 SQL 语法

    • 验证查询是否为有效的 SQL，而非 NoSQL
    • 示例： SELECT * FROM c WHERE c.status = 'active'
    • 无效： db.collection.find({})

  2. 检查字符串引号

    • 在查询中使用单引号
    • 字符串值： 'value'
    • JSON 键： "key"

  3. 验证 JSON 路径

    • 正确：c.address.city
    • 无效： c.address[0].city （没有适当的语法）

  4. 在 Azure 门户中测试查询

    • 首先验证查询在 数据资源管理器 中是否正常工作
    • 将工作查询复制到 shell

问题：“未返回文档”

错误：

CS > query "SELECT * FROM c"
(empty result)

原因：

  • 容器为空
  • 查询筛选器过于严格
  • 错误的容器
  • 分区键不匹配

解决方案：

  • 验证容器是否具有数据

    > query "SELECT COUNT(*) as count FROM c"
    • 应返回计数 > 0

  • 检查容器名称

    > pwd
    • 确认你位于正确的容器中

  • 简化查询

    # Start with simple query
> query "SELECT TOP 1 * FROM c"

# Then add filters
> query "SELECT * FROM c WHERE c.status = 'active'"

  • 查看分区键

    • 确保查询中包含分区键
    • 为了获得更好的性能： SELECT * FROM c WHERE c.id = 'value'

VS Code 扩展问题

问题：扩展程序未显示

错误：

Cannot find "Azure Cosmos DB Shell" in Extensions

原因：

  • VS Code 版本太旧
  • 未安装扩展
  • VS Code 缓存问题

解决方案：

  • 检查 VS Code 版本

    • 有关帮助>
    • 应为 1.85 或更高版本
    • 根据需要更新

  • 重新安装扩展

    • 转到扩展（Ctrl+Shift+X）
    • 搜索“Cosmos DB”
    • 单击“安装”

  • 清除 VS Code 缓存

    • 关闭 VS Code
    • 删除 .vscode 用户目录中的文件夹
    • 重启 VS Code

问题：资源资源管理器空白

错误：

Resource Explorer shows no databases or containers

原因：

  • 未经过身份验证
  • 订阅中没有 Cosmos DB 帐户
  • 选择了错误的订阅
  • 帐户没有数据库

解决方案：

  1. 验证身份验证

    • 单击侧栏中的 Cosmos DB 图标
    • 应显示帐户选择器
    • 出现提示时登录

  2. 检查订阅

    • 验证是否选择了正确的订阅
    • 根据需要切换订阅

  3. 刷新资源管理器

    • 按 F5 或单击“刷新”图标
    • 等待数据加载

  4. 检查帐户是否存在

    • 转到Azure门户
    • 验证 Cosmos DB 帐户是否存在
    • 验证你是否有权访问帐户

问题：MCP 服务器不会在 VS Code 中启动

错误：

Failed to start MCP server

原因：

  • 已在使用的端口
  • 设置无效
  • Cosmos DB Shell 未正确安装
  • 防火墙阻止端口

解决方案：

  1. 检查端口可用性

    # Windows
netstat -ano | findstr 6128

# macOS/Linux
lsof -i :6128
    • 如果使用，终止进程或使用不同的端口

  2. 验证 MCP 设置

    • 打开设置 （Ctrl+，）
    • 搜索“Cosmos DB”
    • 检查 cosmosDB.shell.MCP.enabled 是否为 true

  3. 尝试不同的端口

    {
  "cosmosDB.shell.MCP.port": 6129
}

  4. 检查防火墙

    • 确保防火墙允许 localhost 连接
    • 暂时禁用以进行测试

MCP 服务器问题

问题：“MCP 服务器未响应”

错误：

Cannot connect to MCP server

原因：

  • MCP 服务器未运行
  • 端口错误
  • 防火墙问题
  • 连接超时

解决方案：

  1. 验证 MCP 服务器是否正在运行

    curl http://localhost:6128/health
    • 应返回 JSON 响应

  2. 检查配置

    • 验证 cosmosDB.shell.MCP.enabled 是否为 true
    • 在设置中检查正确的端口

  3. 重启 MCP 服务器

    • 命令面板 （Ctrl+Shift+P）
    • 键入“Cosmos DB：重启 MCP 服务器”

  4. 检查防火墙

    • 确保 localhost：6128 可访问
    • 暂时禁用防火墙以进行测试

问题：“MCP 端口已被占用”

错误：

Cannot bind MCP server to port 6128

原因：

  • 占用该端口的另一个进程
  • MCP 服务器已运行
  • 端口冲突

解决方案：

  1. 停止现有 MCP 服务器

    • 命令面板 （Ctrl+Shift+P）
    • 键入“Cosmos DB：停止 MCP 服务器”

  2. 使用端口查找进程

    # Windows
netstat -ano | findstr 6128
taskkill /PID <PID> /F

# macOS/Linux
lsof -i :6128
kill -9 <PID>

  3. 使用不同的端口

    {
  "cosmosDB.shell.MCP.port": 6129
}

性能问题

问题：Shell 速度缓慢或无响应

原因：

  • 大型查询结果集
  • 网络连接缓慢
  • 系统资源使用率高
  • Cosmos DB 服务问题

解决方案：

  1. 限制查询结果

    > query "SELECT TOP 100 * FROM c"

  2. 将筛选器添加到查询

    > query "SELECT * FROM c WHERE c.status = 'active'"

  3. 检查网络

    • 测试带宽
    • 切换到不同的网络
    • 使用 ping 检查延迟

  4. 监视系统资源

    • 检查 CPU 使用率
    • 检查内存使用情况
    • 关闭不必要的应用程序

问题：查询超时

错误：

Query timeout. Please try again.

原因：

  • 大型结果集
  • 复杂查询
  • 网络速度缓慢
  • Cosmos DB 服务重载

解决方案：

  1. 增加超时设置

    • 设置 （Ctrl+，）
    • 搜索“Cosmos DB”
    • 增加 cosmosDB.queryTimeout

  2. 优化查询

    # Instead of SELECT *
> query "SELECT c.id, c.name FROM c"

# Add filters
> query "SELECT * FROM c WHERE c.status = 'active'"

# Use TOP
> query "SELECT TOP 1000 * FROM c"

  3. 检查 Cosmos DB

获取帮助

  1. 查看文档

  2. Azure 支持

另请参阅

  • Last updated on