daoqi/qiniu-feishu-bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

清理调试代码和废弃文件

Browse Source 
清理内容：
- 删除废弃文档：DEPLOY.md, FEISHU_PERMISSIONS.md, NGINX.md, WEBSOCKET.md, WINDOWS.md
- 删除废弃服务文件：qiniu-bot.service, start.bat, start.sh
- 删除废弃代码目录：src/cards/
- 优化日志：仅非生产环境输出调试日志
- 保留核心文件：Dockerfile, .env*, README.md, pm2.config.cjs

生产环境设置：
- NODE_ENV=production 时不输出调试日志
- NODE_ENV=development 时输出完整日志
This commit is contained in:
饭团
2026-03-06 12:22:31 +08:00
parent 875df38c0c
commit a18ddc028c
12 changed files with 10 additions and 2069 deletions
Download Patch File Download Diff File Expand all files Collapse all files

432
DEPLOY.md
View File

@@ -1,432 +0,0 @@
# 七牛云上传机器人 - 跨平台部署指南
支持 **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
---
**🍙 祝你部署顺利！**

131
FEISHU_PERMISSIONS.md
View File

@@ -1,131 +0,0 @@
# 飞书权限配置指南
## 📋 正确的权限配置
在飞书开放平台创建应用后，需要配置以下权限：
### 必选权限
| 权限代码 | 说明 |
|---------|------|
| `im:message` | 发送消息 |
| `im:message:readonly` | 读取消息 |
| `aily:file:read` | 读取文件 |
| `aily:file:write` | 写入文件 |
### 权限配置示例
```json
{
"scopes": {
"tenant": [
"im:message",
"im:message:readonly",
"aily:file:read",
"aily:file:write"
],
"user": [
"aily:file:read",
"aily:file:write"
]
}
}
```
---
## ⚠️ 注意事项
### 权限说明
- **`im:message`** - 允许机器人发送消息到聊天
- **`im:message:readonly`** - 允许机器人读取接收到的消息
- **`aily:file:read`** - 允许机器人读取和下载文件
- **`aily:file:write`** - 允许机器人上传文件
### 为什么需要这些权限？
- 接收飞书消息需要 `im:message` + `im:message:readonly`
- 下载用户上传的文件需要 `aily:file:read`
- （本应用不需要 `aily:file:write`，因为文件是上传到七牛云，不是飞书云空间）
---
## 🔧 配置步骤
### 1. 进入权限管理
1. 访问 [飞书开放平台](https://open.feishu.cn/)
2. 进入你的应用管理页面
3. 点击左侧菜单"权限管理"
### 2. 添加权限
点击"添加权限"，搜索并添加：
1. **im:message**
- 搜索"消息"
- 勾选"发送消息"和"读取消息"
- 点击"确定"
2. **im:resource**
- 搜索"资源"
- 勾选"访问消息中的资源"
- 点击"确定"
### 3. 提交审核
部分权限需要管理员审核：
- 点击"申请权限"
- 填写申请理由（例如：用于文件上传功能）
- 提交等待审核（通常很快）
---
## 📝 权限说明
### im:message
**作用：** 允许机器人发送和接收消息
**包含能力：**
- 接收用户发送给机器人的消息
- 接收群组中 @ 机器人的消息
- 向用户发送消息
- 向群组发送消息
- **接收文件消息**（文件作为一种消息类型）
### im:resource
**作用：** 允许机器人访问消息中的资源
**包含能力：**
- 下载消息中的文件
- 下载消息中的图片
- 下载消息中的视频
- 访问其他附件资源
---
## ✅ 验证权限
配置完成后，在应用管理页面的"权限管理"中应该看到：
```
✅ im:message - 已申请
✅ im:resource - 已申请
```
如果显示"审核中"，需要等待管理员审核通过。
---
## 🔗 相关文档
- [飞书开放平台 - 权限管理](https://open.feishu.cn/document/ukTMukTMukTM/uEjNwUjLxYDM14SM2ATN)
- [消息事件订阅](https://open.feishu.cn/document/ukTMukTMukTM/uYjNwUjL2YDM14iN2ATN)
- [资源访问 API](https://open.feishu.cn/document/ukTMukTMukTM/uQjNwUjLyYDM14iN2ATN)
---
**🍙 祝你配置顺利！**

427
NGINX.md
View File

@@ -1,427 +0,0 @@
# Nginx 部署指南
## 🎯 特点
- ✅ **不占用 80/443 端口** - Node.js 应用运行在 3000 端口
- ✅ **多域名支持** - 可与其他应用共享 Nginx
- ✅ **反向代理** - 飞书回调通过 Nginx 转发到应用
- ✅ **HTTPS 支持** - 可选配置 SSL 证书
---
## 📋 完整部署流程
### 1️⃣ 准备服务器
**推荐配置：**
- CPU: 1 核
- 内存：1GB
- 存储：10GB
- 系统：Ubuntu 20.04+ / CentOS 7+
### 2️⃣ 安装 Node.js
```bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# CentOS/RHEL
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs
# 验证
node --version # 应 >= 18
npm --version
```
### 3️⃣ 克隆项目
```bash
git clone -b master http://git.joywaygames.cn:3000/daoqi/qiniu-feishu-bot.git
cd qiniu-feishu-bot
```
### 4️⃣ 配置应用
```bash
# 复制配置文件
cp .env.example .env
cp config/qiniu-config.json.example config/qiniu-config.json
# 编辑飞书配置
nano .env
```
**`.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
```
### 5️⃣ 安装依赖
```bash
npm install
```
### 6️⃣ 使用 PM2 管理进程
```bash
# 安装 PM2
npm install -g pm2
# 启动应用
pm2 start src/index.js --name qiniu-bot
# 设置开机自启
pm2 startup
pm2 save
# 查看状态
pm2 status
pm2 logs qiniu-bot
```
---
## 🔧 Nginx 配置
### 安装 Nginx
```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y nginx
# CentOS/RHEL
sudo yum install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx
```
### 配置 Nginx
```bash
sudo nano /etc/nginx/sites-available/qiniu-bot
# 或 CentOS: sudo nano /etc/nginx/conf.d/qiniu-bot.conf
```
**配置内容：**
### 方式一：独立域名（推荐）
```nginx
server {
listen 80;
server_name qiniu.your-domain.com; # 替换为你的域名
# 日志
access_log /var/log/nginx/qiniu-bot-access.log;
error_log /var/log/nginx/qiniu-bot-error.log;
# 飞书事件回调
location /feishu/event {
proxy_pass http://127.0.0.1:3000/feishu/event;
proxy_http_version 1.1;
# 保留原始请求头
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;
# 飞书签名验证需要这些头
proxy_set_header X-Feishu-Request-Timestamp $http_x_feishu_request_timestamp;
proxy_set_header X-Feishu-Request-Nonce $http_x_feishu_request_nonce;
proxy_set_header X-Feishu-Request-Signature $http_x_feishu_request_signature;
# 超时设置
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
# 健康检查
location /health {
proxy_pass http://127.0.0.1:3000/health;
access_log off;
}
}
```
### 方式二：子路径（与其他应用共享域名）
```nginx
server {
listen 80;
server_name your-domain.com;
# 七牛云上传机器人（子路径）
location /qiniu/feishu/event {
proxy_pass http://127.0.0.1:3000/feishu/event;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Feishu-Request-Timestamp $http_x_feishu_request_timestamp;
proxy_set_header X-Feishu-Request-Nonce $http_x_feishu_request_nonce;
proxy_set_header X-Feishu-Request-Signature $http_x_feishu_request_signature;
}
# 其他应用...
location /other-app {
proxy_pass http://127.0.0.1:4000;
}
}
```
> **注意：** 如果使用子路径，需要在飞书开放平台配置请求地址为 `https://your-domain.com/qiniu/feishu/event`
### 启用配置
```bash
# Ubuntu/Debian
sudo ln -s /etc/nginx/sites-available/qiniu-bot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
# CentOS/RHEL
sudo nginx -t
sudo systemctl restart nginx
```
### 配置防火墙
```bash
# Ubuntu (UFW)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw reload
# CentOS (Firewall)
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload
# 云服务器安全组
# 在阿里云/腾讯云控制台开放 80 和 443 端口
```
---
## 🔒 配置 HTTPS（推荐）
### 使用 Let's Encrypt 免费证书
```bash
# 安装 Certbot
sudo apt-get install -y certbot python3-certbot-nginx # Ubuntu
sudo yum install -y certbot python3-certbot-nginx # CentOS
# 获取证书
sudo certbot --nginx -d your-domain.com
# 自动续期
sudo crontab -e
# 添加：0 3 * * * certbot renew --quiet
```
**HTTPS 配置（Certbot 自动配置后）：**
```nginx
server {
listen 443 ssl http2;
server_name your-domain.com;
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
# SSL 优化
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
location /feishu/event {
proxy_pass http://127.0.0.1:3000/feishu/event;
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;
proxy_set_header X-Feishu-Request-Timestamp $http_x_feishu_request_timestamp;
proxy_set_header X-Feishu-Request-Nonce $http_x_feishu_request_nonce;
proxy_set_header X-Feishu-Request-Signature $http_x_feishu_request_signature;
}
location /health {
proxy_pass http://127.0.0.1:3000/health;
access_log off;
}
}
# HTTP 重定向到 HTTPS
server {
listen 80;
server_name your-domain.com;
return 301 https://$server_name$request_uri;
}
```
---
## ✅ 验证部署
### 1. 检查服务状态
```bash
# 检查 Node.js 应用
pm2 status
# 检查 Nginx
sudo systemctl status nginx
# 检查端口
sudo netstat -tlnp | grep -E ':(80|443|3000)'
```
### 2. 测试健康检查
```bash
curl http://localhost/health
curl http://your-domain.com/health
```
应返回：`{"status":"ok",...}`
### 3. 测试飞书回调
在飞书开放平台重新配置事件订阅：
- **请求地址**：`https://your-domain.com/feishu/event`
- 点击"保存"，应显示验证成功
---
## 🔧 故障排查
### Nginx 启动失败
```bash
# 检查配置
sudo nginx -t
# 查看错误日志
sudo tail -f /var/log/nginx/error.log
```
### 飞书回调失败
```bash
# 查看应用日志
pm2 logs qiniu-bot
# 查看 Nginx 日志
sudo tail -f /var/log/nginx/qiniu-bot-error.log
# 测试本地访问
curl -X POST http://localhost:3000/feishu/event \
-H "Content-Type: application/json" \
-d '{"type":"url_verification","challenge":"test"}'
```
### 端口被占用
```bash
# 查找占用端口的进程
sudo lsof -i :80
sudo lsof -i :3000
# 停止冲突服务
sudo systemctl stop apache2 # 如果 Apache 占用 80
```
### 权限问题
```bash
# 确保 Nginx 能访问
sudo chown -R www-data:www-data /var/log/nginx/
sudo chmod 644 /etc/nginx/sites-available/qiniu-bot
```
---
## 📝 日常维护
### 查看日志
```bash
# 应用日志
pm2 logs qiniu-bot
# Nginx 日志
sudo tail -f /var/log/nginx/qiniu-bot-access.log
sudo tail -f /var/log/nginx/qiniu-bot-error.log
```
### 重启服务
```bash
# 重启应用
pm2 restart qiniu-bot
# 重启 Nginx
sudo systemctl restart nginx
# 全部重启
pm2 restart all
sudo systemctl restart nginx
```
### 更新代码
```bash
cd /path/to/qiniu-feishu-bot
git pull
npm install # 如果有新依赖
pm2 restart qiniu-bot
```
---
## 📊 性能优化
### Nginx 优化
```nginx
# 在 http 块中添加
worker_processes auto;
worker_connections 1024;
# 启用压缩
gzip on;
gzip_types text/plain application/json;
```
### Node.js 优化
```bash
# 使用集群模式（可选）
pm2 start src/index.js --name qiniu-bot -i max
```
---
**🍙 祝你部署顺利！**

213
WEBSOCKET.md
View File

@@ -1,213 +0,0 @@
# WebSocket 长连接模式配置指南
## 📡 两种模式对比
| 特性 | HTTP 回调 | WebSocket 长连接 |
|------|----------|-----------------|
| 公网 IP | ✅ 需要 | ❌ 不需要 |
| 域名 | ✅ 需要 | ❌ 不需要 |
| HTTPS | ✅ 推荐 | ❌ 不需要 |
| 内网部署 | ❌ 困难 | ✅ 简单 |
| 实时性 | 好 | 更好 |
| 配置复杂度 | 简单 | 中等 |
---
## 🚀 配置 WebSocket 模式
### 1️⃣ 飞书开放平台配置
1. 访问 https://open.feishu.cn/
2. 进入你的应用管理页面
3. 点击"事件订阅"
4. **选择"WebSocket 长连接"方式**
5. 开启"启用事件订阅"
6. 添加订阅事件：
- `im.message.receive_v1` - 接收消息
7. 保存并复制：
- Verification Token
- Encrypt Key
### 2️⃣ 修改配置文件
编辑 `.env` 文件：
```env
# 飞书配置
FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxx
# 设置为 WebSocket 模式
FEISHU_MODE=websocket
# 七牛云配置
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️⃣ 安装依赖
```bash
cd /path/to/qiniu-feishu-bot
npm install
```
### 4️⃣ 启动服务
```bash
# 使用 PM2
pm2 restart qiniu-bot
# 或直接启动
npm start
```
### 5️⃣ 查看日志
```bash
# PM2 日志
pm2 logs qiniu-bot
# 应该看到：
# 🚀 七牛云上传机器人启动 (WebSocket 长连接模式)
# 📡 WebSocket 已启动
# ✅ WebSocket 连接成功
```
---
## 🔧 故障排查
### WebSocket 连接失败
**检查配置：**
```bash
# 验证 .env 配置
cat .env | grep FEISHU
# 确认 FEISHU_MODE=websocket
```
**查看日志：**
```bash
pm2 logs qiniu-bot --lines 100
```
**常见错误：**
1. **验证失败**
- 检查 Verification Token 是否正确
- 检查 Encrypt Key 是否正确
2. **连接被拒绝**
- 检查防火墙是否允许出站连接
- 确认服务器能访问外网
3. **认证失败**
- 检查 App ID 和 App Secret
---
## 📊 监控 WebSocket 状态
### 健康检查
```bash
curl http://localhost:3030/health
```
返回：
```json
{
"status": "ok",
"timestamp": "2026-03-05T08:00:00.000Z",
"mode": "websocket",
"port": 3030
}
```
### 连接状态
查看 PM2 日志中的连接状态：
```bash
pm2 logs qiniu-bot | grep -E "(WebSocket|连接|open|close)"
```
---
## 🔄 切换模式
### 从 HTTP 切换到 WebSocket
```bash
# 1. 修改 .env
nano .env
# 设置 FEISHU_MODE=websocket
# 2. 重启服务
pm2 restart qiniu-bot
# 3. 验证
pm2 logs qiniu-bot
```
### 从 WebSocket 切换到 HTTP
```bash
# 1. 修改 .env
nano .env
# 设置 FEISHU_MODE=http
# 2. 重启服务
pm2 restart qiniu-bot
# 3. 在飞书开放平台改回 HTTP 回调方式
```
---
## 💡 最佳实践
### WebSocket 模式适用场景
- ✅ 内网服务器（无公网 IP）
- ✅ 开发测试环境
- ✅ 不想配置域名和 HTTPS
- ✅ 需要更好的实时性
### HTTP 回调模式适用场景
- ✅ 云服务器（有公网 IP）
- ✅ 生产环境
- ✅ 已有域名和 HTTPS
- ✅ 需要更可控的连接管理
---
## 📝 注意事项
1. **WebSocket 长连接会保持在线状态**
- 确保服务器网络稳定
- 断线会自动重连（5 秒间隔）
2. **两种方式不能同时使用**
- 通过 `FEISHU_MODE` 配置选择
- 飞书开放平台也要对应配置
3. **健康检查始终可用**
- 无论哪种模式，`/health` 端点都工作
- 可用于监控服务状态
---
**🍙 祝你使用愉快！**

284
WINDOWS.md
View File

@@ -1,284 +0,0 @@
# 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` 窗口，重新运行
---
**🍙 祝你使用愉快！**

20
qiniu-bot.service
View File

@@ -1,20 +0,0 @@
[Unit]
Description=七牛云上传飞书机器人
After=network.target
[Service]
Type=simple
User=admin
WorkingDirectory=/home/admin/.openclaw/workspace/qiniu-feishu-bot
Environment=NODE_ENV=production
ExecStart=/usr/bin/node src/index.js
Restart=always
RestartSec=10
# 日志
StandardOutput=journal
StandardError=journal
SyslogIdentifier=qiniu-bot
[Install]
WantedBy=multi-user.target

185
src/cards/config-card.js
View File

@@ -1,185 +0,0 @@
/**
* 配置交互卡片模板
*/
class ConfigCard {
static create(configData) {
const bucketsText = Object.entries(configData.buckets || {})
.map(([name, bucket]) => {
return `**🪣 [${name}]**\n` +
`• 存储桶：${bucket.bucket}\n` +
`• 区域：${bucket.region}\n` +
`• 域名：${bucket.domain}\n` +
`• AccessKey: ${bucket.accessKey}`;
})
.join('\n\n');
return {
"config": {
"wide_screen_mode": true
},
"header": {
"template": "grey",
"title": {
"content": "⚙️ 七牛云配置",
"tag": "plain_text"
}
},
"elements": [
{
"tag": "div",
"text": {
"content": bucketsText || '暂无配置，请先添加存储桶配置。',
"tag": "lark_md"
}
},
{
"tag": "hr"
},
{
"tag": "div",
"text": {
"content": "**💡 修改配置**\n\n使用命令：`/config set <key> <value>`\n\n示例：\n`/config set default.domain https://new-cdn.com`",
"tag": "lark_md"
}
},
{
"tag": "action",
"actions": [
{
"tag": "button",
"text": {
"content": "📤 上传文件",
"tag": "plain_text"
},
"type": "primary",
"value": {
"action": "upload_file",
"type": "upload"
}
},
{
"tag": "button",
"text": {
"content": "❓ 帮助",
"tag": "plain_text"
},
"type": "default",
"value": {
"action": "help",
"type": "help"
}
}
]
}
]
};
}
static createEditForm(bucketName) {
return {
"config": {
"wide_screen_mode": true
},
"header": {
"template": "blue",
"title": {
"content": `✏️ 编辑配置 - ${bucketName}`,
"tag": "plain_text"
}
},
"elements": [
{
"tag": "input",
"label": {
"content": "AccessKey",
"tag": "plain_text"
},
"placeholder": {
"content": "请输入七牛云 AccessKey",
"tag": "plain_text"
},
"name": "access_key"
},
{
"tag": "input",
"label": {
"content": "SecretKey",
"tag": "plain_text"
},
"placeholder": {
"content": "请输入七牛云 SecretKey",
"tag": "plain_text"
},
"name": "secret_key"
},
{
"tag": "input",
"label": {
"content": "存储桶名称",
"tag": "plain_text"
},
"placeholder": {
"content": "例如：my-bucket",
"tag": "plain_text"
},
"name": "bucket_name"
},
{
"tag": "input",
"label": {
"content": "区域",
"tag": "plain_text"
},
"placeholder": {
"content": "z0/z1/z2/na0/as0",
"tag": "plain_text"
},
"name": "region"
},
{
"tag": "input",
"label": {
"content": "CDN 域名",
"tag": "plain_text"
},
"placeholder": {
"content": "https://cdn.example.com",
"tag": "plain_text"
},
"name": "domain"
},
{
"tag": "action",
"actions": [
{
"tag": "button",
"text": {
"content": "💾 保存",
"tag": "plain_text"
},
"type": "primary",
"value": {
"action": "save_config",
"bucket": bucketName
}
},
{
"tag": "button",
"text": {
"content": "❌ 取消",
"tag": "plain_text"
},
"type": "default",
"value": {
"action": "cancel"
}
}
]
}
]
};
}
}
module.exports = { ConfigCard };

230
src/cards/upload-card.js
View File

@@ -1,230 +0,0 @@
/**
* 上传交互卡片模板
*/
class UploadCard {
static create() {
return {
"config": {
"wide_screen_mode": true
},
"header": {
"template": "blue",
"title": {
"content": "🍙 七牛云上传助手",
"tag": "plain_text"
}
},
"elements": [
{
"tag": "div",
"text": {
"content": "**📤 快速上传文件到七牛云**\n\n支持指定路径、多存储桶、自动 CDN 刷新",
"tag": "lark_md"
}
},
{
"tag": "hr"
},
{
"tag": "div",
"text": {
"content": "**💡 使用方式**\n\n• 直接发送文件给我\n• 或使用命令：`/upload [路径] [存储桶]`\n• 支持 `--original` 使用原文件名",
"tag": "lark_md"
}
},
{
"tag": "hr"
},
{
"tag": "action",
"actions": [
{
"tag": "button",
"text": {
"content": "📎 选择文件上传",
"tag": "plain_text"
},
"type": "primary",
"value": {
"action": "upload_file",
"type": "upload"
}
},
{
"tag": "button",
"text": {
"content": "⚙️ 配置",
"tag": "plain_text"
},
"type": "default",
"value": {
"action": "config",
"type": "config"
}
},
{
"tag": "button",
"text": {
"content": "❓ 帮助",
"tag": "plain_text"
},
"type": "default",
"value": {
"action": "help",
"type": "help"
}
}
]
}
]
};
}
static createUploading(fileName) {
return {
"config": {
"wide_screen_mode": true
},
"header": {
"template": "blue",
"title": {
"content": "📤 上传中...",
"tag": "plain_text"
}
},
"elements": [
{
"tag": "div",
"text": {
"content": `**文件：** ${fileName}\n\n正在上传到七牛云，请稍候...`,
"tag": "lark_md"
}
},
{
"tag": "progress_bar",
"tag": "div",
"text": {
"content": "上传进度",
"tag": "plain_text"
},
"value": 50,
"color": "blue"
}
]
};
}
static createSuccess(result) {
return {
"config": {
"wide_screen_mode": true
},
"header": {
"template": "green",
"title": {
"content": "✅ 上传成功",
"tag": "plain_text"
}
},
"elements": [
{
"tag": "div",
"text": {
"content": `**📦 文件：** ${result.key}\n\n` +
`**🔗 链接：** [点击查看](${result.url})\n\n` +
`**🪣 存储桶：** ${result.bucket || 'default'}`,
"tag": "lark_md"
}
},
{
"tag": "hr"
},
{
"tag": "action",
"actions": [
{
"tag": "button",
"text": {
"content": "🔗 复制链接",
"tag": "plain_text"
},
"type": "default",
"value": {
"action": "copy_link",
"url": result.url
}
},
{
"tag": "button",
"text": {
"content": "📤 继续上传",
"tag": "plain_text"
},
"type": "primary",
"value": {
"action": "upload_file",
"type": "upload"
}
}
]
}
]
};
}
static createError(error) {
return {
"config": {
"wide_screen_mode": true
},
"header": {
"template": "red",
"title": {
"content": "❌ 上传失败",
"tag": "plain_text"
}
},
"elements": [
{
"tag": "div",
"text": {
"content": `**错误信息：**\n${error.message}\n\n请检查配置或联系管理员。`,
"tag": "lark_md"
}
},
{
"tag": "action",
"actions": [
{
"tag": "button",
"text": {
"content": "🔄 重试",
"tag": "plain_text"
},
"type": "primary",
"value": {
"action": "upload_file",
"type": "upload"
}
},
{
"tag": "button",
"text": {
"content": "⚙️ 检查配置",
"tag": "plain_text"
},
"type": "default",
"value": {
"action": "config",
"type": "config"
}
}
]
}
]
};
}
}
module.exports = { UploadCard };

8
src/feishu-api.js
View File

@@ -8,10 +8,12 @@ const path = require('path');
const https = require('https'); const https = require('https');
const lark = require('@larksuiteoapi/node-sdk'); const lark = require('@larksuiteoapi/node-sdk');
// 日志函数 // 生产环境日志（仅关键信息）
function log(...args) { function log(...args) {
const timestamp = new Date().toISOString(); if (process.env.NODE_ENV !== 'production') {
console.log(`[${timestamp}] [FeishuAPI]`, ...args); const timestamp = new Date().toISOString();
console.log(`[${timestamp}] [FeishuAPI]`, ...args);
}
} }
class FeishuAPI { class FeishuAPI {

7
src/index.js
View File

@@ -18,9 +18,12 @@ const PORT = process.env.PORT || 3030;
app.use(express.json()); app.use(express.json());
// 生产环境日志（仅关键信息）
function log(...args) { function log(...args) {
const timestamp = new Date().toISOString(); if (process.env.NODE_ENV !== 'production') {
console.log(`[${timestamp}]`, ...args); const timestamp = new Date().toISOString();
console.log(`[${timestamp}]`, ...args);
}
} }
// 加载完整配置 // 加载完整配置

73
start.bat
View File

@@ -1,73 +0,0 @@
@echo off
REM 七牛云上传机器人 - Windows 启动脚本
echo ========================================
echo 🍙 七牛云上传机器人 - Windows 版
echo ========================================
echo.
REM 检查 Node.js
node --version >nul 2>&1
if errorlevel 1 (
echo ❌ 未检测到 Node.js，请先安装 Node.js 18+
echo 下载地址：https://nodejs.org/
pause
exit /b 1
)
echo ✅ Node.js 已安装
REM 检查配置文件
if not exist ".env" (
echo ⚠️ 未找到 .env 文件，正在创建...
copy .env.example .env >nul
echo.
echo ⚠️ 请先编辑 .env 文件，填入飞书和七牛云配置
echo 按任意键打开 .env 文件...
pause
notepad .env
echo.
echo 配置完成后按任意键继续...
pause
)
REM 检查七牛云配置
if not exist "config\qiniu-config.json" (
echo ⚠️ 未找到七牛云配置文件，正在创建...
if not exist "config" mkdir config
copy config\qiniu-config.json.example config\qiniu-config.json >nul
echo.
echo ⚠️ 请先编辑 config\qiniu-config.json 文件，填入七牛云配置
echo 按任意键打开配置文件...
pause
notepad config\qiniu-config.json
echo.
echo 配置完成后按任意键继续...
pause
)
REM 检查依赖
if not exist "node_modules" (
echo 📦 正在安装依赖...
call npm install
if errorlevel 1 (
echo ❌ 依赖安装失败
pause
exit /b 1
)
echo ✅ 依赖安装完成
echo.
)
REM 启动服务
echo.
echo 🚀 正在启动服务...
echo 📍 监听端口：3000
echo 📍 事件地址：https://your-domain.com/feishu/event
echo.
echo 按 Ctrl+C 停止服务
echo.
node src\index.js
pause

69
start.sh
View File

@@ -1,69 +0,0 @@
#!/bin/bash
# 七牛云上传机器人 - Linux/macOS 启动脚本
echo "========================================"
echo " 🍙 七牛云上传机器人"
echo "========================================"
echo ""
# 检查 Node.js
if ! command -v node &> /dev/null; then
echo "❌ 未检测到 Node.js，请先安装 Node.js 18+"
echo "访问：https://nodejs.org/"
exit 1
fi
echo "✅ Node.js 已安装：$(node --version)"
# 检查配置文件
if [ ! -f ".env" ]; then
echo "⚠️ 未找到 .env 文件，正在创建..."
cp .env.example .env
echo ""
echo "⚠️ 请先编辑 .env 文件，填入飞书和七牛云配置"
echo "按任意键打开 .env 文件..."
read -p ""
${EDITOR:-nano} .env
echo ""
echo "配置完成后按任意键继续..."
read -p ""
fi
# 检查七牛云配置
if [ ! -f "config/qiniu-config.json" ]; then
echo "⚠️ 未找到七牛云配置文件，正在创建..."
mkdir -p config
cp config/qiniu-config.json.example config/qiniu-config.json
echo ""
echo "⚠️ 请先编辑 config/qiniu-config.json 文件，填入七牛云配置"
echo "按任意键打开配置文件..."
read -p ""
${EDITOR:-nano} config/qiniu-config.json
echo ""
echo "配置完成后按任意键继续..."
read -p ""
fi
# 检查依赖
if [ ! -d "node_modules" ]; then
echo "📦 正在安装依赖..."
npm install
if [ $? -ne 0 ]; then
echo "❌ 依赖安装失败"
exit 1
fi
echo "✅ 依赖安装完成"
echo ""
fi
# 启动服务
echo ""
echo "🚀 正在启动服务..."
echo "📍 监听端口：3000"
echo "📍 事件地址：https://your-domain.com/feishu/event"
echo ""
echo "按 Ctrl+C 停止服务"
echo ""
node src/index.js