# 宝塔面板部署指南 > GEO Wiki Pro 宝塔面板完整部署指南，从安装面板到配置 Nginx 反向代理，含踩坑记录 --- ## 概述 宝塔面板是国内常用的服务器管理工具，提供图形化界面管理网站、数据库、SSL 证书等。本文介绍如何在宝塔面板上部署 GEO Wiki Pro。 --- ## 前置条件 | 条件 | 说明 | |------|------| | 服务器 | Linux 服务器（推荐 Ubuntu 20.04+ / CentOS 7+） | | 宝塔面板 | 已安装宝塔面板 | | Node.js | v18 或更高版本 | | PM2 | 用于进程管理 | --- ## 第一步：安装 Node.js 通过宝塔面板的 **软件商店** → **Node.js 版本管理器** 安装 Node.js 18+。 或使用命令行： ```bash # 安装 Node.js 18 curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt-get install -y nodejs # 验证安装 node -v # 应显示 v18.x.x npm -v # 应显示 9.x.x ``` --- ## 第二步：上传代码 1. 在宝塔面板创建网站目录：`/www/wwwroot/geowiki` 2. 上传 GEO Wiki Pro 代码到该目录 3. 解压代码文件 ```bash cd /www/wwwroot/geowiki npm install --production ``` --- ## 第三步：配置环境变量 创建 `.env` 文件： ```bash cat > .env << 'EOF' NODE_ENV=production PORT=3002 JWT_SECRET=your-secret-key-here-min-32-chars BASE_URL=https://your-domain.com EOF ``` ::: warning `JWT_SECRET` 必须设置，且长度至少 32 字符。生产环境请使用随机生成的强密钥。 ::: --- ## 第四步：启动服务 使用 PM2 管理进程： ```bash # 安装 PM2 npm install -g pm2 # 启动服务 pm2 start server/index.js --name geo-wiki # 设置开机自启 pm2 save pm2 startup ``` 验证服务运行： ```bash pm2 status curl http://localhost:3002/api/v1/health ``` --- ## 第五步：配置 Nginx 反向代理 在宝塔面板 → **网站** → **设置** → **反向代理**： | 配置项 | 值 | |--------|-----| | 代理名称 | geowiki | | 目标 URL | http://127.0.0.1:3002 | | 发送域名 | $host | 或手动编辑 Nginx 配置： ```nginx server { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:3002; 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; } } ``` --- ## 第六步：配置 SSL 证书 在宝塔面板 → **网站** → **SSL** → 申请免费 Let's Encrypt 证书。 --- ## 踩坑记录 ### 1. PM2 启动后立即退出 **原因**：Node.js 版本不兼容或缺少依赖。 **解决**： ```bash # 检查日志 pm2 logs geo-wiki # 确保 Node.js 版本 >= 18 node -v # 重新安装依赖 npm install --production ``` ### 2. Nginx 502 Bad Gateway **原因**：Node.js 服务未启动或端口不匹配。 **解决**： ```bash # 检查服务是否运行 pm2 status # 检查端口是否正确 netstat -tlnp | grep 3002 ``` ### 3. 上传文件失败 **原因**：Nginx 上传大小限制。 **解决**：在 Nginx 配置中添加： ```nginx client_max_body_size 50M; ``` ### 4. Cookie / 登录问题 **原因**：Nginx 未正确传递 Cookie。 **解决**：确保配置了 `proxy_set_header Host $host;`。 ### 5. 静态文件 404 **原因**：Nginx 优先匹配了静态文件路径。 **解决**：确保 SPA fallback 配置正确： ```nginx location / { proxy_pass http://127.0.0.1:3002; try_files $uri $uri/ /index.html; } ``` ### 6. HSTS 导致 SSL 错误 **原因**：Helmet 默认开启 HSTS，HTTP 环境下浏览器强制升级 HTTPS。 **解决**：在 `.env` 中设置 `ENABLE_HSTS=false`（如果未使用 SSL）。 --- ## 常用命令 ```bash # 查看状态 pm2 status # 查看日志 pm2 logs geo-wiki # 重启服务 pm2 restart geo-wiki # 停止服务 pm2 stop geo-wiki # 删除服务 pm2 delete geo-wiki ``` --- ## 相关文档 - [Docker 部署指南](/docs/docker-deployment) - [5 分钟快速上手](/docs/quick-start) - [安全机制](/docs/security)