Medusa 保姆级部署教程：开源电商模块化引擎，自由搭建商城/ marketplace 后端

一、项目介绍

Medusa 是一套"commerce modules and tools"（官方 README 原文），让你不必重复造轮子即可构建丰富、可靠、高性能的商业应用。官方 README 原文："Medusa is a set of commerce modules and tools that allow you to build rich, reliable, and performant commerce applications without reinventing core commerce logic. The modules can be customized and used to build advanced ecommerce stores, marketplaces, or any product that needs foundational commerce primitives. All modules are open-source and freely available on npm."

它由 Medusajs 团队开发，采用模块化架构，核心模块（购物车、订单、产品、客户、支付、库存等）全部以 npm 包形式开源，可自由定制。官方提供后端框架、Admin 管理后台、Storefront 店面示例与 REST/GraphQL API。项目在 GitHub（medusajs/medusa）持续活跃维护，官方文档站 docs.medusajs.com，社区在 GitHub Discussions 与 Discord。

二、功能拆解

按官方 README 与文档，核心能力如下：

功能	说明
模块化 commerce 引擎	产品、库存、购物车、订单、客户、支付、配送等模块均为独立 npm 包
可定制	模块可替换/扩展，构建高级电商店铺、marketplace 或任何需要商业原语的产品
Admin 管理后台	随后端一起启动的管理界面
Storefront API	供前端店面调用的 REST API
插件生态	官方插件市场 medusajs.com/plugins
升级指南	官方维护 Upgrade Guides，跟随版本升级
架构文档	官方《Architecture Overview》与《Commerce Modules》文档

三、官方/GitHub 链接

GitHub 仓库：https://github.com/medusajs/medusa
官方网站：https://www.medusajs.com
官方文档：https://docs.medusajs.com
快速开始：https://docs.medusajs.com/create-medusa-app
环境准备：https://docs.medusajs.com/development/backend/prepare-environment
架构概览：https://docs.medusajs.com/development/fundamentals/architecture-overview
模块概览：https://docs.medusajs.com/modules/overview
升级指南：https://docs.medusajs.com/upgrade-guides/
插件市场：https://medusajs.com/plugins/
Discord：https://discord.com/invite/medusajs ｜ Twitter：https://twitter.com/medusajs

四、环境要求

官方文档《Prepare Development Environment》明确列出的前置工具：

Node.js：官方原文："Medusa requires version 16.14.0 or higher of Node." 用 node -v 检查版本。
Windows：从 Node.js 官网下载安装包。
Ubuntu：sudo apt update && sudo apt install nodejs。
macOS：brew install node（Homebrew），或从官网下载 pkg。
Git：官方原文："Medusa uses Git behind the scenes when you create a new project."
Debian/Ubuntu：apt-get install git。
macOS：brew install git（或随 Xcode 命令行工具）。
PostgreSQL：官方原文："The Medusa backend uses PostgreSQL to store data of your commerce system."
Ubuntu 官方安装命令：

sudo sh -c \
  'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet --no-check-certificate -O - \
  https://www.postgresql.org/media/keys/ACCC4CF8.asc | \
  sudo apt-key add -
sudo apt-get update
sudo apt-get -y install postgresql

（可选）Medusa CLI：官方提供全局 CLI，也可用 npx 调用。
端口：Medusa 后端默认 9000（官方 quickstart 默认）；Admin 随后端同端口挂载。
操作系统：官方文档覆盖 Windows / Linux / macOS。
硬件：官方文档未给出最低硬件指标。

五、部署步骤

步骤 1：安装 Medusa CLI（官方文档原文）

npm install @medusajs/medusa-cli -g

逐段解释：npm install -g 全局安装 npm 包；@medusajs/medusa-cli 是官方 CLI。官方文档另给 yarn/pnpm 等价命令：yarn global add @medusajs/medusa-cli 或 pnpm add @medusajs/medusa-cli -g。

预期输出参考： npm 安装进度条，结束显示 added N packages。

步骤 2：验证 CLI 安装

medusa -v

逐段解释：官方文档原文："To confirm that the CLI tool was installed successfully, run the following command:"。

预期输出参考： 打印 CLI 版本号，如 @medusajs/medusa-cli/1.x.x。

步骤 3：创建 Medusa 项目（官方 README 指向 Quickstart Guide）

官方 README 原文："Visit the Quickstart Guide to set up a server." 官方 Quickstart 用 CLI 交互式创建项目：

npx create-medusa-app@latest

逐段解释：npx create-medusa-app@latest 拉取官方脚手架并交互式引导：选择项目目录、数据库连接、是否安装示例数据、是否安装 Next.js 店面。官方 README 与文档均指向此命令作为入口。

预期输出参考： 交互式提示，依次询问项目名、数据库连接串（默认 postgres://localhost/medusa）、是否 seed 示例数据、是否安装 storefront；结束后项目目录就绪。

步骤 4：进入项目并启动开发服务器

cd my-medusa-store
npm run dev

逐段解释：cd my-medusa-store 进入脚手架生成的项目目录；npm run dev 启动 Medusa 后端开发模式。

预期输出参考： Medusa 启动日志，监听 9000 端口，提示 Admin 与 API 地址。

步骤 5：访问 Admin 与 API

Admin：http://localhost:9000/app
Storefront API：http://localhost:9000/store
REST API：http://localhost:9000/admin

六、配置参数详解

Medusa 项目的配置位于项目根目录 medusa-config.js（官方文档惯例）。关键配置项：

配置	说明
`projectConfig.database_url`	PostgreSQL 连接串，如 `postgres://localhost/medusa`
`projectConfig.http_port`	后端监听端口，默认 9000
`projectConfig.jwt_secret`	签发 JWT 的密钥
`projectConfig.cookie_secret`	Cookie 签名密钥
`modules`	启用的 commerce 模块列表
`plugins`	启用的插件列表

环境变量（官方惯例）： 项目根目录 .env 文件中配置：

DATABASE_URL=postgres://localhost/medusa
JWT_SECRET=你的jwt密钥
COOKIE_SECRET=你的cookie密钥

逐段解释：DATABASE_URL 供 TypeORM 连接 Postgres；JWT_SECRET 与 COOKIE_SECRET 由 Medusa 启动时读取。

七、启动与运维

开发模式： npm run dev（官方 quickstart 默认）。
生产构建与启动： 官方文档未在 prepare-environment 页给出生产命令；以官方《Deploy》文档为准（https://docs.medusajs.com/development/backend/deploy ），勿自行编造。
数据库迁移： Medusa CLI 提供迁移命令（medusa migrations run），以官方 CLI 文档为准。
查看日志： 开发模式日志直接输出到终端。
开机自启： 官方文档未提供 Medusa 专用 systemd/开机自启配置；生产部署可使用 Node 进程管理器（如 PM2）或容器编排，属平台通用方案，非 Medusa 官方文档内容。
数据持久化： 业务数据存于 PostgreSQL；文件上传默认存于本地文件系统，生产环境应配置 S3 兼容存储插件（官方插件市场）。
修改端口： 改 medusa-config.js 中 projectConfig.http_port，或设环境变量 PORT=9001 后重启。

八、实操验证

按步骤 1–4 完成项目创建与 npm run dev。
浏览器访问 http://localhost:9000/app，应看到 Medusa Admin 登录页。
首次访问会引导注册管理员邮箱与密码（脚手架 seed 时若选了示例数据，会有默认管理员账号，以终端输出为准）。
登录后在 Admin 中 Products 页签应能看到示例产品（如 seed 了示例数据）。
用 curl 访问 Storefront API 验证：

curl http://localhost:9000/store/products

逐段解释：GET 到 store 端点，返回公开产品列表 JSON。预期输出参考： 一段 JSON，含 products 数组。

登录与安全（重要）

官方默认账号密码： Medusa Admin 首次访问时引导创建管理员账号（邮箱+密码）；脚手架若 seed 了示例数据，默认管理员凭据会打印在终端输出中，以实际输出为准。
登录地址： http://服务器IP:9000/app。
首次登录修改密码： 登录后在 Admin 的 Profile/设置页修改。
密码重置： 通过 Admin 登录页的"忘记密码"流程（需配置邮件服务），或由其他管理员在后台重置。
密码配置存放位置： 用户密码以哈希形式存于 PostgreSQL 的 user 表；JWT_SECRET 与 COOKIE_SECRET 在 .env 文件。
安全提醒：部署到公网前必须设置强 JWT_SECRET 与 COOKIE_SECRET，勿使用默认/示例密钥；Admin 后台应放在反向代理后并启用 HTTPS。

九、故障排查

案例 1：npm install 报 EACCES 权限错误

报错原文（官方文档 Troubleshooting 一节标题）：NPM Error: EACCES Permissions Errors。
报错原因：全局安装 npm 包时目录权限不足。
分步解决：官方文档 Troubleshooting 一节给出该问题标题；按 npm 官方推荐，用 nvm 管理 Node 版本避免 sudo，或修正 npm 全局目录属主（sudo chown -R $(whoami) ~/.npm）。

案例 2：PowerShell 提示 command not found: medusa

报错原文（官方文档 Troubleshooting 一节标题）：Powershell Error: command not found: medusa。
报错原因：npm 全局 bin 目录未加入 PATH。
分步解决：按官方 Troubleshooting 一节，把 npm 全局 bin 目录（npm config get prefix 输出的 bin/ 子目录）加入 Windows PATH 环境变量，重开终端。

案例 3：npm run dev 报数据库连接失败

报错原文（常见形式）：ECONNREFUSED 127.0.0.1:5432 或 database "medusa" does not exist。
报错原因：PostgreSQL 未启动，或 .env 中 DATABASE_URL 指向的数据库/角色不存在。
分步解决：① 确认 Postgres 运行（pg_isready）；② 建库：createdb medusa；③ 确认 DATABASE_URL 中的用户名密码与 pg_hba.conf 匹配；④ 重启 npm run dev。

案例 4：Yarn 报 command not found: medusa

报错原文（官方文档 Troubleshooting 一节标题）：Yarn Error: command not found: medusa。
报错原因：Yarn 全局 bin 目录未在 PATH 中。
分步解决：按官方 Troubleshooting 一节，把 Yarn 全局 bin 目录加入 PATH。

十、升级、回滚与卸载

升级： 官方 README 原文："Follow the Upgrade Guides to keep your Medusa project up-to-date." 升级步骤以官方《Upgrade Guides》（https://docs.medusajs.com/upgrade-guides/ ）为准，按版本号顺序依次执行迁移脚本。

回滚： 官方未提供一键回滚命令；基于 npm 包版本机制，把 package.json 中 @medusajs/* 依赖改回旧版本号后 npm install，并按对应版本的 upgrade guide 反向处理数据库迁移。

卸载： ① 停止 npm run dev；② 删除项目目录；③ 如需彻底清理数据库：dropdb medusa（此操作永久删除全部业务数据，先备份——pg_dump medusa > backup.sql）；④ 全局卸载 CLI：npm uninstall -g @medusajs/medusa-cli。

十一、商用许可合规说明

许可证：MIT License（官方 README 徽章与 License 一节明确："Licensed under the MIT License."，链接指向 https://github.com/medusajs/medusa/blob/master/LICENSE ）。
MIT 许可允许自由使用、修改、分发与商用（包括闭源商业产品），分发时须保留原始版权声明与许可文本。
所有 commerce 模块均以 npm 包开源，商用部署无需付费授权；Medusa 同时提供 Medusa Cloud 托管与企业服务作为可选商业渠道。