365 lines
14 KiB
Markdown
365 lines
14 KiB
Markdown
# 智绘微刻后端技术栈建议方案
|
||
|
||
> 本文档面向「智绘微刻」小程序团队，提供从 0 到 1 搭建后端服务的完整技术选型建议。
|
||
> 撰写日期：2026-07-27
|
||
> 适用场景：初期 MVP 上线（日活 < 1万），兼顾未来扩展。
|
||
|
||
---
|
||
|
||
## 一、总体架构概览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 微信小程序端 │
|
||
│ Taro 3.6 + React + Local Storage（当前无后端缓存阶段） │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│ HTTPS / JSON
|
||
┌──────────────────────────▼──────────────────────────────────┐
|
||
│ Nginx（反向代理 + 静态文件） │
|
||
│ ┌─────────────┬─────────────┐ │
|
||
│ │ SSL 证书 │ 负载均衡 │ │
|
||
│ └─────────────┴─────────────┘ │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│
|
||
┌──────────────────────────▼──────────────────────────────────┐
|
||
│ FastAPI (Python 3.11+) │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ 用户/订单 │ │ 词云生成 │ │ 设计清单 │ │
|
||
│ │ REST API │ │ 异步任务 │ │ REST API │ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│ │ │
|
||
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
||
│ PostgreSQL │ │ Redis │ │ MinIO │
|
||
│ (主数据库) │ │ 缓存/队列 │ │ 对象存储 │
|
||
└─────────────┘ └─────────────┘ └─────────────┘
|
||
│
|
||
┌──────▼──────┐
|
||
│ Celery │
|
||
│ 异步任务队列 │
|
||
│ (词云渲染) │
|
||
└─────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、技术选型与理由
|
||
|
||
### 1. API 框架：FastAPI (Python)
|
||
|
||
| 维度 | 选型 | 理由 |
|
||
|------|------|------|
|
||
| 框架 | **FastAPI** | 自动生成 OpenAPI/Swagger 文档；异步原生支持（`async/await`）；类型提示驱动开发，与前端 TS 思维一致 |
|
||
| 替代方案 | Django / Flask / Go-Gin | Django 太重、Flask 需手写异步、Go 学习成本高；团队若熟悉 Python，FastAPI 是最佳平衡点 |
|
||
| Python 版本 | **3.11+** | 性能优化显著（CPython 3.11 比 3.10 快 10~25%），且支持 `TaskGroup` 等现代并发原语 |
|
||
|
||
**核心职责**：
|
||
- 用户登录（微信 OAuth2 → JWT Token）
|
||
- 商品/品类/价格/工期配置读取
|
||
- 设计清单 CRUD
|
||
- 订单创建/支付回调/状态流转
|
||
- 词云生成任务投递（异步）
|
||
- 文件上传预签名 URL（MinIO）
|
||
|
||
---
|
||
|
||
### 2. 数据库：PostgreSQL 15+
|
||
|
||
| 维度 | 选型 | 理由 |
|
||
|------|------|------|
|
||
| 主数据库 | **PostgreSQL 15+** | 开源、稳定、JSONB 支持灵活存储设计稿元数据；PostGIS 扩展未来可做配送区域 |
|
||
| ORM | **SQLAlchemy 2.0** + Alembic | 成熟、类型安全、迁移脚本自动化 |
|
||
| 连接池 | asyncpg | FastAPI 原生异步兼容 |
|
||
|
||
**核心表结构设计（MVP 版）**：
|
||
|
||
```sql
|
||
-- 用户表（微信授权）
|
||
CREATE TABLE users (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
openid TEXT UNIQUE NOT NULL,
|
||
unionid TEXT,
|
||
nickname TEXT,
|
||
avatar_url TEXT,
|
||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||
);
|
||
|
||
-- 商品品类表（与前端 productConfig 同步）
|
||
CREATE TABLE products (
|
||
id TEXT PRIMARY KEY, -- notebook-small, coaster, penbox ...
|
||
name TEXT NOT NULL,
|
||
desc TEXT,
|
||
price INT NOT NULL, -- 单位：分，避免浮点
|
||
lead_time TEXT,
|
||
description TEXT,
|
||
images TEXT[], -- 图片 URL 数组
|
||
mask JSONB NOT NULL, -- {shape, width, height, borderRadius}
|
||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||
);
|
||
|
||
-- 设计清单表
|
||
CREATE TABLE designs (
|
||
id TEXT PRIMARY KEY, -- DSG + 时间戳
|
||
user_id UUID REFERENCES users(id),
|
||
product_id TEXT REFERENCES products(id),
|
||
count INT NOT NULL DEFAULT 1,
|
||
status TEXT NOT NULL CHECK (status IN ('undesigned','designing','ordered')),
|
||
design_data JSONB, -- {imageSrc, imagePos, category}
|
||
order_id TEXT,
|
||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||
);
|
||
|
||
-- 订单表
|
||
CREATE TABLE orders (
|
||
id TEXT PRIMARY KEY, -- ORD + 时间戳
|
||
user_id UUID REFERENCES users(id),
|
||
design_id TEXT REFERENCES designs(id),
|
||
product_id TEXT REFERENCES products(id),
|
||
product_name TEXT NOT NULL,
|
||
count INT NOT NULL,
|
||
unit_price INT NOT NULL, -- 单位：分
|
||
total_price INT NOT NULL,
|
||
status TEXT NOT NULL CHECK (status IN ('pending','paid','shipping','done','cancelled')),
|
||
sku TEXT,
|
||
paid_at TIMESTAMPTZ,
|
||
shipped_at TIMESTAMPTZ,
|
||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||
);
|
||
|
||
-- 词云生成任务表（追踪异步任务状态）
|
||
CREATE TABLE wordcloud_jobs (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
user_id UUID REFERENCES users(id),
|
||
base_image_key TEXT NOT NULL, -- MinIO 对象 key
|
||
names TEXT[] NOT NULL,
|
||
status TEXT NOT NULL CHECK (status IN ('queued','processing','completed','failed')),
|
||
result_key TEXT,
|
||
error_msg TEXT,
|
||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||
completed_at TIMESTAMPTZ
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 缓存与消息队列：Redis 7+
|
||
|
||
| 用途 | 说明 |
|
||
|------|------|
|
||
| **JWT 黑名单 / Session 缓存** | 用户登出时令牌失效 |
|
||
| **_rate limiting_** | 防止词云接口被刷（每用户 5 次/分钟） |
|
||
| **Celery Broker** | Redis List 作为 Celery 任务队列 |
|
||
| **热点数据缓存** | 商品配置表、首页轮播数据（TTL 10 分钟） |
|
||
|
||
---
|
||
|
||
### 4. 异步任务：Celery + Redis
|
||
|
||
| 场景 | 处理方式 |
|
||
|------|----------|
|
||
| **词云图片生成** | 用户上传底图 → 投递 Celery Task → C++ 布局引擎 / Python 词云库生成 → 结果上传 MinIO → WebSocket/轮询通知前端 |
|
||
| **订单支付回调处理** | 微信 notify_url → FastAPI 接收 → Celery Task 异步更新订单状态、发送通知 |
|
||
| **批量邮件/短信** | 发货通知、营销短信异步发送 |
|
||
|
||
**为什么不用 RabbitMQ？**
|
||
Redis 作为 Broker 在初期足够（架构简单、少维护一个组件）。当每日任务量 > 10万 时，再迁移到 RabbitMQ 或 AWS SQS。
|
||
|
||
---
|
||
|
||
### 5. 对象存储：MinIO
|
||
|
||
| 用途 | 说明 |
|
||
|------|------|
|
||
| **用户上传底图** | 微信小程序 → 直传 MinIO（预签名 URL）→ 返回 key 给后端 |
|
||
| **词云生成结果图** | Celery Worker 生成后上传 → 前端通过 CDN 域名访问 |
|
||
| **商品实物照片** | 运营后台上传 → 前端展示 |
|
||
|
||
**为什么不存数据库？**
|
||
图片二进制存数据库会导致表体积膨胀、备份慢、查询性能下降。MinIO（S3 兼容）是对象存储的最优解。
|
||
|
||
**云服务器部署建议**：
|
||
- 若使用阿里云：可无缝切换到 **阿里云 OSS**（代码只需改 endpoint + access key）。
|
||
- 若自建服务器：MinIO 单机版 Docker 运行，占用 < 200MB 内存。
|
||
|
||
---
|
||
|
||
### 6. 部署与运维：Docker Compose（初期）
|
||
|
||
```yaml
|
||
# docker-compose.yml 示例（MVP 单服务器）
|
||
version: "3.8"
|
||
|
||
services:
|
||
api:
|
||
build: ./backend
|
||
ports:
|
||
- "8000:8000"
|
||
environment:
|
||
- DATABASE_URL=postgresql+asyncpg://user:pass@db:5432/smart_engraving
|
||
- REDIS_URL=redis://redis:6379/0
|
||
- MINIO_ENDPOINT=minio:9000
|
||
depends_on:
|
||
- db
|
||
- redis
|
||
- minio
|
||
|
||
celery_worker:
|
||
build: ./backend
|
||
command: celery -A tasks worker --loglevel=info --concurrency=2
|
||
environment:
|
||
- DATABASE_URL=postgresql+asyncpg://user:pass@db:5432/smart_engraving
|
||
- REDIS_URL=redis://redis:6379/0
|
||
depends_on:
|
||
- db
|
||
- redis
|
||
- minio
|
||
|
||
db:
|
||
image: postgres:15-alpine
|
||
volumes:
|
||
- pgdata:/var/lib/postgresql/data
|
||
environment:
|
||
POSTGRES_DB: smart_engraving
|
||
POSTGRES_USER: user
|
||
POSTGRES_PASSWORD: pass
|
||
|
||
redis:
|
||
image: redis:7-alpine
|
||
volumes:
|
||
- redisdata:/data
|
||
|
||
minio:
|
||
image: minio/minio:latest
|
||
command: server /data --console-address ":9001"
|
||
ports:
|
||
- "9000:9000"
|
||
- "9001:9001"
|
||
volumes:
|
||
- miniodata:/data
|
||
environment:
|
||
MINIO_ROOT_USER: minioadmin
|
||
MINIO_ROOT_PASSWORD: minioadmin
|
||
|
||
volumes:
|
||
pgdata:
|
||
redisdata:
|
||
miniodata:
|
||
```
|
||
|
||
---
|
||
|
||
## 三、API 设计速查（供前端联调用）
|
||
|
||
### 认证
|
||
```http
|
||
POST /api/v1/auth/wechat
|
||
Body: { code: "wx_auth_code" }
|
||
Response: { access_token: "jwt", refresh_token: "jwt", user: {...} }
|
||
```
|
||
|
||
### 商品
|
||
```http
|
||
GET /api/v1/products
|
||
Response: [ { id, name, desc, price, leadTime, images[], mask } ]
|
||
```
|
||
|
||
### 设计清单
|
||
```http
|
||
GET /api/v1/designs # 列表
|
||
POST /api/v1/designs # 新建（加入清单）
|
||
PATCH /api/v1/designs/{id} # 更新（保存设计稿）
|
||
DELETE /api/v1/designs/{id} # 删除
|
||
POST /api/v1/designs/{id}/order # 确认下单（design → order）
|
||
```
|
||
|
||
### 词云
|
||
```http
|
||
POST /api/v1/wordcloud/jobs
|
||
Body: { baseImageKey, names: [] }
|
||
Response: { jobId, status: "queued" }
|
||
|
||
GET /api/v1/wordcloud/jobs/{jobId}
|
||
Response: { status, resultUrl, progress }
|
||
```
|
||
|
||
### 订单
|
||
```http
|
||
GET /api/v1/orders
|
||
POST /api/v1/orders # 创建预支付订单
|
||
POST /api/v1/orders/{id}/pay # 调起微信支付（返回 prepay_id）
|
||
POST /api/v1/orders/wechat_notify # 微信支付回调（服务端内部）
|
||
```
|
||
|
||
### 上传
|
||
```http
|
||
GET /api/v1/upload/presign?filename=xxx.jpg&contentType=image/jpeg
|
||
Response: { url, key, expires }
|
||
# 前端使用 `url` 直传 MinIO / OSS
|
||
```
|
||
|
||
---
|
||
|
||
## 四、费用预估（阿里云 / 腾讯云，MVP 阶段）
|
||
|
||
| 资源 | 配置 | 月费用（人民币） |
|
||
|------|------|-----------------|
|
||
| 云服务器 ECS | 2核4G，共享型 | ~¥60-100 |
|
||
| 云数据库 RDS PostgreSQL | 1核1G，基础版 | ~¥35-60 |
|
||
| 云数据库 Redis | 256MB 主从 | ~¥20-40 |
|
||
| 对象存储 OSS | 50GB 标准存储 | ~¥5-10 |
|
||
| CDN 流量 | 100GB/月 | ~¥15-25 |
|
||
| 域名 + SSL 证书 | 通配符一年 | ~¥200-400/年 |
|
||
| **合计** | | **~¥150-260/月** |
|
||
|
||
> 若用户量极小（< 1000 日活），可将 PostgreSQL 和 Redis 都部署在同一台 ECS 上，初期费用可压到 **¥60-80/月**。
|
||
|
||
---
|
||
|
||
## 五、开发排期建议（后端 MVP，2 人团队）
|
||
|
||
| 阶段 | 周期 | 内容 |
|
||
|------|------|------|
|
||
| **Week 1** | 环境搭建 | Docker Compose 本地跑通；FastAPI 项目脚手架；PostgreSQL + Redis 联调 |
|
||
| **Week 2** | 核心 API | 微信登录 JWT / 商品列表 / 设计清单 CRUD / 订单创建 |
|
||
| **Week 3** | 词云 & 支付 | 词云异步任务接入（Celery）；微信支付预支付+回调；MinIO 预签名上传 |
|
||
| **Week 4** | 联调 & 部署 | 小程序前端联调；阿里云 ECS 生产部署；监控告警（日志 + 告警） |
|
||
|
||
---
|
||
|
||
## 六、风险与预案
|
||
|
||
| 风险 | 影响 | 预案 |
|
||
|------|------|------|
|
||
| 微信登录 code 换取 session_key 失败 | 用户无法登录 | 后端增加 Mock 登录接口（开发环境）|
|
||
| 词云生成耗时长（>30s） | 用户体验差 | 前端轮询 + 后端加进度反馈；高并发时排队提示 |
|
||
| 支付回调网络抖动 | 订单状态不一致 | 支付回调幂等设计（按微信 `out_trade_no` 去重）|
|
||
| 图片存储流量激增 | CDN 费用上升 | 启用 OSS 图片压缩 + WebP 转换 |
|
||
|
||
---
|
||
|
||
## 七、推荐的开箱即用工具链
|
||
|
||
| 工具 | 用途 |
|
||
|------|------|
|
||
| **uv** | Python 包管理与虚拟环境（比 pip + venv 快 10 倍）|
|
||
| **Pydantic v2** | 数据校验与序列化（FastAPI 内置）|
|
||
| **sqlalchemy[asyncio]** | 异步 ORM |
|
||
| **celery[redis]** | 异步任务队列 |
|
||
| **boto3** | MinIO / OSS S3 兼容客户端 |
|
||
| **loguru** | 结构化日志 |
|
||
| **sentry-sdk** | 线上异常追踪（免费额度够用）|
|
||
|
||
---
|
||
|
||
## 八、总结
|
||
|
||
> **推荐技术栈：FastAPI + PostgreSQL + Redis + MinIO + Celery，Docker Compose 单服务器部署。**
|
||
|
||
- **FastAPI**：异步高性能、自动生成文档、团队上手快。
|
||
- **PostgreSQL**：JSONB 灵活存储设计稿元数据，未来扩展无需换库。
|
||
- **Redis**：一物三用（缓存 + 队列 + 限流）。
|
||
- **MinIO**：自托管 S3 兼容对象存储，未来可一键切阿里云 OSS。
|
||
- **Celery**：词云生成、支付回调、通知推送全部异步化，前端响应 < 100ms。
|
||
|
||
该方案在 **日活 1 万以内** 完全不需要 Kubernetes 或微服务拆分，单台 2 核 4G 服务器即可承载。
|