Forge-Sanctum
LOG · 日志

bipu

DATE 日期
2026-10-23
SOURCE 源码
开发/bipu.md
READ 阅读
~5 min

Bipupu

手机里塞一个传呼机：服务器收到消息，手机把消息推到一块 128×64 的 ESP32 小屏上，屏幕装进口袋就不用一直看手机。

状态：后端可用、App 可安装（CI 出 APK）、固件独立维护；入口：本地运行（backend/ + mobile/）；仓库：本仓库（后端 + Flutter App），固件在 bipu-firmware

本质

把手机消息经 App 与 BLE 推到 ESP32 小屏的传呼机系统。

选型

基于 FastAPI + Flutter 的前后端分离应用，前端 Flutter，后端 FastAPI，数据 PostgreSQL + 可选 Redis/Celery，设备 BLE NUS + 0xB0，部署 Docker Compose。

  • 前端
    • Flutter
      • flutter_bloc
      • go_router
      • dio
      • retrofit
      • Hive
      • flutter_secure_storage
      • flutter_blue_plus
      • speech_to_text
      • just_audio
      • flutter_background_service
      • easy_localization
  • 后端
    • FastAPI
      • SQLAlchemy 2.0
        • Alembic
      • Pydantic v2
      • python-jose
      • passlib
      • Jinja2
  • 数据
    • PostgreSQL 15
    • Redis 7
      • Celery 5.5
        • Celery beat
  • 协议
    • BLE Nordic UART Service
      • Bipupu 协议 v1.2
  • 部署
    • Docker Compose
    • GitHub Actions
    • GHCR

功能

  • 后端 12 组路由：认证、消息收发与长轮询、联系人、黑名单、用户与头像、服务号、海报、管理后台、WebSocket
  • 服务号订阅可单独设推送时间，Celery beat 每 15 分钟扫窗口派发，push_logs 记完整状态
  • /admin 服务端渲染后台，管用户、消息、服务号、推送日志、海报
  • App 46 个页面文件：传呼机主界面、会话与收藏、蓝牙扫描/绑定/解绑、后台自动转发、双语与主题设置
  • 未完成：后台转发依赖系统不杀进程，iOS 侧保活与转发可靠性未验证；App 无自动化测试，后端只有 3 个 test_ 用例

启动流程

# 后端
cd backend
cp .env.example .env            # 改 SECRET_KEY 与数据库密码
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --reload --port 8000
# API 文档 /api/docs ，后台 /admin

# 后端容器（含 PostgreSQL）
cd backend && docker compose -f docker/docker-compose.yml up -d

# App
cd mobile && flutter pub get && flutter run    # 真机，模拟器无 BLE

固件编译烧录见 bipu-firmware；协议细节见 mobile/docs/BLUETOOTH_PROTOCOL_QUICK_REFERENCE.md。

边界与已知问题

  • docs/ARCHITECTURE.md 写 Web 管理端是 React/Vue，实际是 Jinja2 模板；写“离线语音识别 (Sherpa-ONNX)”，实际 ASR 走系统 speech_to_text，本地 TTS 引擎已注释关闭
  • bluetooth_forward_service.dart 注释里的“昵称: 正文 前缀”已过时，协议 v1.2 是 [sender_len][sender][body]，以 bipupu_protocol.h 为准
  • Redis 与 Celery 都是可选项；不启 Redis 用内存缓存，不启 Celery 就没有定时推送
  • 没有限流与消息去重的成文策略，同账号多设备行为未定义
  • iOS 打包依赖远程 Mac，mobile/ 下的 IOS_BUILD_REPORT 等是过程记录，不等于现状
  • 默认管理员口令只是示例，部署前必须改
  • 本仓库不含固件；bipu-firmware 没有 OTA 分区，升级只能重烧

文档索引