宝塔面板部署指南

一、服务器环境要求

组件	版本要求	说明
Node.js	>= 18.x	推荐 20.x LTS
pnpm	>= 8.x	包管理器（可选，也可用 npm）
PM2	最新版	进程守护
宝塔面板	最新版	服务器管理面板

二、宝塔面板安装 Node.js 环境

2.1 安装 Node.js 版本管理器

登录宝塔面板 → 左侧菜单「软件商店」
搜索「Node.js 版本管理器」→ 点击安装
安装完成后，在 Node.js 版本管理器中安装 v20.x LTS

2.2 安装 PM2

在宝塔终端中执行：

npm install -g pm2

2.3 安装 pnpm（推荐）

npm install -g pnpm

三、项目部署

3.1 上传项目文件

将整个 qiwe/backend/ 目录上传到服务器，推荐路径：

/www/wwwroot/qiwe/backend/

可以用宝塔「文件」界面直接拖拽上传，或使用 git：

cd /www/wwwroot
git clone <your-repo-url> qiwe
cd qiwe/backend

3.2 上传的文件清单

确保以下关键文件都在服务器上：

backend/
├── .env                    # 环境变量配置（需要根据服务器调整）
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json
└── src/
    ├── index.ts
    └── apps/
        └── pc/
            ├── app.ts
            ├── health/server.ts
            └── qiwe/
                ├── models/
                │   ├── parse-client.ts
                │   └── schema-setup.ts
                ├── routes/webhook.routes.ts
                ├── controllers/
                │   ├── webhook.controller.ts
                │   └── sync.controller.ts
                └── services/
                    ├── webhook.service.ts
                    ├── sync.service.ts
                    └── qiwe-api.service.ts

3.3 安装依赖

cd /www/wwwroot/qiwe/backend
pnpm install
# 如果使用 npm: npm install

3.4 配置环境变量

编辑 .env 文件，确认以下配置正确：

NODE_ENV=production
PC_PORT=3101

# Parse Server（保持不变）
PARSE_APP_ID=lami-ai
PARSE_MASTER_KEY=5s1gfOasPqx9JKsA
PARSE_SERVER_URL=https://server.sh-lami.com/parse

# QiWe 平台配置（保持不变）
QIWE_API_BASE=https://manager.qiweapi.com/qiwe
QIWE_TOKEN=146708f9-1c49-4cf0-aad9-0b7a36834b0b
QIWE_GUID=810456E2-B009-4915-917F-085EC800AA16
QIWE_USER_ID=1688857385538777

注意：NODE_ENV 改为 production。

四、PM2 进程管理

4.1 启动服务

cd /www/wwwroot/qiwe/backend
pm2 start src/index.ts --name qiwe-backend --interpreter npx -- tsx

等价于执行 npx tsx src/index.ts，服务监听在 3101 端口。

4.2 PM2 常用命令

pm2 list                  # 查看所有进程
pm2 logs qiwe-backend     # 查看日志
pm2 stop qiwe-backend     # 停止
pm2 restart qiwe-backend  # 重启
pm2 delete qiwe-backend   # 删除
pm2 monit                 # 实时监控

4.3 设置开机自启

pm2 startup
pm2 save

五、Nginx 反向代理（宝塔）

5.1 添加站点

宝塔面板 → 左侧「网站」→「添加站点」
域名填写：47.96.148.66（或你解析的域名）
PHP 版本选择「纯静态」

5.2 配置反向代理

点击站点右侧「设置」→「反向代理」→「添加反向代理」：

字段	值
代理名称	`qiwe-backend`
目标URL	`http://127.0.0.1:3101`
发送域名	`$host`

或者直接编辑站点配置文件，在 server 块中添加：

location /api/qiwe/ {
    proxy_pass http://127.0.0.1:3101;
    proxy_http_version 1.1;
    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;
    proxy_read_timeout 10s;
    proxy_connect_timeout 5s;
}

5.3 配置防火墙/安全组

确保服务器安全组开放以下端口：

端口	协议	用途
80	TCP	HTTP（回调接收）
443	TCP	HTTPS（如使用）

宝塔面板默认已开放 80 端口，如果有云服务器安全组，需要在云控制台也放行。

六、企微平台回调配置

6.1 配置回调 URL

登录企微管理平台，在相应的应用/群配置中，将回调 URL 设置为：

http://47.96.148.66/api/qiwe/webhook

6.2 验证回调是否生效

在服务器终端查看日志：

pm2 logs qiwe-backend

当日志中出现 [文本消息]、[群创建]、[成员加入] 等输出时，说明回调已正常接收。

也可以用 curl 从外部测试：

curl -X POST http://47.96.148.66/api/qiwe/webhook -H "Content-Type: application/json" -d '{"code":0,"data":[{"guid":"test","cmd":15000,"msgType":0,"fromRoomId":0,"senderId":123,"msgUniqueIdentifier":"deploy-test","timestamp":1716883200,"msgData":{"content":"deploy test"}}],"msg":"success"}'

七、更新与维护

7.1 更新代码

cd /www/wwwroot/qiwe/backend
git pull                    # 拉取最新代码
pnpm install                # 安装可能的新依赖
pm2 restart qiwe-backend    # 重启服务

7.2 查看运行状态

pm2 status                  # 进程状态
curl http://127.0.0.1:3101/api/health   # 健康检查

7.3 查看数据库

Parse Dashboard 可在线查看数据库：

npx parse-dashboard --appId lami-ai --masterKey 5s1gfOasPqx9JKsA --serverURL https://server.sh-lami.com/parse --appName lami-dev --port 4041

然后访问 http://47.96.148.66:4041（需要开放 4041 端口或通过 SSH 隧道访问）。

八、常见问题

Q1: 端口被占用

lsof -i :3101          # 查看占用端口的进程
kill -9 <PID>          # 结束进程

Q2: PM2 进程异常退出

pm2 logs qiwe-backend --lines 50 --err   # 查看错误日志

常见原因：

.env 配置缺失
Parse Server 连接失败（检查 PARSE_SERVER_URL 是否可达）
依赖未安装（运行 pnpm install）

Q3: 反向代理返回 502

检查：

PM2 进程是否运行：pm2 status
端口是否正确：curl http://127.0.0.1:3101/api/health
Nginx 配置中 proxy_pass 是否指向正确端口

Q4: 回调收不到数据

检查：

Nginx 访问日志：/www/wwwlogs/ 目录下对应站点的 .log 文件
服务器防火墙是否开放 80 端口
云服务商安全组是否放行 80 端口
企微平台回调 URL 是否正确配置

九、快速部署检查清单

Node.js v20.x 已安装
PM2 已全局安装
项目文件已上传到 /www/wwwroot/qiwe/backend/
pnpm install 执行成功
.env 中 NODE_ENV=production
PM2 进程正常运行（pm2 status）
curl http://127.0.0.1:3101/api/health 返回 {"status":"ok"}
宝塔站点已创建，反向代理已配置
curl http://47.96.148.66/api/qiwe/webhook 返回正常
企微平台回调 URL 已配置为 http://47.96.148.66/api/qiwe/webhook
PM2 已设置开机自启（pm2 save）

deployment-baota.md 7.2 KB História Raw