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. 验证安装：
   ```cmd
   node --version
   npm --version
   ```

### 3️⃣ 配置应用

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

### 4️⃣ 编辑配置

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

**`.env` 文件**（飞书配置）：
```env
FEISHU_APP_ID=cli_xxxxxx
FEISHU_APP_SECRET=xxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxx
FEISHU_ENCRYPT_KEY=xxxxxx
```

**`config\qiniu-config.json`**（七牛云配置）：
```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️⃣ 安装服务

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

```cmd
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️⃣ 配置服务

```cmd
# 设置工作目录
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️⃣ 启动服务

```cmd
nssm start QiniuBot
```

### 5️⃣ 管理命令

```cmd
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**：

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

docker build -t qiniu-feishu-bot .
```

### 3️⃣ 运行容器

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

### 4️⃣ 管理命令

```powershell
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 被占用

**解决：**
```cmd
# 查找占用端口的进程
netstat -ano | findstr :3000

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

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

### ❌ 权限不足

**解决：**
- 右键 `start.bat` → "以管理员身份运行"
- 或右键命令提示符 → "以管理员身份运行"

### ❌ 依赖安装失败

**解决：**
```cmd
# 使用淘宝镜像
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` 窗口，重新运行

---

**🍙 祝你使用愉快！**