在宝塔面板中创建独立用户部署和运行 Strapi 完整教程

这份教程采用了最佳实践：使用专用用户运行、配置独立的 npm 环境以避免权限问题，并使用 PM2 进行进程守护。

准备工作

在开始之前，请确保你的服务器已完成以下基础设置：

安装宝塔面板并完成初始化。
安装软件商店中的插件：
- Node.js 版本管理器（推荐，用于管理 Node 环境）或直接在终端安装 Node.js（建议 v18 或 v20）。
- PM2 管理器（用于守护 Strapi 进程）。
- MySQL（数据库）。
放行端口：在云服务商的安全组（防火墙）中放行 1337 端口（Strapi 默认端口）以及 8888（宝塔面板端口）、80/443（Web 服务端口）。

第一步：创建专用用户与目录

为了安全起见，我们不建议直接用 root 运行 Strapi。

连接 SSH 登录服务器。
创建用户（假设用户名为 strapi_user）：

# 创建用户，赋予 bash
useradd -m -s /bin/bash strapi_user

# 设置密码（可选，方便以后切换）
passwd strapi_user

创建项目目录（建议在 wwwroot 下）：

mkdir -p /www/wwwroot/my-strapi-app
# 将目录所有权交给新用户
chown -R strapi_user:strapi_user /www/wwwroot/my-strapi-app

第二步：配置 Node.js 环境（解决权限痛点）

这一步非常关键，用于解决 npm install 时常见的 EACCES 权限报错。

切换到新用户：

su - strapi_user

确认 Node/npm 可用：
- 如果你安装了宝塔的”Node.js 版本管理器”，通常可以直接使用 node -v。
- 如果提示找不到命令，可能需要建立软链接：

# 查找 node 路径，通常在 /www/server/nodejs/...
ln -sf $(which node) /usr/bin/node
ln -sf $(which npm) /usr/bin/npm
ln -sf $(which npx) /usr/bin/npx

配置 npm 全局路径与缓存目录（避免 sudo）：

# 1. 创建全局包目录
mkdir ~/.npm-global

# 2. 告诉 npm 使用这个目录
npm config set prefix '~/.npm-global'

# 3. 创建缓存目录并指定给 npm
mkdir ~/.npm_cache
npm config set cache '~/.npm_cache'

# 4. 添加到环境变量
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.bashrc

# 5. 立即生效
source ~/.bashrc

第三步：安装与初始化 Strapi

cd /www/wwwroot/my-strapi-app

创建 Strapi 项目：

npx create-strapi-app@latest my-project

注意：如果这里依然报错权限问题，请检查上一步的环境变量是否生效。
安装过程中会询问数据库类型，建议选择 Custom (manual settings) 以便配置 MySQL。

配置数据库：
- 在宝塔面板 → 数据库中创建一个新数据库（如 strapi_db），记下用户名和密码。
- 在安装向导中选择 MySQL，并填入刚才创建的数据库信息。
修复 Sharp 依赖（常见问题）：Strapi 依赖 sharp 处理图片，有时需要重新构建：

cd my-project
npm install sharp
# 如果报错，尝试清理缓存后重装: npm cache clean --force && npm install

第四步：构建与启动（开发模式测试）

在正式用 PM2 托管前，先手动跑一下确保没问题。

解决构建内存溢出问题（核心步骤）：在 Strapi 项目的生产部署中，由于需要解析大量数据模型、生成 Admin 面板以及处理复杂的依赖关系，默认的 Node.js 内存限制（通常为 1.4GB 左右）极易导致构建中断，抛出 FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory 错误。

打开项目根目录下的 package.json 文件，找到 scripts 字段中的 build 命令，将其修改为以下格式：
```
"scripts": {
  "build": "cross-env NODE_OPTIONS=\"--max-old-space-size=3072\" strapi build"
}
```
说明：这里的 3072 代表将 Node.js 的最大老生代内存限制提升至 3072MB（3GB）。如果你的服务器物理内存充足，也可以将其调整为 4096 或更高。
构建 Admin 面板：

npm run build

启动开发模式：

npm run develop

如果看到 Admin panel built successfully 且无报错，按 Ctrl+C 停止它。
首次启动可能会提示缺少 jwtSecret，按照提示生成并填入 .env 文件或 config/plugins.js 即可。

第五步：使用 PM2 长期守护（生产模式）

这是让 Strapi 在后台稳定运行的关键。

方法 A：使用宝塔面板的”PM2 管理器”（推荐新手）

打开宝塔面板 → PM2 管理器。
点击 添加项目。
配置如下：
- 项目名称：strapi-app
- 启动文件：选择项目目录下的 server.js（如果没有，需手动创建一个，内容见下方代码块）。
- 运行目录：/www/wwwroot/my-strapi-app/my-project（注意要进到具体的项目文件夹）。
- Node 版本：选择你安装的版本。
- 启动方式：自定义启动命令 → 输入 npm start。
- 运行用户：务必选择 strapi_user。
点击提交。

补充：如果需要手动创建 server.js 在项目根目录（my-project）下新建 server.js：
const strapi = require('@strapi/strapi');
strapi({ distDir: './dist' }).start();

方法 B：使用命令行 PM2（更灵活）

在 SSH 中执行：

cd /www/wwwroot/my-strapi-app/my-project
pm2 start npm --name "strapi-app" -- start
pm2 save

第六步：域名访问与反向代理

现在 Strapi 运行在 IP:1337，我们需要通过域名访问。

添加站点：
- 宝塔面板 → 网站 → 添加站点。
- 输入你的域名（如 api.example.com）。
设置反向代理：
- 点击站点设置 → 反向代理 → 添加反向代理。
- 代理名称：strapi
- 目标 URL：http://127.0.0.1:1337（Strapi 的默认端口）。
- 发送域名：$host
- 点击提交。
SSL 证书：
- 在站点设置 → SSL → 申请 Let’s Encrypt 免费证书，开启 HTTPS。

完成

现在，访问你的域名，你应该能看到 Strapi 的管理员注册页面了！