Files

T

zhenyi 0dbac480ae feat(telemetry): integrate OpenTelemetry observability stack with health metrics

- Add OpenTelemetry SDK, OTLP exporter, Prometheus integration
- Implement connection tracking with active/total/disconnection metrics
- Add health endpoint with uptime and connection counts
- Integrate tracing spans for socket events and engine messages
- Add metrics collection for event handling duration
- Update health endpoint to include live runtime state
- Add graceful telemetry shutdown in main function
- Implement engine session active metrics tracking
- Add namespace-specific attributes to connection metrics
- Introduce message edit history retrieval endpoint
- Add scheduled message CRUD operations and dispatcher
- Update Socket.IO event registration with observability
- Refactor component update to remove dead code allowance
- Add comprehensive environment variables documentation
- Implement detailed development guidelines in AGENTS.md

2026-06-11 13:53:29 +08:00

3.8 KiB

Raw Blame History

imks — IM 实时消息服务

基于 Engine.IO + Socket.IO 协议的即时通讯（IM）实时消息服务，支持 WebSocket、WebTransport、HTTP Long-Polling 多种传输层，通过 gRPC 与 appks 核心服务集成，提供认证、权限、消息持久化和跨节点广播。

架构

Client (Browser/App)
    │  Socket.IO over WebSocket / WebTransport / Polling
    ▼
┌─────────────────────────────────────┐
│              imks                    │
│                                     │
│  engine/     socket/                │
│  • WS/WT/      • Socket.IO Server   │
│    Polling     • Namespace/Room     │
│  • Session     • Adapter (Redis/NATS)│
│  • Heartbeat   • Message Bus        │
│                                     │
│  models/      repo/       svc/      │
│  • 20+ 消息     • SQL CRUD   • 业务    │
│    领域模型      • 分页查询    逻辑层   │
│                                     │
│  auth/        rpc/                  │
│  • JWT 双模    • gRPC Stubs         │
│    验证        • Token/Channel/     │
│  • 密钥缓存      Member/Permission  │
└──────────────┬──────────────────────┘
               │ gRPC (mTLS)
               ▼
┌─────────────────────────────────────┐
│              appks (core)           │
│  Token  │ Channel │ Member │ ...    │
│  Postgres • Redis • NATS            │
└─────────────────────────────────────┘

快速开始

前置依赖

Rust 1.85+ (edition 2024)
PostgreSQL 16+ (消息持久化)
appks gRPC 服务 (认证 & 权限)
Redis (可选, 多节点广播)
NATS (可选, 低延迟多节点广播)

安装 & 运行

# 克隆仓库
git clone https://github.com/your-org/imks.git
cd imks

# 配置环境变量
cp .env.example .env
# 编辑 .env，至少设置 DATABASE_URL 和 APPKS_GRPC_ADDR

# 数据库迁移（自动执行）
# 首次启动会自动运行 migrate/ 下的 SQL 迁移

# 编译
cargo build --release

# 运行
cargo run --release
# 默认监听 http://0.0.0.0:3000

端点

端点	说明
`GET /engine.io/`	Engine.IO 握手 & WebSocket 升级
`POST /engine.io/`	Engine.IO HTTP Long-Polling
`GET /health`	健康检查（含连接数、会话数、依赖检查）
`GET /metrics`	Prometheus 格式指标

健康检查示例

{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-06-11T10:00:00Z",
  "uptime_secs": 3600,
  "connections_active": 42,
  "sessions_count": 42,
  "checks": {
    "postgres": { "status": "up", "latency_ms": 3 },
    "redis": { "status": "up", "latency_ms": 1 }
  }
}

环境变量

完整列表见 .env.example。

核心配置

变量	默认值	说明
`IMKS_ADAPTER`	`local`	`local` \| `redis` \| `nats`
`DATABASE_URL`	`postgres://localhost/imks`	PostgreSQL 连接串
`APPKS_GRPC_ADDR`	`http://localhost:50051`	appks gRPC 地址

开发

cargo check          # 快速检查语法
cargo test           # 运行所有测试（111 个）
cargo test --lib     # 仅库测试（91 个）
cargo clippy         # Lint 检查
cargo fmt            # 格式化

文档

AGENTS.md — 开发规范
rpc.md — 认证方案 & Proto 契约
migrate/ — 数据库迁移脚本

许可证

[待定]

3.8 KiB Raw Blame History