release: nexus btpanel session fix and app-v2

2026-07-08 22:31:31 +08:00
commit 1933f0af6e
2457 changed files with 350105 additions and 0 deletions
@@ -0,0 +1,46 @@
+---
+description: Nexus Python/FastAPI 后端规范 — 异步、Pydantic、Repository、UTC 时间
+globs: server/**/*.py
+alwaysApply: false
+---
+
+# Nexus Python 后端
+
+## 依赖版本（勿随意降级）
+
+FastAPI 0.115 · SQLAlchemy 2.0 async · aiomysql · Pydantic v2 · asyncssh 2.17 · redis 5.x · PyJWT 2.10
+
+## API 路由
+
+- 请求/响应模型定义在 `server/api/schemas.py`
+- 业务 API 必须 `Depends(get_current_admin)`；Agent 用 `X-API-Key`；install 路由无 JWT
+- 返回结构化错误，禁止裸 `except: pass`
+
+## 数据库
+
+- 模型：`server/domain/models/__init__.py`（14 表）
+- 访问：`*_repo.py`，分页在 Repository 层 `offset/limit/count`
+- 时间戳：`datetime.now(timezone.utc)`，禁止 naive datetime
+- 连接池：默认 pool=160、overflow=120（安装向导按 MySQL `max_connections` 计算）
+
+## Redis
+
+- 客户端：`server/infrastructure/redis/client.py`，启动时强校验（ADR-009）
+- 心跳 key：`heartbeat:{server_id}` TTL 600；告警 key：`alerts:{server_id}` TTL 3600
+- 跨 worker 广播：Redis Pub/Sub `nexus:alerts`
+
+## SSH
+
+- 仅用 **asyncssh**（已删除 paramiko）
+- 连接池引用计数：`acquire` / `release`，空闲 5min 清理
+- 远程命令参数必须 `shlex.quote()`
+
+## 凭据加密
+
+- Fernet 存储 `Server.password` / `ssh_key_private`
+- API 响应：`password_set` 布尔，禁止返回明文密码
+
+## 测试
+
+- `pytest` + `tests/conftest.py`；改 API/Service 须跑相关测试
+- 新 endpoint 至少覆盖：认证失败、校验失败、成功路径