# 宝塔面板部署指南

## 一、服务器环境要求

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

---

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

### 2.1 安装 Node.js 版本管理器

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

### 2.2 安装 PM2

在宝塔终端中执行：

```bash
npm install -g pm2
```

### 2.3 安装 pnpm（推荐）

```bash
npm install -g pnpm
```

---

## 三、项目部署

### 3.1 上传项目文件

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

```
/www/wwwroot/qiwe/backend/
```

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

```bash
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 安装依赖

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

### 3.4 配置环境变量

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

```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 启动服务

```bash
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 常用命令

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

### 4.3 设置开机自启

```bash
pm2 startup
pm2 save
```

---

## 五、Nginx 反向代理（宝塔）

### 5.1 添加站点

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

### 5.2 配置反向代理

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

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

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

```nginx
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 验证回调是否生效

在服务器终端查看日志：

```bash
pm2 logs qiwe-backend
```

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

也可以用 curl 从外部测试：

```bash
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 更新代码

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

### 7.2 查看运行状态

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

### 7.3 查看数据库

Parse Dashboard 可在线查看数据库：

```bash
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: 端口被占用

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

### Q2: PM2 进程异常退出

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

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

### Q3: 反向代理返回 502

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

### Q4: 回调收不到数据

检查：
1. Nginx 访问日志：`/www/wwwlogs/` 目录下对应站点的 `.log` 文件
2. 服务器防火墙是否开放 80 端口
3. 云服务商安全组是否放行 80 端口
4. 企微平台回调 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`）