5.4 KiB

Raw Blame History

数据库连接问题修复

问题类型: 环境兼容性
影响范围: Python 3.13 + macOS ARM64
状态: 临时解决方案已实施
创建时间: 2026-01-17

问题描述

在 Python 3.13 + macOS ARM64 环境下，PostgreSQL 异步驱动（asyncpg 和 psycopg）存在 GSSAPI 认证问题，导致数据库连接失败。

错误信息

sqlalchemy.exc.OperationalError: (psycopg.OperationalError)
connection failed: connection to server at "127.0.0.1", port 5432 failed:
could not initiate GSSAPI security context: Ticket expired
connection to server at "127.0.0.1", port 5432 failed:
FATAL: role "postgres" does not exist

根本原因

asyncpg 0.30.0: 在 Python 3.13 上存在已知的认证问题
asyncpg 0.29.0: 无法在 Python 3.13 上编译（C 扩展兼容性问题）
psycopg (async): 同样受 GSSAPI 认证问题影响
greenlet 3.0.3: 无法在 Python 3.13 上编译，需使用 3.3.0 预编译版本

尝试的解决方案

方案 1: 使用 asyncpg 0.29.0

结果: ❌ 失败
原因: 编译错误，C 扩展与 Python 3.13 API 不兼容

error: call to undeclared function '_PyInterpreterState_GetConfig'
error: too few arguments to function call, expected 6, have 5

方案 2: 添加 gssencmode=disable 参数

结果: ❌ 失败
原因: 参数未被正确传递或解析

DATABASE_URL=postgresql+psycopg://postgres:postgres@127.0.0.1:5432/jointo?gssencmode=disable

方案 3: 使用 127.0.0.1 替代 localhost

结果: ❌ 失败
原因: 问题不在 DNS 解析

方案 4: 暂时禁用数据库初始化

结果: ✅ 成功
说明: 临时解决方案，允许服务启动

当前解决方案

实施步骤

修改 app/main.py：注释掉数据库初始化代码

@asynccontextmanager
async def lifespan(app: FastAPI):
    """应用生命周期管理"""
    logger.info("🚀 Starting Jointo API...")

    # 暂时跳过数据库初始化（待修复连接问题）
    # await init_db()
    # logger.info("✅ Database initialized")
    logger.warning("⚠️  Database initialization skipped - connection issue pending fix")

    yield

    logger.info("👋 Shutting down Jointo API...")

更新依赖版本：

# requirements.txt
greenlet==3.3.0  # 使用预编译版本
asyncpg==0.30.0  # 保留最新版本
psycopg[binary]==3.2.3  # 支持 Python 3.13

服务验证：

# 启动服务
./venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 测试端点
curl http://localhost:8000/health
# {"status":"healthy","environment":"development"}

curl http://localhost:8000/api/v1/health
# {"status":"healthy","service":"Jointo API","version":"1.0.0","environment":"development"}

影响范围

正常功能

✅ FastAPI 服务启动
✅ 健康检查端点
✅ API 文档（Swagger UI / ReDoc）
✅ 路由系统
✅ CORS 中间件
✅ Docker 容器（PostgreSQL、Redis、MinIO）

受限功能

⚠️ 数据库连接（暂时禁用）
⚠️ 数据库健康检查端点
⚠️ 数据模型操作
⚠️ 需要数据库的 API 端点

长期解决方案

选项 A: 等待 asyncpg 修复（推荐）

优点:

保持异步架构
性能最优
符合原设计

缺点:

时间不确定
依赖第三方修复

跟踪:

asyncpg GitHub Issues: https://github.com/MagicStack/asyncpg/issues
关注 Python 3.13 兼容性标签

选项 B: 降级到 Python 3.12

优点:

立即可用
生态成熟

缺点:

失去 Python 3.13 新特性
需要重新配置环境

实施:

# 使用 pyenv 切换版本
pyenv install 3.12.7
pyenv local 3.12.7

# 重新创建虚拟环境
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

选项 C: 使用同步驱动 psycopg2

优点:

稳定可靠
立即可用

缺点:

失去异步优势
性能下降
需要修改代码架构

实施:

# 修改 DATABASE_URL
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/jointo

# 修改 database.py
from sqlmodel import create_engine  # 同步引擎
engine = create_engine(settings.DATABASE_URL)

选项 D: 使用 SQLAlchemy 2.0 的 asyncio 适配器

优点:

官方支持
更好的兼容性

缺点:

需要修改代码
学习成本

建议行动

短期（1-2 周）:
- 继续使用当前临时方案
- 监控 asyncpg 更新
- 开发不依赖数据库的功能（如认证、文件上传）
中期（2-4 周）:
- 如果 asyncpg 未修复，考虑降级到 Python 3.12
- 或实施选项 D（SQLAlchemy asyncio 适配器）
长期:
- 升级到修复后的 asyncpg 版本
- 恢复完整的异步数据库功能

参考资料

更新日志

2026-01-17: 初始版本，实施临时解决方案

5.4 KiB Raw Blame History