✨ 添加去水印API服务 - MVP版本
新增功能： - 精简的API服务实现（api_service_mvp.py） - 专注单一功能：去水印 - 使用LaMa模型 - API Key认证 - 完整的错误处理和日志 - 完整的部署方案 - Docker配置（APIDockerfile） - Docker Compose配置（docker-compose.mvp.yml） - Nginx反向代理配置 - 详尽的文档 - API_SERVICE_GUIDE.md - MVP到商业化完整方案 - API_SERVICE_README.md - 快速开始指南 - API_CLIENT_EXAMPLES.md - 多语言客户端示例（Python/JS/cURL/PHP/Java/Go） 架构特点： - 遵循MVP和KISS原则 - 提供从单机到Kubernetes的扩展路径 - 包含成本分析��收益模型 - 完整的监控和告警方案 🎯 适用场景： - 个人/小团队快速验证产品（月成本￥300-500） - 中小型商业化部署（月成本￥1000-3000） - 大规模生产环境（月成本￥5000+） 🔧 Generated with Claude Code
This commit is contained in:
let5sne
526
API_SERVICE_GUIDE.md
Normal file
526
API_SERVICE_GUIDE.md
Normal file
@@ -0,0 +1,526 @@
|
||||
# IOPaint 去水印 API 服务设计方案
|
||||
|
||||
## 📋 目录
|
||||
1. [MVP 最小可行产品](#mvp-最小可行产品)
|
||||
2. [商业化架构设计](#商业化架构设计)
|
||||
3. [部署方案对比](#部署方案对比)
|
||||
4. [成本与扩展性分析](#成本与扩展性分析)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 MVP 最小可行产品
|
||||
|
||||
### 设计原则（KISS）
|
||||
- **单一功能**：只提供去水印API，不包含WebUI
|
||||
- **单一模型**：只使用LaMa模型（快速、低资源）
|
||||
- **简单认证**：API Key认证
|
||||
- **本地存储**：无需对象存储
|
||||
- **单机部署**：Docker Compose即可
|
||||
|
||||
### 核心改造
|
||||
|
||||
#### 1. 精简API服务 (`api_service.py`)
|
||||
```python
|
||||
# 只保留核心功能：
|
||||
# - POST /api/v1/remove-watermark - 去水印接口
|
||||
# - GET /api/v1/health - 健康检查
|
||||
# - GET /api/v1/usage - 使用统计（可选）
|
||||
|
||||
# 移除功能：
|
||||
# - WebUI相关路由
|
||||
# - 多模型支持
|
||||
# - 插件系统
|
||||
# - 文件浏览器
|
||||
# - Socket.IO实时通信
|
||||
```
|
||||
|
||||
#### 2. API接口设计
|
||||
|
||||
**去水印接口**
|
||||
```bash
|
||||
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: 处理失败
|
||||
```
|
||||
|
||||
**健康检查**
|
||||
```bash
|
||||
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万张
|
||||
```yaml
|
||||
# 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**
|
||||
```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）
|
||||
|
||||
```sql
|
||||
-- 用户表
|
||||
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指标**：
|
||||
```python
|
||||
# 核心业务指标
|
||||
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. 成本优化策略
|
||||
|
||||
**弹性伸缩**：
|
||||
```yaml
|
||||
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单机** | 个人/小团队<br>月< 10万张 | • 部署简单<br>• 成本低<br>• 维护容易 | • 无法扩展<br>• 单点故障<br>• 性能有限 | ￥300-500 |
|
||||
| **Docker Compose多容器** | 小型商业<br>月10-50万张 | • 支持多实例<br>• 负载均衡<br>• 成本可控 | • 手动扩展<br>• 监控有限<br>• 高可用差 | ￥1000-3000 |
|
||||
| **Kubernetes** | 中大型商业<br>月50万张+ | • 自动扩展<br>• 高可用<br>• 完善监控<br>• 多云部署 | • 复杂度高<br>• 学习成本<br>• 初期成本高 | ￥5000-20000+ |
|
||||
| **Serverless (Lambda/云函数)** | 不规则流量<br>峰谷明显 | • 按用付费<br>• 无需运维<br>• 无限扩展 | • 冷启动慢<br>• GPU支持差<br>• 单次限制 | 按用量计费 |
|
||||
|
||||
---
|
||||
|
||||
## 💰 成本与扩展性分析
|
||||
|
||||
### 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最佳实践](https://fastapi.tiangolo.com/tutorial/)
|
||||
- [Kubernetes生产实践](https://kubernetes.io/docs/setup/production-environment/)
|
||||
- [AWS架构最佳实践](https://aws.amazon.com/architecture/well-architected/)
|
||||
- [API设计指南](https://github.com/microsoft/api-guidelines)
|
||||
Reference in New Issue
Block a user