English · 简体中文 —— 中文版在本文下方

中文摘要 —— 把笔记附件上传到你自己的 S3 兼容存储，本地留一份可丢弃的缓存副本：断网、存储停机也能看。 需要 Obsidian 1.13.0+；界面跟随系统语言；完整中文说明见下方「中文版」。

Upload your attachments to your own S3-compatible storage — Cloudflare R2, AWS S3, MinIO, Backblaze B2 or any other S3 endpoint — and keep a local copy that does the rendering. Paste a file and it uploads; the note keeps a portable, shareable link while the copy stays behind, so files render with zero remote requests.

Install · Releases · Report a problem · Requires Obsidian 1.13.0+ (why)

Recorded from the plugin running in Obsidian: paste an image, a PDF and an audio clip → each one uploads → the note keeps a link while a copy of each stays in the vault's cache folder. The last step stops the storage to show that all three still work — the image, the PDF page, and an audio player.

Everything here has been exercised for real — see How far it is verified. Not proven yet: iOS never run; Android never run on a real device.

Why use it

Upload plugins break your notes the moment you are offline; "localize" plugins only help after you have been online once. This does both — the file goes to your bucket, and the copy that renders stays behind:

Features

• Any S3-compatible storage — Cloudflare R2, AWS S3, MinIO, Backblaze B2, self-hosted.
• Upload however the file gets in — pasted, dropped, added from your phone's gallery or camera, shared into Obsidian, or copied into the vault. The note's link is rewritten to the remote URL. Keys are content-addressed ({hash}.{ext}), so the same bytes are stored once.
• Any file type, not just images — images, audio, video, PDF, archives, documents, extension-less files. Types Obsidian can preview (image/audio/video/PDF) are inserted as embeds; everything else becomes a clickable link.
• Offline, multi-device, and light to sync — the rendering copy is local (zero remote requests, always, not just when the network is down); a new device back-fills copies on demand; and with the default "move into the cache folder" the vault's bulk is text plus disposable copies, so syncing stays fast and cheap.
• Canvas references count the same as note references — a file placed on a canvas is uploaded, and its canvas reference keeps working.
• Bulk-upload what you already have — one command handles the files your notes link to and leaves the rest alone.
• Cloud space cleanup — lists the objects in your storage no note refers to, with the count and the size, and deletes only what you confirm.
• Two optional features, both off by default — caching files from other sites, and a cache size limit that trims least-recently-used copies in the background.

Requirements

• Obsidian 1.13.0 or newer, desktop and mobile. Older versions see No appropriate version found. in the community catalogue — that is Obsidian's installer refusing, not a broken plugin.
• An S3-compatible bucket you control, plus an access key pair for it.
• The bucket must allow anonymous reads, or you must set a public URL prefix (CDN or custom domain) — otherwise the links in your notes open for you but not for anyone else. Test connection checks exactly this.

Installation

From inside Obsidian: Settings → Community plugins → Browse → search Attachment Cloud Cache → Install → Enable.

Manually: put main.js, manifest.json and styles.css from the latest release into <vault>/.obsidian/plugins/attachment-cloud-cache/ (⚠️ the folder name must equal the plugin id).

Then fill in the storage settings below.

Settings

In Settings → Attachment Cloud Cache (the Chinese names are in the 中文版 half):

Commands

Good to know

• tiff, heic and ico are inserted as plain links, not embeds — Obsidian cannot preview them in an embed, so a remote ![]() would be a broken image. Your files are untouched; only the link shape changed in this release.
• A dropped file's link lands at the caret, not at the pointer — no public API maps pointer coordinates to an editor position. Deliberate.
• Links written before you change the storage URL are not recognised as "ours" on a new device — they still work online, but never render offline and are never downloaded automatically.
• When a file you uploaded stops being linked from any note, the plugin asks once whether to clean it up — keep it, delete just the local copy, or delete it locally and from your storage. The default is to keep it. The same content is stored once, so an object may be shared across notes and devices, and a storage deletion cannot be undone; only this device's references are visible.
• "Do not keep a local copy" turns caching off, which is the plain-image-host behaviour: files are uploaded and the note's link is rewritten, but nothing is kept or fetched back, so nothing is available offline.
• Moving to another device: copy the plugin folder, but delete .cache-index.json first — it records where this device keeps its copies. The secret access key is not in the folder at all (it lives in Obsidian's keychain).

Common failures

Privacy & security

• It normally talks only to your storage, and touches nothing outside your vault. No telemetry, no analytics.
• One optional feature reaches other sites — only after you turn it on and tell it to act ("Cache files from other sites", off by default, and doing nothing by default). The request carries nothing beyond the file's own address.
• A web page is never stored — text/html and other text/* answers are refused rather than uploaded.
• The secret access key lives in the OS keychain, never in data.json. The access key ID is written to data.json: an identifier, not a secret, and Obsidian's keychain accepts only lowercase IDs.
• Importing a credentials file reads that file and nothing else, where it already sits.

How far it is verified

• Automated tests cover signing, key and path derivation, settings merging, the cache index, the upload chain (byte-identical, exactly one PUT, zero GETs), paste/drop decisions, canvas rewriting and cleanup safety — then a mutation check breaks each rule on purpose. An assertion that cannot fail is not an assertion.
• Real host, real storage: the shipped build ran in real Obsidian against a real MinIO instance — eight file types checked down to the uploaded bytes and Content-Type, canvas rewriting for both node kinds, audio/video/PDF previewed offline in both view modes with the remote address never reaching an element, both cloud-cleanup entry points, and a full round trip whose key is recomputed from the bytes and whose link opens anonymously. Reproduce with npm run verify:real-storage.
• Not verified: iOS and Android have never been run on a real device (the code avoids APIs known to be missing there, but that is reasoning, not evidence); non-ASCII object keys have tests but no real-provider run.

Getting help

Open an issue: https://github.com/udarent/obsidian-plugins-attachment-cloud-cache/issues — say what you saw, your Obsidian version and which storage provider you use; the errors name the step that failed. Working on the plugin? npm install, then npm run dev (watch build) or npm test (build + suites).

Attachment Cloud Cache（附件云端缓存）

English · 简体中文

把笔记附件上传到你自己的 S3 兼容存储 —— Cloudflare R2、AWS S3、MinIO、Backblaze B2 或任何 S3 端点 —— 同时在 本地留一份负责渲染的缓存副本。粘贴一个文件就自动上传，笔记里留下一条可迁移、可分享的链接，而渲染走本地副本， 零远端请求。

安装 · 版本发布 · 反馈问题 · 需要 Obsidian 1.13.0+（为什么）

动图取自真实运行中的 Obsidian：粘贴图片、PDF 和音频 → 各自上传 → 笔记里各留一条链接，同时 vault 的缓存目录里各留一份副本。最后一步把存储整个停掉，用来证明图片、PDF 页和音频播放器都照常工作。

下面写的每条行为都真机跑过 —— 见已验证到什么程度。 还没验证的： iOS 从未运行过；Android 也没在真机上跑过。

为什么用它

上传类插件一断网就让笔记裂图；「本地化」类插件只有在联网一次之后才有用。本插件两件都做 —— 文件进你的桶， 负责渲染的副本留在本地：

功能

• 任何 S3 兼容存储 —— Cloudflare R2、AWS S3、MinIO、Backblaze B2、自建端点。
• 附件怎么进来都行 —— 粘贴、拖入、手机相册或相机、分享到 Obsidian、从别处拷进库，都会被上传，笔记里的链接换成远端地址。key 默认按内容寻址（{hash}.{ext}），同一份字节只存一份。
• 任何类型的附件，不只图片 —— 图片、音频、视频、PDF、压缩包、文档、没有扩展名的文件。Obsidian 能预览的 类型（图片/音频/视频/PDF）插入为嵌入，其余插入为可点开的普通链接。
• 离线、多设备、同步轻快 —— 渲染走本地副本（零远端请求，始终如此，不只是「网不通」时）；换新设备时副本按需补回； 默认档「移入缓存目录」下，vault 的体量是纯文本 + 可丢弃的副本，把那个目录排除在同步外就又快又省。
• 画布引用与笔记引用同等算数 —— 摆在画布上的文件同样会被上传，画布里的引用会继续有效。
• 存量附件一条命令搬完 —— 只处理笔记引用着的文件，其余的绝不碰。
• 云端空间清理 —— 列出你存储里「本库没有笔记引用」的对象（连同个数与体积），只删你确认过的那些。
• 两个可选功能，默认都关 —— 缓存站外文件；缓存大小上限（超限时后台按最近最少使用清理）。

环境要求

• Obsidian 1.13.0 或更新，桌面端与移动端。更低的版本在社区目录里只回一句 No appropriate version found. —— 那是 Obsidian 的安装机制在拒绝，不是插件坏了。
• 一个你自己控制的 S3 兼容存储桶，以及一对访问密钥。
• 存储桶要允许匿名读取，或者你得填一个公开访问前缀（CDN 或自定义域名）。否则写进笔记的链接你自己打得开、 别人打不开 —— 测试连接 检查的正是这件事。

安装

在 Obsidian 里装： 设置 → 第三方插件 → 浏览 → 搜 Attachment Cloud Cache → 安装并启用。

手动安装： 从最新 release 下载 main.js、manifest.json、styles.css，放进 <vault>/.obsidian/plugins/attachment-cloud-cache/ （⚠️ 目录名必须等于插件 id）。

然后填下面的存储设置。

设置

在 设置 → Attachment Cloud Cache 里（英文名见本文英文半）：

命令

需要注意的

• tiff、heic、ico 插入的是普通链接，不再嵌入 —— 宿主无法在嵌入里预览它们，写 ![]() 只会得到一个坏图。 你的文件没被动；这一版变的只是链接形态。
• 拖放文件的链接插在光标处，不是指针落点 —— 公开 API 里没有「指针坐标 → 编辑器位置」的映射。有意取舍。
• 改了存储地址之后，「新设备」上认不出老链接 —— 那些链接照常在线显示，但离线不显示、也不会被自动下载。
• 某个已上传的对象在本库不再被任何笔记引用时，会问你一次怎么处理 —— 保留、只删本地副本、或本地与云端一起删； 默认保留。相同内容只存一份，所以一个对象可能被多篇笔记、多台设备共用，而云端删除无法撤销；清理只能看到本设备的引用。
• 「不留本地副本」这一档等于关闭缓存，也就是普通图床的行为：文件照常上传、笔记里的链接照样改写， 但不保留副本、也不把副本取回来，所以断网时什么都看不到。
• 换设备：把插件目录复制过去，但先删掉 .cache-index.json —— 它记的是这台设备的副本在哪。秘密访问密钥 根本不在目录里（它存在 Obsidian 的钥匙串中）。

常见故障

隐私与安全

• 默认只连你自己的存储，也不碰 vault 之外的文件。不含遥测、统计。
• 有一个可选功能会访问其它站点，而且只有你打开它、并明确让它做时才会（「缓存站外文件」默认关闭，打开后也默认 什么都不做）。请求里除文件地址本身不带任何其它内容。
• 网页永远不会被存下来 —— text/html 与其它 text/* 一律拒收，而不是传上去。
• 秘密访问密钥存在系统钥匙串里，绝不写进 data.json。访问密钥 ID 会写进 data.json：它是标识符而不是 秘密，而且 Obsidian 的钥匙串只接受小写 ID。
• 导入凭据文件只读那一份文件，就在它原来的位置读。

已验证到什么程度

• 自动化测试覆盖签名、key 与路径推导、设置合并、缓存索引、上传链路（字节一致、恰好 1 次 PUT、0 次 GET）、 粘贴/拖放判定、画布改写与清理安全性质 —— 之后还有一道变异验证：把每条规则故意改坏。不会失败的断言等于没有断言。
• 真实宿主与真实存储： 构建产物在真实 Obsidian 里对着真实 MinIO 跑过 —— 八种类型的文件逐项核对上传字节与 Content-Type；画布两类节点的改写；音频、视频、PDF 在两种视图模式下离线预览，且远端地址从未落进任何元素； 云端清理两条入口；以及一次完整回环 —— key 由脚本从字节独立重算，链接匿名能打开。可用 npm run verify:real-storage 复现。
• 没验证的： iOS 与 Android 都没在真机上跑过（代码避开了已知缺失的 API，但那是推理不是证据）；含非 ASCII 字符的 对象 key 有测试覆盖，但没在真实服务商上跑过。

遇到问题

到 https://github.com/udarent/obsidian-plugins-attachment-cloud-cache/issues 提 issue —— 请说清你看到的、你的 Obsidian 版本和用的哪家存储；插件的报错都写明了失败在哪一步。 想改插件本身？npm install，然后 npm run dev（监听构建）或 npm test（构建 + 全部套件）。