Initial commit: 七牛云上传飞书机器人

功能： - 飞书交互卡片支持 - 七牛云文件上传 - 自动 CDN 刷新 - 多存储桶配置 - 跨平台部署（Linux/macOS/Windows） - Docker 支持
2026-03-05 14:22:26 +08:00
commit b00567762f
15 changed files with 2286 additions and 0 deletions
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -0,0 +1,432 @@
+# 七牛云上传机器人 - 跨平台部署指南
+
+支持 **Linux**、**macOS** 和 **Windows** 系统。
+
+---
+
+## 📋 前置要求
+
+### 所有平台
+
+1. **Node.js 18+**
+   - 下载地址：https://nodejs.org/
+   - 验证：`node --version`
+
+2. **七牛云账号**
+   - 官网：https://www.qiniu.com/
+   - 需要：AccessKey、SecretKey、存储桶
+
+3. **飞书企业管理员权限**
+   - 用于创建自建应用
+
+4. **公网访问能力**（三选一）
+   - 云服务器（阿里云、腾讯云等）
+   - 内网穿透工具（ngrok、cloudflared）
+   - 本地网络有公网 IP
+
+---
+
+## 🐧 Linux 部署
+
+### 方式 A：一键脚本（推荐）
+
+```bash
+# 1. 下载项目
+git clone <repo-url> qiniu-feishu-bot
+cd qiniu-feishu-bot
+
+# 2. 运行启动脚本
+chmod +x start.sh
+./start.sh
+
+# 脚本会自动：
+# - 检查 Node.js
+# - 创建配置文件
+# - 安装依赖
+# - 启动服务
+```
+
+### 方式 B：手动部署
+
+```bash
+# 1. 安装 Node.js
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# 2. 安装依赖
+npm install
+
+# 3. 配置环境变量
+cp .env.example .env
+nano .env  # 编辑配置
+
+# 4. 配置七牛云
+cp config/qiniu-config.json.example config/qiniu-config.json
+nano config/qiniu-config.json
+
+# 5. 启动服务
+npm start
+
+# 6. 后台运行（可选）
+# 使用 systemd
+sudo nano /etc/systemd/system/qiniu-bot.service
+```
+
+**systemd 服务配置：**
+
+```ini
+[Unit]
+Description=七牛云上传机器人
+After=network.target
+
+[Service]
+Type=simple
+User=admin
+WorkingDirectory=/path/to/qiniu-feishu-bot
+Environment=NODE_ENV=production
+ExecStart=/usr/bin/node src/index.js
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+# 启用服务
+sudo systemctl daemon-reload
+sudo systemctl enable qiniu-bot
+sudo systemctl start qiniu-bot
+sudo systemctl status qiniu-bot
+```
+
+### 方式 C：Docker 部署
+
+```bash
+# 1. 安装 Docker
+curl -fsSL https://get.docker.com | sh
+
+# 2. 构建镜像
+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 \
+  -v $(pwd)/qiniu-data:/root/.qiniu \
+  qiniu-feishu-bot
+
+# 4. 查看日志
+docker logs -f qiniu-bot
+```
+
+---
+
+## 🍎 macOS 部署
+
+### 方式 A：一键脚本
+
+```bash
+# 1. 下载项目
+git clone <repo-url> qiniu-feishu-bot
+cd qiniu-feishu-bot
+
+# 2. 运行启动脚本
+chmod +x start.sh
+./start.sh
+```
+
+### 方式 B：Homebrew 安装 Node.js
+
+```bash
+# 1. 安装 Node.js
+brew install node@18
+
+# 2. 安装依赖
+npm install
+
+# 3. 配置
+cp .env.example .env
+nano .env
+
+cp config/qiniu-config.json.example config/qiniu-config.json
+nano config/qiniu-config.json
+
+# 4. 启动
+npm start
+
+# 5. 后台运行（可选）
+brew install pm2
+pm2 start src/index.js --name qiniu-bot
+pm2 save
+pm2 startup
+```
+
+---
+
+## 🪟 Windows 部署
+
+### 方式 A：一键启动（推荐）
+
+```powershell
+# 1. 下载项目
+# 下载 ZIP 或 git clone
+git clone <repo-url> qiniu-feishu-bot
+cd qiniu-feishu-bot
+
+# 2. 双击运行
+start.bat
+
+# 脚本会自动：
+# - 检查 Node.js
+# - 创建配置文件
+# - 安装依赖
+# - 启动服务
+```
+
+### 方式 B：手动部署
+
+```powershell
+# 1. 安装 Node.js
+# 下载：https://nodejs.org/
+# 验证：node --version
+
+# 2. 安装依赖
+npm install
+
+# 3. 配置环境变量
+copy .env.example .env
+notepad .env
+
+# 4. 配置七牛云
+mkdir config
+copy config\qiniu-config.json.example config\qiniu-config.json
+notepad config\qiniu-config.json
+
+# 5. 启动服务
+npm start
+```
+
+### 方式 C：作为 Windows 服务运行
+
+使用 **NSSM** (Non-Sucking Service Manager)：
+
+```powershell
+# 1. 下载 NSSM
+# https://nssm.cc/download
+
+# 2. 安装服务
+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"
+
+# 4. 启动服务
+nssm start QiniuBot
+
+# 5. 管理命令
+nssm stop QiniuBot
+nssm restart QiniuBot
+nssm remove QiniuBot  # 删除服务
+```
+
+### 方式 D：Docker Desktop
+
+```powershell
+# 1. 安装 Docker Desktop
+# https://www.docker.com/products/docker-desktop
+
+# 2. 构建镜像
+docker build -t qiniu-feishu-bot .
+
+# 3. 运行容器
+docker run -d ^
+  --name qiniu-bot ^
+  -p 3000:3000 ^
+  --restart unless-stopped ^
+  --env-file .env ^
+  -v %cd%\config:/app/config ^
+  qiniu-feishu-bot
+
+# 4. 查看日志
+docker logs -f qiniu-bot
+```
+
+---
+
+## 🌐 配置公网访问
+
+### 云服务器（推荐生产环境）
+
+**阿里云/腾讯云 ECS：**
+
+1. 购买云服务器（最低配置：1 核 1G）
+2. 配置安全组，开放端口 3000
+3. 部署应用
+4. 配置域名和 HTTPS（可选但推荐）
+
+**Nginx 反向代理：**
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location /feishu/event {
+        proxy_pass http://localhost:3000;
+        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;
+    }
+}
+```
+
+### 内网穿透（测试用）
+
+**ngrok：**
+
+```bash
+# 下载：https://ngrok.com/
+ngrok http 3000
+
+# 复制生成的 https 地址到飞书事件订阅
+```
+
+**cloudflared：**
+
+```bash
+# 下载：https://github.com/cloudflare/cloudflared/releases
+cloudflared tunnel --url http://localhost:3000
+```
+
+**cpolar（国内推荐）：**
+
+```bash
+# 官网：https://www.cpolar.com/
+cpolar http 3000
+```
+
+---
+
+## 📝 配置文件说明
+
+### .env 文件
+
+```env
+# 飞书配置（从飞书开放平台获取）
+FEISHU_APP_ID=cli_xxxxxxxxxx
+FEISHU_APP_SECRET=xxxxxxxxxxxxxx
+FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxx
+FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxx
+
+# 七牛云配置
+QINIU_ACCESS_KEY=xxxxxxxxxxxxxx
+QINIU_SECRET_KEY=xxxxxxxxxxxxxx
+QINIU_BUCKET=your-bucket-name
+QINIU_REGION=z0
+QINIU_DOMAIN=https://your-cdn.com
+
+# 服务配置
+PORT=3000
+NODE_ENV=production
+```
+
+### 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"
+    }
+  }
+}
+```
+
+---
+
+## ✅ 验证部署
+
+### 1. 检查服务状态
+
+```bash
+# Linux/macOS
+curl http://localhost:3000/health
+
+# Windows PowerShell
+Invoke-WebRequest http://localhost:3000/health
+```
+
+应返回：`{"status":"ok",...}`
+
+### 2. 测试飞书消息
+
+1. 在飞书中找到机器人
+2. 发送任意消息
+3. 应收到交互式卡片
+
+### 3. 测试上传
+
+```
+/upload --original default
+[附上一个文件]
+```
+
+---
+
+## 🔧 故障排查
+
+### 端口被占用
+
+```bash
+# Linux/macOS
+lsof -i :3000
+kill -9 <PID>
+
+# Windows
+netstat -ano | findstr :3000
+taskkill /PID <PID> /F
+```
+
+### 权限问题
+
+```bash
+# Linux/macOS
+chmod +x start.sh
+chmod -R 755 .
+
+# Windows
+# 以管理员身份运行 start.bat
+```
+
+### 依赖安装失败
+
+```bash
+# 清除缓存重试
+npm cache clean --force
+npm install
+
+# 使用淘宝镜像
+npm config set registry https://registry.npmmirror.com
+npm install
+```
+
+---
+
+## 📞 获取帮助
+
+- 查看日志：`docker logs qiniu-bot` 或查看控制台输出
+- 检查配置：确保 `.env` 和 `qiniu-config.json` 正确
+- 网络问题：确认防火墙开放端口 3000
+
+---
+
+**🍙 祝你部署顺利！**