七牛云上传 - 飞书独立应用

基于飞书交互卡片的七牛云文件上传工具，不依赖 OpenClaw。

🚀 快速开始

1. 创建飞书应用

1. 访问 飞书开放平台
2. 登录企业管理员账号
3. 点击"创建应用" → "自建应用"
4. 填写应用信息：
   • 应用名称：七牛云上传助手
   • 应用图标：🍙
5. 进入应用管理页面

2. 配置权限

在"权限管理"中添加以下权限：

{
  "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	写入文件

详细权限配置请查看 FEISHU_PERMISSIONS.md

3. 配置事件订阅

方式一：HTTP 回调（默认）

1. 进入"事件订阅"页面
2. 选择 "HTTP 回调" 方式
3. 开启"启用事件订阅"
4. 填写请求地址：https://your-domain.com/feishu/event
5. 配置订阅事件：
   • im.message.receive_v1 - 接收消息
6. 保存后复制 Verification Token 和 Encrypt Key

方式二：WebSocket 长连接（内网推荐）

1. 进入"事件订阅"页面
2. 选择 "WebSocket 长连接" 方式
3. 开启"启用事件订阅"
4. 配置订阅事件：
   • im.message.receive_v1 - 接收消息
5. 保存后复制 Verification Token 和 Encrypt Key
6. 在 .env 中设置 FEISHU_MODE=websocket

💡 提示： WebSocket 模式不需要公网 IP，适合内网部署。

详细配置请查看 WEBSOCKET.md

4. 配置机器人

1. 进入"机器人"页面
2. 开启"启用机器人"
3. 配置机器人名称和头像
4. 在"消息已读状态"中开启"获取用户已读状态"（可选）

5. 安装应用

1. 进入"版本管理与发布"
2. 点击"发布应用"
3. 在飞书中搜索并添加该机器人

---

📦 部署

🐧 Linux / 🍎 macOS

# 一键启动
chmod +x start.sh
./start.sh

# 或手动部署
npm install
cp .env.example .env
npm start

🪟 Windows

# 双击运行
start.bat

# 或手动部署
npm install
copy .env.example .env
npm start

🐳 Docker（所有平台）

# 构建镜像
docker build -t qiniu-feishu-bot .

# 运行容器
docker run -d \
  --name qiniu-bot \
  -p 3030:3030 \
  --env-file .env \
  -v $(pwd)/config:/app/config \
  qiniu-feishu-bot

🌐 Nginx 反向代理（生产环境推荐）

特点：

• ✅ 不占用 80/443 端口（Node.js 应用使用 3030 端口）
• ✅ 支持多域名部署（与其他应用共享 Nginx）
• ✅ 支持 HTTPS 配置

详细配置请查看 NGINX.md

# 快速配置
sudo nano /etc/nginx/sites-available/qiniu-bot
# 复制 NGINX.md 中的配置
sudo ln -s /etc/nginx/sites-available/qiniu-bot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Nginx 配置示例（多域名）：

# 七牛云上传机器人
server {
    listen 80;
    server_name qiniu.your-domain.com;  # 独立域名
    
    location /feishu/event {
        proxy_pass http://127.0.0.1:3030/feishu/event;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# 其他应用
server {
    listen 80;
    server_name other.your-domain.com;
    
    location / {
        proxy_pass http://127.0.0.1:4000;
    }
}

---

⚙️ 配置

环境变量 (.env)

# 飞书配置
FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxx

# 飞书事件接收模式：http (HTTP 回调) 或 websocket (WebSocket 长连接)
# - http: 需要公网 IP/域名，配置简单
# - websocket: 不需要公网 IP，内网可用
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

七牛云配置 (config/qiniu-config.json)

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

---

💡 使用方式

命令触发

命令	说明
/upload	上传文件到七牛云
/upload --original	使用原文件名上传
/config	管理七牛云配置
/help	查看帮助

卡片交互

发送任意消息给机器人，会收到交互式卡片：

• 📎 选择文件 - 点击后上传附件
• ⚙️ 配置 - 管理七牛云配置
• ❓ 帮助 - 查看使用说明

---

📁 项目结构

qiniu-feishu-bot/
├── src/
│   ├── index.js              # 主入口
│   ├── feishu-api.js         # 飞书 API 封装
│   ├── qiniu-uploader.js     # 七牛云上传
│   └── cards/                # 卡片模板
│       ├── upload-card.js    # 上传卡片
│       └── config-card.js    # 配置卡片
├── config/
│   └── qiniu-config.json.example
├── .env.example
├── .gitignore
├── Dockerfile
├── package.json
├── start.sh                  # Linux/macOS 启动脚本
├── start.bat                 # Windows 启动脚本
├── README.md                 # 项目说明
├── DEPLOY.md                 # 详细部署指南（Linux/macOS/Windows）
├── WINDOWS.md                # Windows 专用指南
├── NGINX.md                  # Nginx 反向代理部署指南
└── WEBSOCKET.md              # WebSocket 长连接模式配置指南

---

🔧 故障排查

上传失败

1. 检查七牛云配置是否正确
2. 确认存储桶区域代码匹配
3. 检查 AccessKey/SecretKey 权限

消息无响应

1. 检查事件订阅配置
2. 确认服务器可被飞书访问（需要公网 IP）
3. 查看日志输出

文件无法覆盖

在七牛云控制台关闭存储桶的"防覆盖"设置。

跨平台问题

• Windows: 查看 WINDOWS.md
• Linux/macOS: 查看 DEPLOY.md

---

📝 许可证

MIT