一、系统架构介绍
Medusa 采用模块化微服务式 Headless 架构，整体分为四大核心部分，结构清晰、扩展性极强：
1.1 电商核心模块（Commerce Modules）
系统基础电商能力载体，所有模块独立解耦、按需启用、可自定义替换，包含商品、库存、订单、购物车、客户、支付、促销、税务、售后退换货等全套电商核心功能，无需重复开发基础业务逻辑。
1.2 Medusa 核心框架
系统底层支撑引擎，提供自定义 API 路由、业务工作流（Workflow）、自定义数据模型、事件订阅等能力，支持开发者深度定制业务逻辑，适配个性化电商需求。
1.3 内置管理后台（Admin）
基于 React 开发的可视化后台面板，开箱即用，支持商品、订单、客户、营销、系统配置全流程管理，同时支持自定义后台组件，可拓展专属管理功能。注：该后台为商家管理端，非用户购物前台。
1.4 独立商城前台（Storefront）
前端商城完全独立，通过 REST/GraphQL 接口调用 Medusa 后端数据，官方提供 Next.js 开源商城模板，开发者可自由替换为任意前端框架，适配多终端展示需求。
1.5 系统运行依赖
• 运行环境：Node.js ≥ 20
• 数据库：PostgreSQL（强制必填，不支持其他数据库）
• 缓存/队列：Redis（开发环境可选，生产环境强制必填）
• 包管理器：npm / pnpm / yarn
核心架构优势：一套后端中台，支撑多终端、多渠道、多场景电商业务，彻底摆脱传统商城前后端绑定的限制。
二、系统核心功能详情
2.1 商品与库存管理
• 支持单品、多规格变体、捆绑商品、套装商品多种商品形态
• 商品分类、标签、合集管理，支持批量编辑、上下架、媒体资源上传
• 多仓库管理、精准库存统计、库存预留、库存预警机制
• 支持自定义商品字段，适配特殊行业商品属性需求
2.2 订单与履约售后
• 完整购物车、下单、支付、订单状态流转全流程
• 多配送方式支持：快递配送、门店自提、多仓库分仓发货
• 完善售后体系：退货、换货、索赔工单、售后进度追踪
• 支持订单手动创建、状态修改、批量管理
2.3 客户与区域管理
• 个人客户、B2B企业客户管理，支持客户分组、专属价目表配置
• 多区域、多币种、多国税率自动适配，支持跨境电商业务
• 多销售渠道管控，可单独设置不同渠道的上架商品、销售规则
2.4 营销与支付体系
• 丰富营销工具：优惠券、阶梯折扣、限时促销、礼品卡、账户余额
• 支持周期性订阅商品，适配会员续费、周期购业务
• 原生支持 Stripe、Paypal 等海外支付网关，支持自定义对接第三方支付
2.5 开发与系统能力
• 全套标准化 API 接口，支持 API 密钥权限管控
• 自定义业务工作流，可实现订单触发自定义业务逻辑
• 事件订阅、Webhook 对接，可联动 ERP、物流、CRM 系统
• 多管理员账号、精细化权限管理，适配团队运营场景
三、系统优缺点分析
3.1 核心优点
• 开源免费无限制：MIT 开源协议，无商用版权费用、无订单交易抽成，仅需承担服务器与开发成本
• 极致可定制性：模块化架构，无插件绑定、无系统锁死，可深度改写业务逻辑，适配复杂 B2B/B2C 场景
• 多终端适配：无头架构设计，一套后端可对接网站、小程序、APP、POS 等所有前端终端
• 性能优异：微服务模块化设计，相比传统单体商城，高并发、高订单量场景下稳定性更强
• 技术现代化：基于 TS 开发，代码规范、官方文档完善、社区活跃，持续迭代更新
• 原生能力齐全：自带多仓库、跨境计税、售后工单、企业客户等高级功能，无需大量二次开发
3.2 现存缺点
• 存在技术门槛：非零代码系统，需要基础开发能力，无法像可视化建站工具直接一键搭建商城
• 国内生态薄弱：原生不支持微信支付、支付宝、国内物流接口，需要自主开发对接
• 部署维护成本高：生产环境需维护服务器、PostgreSQL、Redis，需要定期备份与安全维护
• 前台需自主完善：官方前台仅为 Demo 模板，无法直接商用，需二次开发优化
• 上手学习曲线陡：对比简易商城系统，新手需要花费时间熟悉架构与配置规则
3.3 适用人群与场景
✅ 适合：有开发团队、需要定制化电商、做多渠道新零售、规避 SaaS 平台限制的企业/开发者
❌ 不适合：无任何技术基础、想要零代码一键开店的个人小微卖家
四、系统基础使用教程（后台操作）
Medusa 部署完成后，默认后台访问地址：http://你的域名:9000/app
默认初始账号：admin@medusa-test.com ｜ 密码：supersecret
4.1 基础初始化配置
首次登录需优先完成基础配置：进入 Settings → Regions，新增销售区域、设置默认币种、配置各国税率、开启发货权限，为后续商品上架、订单结算提供基础。
4.2 核心功能操作
• 商品管理（Products）：新建/编辑商品、添加规格变体、上传素材、绑定仓库库存、设置上下架状态；通过 Collections 管理商品合集与分类。
• 库存管理（Inventory）：创建多仓库、分配商品库存、查看库存预留记录、监控库存预警。
• 订单管理（Orders）：查看全部订单、修改订单状态、处理发货、审核售后申请、手动创建订单。
• 客户管理（Customers）：查看客户信息、分组管理、维护企业客户资料、配置专属价格。
• 营销管理（Promotions）：创建优惠券、设置折扣规则、发放礼品卡、配置促销活动。
• 开发配置（API Keys）：创建公开/私密 API 密钥，用于前端商城对接后端数据。
4.3 前台商城访问
官方 Next.js 前台默认地址：http://localhost:8000，可实现商品浏览、搜索、加购、下单、支付全套用户购物流程。
五、保姆级本地部署教程（开发环境）
5.1 部署前置要求
• 安装 Node.js 20 及以上版本
• 安装 Git 工具
• 本地部署 PostgreSQL 数据库
• Redis 可选（开发环境可省略）
5.2 安装官方 CLI 工具
| bash npm install -g create-medusa-app |
5.3 一键初始化项目
| bash create-medusa-app my-medusa-store --seed |
参数说明：my-medusa-store 为项目文件夹名；--seed 自动导入测试商品、订单演示数据，无需手动初始化。
5.4 启动开发服务
| bash cd my-medusa-store npm run develop |
5.5 启动成功访问地址
• 后端 API 接口：http://localhost:9000
• 商家管理后台：http://localhost:9000/app
5.6 部署官方前台商城
| bash cd storefront npm install npm run dev |
前台商城访问地址：http://localhost:8000
六、生产环境 Docker 部署教程（线上服务器）
本方案基于 Docker Compose 一键部署，自动搭载 PostgreSQL、Redis、Medusa 后端，适配云服务器生产环境。
6.1 服务器前置准备
服务器安装 Docker、Docker Compose 环境，开放 9000 端口权限。
6.2 编写 docker-compose.yml 配置文件
| yaml version: "3.8" services: medusa: build: . container_name: medusa restart: unless-stopped ports: - "9000:9000" environment: - DATABASE_URL=postgresql://medusa:你的数据库密码@db:5432/medusa - REDIS_URL=redis://redis:6379 - JWT_SECRET=随机超长密钥字符串 - COOKIE_SECRET=随机超长密钥字符串 - STORE_CORS=https://你的商城域名 - ADMIN_CORS=https://你的后台域名 depends_on: - db - redis db: image: postgres:16-alpine container_name: medusa-db restart: unless-stopped volumes: - postgres_data:/var/lib/postgresql/data environment: - POSTGRES_DB=medusa - POSTGRES_USER=medusa - POSTGRES_PASSWORD=你的数据库密码 redis: image: redis:7-alpine container_name: medusa-redis restart: unless-stopped volumes: postgres_data: |
6.3 生产环境部署步骤
1. 在项目根目录创建并配置 .env 环境变量文件，补充密钥、域名等信息
2. 启动容器服务：docker compose up -d
3. 执行数据库迁移，初始化数据表：docker compose exec medusa npx medusa migrations run
4. 自定义创建管理员账号：docker compose exec medusa npx medusa user -e 自定义邮箱 -p 自定义密码
5. 配置 Nginx 反向代理、SSL 证书，实现域名访问、HTTPS 加密
七、常见问题与避坑指南
• 端口冲突：9000 端口被占用会导致启动失败，可修改容器端口映射解决
• 跨域报错：生产环境必须正确配置 STORE_CORS、ADMIN_CORS 域名，否则前端无法调用接口
• 队列异常：生产环境缺失 Redis 会导致异步任务、订单流程失效，生产环境必须启用 Redis
• 数据丢失风险：需配置 PostgreSQL 定时备份策略，防止服务器故障丢失订单、商品数据
• 国内支付适配：原生无微信、支付宝接口，需自主开发自定义支付模块对接
• 前台无法商用：官方 Demo 前台仅用于测试，上线前需完成UI优化、功能完善、适配国内业务场景