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

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

🚀 快速开始

1. 创建飞书应用

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

2. 配置权限

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

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:readonly",
      "im:resource",
      "im:message.p2p_msg:readonly",
      "cardkit:card:read",
      "cardkit:card:write",
      "cardkit:template:read",
      "aily:file:read",
      "aily:file:write"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:message.p2p_msg:get_as_user"
    ]
  }
}

权限代码	说明
im:message	发送消息
im:message:readonly	读取消息
im:resource	关键：访问消息中的资源（文件）
im:message.p2p_msg:readonly	读取私聊消息
cardkit:*	发送交互式卡片
aily:file:*	文件读写

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

3. 配置事件订阅

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

💡 提示： 也可以使用 WebSocket 长连接模式（不需要公网 IP），在 .env 中设置 FEISHU_MODE=websocket

4. 配置机器人

1. 进入"机器人"页面
2. 开启"启用机器人"
3. 配置机器人名称和头像

5. 安装应用

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

---

📦 部署

🐳 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

🐧 Linux / 🍎 macOS

# 安装依赖
npm install

# 复制环境变量
cp .env.example .env

# 编辑配置
nano .env

# 启动服务（使用 PM2）
pm2 start pm2.config.cjs

# 查看日志
pm2 logs qiniu-bot

🪟 Windows

# 安装依赖
npm install

# 复制环境变量
copy .env.example .env

# 编辑配置
notepad .env

# 启动服务（使用 PM2）
pm2 start pm2.config.cjs

# 查看日志
pm2 logs qiniu-bot

---

⚙️ 配置

环境变量 (.env)

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

# 飞书事件接收模式：http (HTTP 回调) 或 websocket (WebSocket 长连接)
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"
    }
  },
  "uploadPaths": {
    "原文件名": "",
    "ipa": "/ipa/gamehall_jinxianv2.ipa"
  },
  "uploadProfiles": {
    "默认": {
      "bucket": "default",
      "path": ""
    },
    "IPA 上传": {
      "bucket": "default",
      "path": "ipa"
    }
  }
}

---

💡 使用方式

常用命令

📤 上传命令

命令	说明
/upload 或 /u	开始上传流程
/help 或 /qh	查看详细帮助

⚙️ 存储桶配置 (/config 或 /qc)

命令	说明
/config list	查看所有存储桶配置
/config add <名称> <accessKey> <secretKey> <bucket> <region> <domain>	添加存储桶配置
/config remove <名称>	删除存储桶配置
/config set <键路径> <值>	修改配置项

示例：

/config add mybucket xxxxxx yyyyyy my-bucket z0 https://cdn.example.com
/config remove mybucket

📁 预设路径 (/path)

命令	说明
/path list	查看所有预设路径
/path add <名称> <路径>	添加预设路径
/path remove <名称>	删除预设路径

示例：

/path add backup /backup/
/path add ipa /ipa/gamehall_jinxian2.ipa
/path remove backup

📤 上传配置模板 (/profile)

命令	说明
/profile list	查看所有上传配置模板
/profile add <名称> <存储桶> [路径键名]	添加上传配置模板
/profile remove <名称>	删除上传配置模板

示例：

/profile add 默认上传 default
/profile add IPA 上传 default ipa
/profile remove IPA 上传

使用流程

方式 1：选择配置 → 发送文件

1. 发送 /upload
2. 选择上传配置
3. 发送文件
4. 确认上传

方式 2：发送文件 → 选择配置

1. 直接发送文件
2. 选择上传配置
3. 确认上传

---

📁 项目结构

qiniu-feishu-bot/
├── src/
│   ├── index.js              # 主入口
│   ├── feishu-api.js         # 飞书 API 封装
│   └── qiniu-uploader.js     # 七牛云上传
├── config/
│   └── qiniu-config.json     # 七牛云配置
├── .env                      # 环境变量
├── .env.example              # 环境变量示例
├── .env.production           # 生产环境配置
├── .gitignore
├── Dockerfile
├── package.json
├── pm2.config.cjs            # PM2 配置
├── README.md                 # 项目说明
└── FEISHU_SCOPES.md          # 飞书权限配置

---

🔧 故障排查

上传失败

1. 检查七牛云配置是否正确
2. 确认存储桶区域代码匹配
3. 检查 AccessKey/SecretKey 权限
4. 在七牛云控制台关闭存储桶的"防覆盖"设置

消息无响应

1. 检查事件订阅配置
2. 确认服务器可被飞书访问（HTTP 模式需要公网 IP）
3. 查看日志：pm2 logs qiniu-bot
4. 检查飞书应用权限是否已授权

文件下载失败

确保已添加 im:resource 权限，该权限用于访问消息中的文件资源。

---

📝 许可证

MIT