0dbac480ae
- 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
127 lines
3.8 KiB
Markdown
127 lines
3.8 KiB
Markdown
# imks — IM 实时消息服务
|
||
|
||
基于 **Engine.IO + Socket.IO** 协议的即时通讯（IM）实时消息服务，支持 WebSocket、WebTransport、HTTP Long-Polling 多种传输层，通过 gRPC 与 [appks](https://github.com/your-org/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** (可选, 低延迟多节点广播)
|
||
|
||
### 安装 & 运行
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
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 格式指标 |
|
||
|
||
### 健康检查示例
|
||
|
||
```json
|
||
{
|
||
"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`](./.env.example)。
|
||
|
||
### 核心配置
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|---|---|---|
|
||
| `IMKS_ADAPTER` | `local` | `local` \| `redis` \| `nats` |
|
||
| `DATABASE_URL` | `postgres://localhost/imks` | PostgreSQL 连接串 |
|
||
| `APPKS_GRPC_ADDR` | `http://localhost:50051` | appks gRPC 地址 |
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
cargo check # 快速检查语法
|
||
cargo test # 运行所有测试（111 个）
|
||
cargo test --lib # 仅库测试（91 个）
|
||
cargo clippy # Lint 检查
|
||
cargo fmt # 格式化
|
||
```
|
||
|
||
## 文档
|
||
|
||
- [AGENTS.md](./AGENTS.md) — 开发规范
|
||
- [rpc.md](docs/rpc.md) — 认证方案 & Proto 契约
|
||
- [migrate/](./migrate/) — 数据库迁移脚本
|
||
|
||
## 许可证
|
||
|
||
[待定]
|