在宝塔面板中创建独立用户部署和运行Strapi完整教程-星野集-个人编程学习与开发笔记归档

宝塔面板部署 Strapi 完整教程

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

📋 准备工作

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

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

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

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

连接 SSH 登录服务器。

创建用户（假设用户名为 strapi_user）：

# 创建用户，不赋予登录 Shell（安全起见），但为了方便操作，这里我们赋予 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. 添加到环境变量
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.bashrc

# 4. 立即生效
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 托管前，先手动跑一下确保没问题。

构建 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 的管理员注册页面了！🎉

目录CONTENT

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