一套告警协议，
两端安全抵达。

服务器仍会看到必要元数据，例如事件时间、频道 ID、密文大小、发送 IP 和设备数量。正文、标题、链接和业务 Payload 必须加密。

频道必须由已授权 Android 或 Windows 客户端创建。服务器网页默认不能创建私钥。

{
  "endpoint": "https://<YOUR_DOMAIN>/hook/<CHANNEL_ID>",
  "channelId": "<CHANNEL_ID>",
  "webhookToken": "<TOKEN>",
  "channelPublicKey": "<BASE64URL_PUBLIC_KEY>",
  "senderPrivateKey": "<ENCRYPTED_SENDER_KEY>",
  "keyVersion": 1
}

1. 创建邀请在频道成员页设置角色、权限、有效期、使用次数和 all/future。邀请链接只显示一次。
2. 接受邀请新用户可从登录页使用邀请注册；已有用户在应用内粘贴链接。接受后先处于待批准。
3. 批准并分发密钥all 为新成员设备封装所有历史版本；future 原子轮换新版本，新成员看不到加入前历史。
4. 移除成员客户端为剩余成员设备生成新版本密钥包，服务端与成员移除原子提交。

Sender 是独立模块，负责模板、本地加密、签名、幂等、断线重试和密文缓存。普通程序不需要自行实现密码学。

bullbell-sender.exe send \
  --config sender.secure \
  --title "BTC 跌破 70000" \
  --body "请立即检查账户" \
  --image monitor.png \
  --inline-keyboard-file buttons.json

POST http://127.0.0.1:17321/v1/alerts
Authorization: Bearer <LOCAL_RELAY_TOKEN>
Content-Type: application/json

{"title":"磁盘空间不足","body":"只剩 10GB"}

SDK 0.1.0 直接运行在发送脚本内，不需要启动 Sender.exe 或本机中继。库在本机加密、签名后通过 HTTPS 发送，Server 仍看不到标题正文。

登录有权限的 GitHub 账号，从项目私有 Releases 下载 wheel（Python 3.11+）或 tgz（Node.js 22+），校验 SHA256SUMS 后安装。完整安装、配置导入、三种通知级别、定向响铃、内联按钮与重试教程在私有仓库 docs/sdk/README.md。SDK 不发布公共 PyPI/npm，勿安装陌生同名包。

安装与配置

在私有仓库的 sdk-v0.1.0 Release 下载对应安装包和 SHA256SUMS.txt。SDK 下载需要 GitHub 读取权限，日常发送不访问 GitHub。不要把 GitHub Token 写在安装命令或发送脚本中。

# Python：在发送脚本使用的 Python 环境安装
python -m pip install ./bullbell_sdk-0.1.0-py3-none-any.whl

# JavaScript / TypeScript：在业务项目目录安装
npm install ./bullbell-sdk-0.1.0.tgz --save-exact

设置环境变量 BULLBELL_CONFIG 为现有 sender.secure 路径。Windows 必须由导入配置的同一用户运行；Linux 口令配置还需设置 BULLBELL_SENDER_PASSPHRASE。没有安全配置时，Python 使用 protect_config、JavaScript 使用 protectSenderConfig 导入客户端一次性 Sender JSON，无需 Sender 工具。凭据只保存在受信任的发送机器上，不随 SDK 分发。

三种告警级别

normal 为普通通知，important 为重要通知，alarm 为响铃。不传级别时使用 Sender 配置的默认值，同一频道可发送三种级别。

# Python：BULLBELL_CONFIG 指向已有受保护 Sender 配置
import os
from bullbell import BullBell
bell = BullBell(config_file=os.environ["BULLBELL_CONFIG"])
result = bell.send(title="服务异常", body="请检查服务器", urgency="alarm")

// JavaScript / TypeScript（Node.js）
import { BullBell } from "@bullbell/sdk";
const bell = await BullBell.fromFile(process.env.BULLBELL_CONFIG);
const result = await bell.send({title:"服务异常", body:"请检查服务器", urgency:"alarm"});

指定成员响铃

目标使用频道成员 UUID，不是用户名或设备 ID。所有有权成员仍可查看消息；非目标成员按 silent、normal 或 important 处理。

# Python
result = bell.send(
    title="值班告警", body="请值班人员处理", urgency="alarm",
    target_user_ids=["<USER_UUID>"],
    non_target_behavior="normal", acknowledgement_policy="any-target",
)

// JavaScript / TypeScript
const result = await bell.send({
  title: "值班告警", body: "请值班人员处理", urgency: "alarm",
  targetUserIds: ["<USER_UUID>"],
  nonTargetBehavior: "normal", acknowledgementPolicy: "any-target",
});

any-target 表示任一目标确认后停止全部目标；all-targets 要求每个目标用户分别确认。目标列表和级别是服务器可见的路由信息，正文仍为密文。

脚本内联按钮

[
  [{"type":"acknowledge","label":"确认并停止"}],
  [{"type":"url","label":"打开监控","url":"https://monitor.example.invalid/"}],
  [{"type":"copy","label":"复制节点","value":"db-02"}],
  [{"type":"choice","label":"已接单","choiceId":"take","value":"accepted"}]
]

Python 将此数组作为 inline_keyboard=buttons 传入；JavaScript 使用 richContent: {version:1, inlineKeyboard:buttons}。最多 8 行、每行 4 个、总计 20 个按钮。按钮内容随正文加密，选择回执不是服务端代为执行任意 HTTP 回调。

失败与重试

默认最多尝试 3 次，遇到网络错误、408、429 或 5xx 时遵循 Retry-After 并指数退避加抖动；401/403 等永久错误不重试，也不跟随重定向。Python 的 timeout 单位是秒，JavaScript 的 timeoutMs 单位是毫秒，默认每次请求 15 秒。成功结果含 eventId/status/attempts/response，只证明服务端接受，不证明设备已响铃。

# Python：需要业务持久队列时，先保存 prepare 返回的密文
from bullbell import DeliveryError
envelope = bell.prepare(title="服务异常", body="请检查服务器", urgency="alarm")
try:
    result = bell.submit(envelope)
except DeliveryError as error:
    print(error.status, error.retryable)
    # 稍后仅重试 bell.submit(error.envelope)，不要重新 send 创建事件

JavaScript 对应 await bell.prepare(input)、await bell.submit(envelope) 和 DeliveryError。SDK 不自动写持久队列；业务只应保存密文信封。服务端有前后 300 秒的时间窗口，过旧或密钥已轮换的事件不能悄悄改时间戳或换 eventId 补发。频道完整轮换后旧配置失效，需更新发送凭据。

{
  "version": 1,
  "eventId": "<UUID>",
  "channelId": "<CHANNEL_ID>",
  "keyVersion": 1,
  "timestamp": 1786964400,
  "nonce": "<BASE64URL_96_BIT_NONCE>",
  "wrappedKey": "<HPKE_WRAPPED_DEK>",
  "ciphertext": "<AES_GCM_CIPHERTEXT>",
  "senderId": "<SENDER_ID>",
  "signature": "<ED25519_SIGNATURE>"
}

Server 验证 Token、Sender 签名、时间窗口、Nonce、大小和频率。重试必须复用同一 eventId，以保证幂等。任何字段、AAD、密文或签名被篡改都必须失败。

定向确认：any-target 中任一目标确认后，所有目标设备收到 alarm-stop；all-targets 中每个目标用户分别确认，同一用户的其他设备会同步停止。客户端仅在 eventId 与当前响铃一致时执行远程停铃。

客户端导航：底部固定为“总览、频道、告警中心、设置”。频道页使用明亮白色列表展示角色、最后告警、未读和待确认状态；频道资料的“频道”区域直接提供成员、邀请、新成员历史权限和管理员权限入口，并集中显示加密状态及仅创建者可见的 Token/Sender 管理。Token 原值只在创建或重置时显示一次，之后仅显示末尾 6 位与轮换时间。

客户端设置：账号资料位于设置页顶部，独立显示头像、显示名称、@username 和修改密码入口，不归入“常规”。“常规”负责外观、固定配色、最近任务卡片、通知声音和响铃音频；“权限管理”的“系统权限”显示全部七项用户可检查权限，随后管理设备批准和离线恢复；“使用指南”按主题打开本页。Android 的“安装应用更新”只影响下载后安装 APK，不影响日常收警。后台隐藏只改变最近任务卡片，不停止 FCM、通知、响铃或后台任务。Android 不允许应用静默覆盖用户已经确认的通道开关，因此悬浮、振动和锁屏显示必须由用户在跳转后的系统页面修改。

完整历史移入频道内部。告警中心跨频道提供待处理、指向我、全部、已确认、收藏、频道筛选和本地全文搜索，搜索词不会上传服务器。服务端事件游标在 SQLite 重启后仍然有效。客户端按服务器 URL 与设备 ID 隔离缓存；Android 进入频道后优先读取已经验签解密的明文记录，Windows 读取密文并在内存解密，再在后台同步最新密文。每个频道在本机只保留最近 1000 条，超过本地边界的旧记录按服务端游标联网读取。

1. 新设备生成密钥私钥留在 Keystore/CNG，公钥注册到服务器并展示 SHA-256 指纹。
2. Admin 批准设备信任在 /admin/ 核对指纹并批准。此操作不删除旧数据，也不生成或读取频道私钥。
3. 按频道补齐密钥已有设备在本地解封频道私钥并重新封装给新设备；控制台独立显示齐全或缺失。
4. 没有现有设备时恢复已由 Admin 批准的设备使用离线恢复 JSON 解开 HPKE 挑战并补齐频道密钥；恢复文件不能自行授予设备信任。

cd /opt/bullbell/deploy/linux
cp .env.example .env
# 已有 Nginx/Caddy 时只绑定 127.0.0.1:8787
docker compose -f compose.existing-proxy.yaml up -d --build
# 后续正式更新只部署明确标签
./scripts/deploy.sh v0.22.0

8787 不直接开放公网。已有站点时使用独立的现有反向代理 Compose；没有现有代理时使用自带 Caddy 的 compose.yaml。Server 0.15.0 使用 bullbell.sqlite 保存 Admin 摘要与审计、设备注册申请、多用户、设备信任、频道成员/邀请、应用内发送公钥、密钥包、每频道最近 10,000 条密文事件、附件密文和频道头像密文。两套 Compose 均包含健康检查、384 MB 内存限制和 10 MB × 3 日志轮换。客户端正式地址填写 https://<YOUR_DOMAIN>，不要附加 /api。

加密范围只包括 Linux 上的 BullBell 数据卷和 BullBell 备份文件。本机测试目录是 D:\code\bullbell\data\testing，文档不会启用 BitLocker、修改分区或加密整个 D 盘。迁移验证完成前保留的旧 JSON 也必须作为敏感备份保护。

Windows 1.2.1 低内存试用版：关闭主窗口先隐藏再释放界面内存；托盘快速重开会等待旧界面退出并合并重复点击。启动复用后台会话，先显示本地缓存，再通过进度条提示联网同步，不再每次打开都刷新令牌或注册设备密钥。登录失效仍要求重新登录，断网仍明确提示。此优化不让整个界面长期驻留后台，完全退出后的冷启动成本仍存在。

# 当前开发代码
Server 0.15.0
Client 1.1.0+64

# 当前网站正式包
Client 1.1.0+64

• 整套正式发布使用 vX.Y.Z Git 标签，Linux 部署脚本拒绝未标记代码。
• Android 构建号每次发布递增，并始终使用同一份受保护签名密钥；正式脚本交互读取密码，配置缺失时不会回退到 Debug 签名。
• Windows 可下载单文件免安装 EXE（内嵌完整运行文件），或解压完整 ZIP。原始 Flutter 目录中的主 EXE 不能单独复制。
• 发布清单保存版本、构建号、下载 URL、文件大小、APK SHA-256 和发布证书 SHA-256。

1. 01 ✓
   协议与测试向量

   Schema、JCS、HPKE、AES-GCM、Ed25519 已完成。

2. 02 ✓
   设备与恢复

   Keystore、CNG、指纹批准、离线恢复和密钥轮换已完成。

3. 03 ✓
   频道与 Sender

   安全配置、中继、密文队列与单文件打包已完成。

4. 04 ✓
   服务端密文模型

   SQLite WAL、防重放、幂等和持久游标已完成。

5. 05 ✓
   客户端同步与通知

   按频道分页、断网历史和活动告警前台服务已完成。

6. 06 ◐
   生产演练

   生产 FCM、红米锁屏省电、HTTPS 与备份恢复待实测。