binthere 部署与使用指南：零知识、端到端加密的阅后即焚文本分享 | 极客的赛博空间

binthere 是一个安全的文本分享工具。您写入的笔记会在浏览器中使用 AES-256-GCM 加密后上传，服务器仅存储密文，解密密钥仅存在于分享链接的 URL 片段（# 之后）中，永远不会发送到服务器。笔记在被阅读一次后即焚毁，或于 24 小时后自动过期。它既可作为一个公共实例使用，也支持您在自己的 Cloudflare 账户上完全免费地自行部署。

1. 什么是 binthere 以及它的工作方式

1.1 核心原理

本地加密：您在浏览器中写下笔记，浏览器在本地生成随机密钥，并使用 AES-256-GCM 加密内容。加密在发送任何网络请求前完成。
上传密文：仅加密后的密文被上传至服务器。密钥从未被发送，它被附加在您生成的链接中（…/p/<id>#<密钥>）。
分享链接：链接包含了笔记的 ID 和密钥。只有拥有此链接的人才能解密和阅读。
一次阅读：当收件人打开链接时，其浏览器获取密文，从 URL 片段中读取密钥，并在本地解密。服务器从未接触明文。阅读后，该笔记的服务器副本会立即被原子性地销毁（即使在并发点击下也只有一个获胜者能读到），后续访问会返回 410 Gone。未读笔记会在 24 小时后自动删除。

1.2 主要特点

零知识：加解密完全在客户端进行。
阅后即焚：严格的单次读取。
自动过期：24小时自动删除。
可选密码：可在链接密钥之上叠加密码保护。
安全渲染：支持Markdown子集和代码高亮，不使用 innerHTML。

2. 部署选项

binthere 提供了两种使用和部署方式：

方式一：使用公共实例（最简单）
您可以直接使用作者部署的在线服务，无需任何安装：binthere.gaury.dev
方式二：自行部署到 Cloudflare（免费、自托管）
这是本指南的重点。binthere 被设计为一个 Cloudflare Worker，利用其静态资产、KV 存储和 Durable Objects。得益于 Cloudflare 的免费配额，您可以完全免费地运行自己的实例。

3. 自托管部署步骤（推荐）

3.1 前置条件

一个 Cloudflare 账户。
Node.js：版本 >= 20（项目 .nvmrc 指定了 22）。
npm（随 Node.js 安装）。
Git（用于克隆仓库）。

3.2 一键部署（最快方式）

访问项目仓库，点击 “Deploy to Cloudflare” 按钮。
系统会引导您登录 Cloudflare 账户。
授权后，部署脚本会自动：
- 克隆仓库。
- 在您的账户下创建所有必需的资源：PASTES KV 命名空间、BurnPaste Durable Object、CREATE_RL 速率限制器。
- 配置并部署 Worker。
等待部署完成，您的 binthere 实例将立即上线。

3.3 手动部署（更精细的控制）

如果一键部署遇到问题，或您需要手动配置，请遵循以下步骤：

第一步：克隆并安装

1
2
3

git clone https://github.com/nxfu/binthere.git
cd binthere
npm install

第二步：创建 KV 命名空间

您需要为 PASTES 创建一个 KV 命名空间（用于存储密文）。

1	npm run kv:create

此命令会输出 id 和 preview_id。请复制这两个值。

第三步：配置 `wrangler.toml`

项目根目录下有一个 wrangler.toml.example 模板文件。
将其重命名为 wrangler.toml，或编辑现有的 wrangler.toml。

将上一步获取的 id 和 preview_id 填入对应位置：

[[kv_namespaces]]
binding = "PASTES"
id = "你的-KV-命名空间-ID"
preview_id = "你的-KV-预览命名空间-ID"

第四步：（可选）更新品牌和链接信息

如果您打算公开使用此实例，建议更新 public/index.html 中的 og:url 和 og:image，以及页面底部的链接，使其指向您自己的域名或仓库。

第五步：本地测试

在部署前，可以先在本地运行测试：

1 2	# 本地开发服务器（模拟 Cloudflare 环境） npm run dev

访问 http://127.0.0.1:8787 进行预览。npm test 可运行完整测试套件。

第六步：部署到 Cloudflare

1	npm run deploy

此命令会将您的 Worker 部署到 Cloudflare 网络。部署成功后，您将获得一个 *.workers.dev 的子域名，也可以绑定您自己的自定义域名。

4. 使用 CLI 客户端（可选）

binthere 提供了一个官方的命令行客户端，可通过 npm 全局安装，方便在终端中创建和分享加密笔记。

# 全局安装
npm install -g binthere

# 直接使用（无需安装）
npx binthere

# 交互式全屏菜单
binthere

# 从管道输入（如 git diff）
git diff | npx binthere  # 会输出分享链接到 stdout

5. 架构与 API（供开发者参考）

5.1 项目结构

public/：前端静态资源（SPA）。
src/index.js：Worker 入口，处理 /api/* 路由。
src/burn-do.js：Durable Object，实现原子性的“阅后即焚”。
cli/：官方 CLI 客户端源码。

5.2 HTTP API

所有 API 端点都处理密文，加密在客户端完成。

方法	路径	描述
`POST`	`/api/paste`	创建笔记（格式 v1 JSON）。成功返回 `201`。
`GET`	`/api/paste/:id`	获取并消耗笔记（一次读取）。成功返回 `200`，已焚毁返回 `410`。
`GET`	`/api/paste/:id?meta=1`	查看笔记元数据而不消耗。
`DELETE`	`/api/paste/:id`	通过 `X-Delete-Token` 头删除笔记。

6. 重要注意事项与限制

不是匿名工具：服务器仍会看到 IP、时间、密文大小等元数据，只是无法读取内容。
信任部署代码：加密在浏览器 JavaScript 中执行。如果服务端被攻击或提供恶意代码，安全性会受损。自托管可缓解此风险。
丢失链接 = 丢失笔记：没有账户，没有索引，无法恢复。
密码保护仅增强安全性：若分享链接和密码一同泄露，仍不安全。且持有链接者可离线暴力破解弱密码。
自托管费用注意：虽然免费配额通常足够，但如果修改代码支持“永不过期”选项，且积累了未读笔记，Durable Object 的存储可能产生持续费用。默认24小时过期模式在免费配额内是安全的。