# Windows 部署指南

## 📦 快速开始

### 方法一：一键部署（推荐）

1. **双击运行** `deploy-windows.bat`
2. 按提示完成配置
3. 部署完成后服务自动启动

### 方法二：Docker 部署

1. **双击运行** `docker-windows.bat`
2. 按提示完成配置
3. Docker 自动构建并启动

---

## 🛠️ 脚本说明

| 脚本文件 | 用途 |
|---------|------|
| `deploy-windows.bat` | 一键部署脚本（Node.js + PM2） |
| `docker-windows.bat` | Docker 一键部署脚本 |
| `manage-windows.bat` | 服务管理工具（启动/停止/日志） |
| `check-env.bat` | 环境检查工具 |
| `uninstall.bat` | 卸载清理工具 |

---

## 📋 前置要求

### Node.js 部署方式

- **Node.js** v18+ ([下载地址](https://nodejs.org/))
- **npm**（随 Node.js 自动安装）

### Docker 部署方式

- **Docker Desktop for Windows** ([下载地址](https://www.docker.com/products/docker-desktop/))
- 启用 WSL2 后端（推荐）

---

## 🔧 详细步骤

### 1. 环境检查

运行 `check-env.bat` 检查环境是否就绪。

```cmd
.\check-env.bat
```

根据输出安装缺失的组件。

---

### 2. 配置环境变量

编辑 `.env` 文件：

```env
# 飞书配置
FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxx

# 飞书事件接收模式
FEISHU_MODE=http

# 七牛云配置（可选）
QINIU_ACCESS_KEY=xxxxxxxxxxxxxx
QINIU_SECRET_KEY=xxxxxxxxxxxxxx
QINIU_BUCKET=your-bucket-name
QINIU_REGION=z0
QINIU_DOMAIN=https://your-cdn.com

# 服务配置
PORT=3030
NODE_ENV=production
```

---

### 3. 配置七牛云

编辑 `config/qiniu-config.json`：

```json
{
  "buckets": {
    "default": {
      "accessKey": "YOUR_ACCESS_KEY",
      "secretKey": "YOUR_SECRET_KEY",
      "bucket": "your-bucket-name",
      "region": "z0",
      "domain": "https://your-cdn.com"
    }
  },
  "uploadPaths": {
    "ipa": "/ipa/app.ipa",
    "apk": "/apk/app.apk"
  },
  "uploadProfiles": {
    "iOS": {
      "bucket": "default",
      "path": "ipa"
    },
    "安卓": {
      "bucket": "default",
      "path": "apk"
    }
  }
}
```

---

### 4. 启动服务

#### 使用 PM2

```cmd
.\manage-windows.bat
```

选择 `1. 启动服务`

#### 使用 Docker

```cmd
docker-compose up -d
```

---

### 5. 设置开机自启

**PM2 方式**（需要管理员权限）：

```cmd
# 以管理员身份打开命令提示符
pm2 startup
pm2 save
```

**Docker 方式**：

Docker Desktop 会自动随系统启动。

---

## 📊 管理命令

### PM2 命令

```cmd
# 查看状态
pm2 list

# 查看日志
pm2 logs qiniu-bot

# 重启服务
pm2 restart qiniu-bot

# 停止服务
pm2 stop qiniu-bot

# 删除服务
pm2 delete qiniu-bot

# 清空日志
pm2 flush
```

### Docker 命令

```cmd
# 查看日志
docker-compose logs -f qiniu-bot

# 重启服务
docker-compose restart

# 停止服务
docker-compose stop

# 启动服务
docker-compose start

# 停止并删除
docker-compose down

# 重新构建
docker-compose build --no-cache
```

---

## 🔍 故障排查

### 问题 1: 端口 3030 被占用

**解决方案：**

```cmd
# 查找占用进程
netstat -ano | findstr :3030

# 杀掉进程（替换 PID）
taskkill /PID 12345 /F

# 或修改 .env 中的 PORT
PORT=3031
```

---

### 问题 2: PM2 未找到

**解决方案：**

```cmd
# 全局安装 PM2
npm install -g pm2

# 如果权限不足，以管理员身份运行
# 或使用 yarn
yarn global add pm2
```

---

### 问题 3: Docker 构建失败

**解决方案：**

1. 确保 Docker Desktop 正在运行
2. 增加 Docker 资源分配（设置 → Resources）
3. 使用国内镜像加速器：

```json
// Docker Desktop 设置 → Docker Engine
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}
```

---

### 问题 4: 依赖安装失败

**解决方案：**

```cmd
# 清理缓存
npm cache clean --force

# 删除 node_modules
rmdir /s /q node_modules

# 重新安装
npm install

# 或使用淘宝镜像
npm config set registry https://registry.npmmirror.com
npm install
```

---

### 问题 5: 飞书回调失败

**检查清单：**

- [ ] 服务器有公网 IP 或使用内网穿透
- [ ] 防火墙开放 3030 端口
- [ ] 飞书开放平台配置正确的回调 URL
- [ ] `.env` 中 `FEISHU_VERIFICATION_TOKEN` 和 `FEISHU_ENCRYPT_KEY` 正确

**测试回调 URL：**

```cmd
# 使用 ngrok 内网穿透
ngrok http 3030

# 将生成的 URL 配置到飞书开放平台
# 例如：https://xxxx.ngrok.io/feishu/event
```

---

## 📝 日志位置

### PM2 日志

```
C:\Users\你的用户名\.pm2\logs\
```

### Docker 日志

```cmd
docker-compose logs qiniu-bot
```

### 应用日志

```
logs\*.log
```

---

## 🧹 卸载

运行 `uninstall.bat` 自动清理。

或手动执行：

```cmd
# PM2 方式
pm2 stop qiniu-bot
pm2 delete qiniu-bot
rmdir /s /q node_modules
del /q /s logs\*.*

# Docker 方式
docker-compose down
docker rmi qiniu-feishu-bot:latest
```

---

## 💡 最佳实践

1. **生产环境** 使用 Docker 部署（更稳定、易迁移）
2. **开发环境** 使用 PM2 部署（调试方便）
3. **定期备份** `config/` 和 `.env` 文件
4. **监控日志** 使用 `pm2 logs` 或 `docker-compose logs -f`
5. **更新部署** 先备份配置，再拉取代码，最后重启服务

---

## 📞 获取帮助

如遇问题，请提供以下信息：

1. 运行 `check-env.bat` 的输出
2. 错误日志（`pm2 logs` 或 `docker-compose logs`）
3. `.env` 配置（隐藏敏感信息）
4. 操作系统版本