Flow2API HuggingFace Spaces 部署指南
📋 部署清单
在部署到 HuggingFace Spaces 之前，请确认以下项目：
✅ 必需配置
- Google VideoFX API 密钥
- 自定义管理员用户名和密码
- 代理配置（如需要）
- 超时和重试设置
✅ 文件结构
确认以下文件已正确配置：
zzz/
├── Dockerfile # ✅ 已创建
├── requirements.txt # ✅ 已创建
├── .env # ✅ 已创建
├── README.md # ✅ 已优化
├── config/
│ └── setting.toml # ✅ 已创建
└── DEPLOYMENT_GUIDE.md # ✅ 本文件
🚀 部署步骤
1. 准备 HuggingFace Space
创建新 Space：
- 访问 huggingface.co/spaces
- 点击 "Create new Space"
- 选择 Docker 作为 SDK
- 设置 Space 名称（例如：flow2api-video）
- 选择 Public 或 Private（Private 需要订阅）
上传代码：
# 方法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 设置中配置以下环境变量：
🔑 核心配置（必须设置）
FLOW2API_API_KEY=your-google-videofx-api-key
FLOW2API_ADMIN_USERNAME=your-admin-username
FLOW2API_ADMIN_PASSWORD=your-secure-password-change-this
⚙️ 服务器配置
FLOW2API_HOST=0.0.0.0
FLOW2API_PORT=7860
🐛 调试配置（可选）
FLOW2API_DEBUG_ENABLED=false
FLOW2API_DEBUG_LOG_REQUESTS=true
FLOW2API_DEBUG_LOG_RESPONSES=true
FLOW2API_DEBUG_MASK_TOKEN=true
⏱️ 性能配置（可选）
FLOW2API_IMAGE_TIMEOUT=600
FLOW2API_VIDEO_TIMEOUT=1800
FLOW2API_TIMEOUT=180
FLOW2API_MAX_RETRIES=5
🌐 代理配置（如果需要）
FLOW2API_PROXY_ENABLED=true
FLOW2API_PROXY_URL=http://your-proxy.com:8080
💾 缓存配置（可选）
FLOW2API_CACHE_ENABLED=true
FLOW2API_CACHE_TIMEOUT=14400
FLOW2API_CACHE_BASE_URL=https://your-cdn.com
3. 启动和测试
启动 Space：
- 代码上传后会自动开始构建
- 等待构建完成（通常需要 2-5 分钟）
- 构建成功后会自动启动
测试访问：
# 测试基础连接 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}'访问管理界面：
- 打开：
https://your-space.hf.space - 使用配置的管理员凭据登录
- 添加你的 Google VideoFX API 密钥
- 打开：
🔧 配置管理
通过环境变量修改配置
# 示例：启用缓存
FLOW2API_CACHE_ENABLED=true
FLOW2API_CACHE_TIMEOUT=7200
# 示例：调整超时设置
FLOW2API_IMAGE_TIMEOUT=450
FLOW2API_VIDEO_TIMEOUT=1200
# 示例：启用调试模式
FLOW2API_DEBUG_ENABLED=true
通过管理界面修改配置
- 登录管理界面
- 进入 Configuration 页面
- 修改设置
- 点击 Save Changes
📊 监控和日志
查看日志
在 HuggingFace Spaces 界面：
- 进入你的 Space
- 点击 Files and versions
- 点击 Logs 标签
- 查看实时日志
健康检查
# 定期检查服务状态
curl -f https://your-space.hf.space/ || echo "Service down"
# 检查响应时间
time curl https://your-space.hf.space/
🛠️ 故障排除
常见问题
构建失败
# 检查 Dockerfile 语法 docker build -t test . # 查看 HuggingFace Spaces 构建日志服务无法启动
# 检查环境变量配置 echo $FLOW2API_HOST echo $FLOW2API_PORT # 查看容器启动日志 docker logs container-idAPI 调用失败
# 检查 API 密钥配置 curl -H "Authorization: Bearer your-key" https://your-space.hf.space/v1/models # 检查管理界面中的 API 密钥设置权限错误
# 确认文件权限设置 ls -la /app/data ls -la /app/config
性能优化
调整超时设置：
FLOW2API_POLL_INTERVAL=5.0 FLOW2API_MAX_POLL_ATTEMPTS=300启用缓存：
FLOW2API_CACHE_ENABLED=true FLOW2API_CACHE_TIMEOUT=3600调整并发设置： 在管理界面的 Performance 部分调整并发限制
🔒 安全最佳实践
立即更改默认密码：
- 管理员用户名和密码
- API 密钥
使用 Private Space（如果包含敏感信息）
定期更新：
- 监控基础镜像更新
- 定期检查安全漏洞
监控使用情况：
- 检查 API 调用日志
- 监控资源使用情况
📈 扩展部署
多区域部署
# 为不同地区创建多个 Space
# 美国：https://us-flow2api.hf.space
# 欧洲：https://eu-flow2api.hf.space
# 亚洲：https://asia-flow2api.hf.space
负载均衡
使用 HuggingFace Spaces 的内置负载均衡：
- 创建多个相同的 Space
- 使用 CDN 或负载均衡器分发请求
- 监控各个 Space 的健康状态
自定义域名
# 在 Space 设置中添加自定义域名
FLOW2API_HOST=your-custom-domain.com
📞 支持
如果遇到问题：
- 查看官方文档：HuggingFace Spaces Docs
- 检查项目 Issues：GitHub Issues
- 社区支持：GitHub Discussions
🔄 更新和维护
更新到最新版本
# 更新基础镜像引用（如果有新版本）
FROM ghcr.io/gdtiti/flow2api:latest
# 重新部署
git add Dockerfile
git commit -m "Update to latest Flow2API version"
git push
备份配置
# 导出当前配置
curl https://your-space.hf.space/api/config > config-backup.json
# 定期备份重要的配置文件
部署成功后，你的 Flow2API 服务将在 HuggingFace Spaces 上运行，提供强大的图像和视频生成能力！ 🎉