gouki
0d28c155e8
新增 AI 适配器时须同步在 seed.py PRESET_PROVIDERS 添加平台记录， 前端 AI 平台选择器从数据库 Provider 动态渲染，无硬编码列表。
59 lines
2.7 KiB
Markdown
59 lines
2.7 KiB
Markdown
---
|
||
description: vps-manager 核心编码规范，每次会话自动加载
|
||
alwaysApply: true
|
||
---
|
||
|
||
# vps-manager 编码规范
|
||
|
||
## 技术栈
|
||
|
||
- 后端：Python + FastAPI + SQLModel
|
||
- 前端：Vue 3 + Tailwind CSS（本地化、深色模式、PWA）
|
||
- 数据库：SQLite 分库（assets.db / metrics.db）
|
||
- 加密：cryptography.Fernet（MASTER_KEY 存 .env）
|
||
- 部署：cc1 节点，Gitea push 自动更新，HTTPS via Tailscale
|
||
|
||
## 前端：移动端优先
|
||
|
||
- UI 设计遵循移动端优先原则，采用底部导航栏适配小屏幕
|
||
- 确保页面 scrollWidth 等于 clientWidth，避免横向溢出
|
||
- 桌面端使用侧边栏布局，移动端使用底部 Tab 导航
|
||
- 静态资源基于文件 mtime 自动注入 `?v={mtime}` 版本号，配合 Service Worker 实现缓存失效
|
||
|
||
## Service Worker 缓存策略
|
||
|
||
- HTML 导航请求：`network-first`（回源失败才用缓存）
|
||
- 静态资源：`stale-while-revalidate`（SWR），配合 `?v={mtime}` 版本号
|
||
- API 请求：纯网络模式，不经过 Service Worker
|
||
- `sw.js` 本体由服务端设置 `Cache-Control: no-cache`
|
||
|
||
## 数据库分库
|
||
|
||
- `data/assets.db`：资产核心数据（Provider / Asset / VPSDetail / DomainDetail / AIAccount / Credential）
|
||
- `data/metrics.db`：监控指标与日志（MetricPoint / ServerInfo / SecurityCheck / EventLog）
|
||
- 备份策略：assets.db 每日备份保留 14 份，metrics.db 每周备份保留 4 份
|
||
|
||
## 凭证与加密
|
||
|
||
- 凭据中心化架构：`credentials` 表作为登录凭据唯一事实源
|
||
- 使用 `cryptography.Fernet` 加密敏感字段，MASTER_KEY 存于 `.env`
|
||
- 账号表降级为纯"归属 + API 配置"容器，通过 `account.credential_id` 关联凭据
|
||
|
||
## 云厂商适配层
|
||
|
||
- 位于 `app/adapters/`：BaseAdapter 抽象基类 + `@register` 装饰器注册
|
||
- 按 `Provider.sdk_type` 路由，完整适配器清单以 `app/adapters/registry.py` 的 `@register` 注册项为唯一事实源
|
||
- 当前已注册：Vultr / DO / Cloudflare / 阿里云 / 腾讯云 / AWS / Linode / NameSilo / AI 适配器组（DeepSeek / Moonshot / OpenAI / MiniMax）
|
||
- 新增 AI 适配器时，须同步在 `app/core/seed.py` 的 `PRESET_PROVIDERS` 中添加对应平台记录（`category: ai_agent`、`services: ai_agent`），前端 AI 平台选择器从数据库 Provider 动态渲染，无硬编码列表
|
||
- sync_service 以 `(provider_id, external_id)` 去重同步入库
|
||
|
||
## 平台分类
|
||
|
||
- `category` 字段仅作主业务标签用于列表排序和兜底展示，不设"综合平台"分类
|
||
- 资产关联平台时以 `services` 多标签为准，优先匹配目标资产类型对应的服务能力
|
||
|
||
## 通知
|
||
|
||
- 通知服务根据 `.env` 配置自动选择 Telegram 或邮件渠道
|
||
- 未配置渠道自动跳过，不中断通知流程
|