qiniu-feishu-bot/WINDOWS_DEPLOY.md

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+ (下载地址)
• npm（随 Node.js 自动安装）

Docker 部署方式

• Docker Desktop for Windows (下载地址)
• 启用 WSL2 后端（推荐）

---

🔧 详细步骤

1. 环境检查

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

.\check-env.bat

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

---

2. 配置环境变量

编辑 .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：

{
  "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

.\manage-windows.bat

选择 1. 启动服务

使用 Docker

docker-compose up -d

---

5. 设置开机自启

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

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

Docker 方式：

Docker Desktop 会自动随系统启动。

---

📊 管理命令

PM2 命令

# 查看状态
pm2 list

# 查看日志
pm2 logs qiniu-bot

# 重启服务
pm2 restart qiniu-bot

# 停止服务
pm2 stop qiniu-bot

# 删除服务
pm2 delete qiniu-bot

# 清空日志
pm2 flush

Docker 命令

# 查看日志
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 被占用

解决方案：

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

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

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

---

问题 2: PM2 未找到

解决方案：

# 全局安装 PM2
npm install -g pm2

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

---

问题 3: Docker 构建失败

解决方案：

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

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

---

问题 4: 依赖安装失败

解决方案：

# 清理缓存
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：

# 使用 ngrok 内网穿透
ngrok http 3030

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

---

📝 日志位置

PM2 日志

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

Docker 日志

docker-compose logs qiniu-bot

应用日志

logs\*.log

---

🧹 卸载

运行 uninstall.bat 自动清理。

或手动执行：

# 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. 操作系统版本