Msg Sync

基于 FastAPI 的内存聊天框示例。多个设备打开同一个网页后，会通过 WebSocket 同步显示所有人发送的消息。

功能

• 原生 HTML/CSS/JavaScript 前端聊天框
• FastAPI 后端提供静态页面与异步 WebSocket 服务
• 多客户端实时广播消息
• 支持上传图片，图片以 base64 data URL 形式在 WebSocket 中传输并存入内存
• 支持手动清空消息
• 支持在前端通过下拉框设置自动清理时间，前后端通过 cron 表达式传输配置
• 消息只存储在内存中，重启服务后丢失
• 默认每 12 小时自动清空全部历史消息
• 健康检查接口：/health

目录结构

msg-sync/
├── app/
│   ├── main.py
│   └── static/
│       └── index.html
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md

本地调试

pip install -r requirements.txt
python app/main.py

访问：

• 前端页面：http://127.0.0.1:8080
• 健康检查：http://127.0.0.1:8080/health

python app/main.py 内部会启动 uvicorn，适合本地调试。

生产运行

conda activate pytools
cd app
uvicorn main:app --host 0.0.0.0 --port ${PORT:-8080} --workers 1

这里固定 --workers 1 是因为消息保存在进程内存中；如果开多个 worker，每个进程会有各自独立的消息列表和 WebSocket 连接池，客户端之间可能收不到彼此的消息。需要横向扩展时，应改成 Redis pub/sub 或类似的共享消息通道。

Docker 运行

docker compose up -d --build

访问：

http://127.0.0.1:8080

环境变量

变量	默认值	说明
TZ	Asia/Shanghai	消息发送时间使用的时区
PORT	8080	python app/main.py 启动时监听的端口
UVICORN_RELOAD	false	是否开启 uvicorn reload 模式，仅建议本地调试使用
CLEANUP_CRON	0 */12 * * *	自动清空消息的 cron 表达式，默认每 12 小时
MAX_MESSAGES	500	内存中最多保留的消息数
MAX_MESSAGE_LENGTH	1000	单条消息最大字符数
MAX_IMAGE_BYTES	2097152	单张图片最大字节数，默认 2MB

WebSocket 协议

连接地址：

ws://127.0.0.1:8080/ws

发送消息：

{
  "type": "message",
  "content": "你好",
  "image": null
}

发送图片：

{
  "type": "message",
  "content": "这是一张图片",
  "image": {
    "name": "photo.png",
    "mime": "image/png",
    "data": "data:image/png;base64,..."
  }
}

接收历史消息：

{
  "type": "history",
  "messages": [],
  "settings": {
    "cleanup_cron": "0 */12 * * *"
  }
}

接收新消息：

{
  "type": "message",
  "message": {
    "id": "uuid",
    "content": "你好",
    "image": null,
    "sent_at": "2026-07-02 12:00:00"
  }
}

手动清空消息：

{
  "type": "clear_messages"
}

设置自动清理时间：

{
  "type": "set_cleanup_cron",
  "cleanup_cron": "0 */6 * * *"
}

设置更新广播：

{
  "type": "settings",
  "settings": {
    "cleanup_cron": "0 */6 * * *"
  }
}