# 七牛云覆盖上传功能 - 重要说明

## ⚠️ 为什么同名文件无法覆盖？

七牛云存储桶默认可能启用了**"防覆盖"**设置，这是一个**存储桶级别的设置**，需要在七牛云控制台手动关闭。

## ✅ 解决方案（推荐）

### 方法 1：通过七牛云控制台（最简单）

1. **登录七牛云控制台**
   - 网址：https://portal.qiniu.com/

2. **进入对象存储**
   - 点击左侧菜单 "对象存储"
   - 找到你的存储桶（根据配置是 `daoqires`）

3. **进入存储桶设置**
   - 点击存储桶名称进入详情页
   - 点击顶部 "设置" 标签
   - 选择 "空间设置"

4. **关闭防覆盖**
   - 找到 "防覆盖" 或 "禁止覆盖" 选项
   - 将其设置为 **关闭** 状态
   - 点击 "保存"

5. **重启 Gateway**
   ```bash
   openclaw gateway restart
   ```

6. **测试上传**
   ```bash
   /upload /test/file.txt
   # 再次上传同名文件
   /upload /test/file.txt
   # 现在应该可以覆盖了
   ```

---

### 方法 2：使用不同文件名（临时方案）

如果无法修改存储桶设置，可以使用时间戳或随机数生成唯一文件名：

```bash
# 使用日期时间
/upload /config/file_20260304_133000.txt

# 或使用随机数
/upload /config/file_$(openssl rand -hex 4).txt
```

---

### 方法 3：修改上传脚本添加覆盖参数

在 `upload-to-qiniu.js` 中，上传凭证已设置 `insertOnly: 0`，但这**仅在存储桶允许覆盖时生效**。

如果存储桶本身禁止覆盖，上传凭证的设置不会生效。

---

## 🔍 如何确认是否启用了防覆盖？

### 方法 1：查看上传错误信息

上传同名文件时，如果返回以下错误，说明启用了防覆盖：

```
❌ 上传失败：file exists
或
❌ 上传失败：400 Bad Request - overwriting is not allowed
```

### 方法 2：查看七牛云控制台

1. 登录 https://portal.qiniu.com/
2. 进入对象存储 → 你的存储桶
3. 点击 "设置" → "空间设置"
4. 查看 "防覆盖" 选项的状态

---

## 📋 当前配置

根据你的配置：

| 配置项 | 值 |
|--------|-----|
| 存储桶名称 | `daoqires` |
| 区域 | `z2` (华南) |
| CDN 域名 | `https://daoqi.daoqi888.cn` |
| AccessKey | `YO_W...S_pK` |

---

## 🛠️ 已修改的文件

1. **scripts/upload-to-qiniu.js**
   - 添加 `insertOnly: 0` 到上传凭证
   - 修复上传 API 端点为 `/`（标准表单上传）

2. **SKILL.md**
   - 添加覆盖上传说明
   - 添加故障排查指南

3. **scripts/check-bucket-override.js** (新增)
   - 检查存储桶覆盖设置

4. **scripts/update-bucket-setting.js** (新增)
   - 更新存储桶设置

---

## 📞 需要帮助？

如果以上方法都无法解决问题，请提供：

1. 上传错误信息的完整输出
2. 七牛云控制台中"空间设置"的截图
3. 存储桶名称和区域

---

## 📖 参考文档

- [七牛云上传策略文档](https://developer.qiniu.com/kodo/1206/put-policy)
- [七牛云空间设置](https://developer.qiniu.com/kodo/manual/1312/bucket-settings)
- [七牛云表单上传](https://developer.qiniu.com/kodo/1312/upload)