47 lines
1.5 KiB
Plaintext
47 lines
1.5 KiB
Plaintext
|
---
|
|||
|
|
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 至少覆盖：认证失败、校验失败、成功路径
|