Skip to content

docs(patrol): 2026-06-18 文档维护 — session key 公式 + Pool 指标同步 #759

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hotplex-ai merged 1 commit into from
Jun 17, 2026
+8 −1
Merged

docs(patrol): 2026-06-18 文档维护 — session key 公式 + Pool 指标同步 #759

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/explanation/session-lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ HotPlex 使用 UUIDv5（SHA-1 哈希 + 固定命名空间）生成确定性的 S

**两种 Key 派生方式**：

1. **通用 Key**（`DeriveSessionKey`）：`SHA1(namespace, ownerID|workerType|clientKey|workDir)`，适用于 WebChat 和直连 WebSocket。`clientKey` 是客户端传入的 `client_session_id`（REST）或 `session_id`（WS init），经过 `SanitizeText()` 清洗和 `MaxClientKeyLen`（256 字符）长度校验。
1. **通用 Key**（`DeriveSessionKey`）：`SHA1(namespace, ownerID|workerType|clientKey[|workspaceID]|workDir)`，适用于 WebChat 和直连 WebSocket。`clientKey` 是客户端传入的 `client_session_id`（REST）或 `session_id`（WS init），经过 `SanitizeText()` 清洗和 `MaxClientKeyLen`（256 字符）长度校验。`workspaceID` 是 WebChat 多租户锚点（spec ① 方案3），仅非空时加入派生——不同 workspace 即使其余字段相同也得到不同 Session Key；切换 workspace 或 worker_type 均产生新 Key（spec ③ 锁定此不变量）。
2. **平台 Key**（`DerivePlatformSessionKey`）：根据平台类型拼接不同字段：
- Slack：`ownerID|wt|slack[|teamID][|channelID][|threadTS][|userID][|workDir]`
- 飞书：`ownerID|wt|feishu[|chatID][|threadTS][|userID][|workDir]`
Expand Down
7 changes: 7 additions & 0 deletions docs/reference/metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,11 @@ sum by (event_type) (rate(hotplex_gateway_messages_total{direction="outgoing"}[5
|------|------|------|
| `hotplex.pool.acquire` | Counter | 配额获取尝试次数，label: `result` |
| `hotplex.pool.release.errors` | Counter | 双重释放错误数（表示 bug） |
| `hotplex.pool.utilization` | ObservableGauge (float) | 资源池利用率（0-1），活跃会话数 / `max_size` |
| `hotplex.pool.active_sessions` | ObservableGauge | 活跃 worker 会话数（全局，含 platform/cron） |
| `hotplex.pool.distinct_users` | ObservableGauge | 至少有一个活跃会话的去重用户数 |
| `hotplex.pool.distinct_workspaces` | ObservableGauge | 至少有一个活跃会话的去重 WebChat workspace 数（不含 platform 会话，spec ⑤） |
| `hotplex.pool.memory_reserved_bytes` | ObservableGauge | per-user 内存配额下预留的字节数（仅 `max_memory_per_user` 设置时累加；512MB/worker 估算值，非实际 RSS，spec ⑤） |

### 获取结果标签

Expand All @@ -147,6 +152,8 @@ sum by (event_type) (rate(hotplex_gateway_messages_total{direction="outgoing"}[5
| `success` | 成功获取 |
| `pool_exhausted` | 全局 Worker 数已满 |
| `user_quota_exceeded` | 单用户 Session 数已满 |
| `workspace_quota_exceeded` | 单 workspace Session 数已满（`max_per_workspace`，spec ①） |
| `memory_exceeded` | 单用户内存配额超限（`max_memory_per_user`） |

### 常用查询

Expand Down