EIEI/wechat_wc

Fork 0

Files

T

lhmin0604 4d086758e8 first commit

2026-07-27 14:54:21 +08:00

14 KiB

Raw Blame History

智绘微刻后端技术栈建议方案

本文档面向「智绘微刻」小程序团队，提供从 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 版）：

-- 用户表（微信授权）
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（初期）

# 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 设计速查（供前端联调用）

认证

POST /api/v1/auth/wechat
Body: { code: "wx_auth_code" }
Response: { access_token: "jwt", refresh_token: "jwt", user: {...} }

商品

GET /api/v1/products
Response: [ { id, name, desc, price, leadTime, images[], mask } ]

设计清单

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）

词云

POST /api/v1/wordcloud/jobs
Body: { baseImageKey, names: [] }
Response: { jobId, status: "queued" }

GET /api/v1/wordcloud/jobs/{jobId}
Response: { status, resultUrl, progress }

订单

GET  /api/v1/orders
POST /api/v1/orders                  # 创建预支付订单
POST /api/v1/orders/{id}/pay         # 调起微信支付（返回 prepay_id）
POST /api/v1/orders/wechat_notify    # 微信支付回调（服务端内部）

上传

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 服务器即可承载。

14 KiB Raw Blame History Unescape Escape