STARTUP_TROUBLESHOOTING.md

# Flow2API HuggingFace Spaces 启动问题诊断和解决方案

## 🐛 问题描述

应用在 HuggingFace Spaces 上启动后卡在：
```
===== Application Startup at 2025-11-24 17:30:58 =====
```

## 🔍 可能的原因分析

### 1. **数据库初始化阻塞**
- SQLite 数据库创建时的权限问题
- 异步数据库操作在容器环境中被阻塞
- 数据库迁移过程中的死锁

### 2. **异步操作超时**
- 应用启动时的并发初始化操作
- 资源竞争导致的阻塞
- HuggingFace Spaces 的资源限制

### 3. **文件系统权限问题**
- 日志文件写入权限
- 数据目录创建权限
- 配置文件读取权限

### 4. **网络��接问题**
- Google API 连接检查
- 代理设置配置
- 网络超时设置

## 🔧 提供的解决方案

### 方案 1：增强调试版 Dockerfile
```dockerfile
# 已创建 Dockerfile，包含：
- 详细的启动调试信息
- 文件权限修复
- 更长的健康检查启动时间（120s）
- 调试启动脚本
```

### 方案 2：简化版 Dockerfile
```dockerfile
# 已创建 Dockerfile.simple：
- 最大权限设置（777）
- 使用 root 用户运行
- 180秒启动时间
- 备用启动脚本
```

### 方案 3：诊断脚本
```python
# 已创建 start_simple.py：
- 环境变量检查
- 文件权限验证
- 数据库连接测试
- 简单的备用服务器
```

## 🚀 部署步骤

### 第一步：尝试增强版
1. **推送当前的 Dockerfile**
2. **配置环境变量**：
   ```bash
   FLOW2API_DEBUG_ENABLED=true
   FLOW2API_DEBUG_LOG_REQUESTS=false
   FLOW2API_DEBUG_LOG_RESPONSES=false
   ```
3. **查看启动日志**，应该看到详细的调试信息

### 第二步：如果仍然卡住，使用简化版
1. **重命名文件**：
   ```bash
   mv Dockerfile Dockerfile.backup
   mv Dockerfile.simple Dockerfile
   ```
2. **重新部署**
3. **监控启动过程**

### 第三步：手动调试
如果自动启动仍然失败，可以：
1. **使用 start_simple.py** 作为主启动脚本
2. **通过 HuggingFace Spaces 终端**（如果可用）手动执行：
   ```bash
   cd /app
   python start_simple.py
   ```

## 📋 诊断检查清单

### 环境变量确认
在 HuggingFace Spaces 设置中确认：
- [ ] `FLOW2API_HOST=0.0.0.0`
- [ ] `FLOW2API_PORT=7860`
- [ ] `PYTHONUNBUFFERED=1`
- [ ] `FLOW2API_DEBUG_ENABLED=false`（生产环境）或 `true`（调试）

### 文件权限检查
查看启动日志中是否显示：
- [ ] `File permissions fixed`
- [ ] 用户信息正确
- [ ] 日志文件权限 `666` 或 `777`

### 数据库初始化检查
查看日志中的数据库相关消息：
- [ ] `Database initialized`
- [ ] `Total tokens: 0`
- [ ] 没有 SQLite 错误

### 服务状态检查
部署后检查：
- [ ] 健康检查通过
- [ ] 根路由响应：`curl https://your-space.hf.space/`
- [ ] API 路由响应：`curl https://your-space.hf.space/v1/models`

## 🛠️ 高级调试技巧

### 启用详细日志
```bash
# 在环境变量中设置
FLOW2API_DEBUG_ENABLED=true
PYTHONUNBUFFERED=1
```

### 检查容器内部
如果可以访问容器终端：
```bash
# 检查进程
ps aux

# 检查端口
netstat -tlnp

# 检查文件
ls -la /app/

# 手动测试数据库
python -c "import aiosqlite; print('OK')"
```

### 替代启动方法
如果主启动脚本失败，可以：
1. **直接使用 Uvicorn**：
   ```bash
   uvicorn src.main:app --host 0.0.0.0 --port 7860
   ```

2. **禁用某些功能**：
   ```bash
   # 通过环境变量禁用缓存和调试
   FLOW2API_CACHE_ENABLED=false
   FLOW2API_DEBUG_ENABLED=false
   ```

## 🔄 迁移到生产配置

一旦应用成功启动，建议：

1. **禁用调试**：
   ```bash
   FLOW2API_DEBUG_ENABLED=false
   FLOW2API_DEBUG_LOG_REQUESTS=false
   FLOW2API_DEBUG_LOG_RESPONSES=false
   ```

2. **优化性能**：
   ```bash
   FLOW2API_IMAGE_TIMEOUT=600
   FLOW2API_VIDEO_TIMEOUT=1800
   FLOW2API_CACHE_ENABLED=true
   ```

3. **安全配置**：
   ```bash
   # 更改默认密码
   FLOW2API_ADMIN_PASSWORD=your-secure-password
   # 配置真实的 API 密钥
   FLOW2API_API_KEY=your-google-api-key
   ```

## 📞 故障排除联系

如果问题仍然存在：

1. **查看详细日志**：HuggingFace Spaces 构建日志
2. **尝试本地测试**：使用相同配置在本地运行
3. **报告问题**：在 GitHub 上创建 issue 并提供：
   - 完整的启动日志
   - 环境变量配置
   - 使用的是哪个 Dockerfile 版本

## 📚 相关资源

- [HuggingFace Spaces 文档](https://huggingface.co/docs/hub/spaces)
- [FastAPI 调试指南](https://fastapi.tiangolo.com/tutorial/debugging/)
- [SQLite 权限问题](https://www.sqlite.org/permissionless.html)

---

**目标**：让 Flow2API 在 HuggingFace Spaces 上稳定运行，提供完整的图像和视频生成 API 服务。