qiniu-feishu-bot/WINDOWS.md

Windows 快速开始指南

🪟 Windows 用户专用部署指南

---

方法一：双击启动（最简单）

1️⃣ 下载项目

• 从 GitHub 下载 ZIP 文件
• 或使用 Git：git clone <repo-url>

2️⃣ 安装 Node.js

1. 访问 https://nodejs.org/
2. 下载 LTS 版本（推荐 18.x 或更高）
3. 双击安装，一路"下一步"
4. 验证安装：

   node --version
   npm --version
   

3️⃣ 配置应用

1. 打开项目文件夹
2. 双击运行 start.bat
3. 脚本会自动：
   • ✅ 检查 Node.js
   • ✅ 创建配置文件
   • ✅ 安装依赖
   • ⚠️ 提示你编辑配置

4️⃣ 编辑配置

脚本会提示你编辑两个文件：

.env 文件（飞书配置）：

FEISHU_APP_ID=cli_xxxxxx
FEISHU_APP_SECRET=xxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxx
FEISHU_ENCRYPT_KEY=xxxxxx

config\qiniu-config.json（七牛云配置）：

{
  "buckets": {
    "default": {
      "accessKey": "YOUR_ACCESS_KEY",
      "secretKey": "YOUR_SECRET_KEY",
      "bucket": "your-bucket",
      "region": "z0",
      "domain": "https://your-cdn.com"
    }
  }
}

5️⃣ 启动服务

配置完成后，再次双击 start.bat，看到：

========================================
  🍙 七牛云上传机器人 - Windows 版
========================================

✅ Node.js 已安装
📦 正在安装依赖...
✅ 依赖安装完成

🚀 正在启动服务...
📍 监听端口：3000

---

方法二：作为 Windows 服务运行（推荐生产环境）

使用 NSSM 让服务开机自启、后台运行。

1️⃣ 下载 NSSM

访问 https://nssm.cc/download 下载最新版

2️⃣ 安装服务

以管理员身份打开命令提示符：

cd C:\path\to\qiniu-feishu-bot

nssm install QiniuBot "C:\Program Files\nodejs\node.exe" "C:\path\to\qiniu-feishu-bot\src\index.js"

3️⃣ 配置服务

# 设置工作目录
nssm set QiniuBot AppDirectory "C:\path\to\qiniu-feishu-bot"

# 设置环境变量
nssm set QiniuBot AppEnvironmentExtra "NODE_ENV=production"
nssm set QiniuBot AppEnvironmentExtra "PATH=%PATH%"

# 设置日志
nssm set QiniuBot AppStdout "C:\path\to\qiniu-feishu-bot\logs\stdout.log"
nssm set QiniuBot AppStderr "C:\path\to\qiniu-feishu-bot\logs\stderr.log"

4️⃣ 启动服务

nssm start QiniuBot

5️⃣ 管理命令

nssm stop QiniuBot      # 停止
nssm restart QiniuBot   # 重启
nssm status QiniuBot    # 查看状态
nssm remove QiniuBot    # 删除服务（会提示确认）

---

方法三：Docker Desktop

1️⃣ 安装 Docker Desktop

访问 https://www.docker.com/products/docker-desktop 下载

2️⃣ 构建镜像

打开 PowerShell：

cd C:\path\to\qiniu-feishu-bot

docker build -t qiniu-feishu-bot .

3️⃣ 运行容器

docker run -d ^
  --name qiniu-bot ^
  -p 3000:3000 ^
  --restart unless-stopped ^
  --env-file .env ^
  -v ${PWD}\config:/app/config ^
  qiniu-feishu-bot

4️⃣ 管理命令

docker logs -f qiniu-bot      # 查看日志
docker stop qiniu-bot         # 停止
docker start qiniu-bot        # 启动
docker rm qiniu-bot           # 删除

---

🔧 常见问题

❌ "node 不是内部或外部命令"

解决：

1. 重新安装 Node.js
2. 安装时勾选"Add to PATH"
3. 重启命令提示符

❌ 端口 3000 被占用

解决：

# 查找占用端口的进程
netstat -ano | findstr :3000

# 杀死进程（替换 <PID> 为实际进程 ID）
taskkill /PID <PID> /F

# 或修改端口
# 编辑 .env 文件，设置 PORT=3001

❌ 权限不足

解决：

• 右键 start.bat → "以管理员身份运行"
• 或右键命令提示符 → "以管理员身份运行"

❌ 依赖安装失败

解决：

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

# 清除缓存重试
npm cache clean --force
npm install

❌ 防火墙阻止访问

解决：

1. 控制面板 → Windows Defender 防火墙
2. 高级设置 → 入站规则 → 新建规则
3. 端口 → TCP → 3000 → 允许连接

---

📝 配置飞书应用

1️⃣ 创建飞书应用

1. 访问 https://open.feishu.cn/
2. 登录企业管理员账号
3. 创建自建应用

2️⃣ 配置权限

添加权限：

• im:message - 消息
• im:file - 文件

3️⃣ 配置事件订阅

• 请求地址：https://your-domain.com/feishu/event
• 订阅事件：im.message.receive_v1

⚠️ 注意：飞书需要能访问你的服务器

• 云服务器：配置安全组开放 3000 端口
• 本地测试：使用内网穿透（ngrok、cpolar）

4️⃣ 获取配置信息

从飞书开放平台复制以下信息到 .env：

• App ID
• App Secret
• Verification Token
• Encrypt Key

---

✅ 验证部署

1️⃣ 检查服务

浏览器访问：http://localhost:3000/health

应看到：{"status":"ok",...}

2️⃣ 测试飞书

1. 在飞书中找到机器人
2. 发送任意消息
3. 应收到交互式卡片

3️⃣ 测试上传

/upload --original default
[附上一个文件]

---

📞 获取帮助

• 查看日志：控制台输出或 logs\ 目录
• 检查配置：.env 和 config\qiniu-config.json
• 重启服务：关闭 start.bat 窗口，重新运行

---

🍙 祝你使用愉快！