f6dfa2c8f2
README.md: - 更新部署方式说明（OpenClaw 集成 vs 独立监听器） - 更新文件结构 - 完善故障排查章节 INSTALL.md: - 更新文件结构（删除已清理文件） - 添加 v2.0.0 更新日志 - 标注代码行数 SKILL.md: - 说明卡片交互为可选模式 - 推荐 OpenClaw 集成使用命令触发
259 lines
6.7 KiB
Markdown
259 lines
6.7 KiB
Markdown
---
|
||
name: qiniu-uploader
|
||
description: 七牛云文件上传和管理。支持命令触发和飞书卡片交互两种方式。
|
||
---
|
||
|
||
# 七牛云上传 Skill
|
||
|
||
## 使用方式
|
||
|
||
本 Skill 支持两种使用方式：
|
||
|
||
### 方式 1：命令触发（简单）
|
||
|
||
| 命令 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `/upload` | 上传文件到七牛云 | `/upload /config/file.txt` |
|
||
| `/u` | 上传快捷命令（别名） | `/u file.txt` |
|
||
| `/qiniu-config` | 管理七牛云配置 | `/qiniu-config list` |
|
||
| `/qc` | 配置管理快捷命令（别名） | `/qc list` |
|
||
| `/qiniu-help` | 查看帮助 | `/qiniu-help` |
|
||
| `/qh` | 帮助快捷命令（别名） | `/qh` |
|
||
|
||
### 方式 2：飞书卡片交互（可选）
|
||
|
||
通过飞书消息卡片按钮操作，体验更佳。需要独立部署监听器。
|
||
|
||
**注意：** OpenClaw 集成模式下推荐使用命令触发方式。
|
||
|
||
## 命令格式
|
||
|
||
### 上传文件
|
||
|
||
```
|
||
/upload [目标路径] [存储桶名]
|
||
/upload --original [存储桶名]
|
||
```
|
||
|
||
**参数说明：**
|
||
- `目标路径`：可选，指定上传到七牛云的路径（如 `/config/test/file.txt`）
|
||
- `存储桶名`：可选，默认使用 `default` 存储桶
|
||
- `--original`：使用原始文件名
|
||
|
||
**示例：**
|
||
```
|
||
/upload # 使用原文件名上传到 default
|
||
/upload --original # 同上
|
||
/upload /config/test.txt # 上传到指定路径
|
||
/upload /docs/r.pdf production # 指定路径和存储桶
|
||
```
|
||
|
||
**文件覆盖行为：**
|
||
- ✅ 上传同名文件会**自动覆盖**旧文件
|
||
- ✅ 支持指定路径覆盖（如 `/config/test.txt`）
|
||
- ✅ 覆盖后 CDN 会自动刷新（可能有几秒延迟）
|
||
|
||
### 配置管理
|
||
|
||
```
|
||
/qiniu-config list # 查看当前配置
|
||
/qiniu-config set <键> <值> # 修改单个配置项
|
||
/qiniu-config set-bucket <名> <JSON> # 添加/修改存储桶
|
||
/qiniu-config reset # 重置配置
|
||
```
|
||
|
||
**配置项说明：**
|
||
- `default.accessKey` - 七牛访问密钥
|
||
- `default.secretKey` - 七牛密钥
|
||
- `default.bucket` - 存储桶名称
|
||
- `default.region` - 区域代码（z0/z1/z2/na0/as0）
|
||
- `default.domain` - CDN 域名
|
||
|
||
**示例：**
|
||
```
|
||
/qiniu-config list
|
||
/qiniu-config set default.accessKey YOUR_KEY
|
||
/qiniu-config set default.domain https://cdn.example.com
|
||
/qiniu-config set-bucket production {"accessKey":"...","secretKey":"...","bucket":"prod","region":"z0","domain":"https://prod-cdn.com"}
|
||
```
|
||
|
||
## 配置文件
|
||
|
||
位置：`~/.openclaw/credentials/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"
|
||
},
|
||
"production": {
|
||
"accessKey": "...",
|
||
"secretKey": "...",
|
||
"bucket": "prod-bucket",
|
||
"region": "z0",
|
||
"domain": "https://prod-cdn.com"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 执行脚本
|
||
|
||
核心脚本：`~/.openclaw/workspace/skills/qiniu-uploader/scripts/upload-to-qiniu.js`
|
||
|
||
### 调用方式
|
||
|
||
```bash
|
||
# 上传文件
|
||
node scripts/upload-to-qiniu.js upload --file <文件路径> --key <目标路径> --bucket <存储桶名>
|
||
|
||
# 配置管理
|
||
node scripts/upload-to-qiniu.js config list
|
||
node scripts/upload-to-qiniu.js config set <键> <值>
|
||
node scripts/upload-to-qiniu.js config set-bucket <名> <JSON>
|
||
```
|
||
|
||
## 回复格式
|
||
|
||
### 上传成功
|
||
|
||
```
|
||
✅ 上传成功！
|
||
|
||
📦 文件：config/test.txt
|
||
🔗 链接：https://cdn.example.com/config/test.txt
|
||
💾 原文件：test.txt
|
||
🪣 存储桶：default
|
||
```
|
||
|
||
### 上传失败
|
||
|
||
```
|
||
❌ 上传失败：文件不存在
|
||
```
|
||
|
||
### 配置列表
|
||
|
||
```
|
||
📋 当前配置：
|
||
|
||
存储桶配置：
|
||
|
||
🪣 [default]
|
||
accessKey: YO_W...S_pK
|
||
secretKey: NlcJ...rMX7
|
||
bucket: daoqires
|
||
region: z0
|
||
domain: https://daoqi.daoqi888.cn
|
||
|
||
💡 使用 config set <key> <value> 修改配置
|
||
```
|
||
|
||
## 处理流程
|
||
|
||
1. **识别命令**：检测消息是否以 `/upload`、`/qiniu-config` 或 `/qiniu-help` 开头
|
||
2. **解析参数**：提取目标路径、存储桶名等参数
|
||
3. **下载文件**：从飞书/钉钉下载附件到临时目录
|
||
4. **执行上传**：调用 `upload-to-qiniu.js` 脚本上传到七牛云
|
||
5. **刷新 CDN**：自动刷新 CDN 缓存
|
||
6. **回复结果**：在聊天中回复上传结果
|
||
7. **清理临时文件**：删除临时下载的文件
|
||
|
||
## 依赖
|
||
|
||
- Node.js v14+
|
||
- 七牛云账号和存储桶
|
||
- 飞书/钉钉机器人配置
|
||
|
||
## 注意事项
|
||
|
||
1. **文件需要先下载**：从聊天平台下载附件到临时目录
|
||
2. **上传后清理**：完成后删除临时文件
|
||
3. **配置安全**：AccessKey/SecretKey 妥善保管
|
||
4. **路径规范**：建议使用 `/` 开头的路径（如 `/config/file.txt`）
|
||
5. **区域代码**：确保 region 与存储桶实际区域一致
|
||
6. **文件覆盖**：上传同名文件会自动覆盖（`insertOnly: 0`）
|
||
|
||
## 区域代码
|
||
|
||
| 代码 | 区域 |
|
||
|------|------|
|
||
| `z0` | 华东（浙江） |
|
||
| `z1` | 华北（河北） |
|
||
| `z2` | 华南（广东） |
|
||
| `na0` | 北美 |
|
||
| `as0` | 东南亚 |
|
||
|
||
## 故障排查
|
||
|
||
### 上传失败
|
||
|
||
1. 检查配置文件是否存在：`~/.openclaw/credentials/qiniu-config.json`
|
||
2. 检查 AccessKey/SecretKey 是否正确
|
||
3. 检查存储桶名称是否匹配
|
||
4. 检查区域代码是否正确
|
||
|
||
### **同名文件无法覆盖** ⚠️
|
||
|
||
**原因：** 七牛云存储桶启用了"防覆盖"设置
|
||
|
||
**解决方法 1：通过七牛云控制台**
|
||
1. 登录七牛云控制台：https://portal.qiniu.com/
|
||
2. 进入"对象存储" → 选择你的存储桶
|
||
3. 点击"设置" → "空间设置"
|
||
4. 找到"防覆盖"选项，**关闭**它
|
||
5. 保存设置后重试上传
|
||
|
||
**解决方法 2：通过命令行**
|
||
```bash
|
||
# 1. 检查当前设置
|
||
node scripts/check-bucket-override.js default
|
||
|
||
# 2. 关闭防覆盖
|
||
node scripts/update-bucket-setting.js mybucket noOverwrite 0
|
||
|
||
# 3. 重启 Gateway
|
||
openclaw gateway restart
|
||
```
|
||
|
||
**解决方法 3：修改上传脚本（临时）**
|
||
在上传时使用不同的文件名（如添加时间戳）：
|
||
```bash
|
||
/upload /config/file_$(date +%Y%m%d_%H%M%S).txt
|
||
```
|
||
|
||
### 配置命令无响应
|
||
|
||
1. 检查脚本权限：`chmod +x scripts/upload-to-qiniu.js`
|
||
2. 手动测试：`node scripts/upload-to-qiniu.js config list`
|
||
3. 查看日志输出
|
||
|
||
### 文件下载失败
|
||
|
||
1. 检查飞书/钉钉 App ID 和 App Secret 配置
|
||
2. 检查机器人权限（im:message, im:file）
|
||
3. 检查网络连接
|
||
|
||
### 诊断工具
|
||
|
||
```bash
|
||
# 检查存储桶覆盖设置
|
||
node scripts/check-bucket-override.js [bucket-name]
|
||
|
||
# 更新存储桶设置
|
||
node scripts/update-bucket-setting.js <bucket> <setting> <value>
|
||
```
|
||
|
||
## 相关文件
|
||
|
||
- `scripts/upload-to-qiniu.js` - 核心上传脚本
|
||
- `scripts/feishu-listener.js` - 飞书独立监听器（可选）
|
||
- `~/.openclaw/credentials/qiniu-config.json` - 七牛云配置
|
||
- `README.md` - 完整使用文档
|
||
- `CHEATSHEET.md` - 快速参考卡片
|