Initial commit: 七牛云上传飞书机器人
功能： - 飞书交互卡片支持 - 七牛云文件上传 - 自动 CDN 刷新 - 多存储桶配置 - 跨平台部署（Linux/macOS/Windows） - Docker 支持
This commit is contained in:
饭团
211
README.md
Normal file
211
README.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# 七牛云上传 - 飞书独立应用
|
||||
|
||||
基于飞书交互卡片的七牛云文件上传工具，不依赖 OpenClaw。
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 创建飞书应用
|
||||
|
||||
1. 访问 [飞书开放平台](https://open.feishu.cn/)
|
||||
2. 登录企业管理员账号
|
||||
3. 点击"创建应用" → "自建应用"
|
||||
4. 填写应用信息：
|
||||
- 应用名称：七牛云上传助手
|
||||
- 应用图标：🍙
|
||||
5. 进入应用管理页面
|
||||
|
||||
### 2. 配置权限
|
||||
|
||||
在"权限管理"中添加以下权限：
|
||||
|
||||
| 权限 | 说明 |
|
||||
|------|------|
|
||||
| `im:message` | 发送和接收消息 |
|
||||
| `im:file` | 文件上传下载 |
|
||||
| `contact:group:readonly` | 读取群组信息（可选） |
|
||||
|
||||
### 3. 配置事件订阅
|
||||
|
||||
1. 进入"事件订阅"页面
|
||||
2. 开启"启用事件订阅"
|
||||
3. 填写请求地址：`https://your-domain.com/feishu/event`
|
||||
4. 配置订阅事件：
|
||||
- `im.message.receive_v1` - 接收消息
|
||||
- `im.message.group_at_msg.receive_v1` - 群组 @ 消息（可选）
|
||||
5. 保存后复制 Verification Token 和 Encrypt Key
|
||||
|
||||
### 4. 配置机器人
|
||||
|
||||
1. 进入"机器人"页面
|
||||
2. 开启"启用机器人"
|
||||
3. 配置机器人名称和头像
|
||||
4. 在"消息已读状态"中开启"获取用户已读状态"（可选）
|
||||
|
||||
### 5. 安装应用
|
||||
|
||||
1. 进入"版本管理与发布"
|
||||
2. 点击"发布应用"
|
||||
3. 在飞书中搜索并添加该机器人
|
||||
|
||||
---
|
||||
|
||||
## 📦 部署
|
||||
|
||||
### 🐧 Linux / 🍎 macOS
|
||||
|
||||
```bash
|
||||
# 一键启动
|
||||
chmod +x start.sh
|
||||
./start.sh
|
||||
|
||||
# 或手动部署
|
||||
npm install
|
||||
cp .env.example .env
|
||||
npm start
|
||||
```
|
||||
|
||||
### 🪟 Windows
|
||||
|
||||
```cmd
|
||||
# 双击运行
|
||||
start.bat
|
||||
|
||||
# 或手动部署
|
||||
npm install
|
||||
copy .env.example .env
|
||||
npm start
|
||||
```
|
||||
|
||||
### 🐳 Docker（所有平台）
|
||||
|
||||
```bash
|
||||
# 构建镜像
|
||||
docker build -t qiniu-feishu-bot .
|
||||
|
||||
# 运行容器
|
||||
docker run -d \
|
||||
--name qiniu-bot \
|
||||
-p 3000:3000 \
|
||||
--env-file .env \
|
||||
-v $(pwd)/config:/app/config \
|
||||
qiniu-feishu-bot
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 配置
|
||||
|
||||
### 环境变量 (.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-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 专用指南
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 故障排查
|
||||
|
||||
### 上传失败
|
||||
|
||||
1. 检查七牛云配置是否正确
|
||||
2. 确认存储桶区域代码匹配
|
||||
3. 检查 AccessKey/SecretKey 权限
|
||||
|
||||
### 消息无响应
|
||||
|
||||
1. 检查事件订阅配置
|
||||
2. 确认服务器可被飞书访问（需要公网 IP）
|
||||
3. 查看日志输出
|
||||
|
||||
### 文件无法覆盖
|
||||
|
||||
在七牛云控制台关闭存储桶的"防覆盖"设置。
|
||||
|
||||
### 跨平台问题
|
||||
|
||||
- **Windows**: 查看 [`WINDOWS.md`](./WINDOWS.md)
|
||||
- **Linux/macOS**: 查看 [`DEPLOY.md`](./DEPLOY.md)
|
||||
|
||||
---
|
||||
|
||||
## 📝 许可证
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user