部署在Azure Web App的ChromaDB客户端连接超时问题排查

问题重现 #

尝试连接部署在Azure Web App上的ChromaDB v3.9.10时，持续出现连接超时错误，代码示例：

import chromadb

client = chromadb.HttpClient(host="https://chroma-db.azurewebsites.net")

client.list_collections()

错误日志核心片段：

TimeoutError: [Errno 60] Operation timed out
urllib3.exceptions.ConnectTimeoutError: Connection to chroma-db.azurewebsites.net timed out
MaxRetryError: HTTPConnectionPool(host='chroma-db.azurewebsites.net', port=8000): Max retries exceeded with url: /api/v1/collections

Azure Web App配置调整 #

• 设置正确的启动命令：在Azure Portal进入Web App的「配置」→「常规设置」，将启动命令改为：

  chroma run --host 0.0.0.0 --port 8000
  

  确保Chroma监听所有内部IP和8000端口，让Azure反向代理能正常转发流量到Chroma服务。
• 配置内部端口映射：同样在「常规设置」里，将「端口」字段设置为8000，Azure会自动把外部80/443端口的请求转发到这个内部端口。
• 检查访问限制规则：进入「网络」→「访问限制」，确认没有阻止客户端IP的规则；如果需要IP白名单，将客户端公网IP加入允许列表。
• 启用强制HTTPS：进入「自定义域名」，开启「HTTPS only」选项，保证外部请求通过HTTPS协议访问。

代码调整 #

• 修正HttpClient参数：Chroma的HttpClient不支持在host参数中带协议前缀，需单独指定ssl=True和外部HTTPS端口443（Azure Web App默认HTTPS端口），修改后的代码：

  import chromadb
  
  client = chromadb.HttpClient(
      host="chroma-db.azurewebsites.net",
      port=443,
      ssl=True
  )
  
  client.list_collections()
  

• 可选：增加超时设置：若网络环境不稳定，可添加超时参数避免长时间等待：

  client = chromadb.HttpClient(
      host="chroma-db.azurewebsites.net",
      port=443,
      ssl=True,
      timeout=30  # 超时时间，单位秒
  )
  

验证步骤 #

先通过浏览器访问 https://chroma-db.azurewebsites.net/api/v1/collections，若返回[]或正常JSON响应，说明Chroma服务已正常对外提供接口，再运行调整后的代码即可成功连接。

内容的提问来源于stack exchange，提问作者Gid