Medusa 开源电商后端搭建教程

Medusa 是一个基于 Node.js 的开源电商后端框架，被视为 Shopify 的开源替代方案。它提供了模块化的电商核心功能（商品、订单、支付、物流等），通过 REST API 和管理后台与前端解耦。Medusa 的插件系统允许你自由扩展功能，非常适合需要深度定制的电商项目。本文将在搬瓦工 VPS 上搭建完整的 Medusa 电商后端。

一、系统要求

Node.js：20.x LTS 或更高。
PostgreSQL：14 或更高。
Redis：用于事件队列和缓存。
内存：至少 1GB，推荐 2GB 以上。

二、环境准备

2.1 安装 Node.js

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install nodejs -y
node -v
npm -v

2.2 安装 PostgreSQL

apt install postgresql postgresql-contrib -y
systemctl enable postgresql
systemctl start postgresql

# 创建数据库和用户
sudo -u postgres psql
CREATE USER medusa_user WITH PASSWORD '你的强密码';
CREATE DATABASE medusa_db OWNER medusa_user;
GRANT ALL PRIVILEGES ON DATABASE medusa_db TO medusa_user;
\q

2.3 安装 Redis

apt install redis-server -y
systemctl enable redis-server
systemctl start redis-server

三、安装 Medusa

3.1 使用 Medusa CLI 创建项目

npx create-medusa-app@latest my-store
cd my-store

CLI 会引导你选择数据库类型（选择 PostgreSQL）和是否安装管理面板。

3.2 手动安装（更灵活）

mkdir medusa-store && cd medusa-store
npm init -y
npm install @medusajs/medusa @medusajs/medusa-cli

创建 medusa-config.js 配置文件：

const { defineConfig } = require('@medusajs/medusa');

module.exports = defineConfig({
  projectConfig: {
    databaseUrl: 'postgres://medusa_user:你的强密码@localhost:5432/medusa_db',
    redisUrl: 'redis://localhost:6379',
    jwtSecret: '你的JWT密钥',
    cookieSecret: '你的Cookie密钥',
    store_cors: 'https://store.example.com',
    admin_cors: 'https://admin.example.com',
  },
  plugins: [],
});

3.3 初始化数据库

# 运行数据库迁移
npx medusa migrations run

# 创建管理员账号
npx medusa user --email admin@example.com --password 你的管理员密码

# 填充示例数据（可选）
npx medusa seed --seed-file=data/seed.json

四、安装管理后台

Medusa 提供了独立的管理后台（Admin Dashboard）：

# 在项目目录中安装管理后台插件
npm install @medusajs/admin

在 medusa-config.js 的 plugins 中添加：

plugins: [
  {
    resolve: '@medusajs/admin',
    options: {
      serve: true,
      autoRebuild: true,
      path: '/app',
    },
  },
],

五、配置支付和物流

5.1 安装 Stripe 支付插件

npm install medusa-payment-stripe

在配置文件中添加：

{
  resolve: 'medusa-payment-stripe',
  options: {
    api_key: process.env.STRIPE_API_KEY,
    webhook_secret: process.env.STRIPE_WEBHOOK_SECRET,
  },
},

5.2 配置物流

# 安装手动物流插件
npm install medusa-fulfillment-manual

六、生产部署

6.1 使用 PM2 管理进程

npm install -g pm2

# 构建项目
npm run build

# 使用 PM2 启动
pm2 start npm --name "medusa" -- run start
pm2 save
pm2 startup

6.2 Nginx 反向代理

server {
    listen 80;
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

nginx -t && systemctl reload nginx

6.3 环境变量配置

# 创建 .env 文件
DATABASE_URL=postgres://medusa_user:密码@localhost:5432/medusa_db
REDIS_URL=redis://localhost:6379
JWT_SECRET=你的随机JWT密钥
COOKIE_SECRET=你的随机Cookie密钥
STRIPE_API_KEY=sk_live_你的密钥
STRIPE_WEBHOOK_SECRET=whsec_你的密钥
NODE_ENV=production

七、前端对接

Medusa 的 Store API 提供完整的电商功能接口：

# 获取商品列表
curl http://localhost:9000/store/products

# 创建购物车
curl -X POST http://localhost:9000/store/carts

# 向购物车添加商品
curl -X POST http://localhost:9000/store/carts/{cart_id}/line-items \
  -H "Content-Type: application/json" \
  -d '{"variant_id": "variant_xxx", "quantity": 1}'

Medusa 官方提供了 Next.js Starter 模板，可以快速搭建前端：

npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-storefront
cd my-storefront
# 配置 .env.local 中的 NEXT_PUBLIC_MEDUSA_BACKEND_URL
npm run dev

总结

Medusa 是构建定制化电商平台的优秀选择，模块化架构和丰富的插件系统让你可以根据业务需求自由组合功能。在搬瓦工 VPS 上部署 Medusa，2GB 内存即可流畅运行完整的电商后端。如果你需要 GraphQL 优先的电商方案，可以参考 Saleor 电商平台。选购搬瓦工 VPS 请查看全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，通过 bwh81.net 进入官网购买。