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

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

1.1 核心原理

  1. 本地加密：您在浏览器中写下笔记，浏览器在本地生成随机密钥，并使用 AES-256-GCM 加密内容。加密在发送任何网络请求前完成。
  2. 上传密文：仅加密后的密文被上传至服务器。密钥从未被发送，它被附加在您生成的链接中（…/p/<id>#<密钥>）。
  3. 分享链接：链接包含了笔记的 ID 和密钥。只有拥有此链接的人才能解密和阅读。
  4. 一次阅读：当收件人打开链接时，其浏览器获取密文，从 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 一键部署（最快方式）

  1. 访问项目仓库，点击 “Deploy to Cloudflare” 按钮。
  2. 系统会引导您登录 Cloudflare 账户。
  3. 授权后，部署脚本会自动：
    • 克隆仓库。
    • 在您的账户下创建所有必需的资源：PASTES KV 命名空间、BurnPaste Durable Object、CREATE_RL 速率限制器。
    • 配置并部署 Worker。
  4. 等待部署完成，您的 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

  1. 项目根目录下有一个 wrangler.toml.example 模板文件。

  2. 将其重命名为 wrangler.toml，或编辑现有的 wrangler.toml。

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

    1
    2
    3
    4
    [[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 全局安装，方便在终端中创建和分享加密笔记。

1
2
3
4
5
6
7
8
9
10
11
# 全局安装
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小时过期模式在免费配额内是安全的。

7. 总结

binthere 是一个设计精巧、注重安全的加密分享工具。

核心使用路径：

  1. 公共实例：直接访问 binthere.gaury.dev，写下内容，获取链接，分享给他人。
  2. 自托管（推荐）：一键部署到 Cloudflare 是最简单的方式，免费且完全掌控。适合对隐私和持久性有更高要求的用户。
  3. CLI 工具：对于开发者和终端用户，可通过 npm install -g binthere 安装命令行客户端，方便脚本化操作。

建议：如果您只是想快速分享一个秘密，使用公共实例即可。如果您希望长期拥有一个属于自己的、不受他人限制的私密分享服务，或者您对数据主权有要求，那么花几分钟通过一键部署按钮在 Cloudflare 上创建一个自己的实例，是性价比极高的选择。