DEPLOYMENT_GUIDE.md

# Flow2API HuggingFace Spaces 部署指南

## 📋 部署清单

在部署到 HuggingFace Spaces 之前，请确认以下项目：

### ✅ 必需配置
- [ ] Google VideoFX API 密钥
- [ ] 自定义管理员用户名和密码
- [ ] 代理配置（如需要）
- [ ] 超时和重试设置

### ✅ 文件结构
确认以下文件已正确配置：
```
zzz/
├── Dockerfile                    # ✅ 已创建
├── requirements.txt              # ✅ 已创建
├── .env                         # ✅ 已创建
├── README.md                    # ✅ 已优化
├── config/
│   └── setting.toml             # ✅ 已创建
└── DEPLOYMENT_GUIDE.md          # ✅ 本文件
```

## 🚀 部署步骤

### 1. 准备 HuggingFace Space

1. **创建新 Space**：
   - 访问 [huggingface.co/spaces](https://huggingface.co/spaces)
   - 点击 "Create new Space"
   - 选择 **Docker** 作为 SDK
   - 设置 Space 名称（例如：flow2api-video）
   - 选择 **Public** 或 **Private**（Private 需要订阅）

2. **上传代码**：
   ```bash
   # 方法1：使用 Git 克隆和推送
   git clone https://huggingface.co/spaces/your-username/flow2api-video
   cd flow2api-video
   cp -r /path/to/zzz/* .
   git add .
   git commit -m "Initial Flow2API deployment"
   git push

   # 方法2：直接上传文件（通过网页界面）
   # 上传所有文件到 Space
   ```

### 2. 配置环境变量

在 HuggingFace Space 设置中配置以下环境变量：

#### 🔑 核心配置（必须设置）
```bash
FLOW2API_API_KEY=your-google-videofx-api-key
FLOW2API_ADMIN_USERNAME=your-admin-username
FLOW2API_ADMIN_PASSWORD=your-secure-password-change-this
```

#### ⚙️ 服务器配置
```bash
FLOW2API_HOST=0.0.0.0
FLOW2API_PORT=7860
```

#### 🐛 调试配置（可选）
```bash
FLOW2API_DEBUG_ENABLED=false
FLOW2API_DEBUG_LOG_REQUESTS=true
FLOW2API_DEBUG_LOG_RESPONSES=true
FLOW2API_DEBUG_MASK_TOKEN=true
```

#### ⏱️ 性能配置（可选）
```bash
FLOW2API_IMAGE_TIMEOUT=600
FLOW2API_VIDEO_TIMEOUT=1800
FLOW2API_TIMEOUT=180
FLOW2API_MAX_RETRIES=5
```

#### 🌐 代理配置（如果需要）
```bash
FLOW2API_PROXY_ENABLED=true
FLOW2API_PROXY_URL=http://your-proxy.com:8080
```

#### 💾 缓存配置（可选）
```bash
FLOW2API_CACHE_ENABLED=true
FLOW2API_CACHE_TIMEOUT=14400
FLOW2API_CACHE_BASE_URL=https://your-cdn.com
```

### 3. 启动和测试

1. **启动 Space**：
   - 代码上传后会自动开始构建
   - 等待构建完成（通常需要 2-5 分钟）
   - 构建成功后会自动启动

2. **测试访问**：
   ```bash
   # 测试基础连接
   curl https://your-space.hf.space/

   # 测试健康检查
   curl https://your-space.hf.space/health

   # 测试 API 端点
   curl -X POST "https://your-space.hf.space/v1/chat/completions" \
     -H "Authorization: Bearer your-api-key" \
     -H "Content-Type: application/json" \
     -d '{"model": "gemini-2.5-flash-image-landscape", "messages": [{"role": "user", "content": "test"}], "stream": false}'
   ```

3. **访问管理界面**：
   - 打开：`https://your-space.hf.space`
   - 使用配置的管理员凭据登录
   - 添加你的 Google VideoFX API 密钥

## 🔧 配置管理

### 通过环境变量修改配置

```bash
# 示例：启用缓存
FLOW2API_CACHE_ENABLED=true
FLOW2API_CACHE_TIMEOUT=7200

# 示例：调整超时设置
FLOW2API_IMAGE_TIMEOUT=450
FLOW2API_VIDEO_TIMEOUT=1200

# 示例：启用调试模式
FLOW2API_DEBUG_ENABLED=true
```

### 通过管理界面修改配置

1. 登录管理界面
2. 进入 **Configuration** 页面
3. 修改设置
4. 点击 **Save Changes**

## 📊 监控和日志

### 查看日志

在 HuggingFace Spaces 界面：
1. 进入你的 Space
2. 点击 **Files and versions**
3. 点击 **Logs** 标签
4. 查看实时日志

### 健康检查

```bash
# 定期检查服务状态
curl -f https://your-space.hf.space/ || echo "Service down"

# 检查响应时间
time curl https://your-space.hf.space/
```

## 🛠️ 故障排除

### 常见问题

1. **构建失败**
   ```bash
   # 检查 Dockerfile 语法
   docker build -t test .

   # 查看 HuggingFace Spaces 构建日志
   ```

2. **服务无法启动**
   ```bash
   # 检查环境变量配置
   echo $FLOW2API_HOST
   echo $FLOW2API_PORT

   # 查看容器启动日志
   docker logs container-id
   ```

3. **API 调用失败**
   ```bash
   # 检查 API 密钥配置
   curl -H "Authorization: Bearer your-key" https://your-space.hf.space/v1/models

   # 检查管理界面中的 API 密钥设置
   ```

4. **权限错误**
   ```bash
   # 确认文件权限设置
   ls -la /app/data
   ls -la /app/config
   ```

### 性能优化

1. **调整超时设置**：
   ```bash
   FLOW2API_POLL_INTERVAL=5.0
   FLOW2API_MAX_POLL_ATTEMPTS=300
   ```

2. **启用缓存**：
   ```bash
   FLOW2API_CACHE_ENABLED=true
   FLOW2API_CACHE_TIMEOUT=3600
   ```

3. **调整并发设置**：
   在管理界面的 **Performance** 部分调整并发限制

## 🔒 安全最佳实践

1. **立即更改默认密码**：
   - 管理员用户名和密码
   - API 密钥

2. **使用 Private Space**（如果包含敏感信息）

3. **定期更新**：
   - 监控基础镜像更新
   - 定期检查安全漏洞

4. **监控使用情况**：
   - 检查 API 调用日志
   - 监控资源使用情况

## 📈 扩展部署

### 多区域部署

```bash
# 为不同地区创建多个 Space
# 美国：https://us-flow2api.hf.space
# 欧洲：https://eu-flow2api.hf.space
# 亚洲：https://asia-flow2api.hf.space
```

### 负载均衡

使用 HuggingFace Spaces 的内置负载均衡：
1. 创建多个相同的 Space
2. 使用 CDN 或负载均衡器分发请求
3. 监控各个 Space 的健康状态

### 自定义域名

```bash
# 在 Space 设置中添加自定义域名
FLOW2API_HOST=your-custom-domain.com
```

## 📞 支持

如果遇到问题：

1. **查看官方文档**：[HuggingFace Spaces Docs](https://huggingface.co/docs/hub/spaces)
2. **检查项目 Issues**：[GitHub Issues](https://github.com/thesmallhancat/gdtiti_flow2api/issues)
3. **社区支持**：[GitHub Discussions](https://github.com/thesmallhancat/gdtiti_flow2api/discussions)

## 🔄 更新和维护

### 更新到最新版本

```bash
# 更新基础镜像引用（如果有新版本）
FROM ghcr.io/gdtiti/flow2api:latest

# 重新部署
git add Dockerfile
git commit -m "Update to latest Flow2API version"
git push
```

### 备份配置

```bash
# 导出当前配置
curl https://your-space.hf.space/api/config > config-backup.json

# 定期备份重要的配置文件
```

---

**部署成功后，你的 Flow2API 服务将在 HuggingFace Spaces 上运行，提供强大的图像和视频生成能力！** 🎉