# obsidian-qiniuimage

- **chenxuan**

在 Obsidian 里粘贴或拖入图片时，自动上传到七牛云对象存储，并在笔记里插入 CDN 链接，而不是把图片存进本地附件目录。

Paste or drop an image in Obsidian and it is uploaded to Qiniu object storage, with the CDN link inserted into the note instead of a local attachment.

## 作用

- 粘贴截图 → 自动上传到图床 → 笔记里只留一个 `![](http://your-cdn/xxx.png)` 链接
- 拖入图片文件同样处理
- 上传中显示占位文字，上传完成后原地替换成链接
- 上传失败时自动退回 Obsidian 的默认行为（存到库里），图片不会丢
- 支持两种上传方式：直连七牛云，或者转发给自建的 [qiniuserver](https://github.com/chenxuan520/qiniuserver)

## 安装

### 从 release 安装

1. 到 [release 页面](https://github.com/chenxuan520/obsidian-qiniuimage/releases) 下载 `main.js`、`manifest.json`、`styles.css`

2. 在库目录下新建文件夹 `.obsidian/plugins/qiniu-image/`，把三个文件放进去

3. 重启 Obsidian，在 `设置 → 第三方插件` 里启用 **Qiniu Image**

### 从源码编译

```bash
git clone https://github.com/chenxuan520/obsidian-qiniuimage
cd obsidian-qiniuimage
npm install
npm run build
```

编译产物 `main.js` 和 `manifest.json`、`styles.css` 一起复制到 `.obsidian/plugins/qiniu-image/` 即可。

## 参数说明

打开 `设置 → Qiniu Image`，填入下面的参数，最后点 **Run test** 验证。

| 参数 | 说明 |
| --- | --- |
| Upload mode | `Direct to Qiniu` 直连七牛；`Relay through qiniuserver` 转发给自建服务 |
| Access key / Secret key | 七牛云密钥，[在这里获取](https://portal.qiniu.com/developer/user/key) |
| Bucket | 存储空间名字，[在这里获取](https://portal.qiniu.com/kodo/bucket) |
| Region | 存储区域，选 `Auto detect` 会自动向七牛查询 |
| Custom upload host | 可选，私有云或代理时覆盖上面的区域 |
| CDN domain | 绑定的加速域名，例如 `http://cdn.example.com` |
| Upload path | 空间内的路径前缀，例如 `test`，留空表示根目录 |
| File name template | 文件名模板，见下 |
| URL suffix | 追加到链接后面，例如 `?imageslim` 走七牛的图片处理 |
| Server URL / Server password | 只在转发模式下使用，对应 qiniuserver 的地址和 `host.password` |

### 文件名模板

和 qiniuserver 的 `file_name` 保持一致：

| 占位符 | 含义 |
| --- | --- |
| `%d` | 时间戳，格式 `YYYYMMDDHHmmss` |
| `%f` | 原文件名（空格会替换成下划线） |
| `%r` | 6 位随机字符串 |
| `%e` | 扩展名，例如 `.png` |

默认 `%d%f`，即 `20260830170509image.png`。留空表示保持原文件名。

### 其他选项

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| Upload on paste | 开 | 粘贴时上传 |
| Upload on drop | 开 | 拖入时上传 |
| Upload non-image files too | 关 | 打开后 PDF、压缩包等附件也上传 |
| Maximum file size (MB) | 20 | 超过大小的文件留在本地库，`0` 表示不限制 |
| Save to the vault when upload fails | 开 | 上传失败时退回本地保存，避免丢图 |

## 实现细节

- 上传凭证用 WebCrypto 的 HMAC-SHA1 在本地签发，桌面端和移动端都能用，不依赖 Node
- 上传令牌的 `scope` 只包含 bucket，因此是「只允许新增」，不会覆盖空间里已有的文件；万一文件名撞车（返回 614），会自动加一个随机后缀重试一次
- 网络请求走 Obsidian 的 `requestUrl`，不受浏览器 CORS 限制
- 密钥保存在 `.obsidian/plugins/qiniu-image/data.json` 里。如果你的库会同步或提交到公开仓库，请确认 `.obsidian` 已被忽略，或者改用转发模式，把密钥留在自建服务端

## 开发

```bash
npm install
npm run dev        # 监听编译
npm test           # 单元测试 + mock 服务器 + 构建产物冒烟测试
npm run typecheck
```

真机联调（会向真实空间上传一个 1x1 的图片并在结束时删除）：

```bash
QINIU_E2E=1 \
QINIU_ACCESS_KEY=xxx QINIU_SECRET_KEY=xxx QINIU_BUCKET=xxx \
QINIU_DOMAIN=http://cdn.example.com QINIU_UPLOAD_PATH=test QINIU_ZONE=z2 \
node --test test/e2e-qiniu.test.ts
```

也可以直接复用 qiniuserver 的配置文件：

```bash
QINIU_E2E=1 QINIU_CONFIG_PATH=/path/to/qiniuserver/config/config.json node --test test/e2e-qiniu.test.ts
```

## License

[MIT](./LICENSE)