Files
webup-cloud/docs/ARCHITECTURE.md
T
WebUp Cloud db82325ed7
Verify control plane / verify (push) Canceled after 0s
Initial import of WebUp Cloud
2026-11-07 13:31:14 +08:00

39 lines
3.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 架构与实施计划
## 范围与边界
原始需求描述的是八个阶段的商业平台。当前从空目录开始,先交付可验证的控制面基础,不以占位页面或模拟基础设施宣称全部完成。各阶段的验收情况见 TEST-REPORT.md。
## 技术架构
- 用户端 / 管理端:Vue 3、TypeScript、Vite、Pinia、Vue Router,独立布局与路由守卫。
- 控制面:Java 21、Spring Boot 3.5、Spring Security、Bean Validation、JDBC、Flyway。模块化单体,同一数据库事务处理账户、审计和资金。
- PostgreSQL 为事实来源;Redis 存储限流窗口和一次性验证码,Redis 故障时认证关闭而非绕过验证。
- 不透明 Bearer 会话令牌,数据库只保存 SHA-256 摘要;用户端 sessionStorage 保存令牌,关闭标签页后清除。令牌不使用 Cookie 自动发送,因此不依赖 Cookie 认证的 CSRF 豁免。
- 管理角色由后端授权,前端守卫只改善体验。每次请求检查用户当前状态与会话撤销状态。
- AI Worker 和节点 Agent 在后续阶段独立部署。控制面不执行用户 shell,不挂载 Docker Socket。
## 数据设计
V1:users、roles、permissions、role_permissions、user_roles、user_sessions、login_logs、system_settings、admin_operation_logs。
V2:projects。V3:wallets、wallet_ledger、wallet_reservations、ai_providers、ai_models、ai_model_price_versions、ai_tasks、ai_task_messages、ai_task_steps、ai_usage_records。V4:ai_reconciliations。V5:模型当前价格版本指针。
用户 ID / 业务 ID 使用 UUID;会话有到期时间与撤销时间。账户使用 BCrypt,失败登录保留脱敏审计。系统设置采用允许列表,品牌、域名及页脚均从 API 加载。管理员初始化通过环境变量一次性引导,不使用默认密码。
## 分阶段交付
1. 基础:登录注册、一次性图形验证码、限流、账户 / 会话、管理员 RBAC、动态品牌、审计、Compose、测试。
2. 模型与 Agent:加密凭证、协议适配器、价格版本、不可变账本、预算预留、任务状态机、隔离工具执行、测试。
3. 网站运行:项目 / 服务 / 版本,构建 Worker、OCI、K3s 受控部署、日志及探针。
4. 数据库 / 存储:配额、独立凭证、S3、快照、恢复演练。
5. Pages / ESA:先核实账号能力,DNS 所有权、非标准回源端口、证书、蓝绿发布与回滚。
6. 节点 / 高可用:心跳、双探测、可靠 fencing、一致性迁移、RPO / RTO 验证。
7. 商业化:渠道分别适配、签名和金额校验、回调幂等、套餐、通知。
8. 运营 / 安全:细粒度权限、风控、可观测性、备份和故障演练。
## 风险约束
Docker 不等于虚拟机隔离;生产执行不可信代码前必须部署 gVisor / Kata 或同等级隔离并验证网络策略。迁移不能只复制卷,必须协调数据库写入及入口切换。没有凭证和独立测试环境时,不声明 ESA、支付、短信或生产高可用已联调。邮件与短信验证在适配器完成前不提供可启用开关,避免产生可绕过的认证流程。
版本依据:[Spring Boot 3.5 系统要求](https://docs.spring.io/spring-boot/3.5/system-requirements.html)、[Spring Security 密码存储](https://docs.spring.io/spring-security/reference/6.5/features/authentication/password-storage.html)、[Vite 要求](https://vite.dev/guide/)。