# 数据库连接问题修复

> **问题类型**: 环境兼容性  
> **影响范围**: 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
```

## 根本原因

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

## 尝试的解决方案

### 方案 1: 使用 asyncpg 0.29.0

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

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

### 方案 2: 添加 gssencmode=disable 参数

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

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

### 方案 3: 使用 127.0.0.1 替代 localhost

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

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

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

## 当前解决方案

### 实施步骤

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

```python
@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...")
```

2. **更新依赖版本**：

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

3. **服务验证**：

```bash
# 启动服务
./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 新特性
- 需要重新配置环境

**实施**:

```bash
# 使用 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

**优点**:

- 稳定可靠
- 立即可用

**缺点**:

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

**实施**:

```python
# 修改 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. **短期（1-2 周）**:
   - 继续使用当前临时方案
   - 监控 asyncpg 更新
   - 开发不依赖数据库的功能（如认证、文件上传）

2. **中期（2-4 周）**:
   - 如果 asyncpg 未修复，考虑降级到 Python 3.12
   - 或实施选项 D（SQLAlchemy asyncio 适配器）

3. **长期**:
   - 升级到修复后的 asyncpg 版本
   - 恢复完整的异步数据库功能

## 相关文件

- `server/app/main.py` - 应用入口（已修改）
- `server/app/core/database.py` - 数据库配置
- `server/requirements.txt` - 依赖版本
- `server/.env` - 环境变量配置

## 参考资料

- [asyncpg Python 3.13 Support](https://github.com/MagicStack/asyncpg/issues)
- [psycopg3 Documentation](https://www.psycopg.org/psycopg3/docs/)
- [SQLAlchemy 2.0 Async](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html)
- [Python 3.13 Release Notes](https://docs.python.org/3.13/whatsnew/3.13.html)

## 更新日志

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