IOPaint/docs/API_SERVICE_GUIDE.md

IOPaint 去水印 API 服务设计方案

📋 目录

1. MVP 最小可行产品
2. 商业化架构设计
3. 部署方案对比
4. 成本与扩展性分析

---

🚀 MVP 最小可行产品

设计原则（KISS）

• 单一功能：只提供去水印API，不包含WebUI
• 单一模型：只使用LaMa模型（快速、低资源）
• 简单认证：API Key认证
• 本地存储：无需对象存储
• 单机部署：Docker Compose即可

核心改造

1. 精简API服务 (api_service.py)

# 只保留核心功能：
# - POST /api/v1/remove-watermark - 去水印接口
# - GET /api/v1/health - 健康检查
# - GET /api/v1/usage - 使用统计（可选）

# 移除功能：
# - WebUI相关路由
# - 多模型支持
# - 插件系统
# - 文件浏览器
# - Socket.IO实时通信

2. API接口设计

去水印接口

POST /api/v1/remove-watermark
Headers:
  X-API-Key: your_api_key_here
  Content-Type: multipart/form-data

Body:
  image: file (必需) - 原始图片
  mask: file (可选) - 水印遮罩，不提供则自动检测

Response:
  - 200: 返回处理后的图片（image/png）
  - 401: API Key无效
  - 400: 参数错误
  - 500: 处理失败

健康检查

GET /api/v1/health
Response: {"status": "ok", "model": "lama"}

3. MVP部署架构

┌─────────────────────────────────────┐
│          Nginx (反向代理)            │
│   - SSL终止                          │
│   - 限流 (rate limiting)             │
│   - 日志记录                         │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│      IOPaint API Service            │
│   - FastAPI                          │
│   - LaMa模型                         │
│   - API Key认证                      │
│   - 本地存储                         │
└─────────────────────────────────────┘

4. MVP Docker配置

单容器方案：适合月处理量 < 10万张

# docker-compose.mvp.yml
version: '3.8'
services:
  api:
    build:
      context: .
      dockerfile: docker/APIDockerfile
    ports:
      - "8080:8080"
    environment:
      - API_KEY=your_secret_key_here
      - MAX_IMAGE_SIZE=4096
      - ENABLE_METRICS=true
    volumes:
      - ./models:/root/.cache
      - ./logs:/app/logs
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G

成本估算（MVP阶段）：

• 云服务器：2核4G，约￥200-300/月（阿里云、腾讯云）
• 存储：100GB SSD，约￥50/月
• 流量：100GB/月，约￥50/月
• 总计：约￥300-400/月

性能预估：

• 处理速度：约1-2秒/张（1024x1024）
• 并发能力：2-4个请求
• 月处理量：~5-10万张

---

🏢 商业化架构设计

设计原则

• 横向扩展：支持动态增减实例
• 高可用：无单点故障
• 异步处理：支持批量和队列
• 监控完善：实时监控和告警
• 成本优化：按需扩展

商业化架构图

                   ┌─────────────────┐
                   │   CDN / CloudFlare  │
                   └────────┬────────┘
                            │
                   ┌────────▼────────┐
                   │  Load Balancer   │  (Nginx/HAProxy/ALB)
                   │  - SSL终止       │
                   │  - 限流          │
                   │  - WAF           │
                   └────────┬────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
   ┌────▼────┐        ┌────▼────┐        ┌────▼────┐
   │API Pod 1│        │API Pod 2│        │API Pod N│
   │ (GPU)   │        │ (GPU)   │        │ (GPU)   │
   └────┬────┘        └────┬────┘        └────┬────┘
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
   ┌────▼────┐        ┌────▼────┐        ┌────▼────┐
   │  Redis  │        │PostgreSQL│        │   S3    │
   │ (队列)  │        │ (元数据) │        │ (存储)  │
   └─────────┘        └──────────┘        └─────────┘
        │
   ┌────▼────┐
   │ Celery  │
   │ Worker  │
   └─────────┘
        │
   ┌────▼────┐
   │Prometheus│
   │ Grafana │
   └─────────┘

核心组件

1. API层（Kubernetes部署）

api-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: iopaint-api
spec:
  replicas: 3  # 根据负载自动扩展
  template:
    spec:
      containers:
      - name: api
        image: let5sne/iopaint-api:latest
        resources:
          requests:
            memory: "4Gi"
            cpu: "2"
            nvidia.com/gpu: 1
          limits:
            memory: "8Gi"
            cpu: "4"
            nvidia.com/gpu: 1
        env:
        - name: REDIS_URL
          value: "redis://redis:6379"
        - name: S3_BUCKET
          value: "iopaint-images"

2. 异步任务队列（Redis + Celery）

好处：

• 避免API超时
• 支持批量处理
• 可重试失败任务
• 平滑处理流量峰值

工作流程：

1. 用户上传图片 → API返回任务ID
2. 图片存入S3 → 任务推入Redis队列
3. Celery Worker异步处理
4. 处理完成 → 更新数据库 → 触发回调/Webhook

3. 数据库设计（PostgreSQL）

-- 用户表
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    api_key VARCHAR(64) UNIQUE NOT NULL,
    plan VARCHAR(20) NOT NULL,  -- free, basic, pro, enterprise
    quota_monthly INT NOT NULL,
    quota_used INT DEFAULT 0,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 任务表
CREATE TABLE tasks (
    id UUID PRIMARY KEY,
    user_id INT REFERENCES users(id),
    status VARCHAR(20) NOT NULL,  -- pending, processing, completed, failed
    image_url TEXT NOT NULL,
    result_url TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    completed_at TIMESTAMP,
    processing_time_ms INT
);

-- 使用统计表（按日汇总）
CREATE TABLE usage_stats (
    date DATE NOT NULL,
    user_id INT REFERENCES users(id),
    requests_count INT DEFAULT 0,
    success_count INT DEFAULT 0,
    avg_processing_time_ms INT,
    PRIMARY KEY (date, user_id)
);

4. 监控与告警

Prometheus指标：

# 核心业务指标
requests_total = Counter('api_requests_total', 'Total API requests', ['status', 'endpoint'])
processing_time = Histogram('image_processing_seconds', 'Image processing time')
model_inference_time = Histogram('model_inference_seconds', 'Model inference time')
queue_size = Gauge('redis_queue_size', 'Current queue size')
gpu_utilization = Gauge('gpu_utilization', 'GPU utilization %')

告警规则：

• API错误率 > 5%
• 队列积压 > 1000
• GPU利用率 > 90%（持续5分钟）
• 响应时间 > 10秒（P95）

5. 成本优化策略

弹性伸缩：

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: iopaint-api-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: iopaint-api
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: nvidia.com/gpu
      target:
        type: Utilization
        averageUtilization: 80

Spot实例：

• 使用云厂商Spot/抢占式实例，成本降低60-80%
• 配合优先级队列，重要任务用按需实例

---

🔄 部署方案对比

方案	适用场景	优点	缺点	月成本估算
Docker单机	个人/小团队 月< 10万张	• 部署简单 • 成本低 • 维护容易	• 无法扩展 • 单点故障 • 性能有限	￥300-500
Docker Compose多容器	小型商业 月10-50万张	• 支持多实例 • 负载均衡 • 成本可控	• 手动扩展 • 监控有限 • 高可用差	￥1000-3000
Kubernetes	中大型商业 月50万张+	• 自动扩展 • 高可用 • 完善监控 • 多云部署	• 复杂度高 • 学习成本 • 初期成本高	￥5000-20000+
Serverless (Lambda/云函数)	不规则流量 峰谷明显	• 按用付费 • 无需运维 • 无限扩展	• 冷启动慢 • GPU支持差 • 单次限制	按用量计费

---

💰 成本与扩展性分析

MVP阶段（月处理10万张）

方案：单机Docker

硬件：
  - 云服务器 2核4G（CPU版本）：￥200/月
  或
  - GPU服务器 4核16G + T4（GPU版本）：￥800/月

存储：
  - 系统盘 100GB SSD：￥50/月
  - 模型缓存：~5GB（LaMa）

带宽：
  - 假设平均每张图500KB，10万张 = 50GB
  - 上传 + 下载 = 100GB，约￥60/月

总计：
  - CPU版本：约￥310/月
  - GPU版本：约￥910/月（推荐，处理速度快10倍）

商业化阶段（月处理100万张）

方案：Kubernetes + GPU节点池

计算资源（3个GPU节点，自动扩展）：
  - 3 x (4核16G + T4 GPU)：￥2400/月
  - 高峰期额外2个节点（Spot实例）：￥400/月

数据库：
  - PostgreSQL云数据库（2核4G）：￥300/月
  - Redis云实例（2G）：￥150/月

存储：
  - 对象存储 500GB：￥100/月
  - 数据库存储 100GB：￥50/月

CDN + 流量：
  - CDN加速：￥200/月
  - 带宽流量（1TB）：￥600/月

监控 + 日志：
  - 日志服务：￥100/月
  - 监控告警：￥100/月

负载均衡：￥100/月

总计：约￥4500-5000/月

收益模型（参考）：

定价方案：
  - Free: 10张/天，免费
  - Basic: ￥99/月，3000张
  - Pro: ￥399/月，20000张
  - Enterprise: ￥1999/月，150000张，优先处理

假设用户分布：
  - Free用户：1000人 = 0元（引流）
  - Basic用户：200人 = ￥19,800
  - Pro用户：50人 = ￥19,950
  - Enterprise：10人 = ￥19,990

月收入：约￥59,740
月成本：约￥5,000
月利润：约￥54,740

---

📝 推荐实施路线

阶段1：MVP验证（1-2个月）

目标：验证市场需求，获取前100个付费用户

技术栈：

• Docker单机部署
• FastAPI + LaMa模型
• 简单API Key认证
• SQLite本地数据库

投入：

• 开发时间：1周
• 服务器成本：￥300-500/月
• 域名+SSL：￥100/年

里程碑：

• API服务上线
• 文档和示例代码
• 支付集成（微信/支付宝）
• 获取前10个付费用户
• 收集用户反馈

阶段2：产品优化（2-4个月）

目标：优化体验，扩展到1000付费用户

技术栈：

• Docker Compose多容器
• PostgreSQL数据库
• Redis缓存
• 简单监控（Prometheus）

投入：

• 开发时间：2周
• 服务器成本：￥1000-2000/月

里程碑：

• 批量处理API
• Webhook回调
• 使用Dashboard
• 自动检测水印（可选）
• API SDK（Python/Node.js）

阶段3：规模化（4-6个月）

目标：支持月百万级处理，稳定盈利

技术栈：

• Kubernetes集群
• 对象存储
• 完整监控体系
• 多模型支持（可选）

投入：

• 开发时间：4周
• 基础设施成本：￥5000-10000/月

里程碑：

• 自动扩展
• 多区域部署
• SLA保证（99.9%）
• 企业级支持

---

🎯 关键建议

1. MVP阶段重点

✅ 做：

• 专注核心功能（去水印）
• 简单可靠的API
• 完善的文档和示例
• 快速迭代

❌ 不做：

• 复杂的功能（多模型、插件）
• 过度设计的架构
• 过早优化性能
• WebUI界面

2. Docker vs Kubernetes

用Docker如果：

• 月处理量 < 50万张
• 团队 < 3人
• 预算有限
• 流量相对稳定

用Kubernetes如果：

• 月处理量 > 50万张
• 需要高可用（99.9%+）
• 流量波动大
• 计划多区域部署

3. 技术债务控制

从一开始就做好：

• API版本控制（/api/v1/）
• 完善的错误处理和日志
• API限流和认证
• 数据备份策略

可以后续优化：

• 监控系统（先简单后完善）
• 自动扩展（先手动后自动）
• 多模型支持（先单模型验证）
• 高级功能（批量、回调等）

4. 安全建议

必须：

• HTTPS强制
• API Key认证
• 请求限流
• 输入验证（文件大小、格式）
• 敏感信息加密

推荐：

• WAF防护
• DDoS防护
• 审计日志
• 定期安全扫描

---

📚 参考资源

• FastAPI最佳实践
• Kubernetes生产实践
• AWS架构最佳实践
• API设计指南