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

服务器仍会看到必要元数据，例如事件时间、频道 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"}

{
  "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 和修改密码入口，不归入“常规”。“常规”负责外观、固定配色、最近任务卡片、通知声音和响铃音频；“权限管理”集中管理通知、全屏响铃、后台电池、设备批准和离线恢复；“使用指南”按主题打开本页。后台隐藏只改变最近任务卡片，不停止 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.13.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 也必须作为敏感备份保护。

# 当前开发代码
Server 0.13.0
Client 0.22.0+56

# 当前网站正式包
Client 0.21.0+55

• 整套正式发布使用 vX.Y.Z Git 标签，Linux 部署脚本拒绝未标记代码。
• Android 构建号每次发布递增，并始终使用同一份受保护签名密钥；正式脚本交互读取密码，配置缺失时不会回退到 Debug 签名。
• Windows 必须分发完整 Release 目录或安装器，不能只复制 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 与备份恢复待实测。