Upload 13 files

.dockerignore

@@ -0,0 +1,103 @@
+# HuggingFace Spaces .dockerignore
+# Exclude files not needed in the final container image
+
+# Git
+.git
+.gitignore
+.gitattributes
+
+# Documentation (keep README.md)
+*.md
+!README.md
+
+# Environment files (keep .env)
+.env.*
+!.env
+
+# Python cache and build files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs and temporary files
+*.log
+logs/
+tmp/
+temp/
+*.tmp
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Test files and coverage
+tests/
+test_*.py
+*_test.py
+.coverage
+.pytest_cache/
+coverage/
+
+# Development tools
+pytest.ini
+tox.ini
+.mypy_cache/
+
+# CI/CD files
+.github/
+.gitlab-ci.yml
+.travis.yml
+
+# Local configuration overrides
+.env.local
+.env.development
+.env.test
+
+# Backup files
+*.bak
+*.backup
+
+# Docker specific (Dockerfile will be included)
+docker-compose*.yml
+docker-compose.override.yml

.env

@@ -0,0 +1,45 @@
+# HuggingFace Spaces Environment Configuration
+# These variables will be available in the running container
+
+# Core API Configuration
+FLOW2API_API_KEY=your-api-key-here
+FLOW2API_ADMIN_USERNAME=admin
+FLOW2API_ADMIN_PASSWORD=change-this-password
+
+# Server Configuration (for HuggingFace Spaces)
+FLOW2API_HOST=0.0.0.0
+FLOW2API_PORT=7860
+
+# Debug Configuration (Important for HuggingFace Spaces)
+FLOW2API_DEBUG_ENABLED=false
+FLOW2API_DEBUG_LOG_REQUESTS=false
+FLOW2API_DEBUG_LOG_RESPONSES=false
+FLOW2API_DEBUG_MASK_TOKEN=true
+
+# Note: Set debug logging to false to avoid log file permission issues
+# in HuggingFace Spaces environment
+
+# Flow API Configuration
+FLOW2API_LABS_BASE_URL=https://labs.google/fx/api
+FLOW2API_API_BASE_URL=https://aisandbox-pa.googleapis.com/v1
+FLOW2API_TIMEOUT=120
+FLOW2API_MAX_RETRIES=3
+FLOW2API_POLL_INTERVAL=3.0
+FLOW2API_MAX_POLL_ATTEMPTS=200
+
+# Generation Configuration
+FLOW2API_IMAGE_TIMEOUT=300
+FLOW2API_VIDEO_TIMEOUT=1500
+
+# Cache Configuration
+FLOW2API_CACHE_ENABLED=false
+FLOW2API_CACHE_TIMEOUT=7200
+FLOW2API_CACHE_BASE_URL=
+
+# Proxy Configuration (if needed)
+FLOW2API_PROXY_ENABLED=false
+FLOW2API_PROXY_URL=
+
+# HuggingFace Spaces Specific
+GRADIO_SERVER_NAME=0.0.0.0
+GRADIO_SERVER_PORT=7860

.gitattributes

@@ -1,35 +1,35 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

DEPLOYMENT_GUIDE.md

@@ -0,0 +1,296 @@
+# 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 上运行，提供强大的图像和视频生成能力！** 🎉

DOCKERFILE_FIX.md

@@ -0,0 +1,137 @@
+# Dockerfile 修复说明
+
+## 🐛 问题描述
+
+在 HuggingFace Spaces 构建过程中遇到错误：
+
+```
+ERROR: failed to calculate checksum of ref y3ta9lvs57rkhtkwy85l33nw8::p4k2tqiytyjk27fh7j54w4smm: "/||": not found
+```
+
+这个错误是由于在 `COPY` 指令中使用了不支持的语法造成的。
+
+## 🔧 修复过程
+
+### 第一次尝试的问题
+```dockerfile
+COPY --chown=app:app config/setting.toml /app/config/setting.toml || true  # ❌
+```
+
+问题：`COPY` 指令不支持 `|| true` 语法。
+
+### 第二次尝试的问题
+```dockerfile
+RUN ls config/setting.toml 2>/dev/null && cp config/setting.toml /app/config/setting.toml || echo "No local config file"  # ❌
+```
+
+问题：基础镜像已经包含了完整的目录结构和权限设置，不需要重复创建。
+
+### 最终解决方案
+
+**简化 Dockerfile**，只包含 HuggingFace Spaces 特定的配置：
+
+```dockerfile
+# Use the pre-built Flow2API image from GitHub Container Registry
+FROM ghcr.io/gdtiti/flow2api:latest
+
+# Set HuggingFace Spaces specific environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV FLOW2API_HOST=0.0.0.0
+ENV FLOW2API_PORT=7860
+
+# Expose the HuggingFace Spaces default port
+EXPOSE 7860
+
+# Health check for HuggingFace Spaces
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+    CMD python -c "import socket; s=socket.socket(); s.connect(('localhost', 7860)); s.close()" || exit 1
+```
+
+## ✅ 修复原因
+
+### 1. **基础镜像完整性**
+`ghcr.io/gdtiti/flow2api:latest` 镜像已经包含：
+- ✅ 完整的目录结构 (`/app/data`, `/app/config` 等)
+- ✅ 正确的文件权限
+- ✅ 默认配置文件
+- ✅ 应用程序代码
+- ✅ 依赖包
+
+### 2. **HuggingFace Spaces 适配需求**
+只需要配置 HuggingFace Spaces 特定的设置：
+- 🌐 端口从 8000 改为 7860
+- 🏥 健康检查端口更新
+- 📦 环境变量设置
+
+### 3. **减少构建复杂性**
+- 🔧 移除不必要的文件操作
+- ⚡ 加快构建速度
+- 🛡️ 降低出错风险
+
+## 📋 当前 Dockerfile 说明
+
+```dockerfile
+FROM ghcr.io/gdtiti/flow2api:latest
+```
+使用预构建镜像，包含完整的 Flow2API 应用。
+
+```dockerfile
+ENV FLOW2API_HOST=0.0.0.0
+ENV FLOW2API_PORT=7860
+```
+设置 HuggingFace Spaces 所需的环境变量。
+
+```dockerfile
+EXPOSE 7860
+```
+暴露 HuggingFace Spaces 的默认端口。
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+    CMD python -c "import socket; s=socket.socket(); s.connect(('localhost', 7860)); s.close()" || exit 1
+```
+配置健康检查，使用正确的端口号 7860。
+
+## 🚀 部署验证
+
+修复后的 Dockerfile 应该能够：
+1. ✅ 成功构建
+2. ✅ 正确启动服务
+3. ✅ 响应健康检查
+4. ✅ 提供完整的 API 功能
+
+## 📝 重要说明
+
+### 配置管理
+- 应用配置通过环境变量设置
+- 默认配置文件在基础镜像中已包含
+- 可以通过 HuggingFace Spaces 的环境变量覆盖默认设置
+
+### 端口配置
+- 原始端口：8000
+- HuggingFace Spaces 端口：7860
+- 环境变量 `FLOW2API_PORT=7860` 自动处理端口变更
+
+### 文件权限
+- 基础镜像已正确设置所有文件权限
+- 不需要额外处理权限问题
+
+## 🔍 故障排除
+
+如果仍然遇到问题，请检查：
+
+1. **基础镜像可用性**
+   ```bash
+   docker pull ghcr.io/gdtiti/flow2api:latest
+   ```
+
+2. **环境变量配置**
+   - 确保在 HuggingFace Spaces 设置中正确配置环境变量
+   - 特别是 `FLOW2API_API_KEY` 等关键配置
+
+3. **日志查看**
+   - 查看 HuggingFace Spaces 的构建日志
+   - 检查应用启动日志
+
+这个修复确保了 Docker 构建的成功和服务的正常运行。

Dockerfile

@@ -0,0 +1,34 @@
+# Simplified Dockerfile for troubleshooting
+FROM ghcr.io/gdtiti/flow2api:latest
+
+# Fix all permissions first
+USER root
+RUN cd /app && \
+    mkdir -p data logs config && \
+    touch logs.txt && \
+    chmod -R 777 /app && \
+    echo "All permissions set to 777 for debugging"
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV FLOW2API_HOST=0.0.0.0
+ENV FLOW2API_PORT=7860
+ENV FLOW2API_DEBUG_ENABLED=false
+
+# Switch to root user for maximum compatibility
+USER root
+
+# Expose port
+EXPOSE 7860
+
+# Health check with long startup time
+HEALTHCHECK --interval=30s --timeout=10s --start-period=180s --retries=3 \
+    CMD python -c "import socket; s=socket.socket(); s.connect(('localhost', 7860)); s.close()" || exit 1
+
+# Start with debugging script if main app fails
+COPY start_simple.py /app/start_simple.py
+RUN chmod +x /app/start_simple.py
+
+# Try main app first, fallback to simple version
+CMD ["/bin/bash", "-c", "python main.py || python start_simple.py"]

Dockerfile.old

@@ -0,0 +1,56 @@
+# Use the pre-built Flow2API image from GitHub Container Registry
+FROM ghcr.io/gdtiti/flow2api:latest
+
+# Switch to root to fix permissions and setup
+USER root
+
+# Fix file permissions for HuggingFace Spaces
+RUN cd /app && \
+    # Create and fix log file permissions
+    touch logs.txt && \
+    chmod 666 logs.txt && \
+    # Ensure data directory exists with proper permissions
+    mkdir -p data && \
+    chmod 755 data && \
+    # Try to set proper ownership
+    chown -R app:app /app 2>/dev/null || \
+    # If app user doesn't exist, make critical files world writable
+    (chmod 777 logs.txt data && echo "Made files world writable as fallback") && \
+    echo "File permissions fixed"
+
+# Add startup script for debugging
+RUN echo '#!/bin/bash\n\
+echo "=== Startup Debug Info ==="\n\
+echo "User: $(whoami)"\n\
+echo "Current dir: $(pwd)"\n\
+echo "Listing /app:"\n\
+ls -la /app/\n\
+echo "Checking logs.txt permissions:"\n\
+ls -la /app/logs.txt\n\
+echo "=== End Debug Info ==="\n\
+exec python main.py' > /app/start_debug.sh && \
+    chmod +x /app/start_debug.sh
+
+# Set HuggingFace Spaces specific environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV FLOW2API_HOST=0.0.0.0
+ENV FLOW2API_PORT=7860
+
+# Add debug environment variables
+ENV FLOW2API_DEBUG_ENABLED=true
+ENV FLOW2API_DEBUG_LOG_REQUESTS=false
+ENV FLOW2API_DEBUG_LOG_RESPONSES=false
+
+# Switch back to app user if it exists
+USER app 2>/dev/null || USER root
+
+# Expose the HuggingFace Spaces default port
+EXPOSE 7860
+
+# Health check for HuggingFace Spaces with longer startup time
+HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
+    CMD python -c "import socket; s=socket.socket(); s.connect(('localhost', 7860)); s.close()" || exit 1
+
+# Use debug startup script
+CMD ["/app/start_debug.sh"]

PERMISSION_FIX.md

@@ -0,0 +1,189 @@
+# 日志权限问题修复说明
+
+## 🐛 问题描述
+
+在 HuggingFace Spaces 部署时遇到权限错误：
+
+```
+PermissionError: [Errno 13] Permission denied: '/app/logs.txt'
+```
+
+**错误原因**：
+- Flow2API 应用尝试创建 `/app/logs.txt` 文件
+- 容器中的 `app` 用户没有 `/app` 目录的写权限
+- HuggingFace Spaces 的环境与标准 Docker 环境在用户权限方面有所不同
+
+## 🔧 修复方案
+
+### 方案 1：修复文件权限（已实施）
+
+**修改后的 Dockerfile**：
+```dockerfile
+# Switch to root to create log file with proper permissions
+USER root
+
+# Create logs.txt file with proper permissions for HuggingFace Spaces
+RUN cd /app && \
+    touch logs.txt && \
+    chmod 666 logs.txt && \
+    # Try to set proper ownership
+    chown app:app logs.txt 2>/dev/null || \
+    # If app user doesn't exist, make it world writable
+    chmod 777 logs.txt
+
+# Switch back to app user if it exists
+USER app 2>/dev/null || USER root
+```
+
+### 方案 2：通过环境变量禁用日志文件
+
+**在 HuggingFace Spaces 设置中配置**：
+```bash
+FLOW2API_DEBUG_ENABLED=false
+FLOW2API_DEBUG_LOG_REQUESTS=false
+FLOW2API_DEBUG_LOG_RESPONSES=false
+```
+
+这样可以避免创建日志文件，所有日志输出到 stdout。
+
+## 📋 修复详解
+
+### 权限修复逻辑
+
+1. **切换到 root 用户**：获取足够的权限来创建和修改文件
+2. **创建日志文件**：`touch logs.txt` 创建空的日志文件
+3. **设置权限**：
+   - `chmod 666 logs.txt` - 设置文件为读写权限
+   - 尝试 `chown app:app logs.txt` 设置所有��
+   - 如果失败，使用 `chmod 777 logs.txt` 使文件全局可写
+4. **切换回应用用户**：恢复到安全的用户身份运行应用
+
+### 环境变量配置
+
+```bash
+# 禁用调试日志（推荐用于生产环境）
+FLOW2API_DEBUG_ENABLED=false
+FLOW2API_DEBUG_LOG_REQUESTS=false
+FLOW2API_DEBUG_LOG_RESPONSES=false
+
+# 如果需要调试，可以临时启用
+FLOW2API_DEBUG_ENABLED=true
+```
+
+## 🚀 部署步骤
+
+### 1. 更新 Dockerfile
+修复后的 Dockerfile 已包含权限修复逻辑。
+
+### 2. 配置环境变量
+在 HuggingFace Space 设置中添加：
+```bash
+FLOW2API_DEBUG_ENABLED=false
+FLOW2API_DEBUG_LOG_REQUESTS=false
+FLOW2API_DEBUG_LOG_RESPONSES=false
+FLOW2API_ADMIN_PASSWORD=your-secure-password
+```
+
+### 3. 重新部署
+推送修复后的 Dockerfile 并等待构建完成。
+
+## ✅ 验证修复
+
+### 检查应用启动状态
+```bash
+# 检查应用是否正常启动
+curl -f https://your-space.hf.space/ || echo "Service not responding"
+
+# 检查健康状态
+curl -f https://your-space.hf.space/health || echo "Health check failed"
+```
+
+### 查看容器日志
+在 HuggingFace Spaces 控制台查看应用启动日志，应该看到：
+```
+===== Application Startup at YYYY-MM-DD HH:MM:SS =====
+Uvicorn running on http://0.0.0.0:7860
+```
+
+### 测试 API 功能
+```bash
+# 测试基础连接
+curl https://your-space.hf.space/v1/models
+
+# 测试 API 调用（需要有效 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}'
+```
+
+## 🔍 故障排除
+
+### 如果仍然遇到权限错误
+
+1. **检查日志文件**：
+   ```bash
+   # 在容器中检查文件权限
+   ls -la /app/logs.txt
+   ```
+
+2. **手动创建日志文件**（如果需要）：
+   ```bash
+   # 通过 HuggingFace Spaces 终端执行（如果可用）
+   touch /app/logs.txt
+   chmod 777 /app/logs.txt
+   ```
+
+3. **完全禁用日志文件**：
+   设置环境变量：
+   ```bash
+   FLOW2API_DEBUG_ENABLED=false
+   FLOW2API_DEBUG_LOG_REQUESTS=false
+   FLOW2API_DEBUG_LOG_RESPONSES=false
+   ```
+
+### HuggingFace Spaces 特殊性
+
+HuggingFace Spaces 有以下特殊考虑：
+
+1. **用户权限**：可能没有预定义的 `app` 用户
+2. **文件系统**：可能有特殊的挂载和权限限制
+3. **日志输出**：推荐将日志输出到 stdout 而不是文件
+4. **持久化**：文件可能不会持久化存储
+
+## 📝 最佳实践建议
+
+1. **生产环境**：
+   - 禁用调试日志：`FLOW2API_DEBUG_ENABLED=false`
+   - 监控 HuggingFace Spaces 的标准日志输出
+
+2. **开发/调试**：
+   - 临时启用调试：`FLOW2API_DEBUG_ENABLED=true`
+   - 使用 HuggingFace Spaces 的实时日志查看功能
+
+3. **性能优化**：
+   - 禁用不必要的日志记录
+   - 调整 API 调用频率和并发限制
+
+## 🔄 替代方案
+
+如果权限问题持续存在，可以考虑：
+
+### 方案 A：完全基于 stdout 的日志
+修改 logger.py 将所有日志输出到 stdout 而不是文件。
+
+### 方案 B：使用 /tmp 目录
+��日志文件写入 `/tmp` 目录，该目录通常有更宽松的权限。
+
+### 方案 C：使用环境变量控制
+通过环境变量控制日志行为，避免文件系统依赖。
+
+## 📚 相关资源
+
+- [HuggingFace Spaces 文档](https://huggingface.co/docs/hub/spaces)
+- [Docker 权限最佳实践](https://docs.docker.com/engine/security/userns-remap/)
+- [Python logging 模块](https://docs.python.org/3/library/logging.html)
+
+---
+
+这个修复确保了 Flow2API 在 HuggingFace Spaces 环境中的正常运行，同时保持了应用的完整功能。

README.md

@@ -1,10 +1,9 @@
----
-title: Zzz
-emoji: 📈
-colorFrom: indigo
-colorTo: pink
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: zzz - Flow2
+emoji: 🎨
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: mit
+---

STARTUP_TROUBLESHOOTING.md

@@ -0,0 +1,202 @@
+# 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 服务。

config/setting.toml

@@ -0,0 +1,38 @@
+# Flow2API Configuration for HuggingFace Spaces
+# This is the default configuration, can be overridden by environment variables
+
+[global]
+api_key = "your-api-key-here"
+admin_username = "admin"
+admin_password = "change-this-password"
+
+[flow]
+labs_base_url = "https://labs.google/fx/api"
+api_base_url = "https://aisandbox-pa.googleapis.com/v1"
+timeout = 120
+max_retries = 3
+poll_interval = 3.0
+max_poll_attempts = 200
+
+[server]
+host = "0.0.0.0"
+port = 7860
+
+[debug]
+enabled = false
+log_requests = true
+log_responses = true
+mask_token = true
+
+[proxy]
+proxy_enabled = false
+proxy_url = ""
+
+[generation]
+image_timeout = 300
+video_timeout = 1500
+
+[cache]
+enabled = false
+timeout = 7200
+base_url = ""

requirements.txt

@@ -0,0 +1,16 @@
+# HuggingFace Spaces requirements
+# This file is primarily for documentation since we're using a pre-built Docker image
+# but it helps with local development and potential customizations
+
+fastapi==0.119.0
+uvicorn[standard]==0.32.1
+aiosqlite==0.20.0
+pydantic==2.10.4
+curl-cffi==0.7.3
+tomli==2.2.1
+bcrypt==4.2.1
+python-multipart==0.0.20
+python-dateutil==2.8.2
+
+# HuggingFace Spaces specific
+gradio==4.44.0

start_simple.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Simple startup script for debugging Flow2API on HuggingFace Spaces"""
+
+import os
+import sys
+import time
+import asyncio
+from pathlib import Path
+
+def debug_environment():
+    """Print environment debug information"""
+    print("=" * 60)
+    print("🔍 FLOW2API DEBUG STARTUP")
+    print("=" * 60)
+    print(f"Python version: {sys.version}")
+    print(f"Current working directory: {os.getcwd()}")
+    print(f"User ID: {os.getuid()}")
+    print(f"Group ID: {os.getgid()}")
+    print(f"Environment variables:")
+    for key, value in sorted(os.environ.items()):
+        if key.startswith('FLOW2API') or key in ['HOST', 'PORT', 'HOME', 'PATH']:
+            print(f"  {key}: {value}")
+    print("=" * 60)
+
+def check_file_permissions():
+    """Check critical file permissions"""
+    files_to_check = [
+        '/app',
+        '/app/logs.txt',
+        '/app/data',
+        '/app/config'
+    ]
+
+    print("📁 FILE PERMISSIONS CHECK:")
+    for file_path in files_to_check:
+        path = Path(file_path)
+        if path.exists():
+            stat_info = path.stat()
+            print(f"  ✅ {file_path}: exists, mode={oct(stat_info.st_mode)}")
+            if path.is_file():
+                try:
+                    # Test write permission
+                    with open(path, 'a') as f:
+                        f.write("")
+                    print(f"  ✅ {file_path}: writable")
+                except Exception as e:
+                    print(f"  ❌ {file_path}: NOT writable - {e}")
+        else:
+            print(f"  ❌ {file_path}: does not exist")
+    print("=" * 60)
+
+async def test_basic_import():
+    """Test if basic modules can be imported"""
+    print("📦 IMPORT TEST:")
+    try:
+        import fastapi
+        print(f"  ✅ FastAPI: {fastapi.__version__}")
+    except Exception as e:
+        print(f"  ❌ FastAPI import failed: {e}")
+
+    try:
+        import uvicorn
+        print(f"  ✅ Uvicorn: available")
+    except Exception as e:
+        print(f"  ❌ Uvicorn import failed: {e}")
+
+    try:
+        import aiosqlite
+        print(f"  ✅ aiosqlite: available")
+    except Exception as e:
+        print(f"  ❌ aiosqlite import failed: {e}")
+
+    print("=" * 60)
+
+async def test_database_connection():
+    """Test database creation and connection"""
+    print("💾 DATABASE TEST:")
+    try:
+        import aiosqlite
+
+        # Test database directory creation
+        data_dir = Path("/app/data")
+        data_dir.mkdir(exist_ok=True)
+        print(f"  ✅ Data directory: {data_dir}")
+
+        # Test database connection
+        db_path = "/app/data/test.db"
+        async with aiosqlite.connect(db_path) as db:
+            await db.execute("SELECT 1")
+            print(f"  ✅ Database connection: successful")
+
+        # Clean up test file
+        os.remove(db_path)
+        print(f"  ✅ Test database: cleaned up")
+
+    except Exception as e:
+        print(f"  ❌ Database test failed: {e}")
+        import traceback
+        traceback.print_exc()
+
+    print("=" * 60)
+
+def start_simple_server():
+    """Start a simple test server"""
+    print("🌐 SIMPLE SERVER TEST:")
+    try:
+        from fastapi import FastAPI
+        import uvicorn
+
+        app = FastAPI()
+
+        @app.get("/")
+        async def root():
+            return {"message": "Flow2API is running", "status": "ok"}
+
+        @app.get("/health")
+        async def health():
+            return {"status": "healthy"}
+
+        print("  ✅ Simple FastAPI app created")
+        print("  🚀 Starting simple server on port 7860...")
+
+        # Start server
+        uvicorn.run(
+            app,
+            host="0.0.0.0",
+            port=7860,
+            log_level="info"
+        )
+
+    except Exception as e:
+        print(f"  ❌ Simple server failed: {e}")
+        import traceback
+        traceback.print_exc()
+
+async def main():
+    """Main debugging function"""
+    debug_environment()
+    check_file_permissions()
+    await test_basic_import()
+    await test_database_connection()
+
+    print("🎯 STARTING FLOW2API:")
+    try:
+        # Import and start the main application
+        from src.main import app
+        print("  ✅ Main app imported successfully")
+
+        # Start with uvicorn directly
+        import uvicorn
+        print("  🚀 Starting main application...")
+
+        uvicorn.run(
+            app,
+            host="0.0.0.0",
+            port=7860,
+            log_level="info",
+            access_log=True
+        )
+
+    except Exception as e:
+        print(f"  ❌ Main app startup failed: {e}")
+        import traceback
+        traceback.print_exc()
+        print("🔄 FALLING BACK TO SIMPLE SERVER...")
+        start_simple_server()
+
+if __name__ == "__main__":
+    print("Starting Flow2API with debug mode...")
+    asyncio.run(main())