使用Firebase Admin SDK连接Firestore时应用冻结问题咨询

AI 小北

2026-8-27

问题根因

卡在OAuth2令牌请求环节无响应，本质是SDK发起HTTP请求后既没有收到响应、也没有触发超时退出逻辑，最终无限阻塞。常见诱因有三个：

网络连通性异常：Python进程无法正常访问Google OAuth2服务端点。注意Python默认HTTP客户端不会自动读取系统全局代理配置，很多时候系统开了代理但Python进程没继承代理规则，会直接卡在TCP建连环节，不会主动抛出连接错误；此外防火墙、出口网络拦截也会导致同类问题。多数本地开发环境的同类问题都是这个原因导致的——代理工具仅配置了浏览器代理，未设置系统级环境变量，Python进程默认不经过代理直接发起连接被拦截。
运行时环境冲突：如果Django以ASGI模式运行、在异步视图中直接调用同步的Firebase SDK方法，或是部署时用了gevent/eventlet这类猴子补丁但加载顺序不对，会导致底层socket请求被阻塞，无法正常返回。
旧版本SDK缺陷：6.2以下版本的Firebase Admin Python SDK没有给HTTP请求设置默认超时，遇到网络异常时会无限等待，不会抛出任何错误日志。

排查与解决步骤

先验证基础网络连通性：在运行Django的相同Python环境下执行如下测试代码，确认网络层是否正常：

import requests
try:
    r = requests.post("https://oauth2.googleapis.com/token", timeout=10)
    print(f"连通正常，响应状态码：{r.status_code}")
except Exception as e:
    print(f"连通失败：{str(e)}")

如果测试提示连接超时、连接被重置，优先解决网络问题：需要走代理的场景，要显式给Python进程设置HTTP_PROXY、HTTPS_PROXY环境变量，不要依赖系统全局代理；同时排查服务器防火墙、安全组规则是否放开了对应域名的443端口出站权限。

给SDK显式配置超时，避免无限阻塞：初始化Firebase应用时主动传入超时参数，从根源上避免无限挂起：

import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore

cred = credentials.Certificate(key_path)
# 显式设置10秒请求超时
firebase_admin.initialize_app(cred, options={"httpTimeout": 10})
db = firestore.client()

# 后续业务代码保持不变
doc_ref = db.collection(u'users').document(u'alovelace') 
doc_ref.set({
    u'first': u'Ada',
    u'last': u'Lovelace',
    u'born': 1815
})

需要指定代理的场景，可以在初始化时自定义HTTP客户端传入对应代理配置。

排查运行时冲突：如果用了异步Django视图（async def定义的视图），不要直接在异步上下文里调用Firebase SDK的同步方法，要用sync_to_async包装后再执行；如果用Gunicorn+gevent模式部署，确认gevent猴子补丁在所有第三方库导入之前执行，也可以临时切换为默认sync worker测试是否还会复现阻塞问题。
升级SDK到最新版本：执行pip install --upgrade firebase-admin，修复旧版本已知的HTTP客户端阻塞bug。

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