跳到主要内容

系统架构

系统总览

Open ACE (AI Computing Explorer) 是一个企业级 AI 工作区平台,包含三层架构:

┌─────────────────────────────────────────────────────────┐
│ Browser (React SPA) │
│ Work Mode (all users) Manage Mode (admin only) │
│ ┌────────┬──────────┐ ┌──────────────────────┐ │
│ │Session │Workspace │ │ Dashboard / Admin │ │
│ │ List │(iframe) │ │ Pages (20+) │ │
│ │ │Terminal │ │ │ │
│ └────────┴──────────┘ └──────────────────────┘ │
└──────────────────────┬──────────────────────────────────┘
│ HTTP / WebSocket
┌──────────────────────┴──────────────────────────────────┐
│ Flask API Server │
│ 23 Blueprints │ 14 Services │ 11 Repositories │ 31 Mods │
│ Background Schedulers │ Middleware │ Auth │
└──────────┬───────────────────┬───────────────────────────┘
│ │
┌──────────┴──────┐ ┌────────┴────────────────────────────┐
│ SQLite/PostgreSQL│ │ Remote Agent (daemon) │
│ 35+ tables │ │ HTTP polling │ CLI subprocesses │
│ Alembic │ │ WebSocket PTY │ Session sync │
└─────────────────┘ │ Claude/Qwen/Codex/OpenClaw │
└─────────────────────────────────────┘

后端架构

分层架构

Routes (Flask Blueprints)
→ Services (business logic, schedulers)
→ Repositories (data access)
→ Database abstraction (SQLite or PostgreSQL)

Modules (domain logic):
analytics/ compliance/ governance/ sso/ workspace/

应用入口

app/__init__.pycreate_app() 工厂函数:

  1. 创建 Flask 应用
  2. 应用 ProxyFix 中间件以支持 nginx
  3. 配置 SECRET_KEY
  4. 注册错误处理器(API 返回 JSON,页面返回标准格式)
  5. 注册 23 个 Flask Blueprint
  6. 运行 ensure_all_tables() 初始化 DDL 模式
  7. 启动后台调度器

Blueprint 路由

Blueprint前缀说明
admin_bp/api用户 CRUD、系统账户创建
alerts_bp/api告警管理、WebSocket 推送
analysis_bp/api使用分析、趋势、异常检测
analytics_bp/api企业分析、CSV 导出
auth_bp/api登录、注册、登出、会话、头像
compliance_bp/api/compliance合规报告、数据保留
fetch_bp/api数据采集脚本、采集状态
fs_bp/api文件系统浏览
governance_bp/api审计日志、配额、内容过滤
insights_bp/apiAI 对话洞察
messages_bp/api消息数据、分页、导出
pages_bp/React SPA 全局捕获
projects_bp/api项目 CRUD、统计、文件扫描
quota_bp/api配额检查、执行
remote_bp/api/remote远程机器、会话、LLM 代理
report_bp/api使用报告
roi_bp/apiROI 分析、成本优化
sso_bp/api/ssoSSO 提供商管理、OAuth2/OIDC
tenant_bp/api/tenants多租户管理
tool_accounts_bp/api用户-工具-账户映射
upload_bp/api外部数据导入
usage_bp/api使用数据、CSV 导出
workspace_bp/api/workspace会话、提示词、工具连接

服务层

服务说明
AnalysisService批量分析、指标、异常检测(ThreadPoolExecutor 4 线程)
AuthService认证、会话管理、速率限制
DataFetchScheduler后台调度器,每 5 分钟运行采集脚本
InsightsService通过 GLM-5 模型提供 AI 洞察
MessageService消息查询、筛选、分页
PermissionServiceRBAC、角色-权限映射、自定义权限
QuotaEnforcementScheduler每 60 秒检查配额,终止超额会话
SummaryService预聚合使用摘要
TenantService多租户 CRUD、基于套餐的配额
UsageService使用数据、按工具统计
UserDailyStatsAggregator将 daily_messages 聚合到 user_daily_stats
WebUIManager每用户 qwen-code-webui 进程(端口 3100-3200)
WorkspaceService协调协作、提示词、会话

仓储层

仓储说明
DailyStatsRepository预聚合每日统计
GovernanceRepository内容过滤规则、安全设置
InsightsReportRepository洞察报告 CRUD
MessageRepository基于 daily_messages 的消息数据访问
ProjectRepository项目 CRUD、统计
TenantRepository租户 CRUD、设置、用户
UsageRepository每日使用量、按工具统计、CSV 导出
UserRepository用户 CRUD、认证查询
UserToolAccountRepository用户-工具-账户映射

模块包

app/modules/analytics/ — 使用分析、ROI 计算、成本优化

app/modules/compliance/ — 审计分析、合规报告(SOX/GDPR/HIPAA)、数据保留

app/modules/governance/ — 审计日志、告警通知、配额管理、内容过滤(PII 检测)

app/modules/sso/ — SSO 提供商生命周期、OAuth2 授权码流程、带 ID Token 验证的 OIDC

app/modules/workspace/ — API Key 代理(加密存储)、协作、提示词库、远程代理/会话管理器、会话持久化、状态同步、终端存储、工具连接器、WebSocket 代理

数据模型

模型说明
User + UserRole + Permission基于角色的用户管理
Message带 token 和元数据的消息追踪
Session认证会话
Tenant + TenantSettings + TenantUsage多租户与基于套餐的配额
Usage按日期/工具的使用追踪
Project + ProjectStats项目管理和统计
UserToolAccount用户到 AI 工具发送者名称的映射

数据库

双数据库支持

app/repositories/database.py 中的 Database 抽象层同时支持 SQLite(单机)和 PostgreSQL(生产环境):

  • adapt_sql(query) — 将 ? 占位符转换为 PostgreSQL 的 %s
  • is_postgresql() — 从 DATABASE_URL 检测当前数据库类型
  • 连接池psycopg2.pool.ThreadedConnectionPool(min=1, max=10)
  • Database — 支持 DI 的封装,提供 execute()fetch_one()fetch_all()table_exists()
  • 默认 SQLite 路径:~/.open-ace/ace.db

完整表结构参考请参阅 DATABASE-SCHEMA.md

中间件

中间件用途
ProxyFix信任来自 nginx 的 X-Forwarded-For / X-Forwarded-Proto
CORS 头after_request 处理器,用于 /api/ 路由的 localhost 跨域
OPTIONS 处理器预检 CORS 响应
错误处理器API 路由返回 JSON,页面返回标准 HTTP
/health返回服务状态和 git commit hash

后台服务

调度器间隔说明
DataFetchScheduler5 分钟(最小 60 秒)运行采集脚本、刷新物化视图、聚合统计、检查配额
QuotaEnforcementScheduler60 秒(最小 30 秒)检查用户配额、终止超额会话、生成告警

两者都是在 create_app() 中启动的单例守护线程,包裹在 try/except 中以防止启动失败。

前端架构

技术栈

  • React 18 + TypeScript + Vite 6
  • TanStack React Query v5 — 数据获取,1 分钟 stale time
  • Zustand v5 — 状态管理,支持 localStorage 持久化
  • Bootstrap 5 + Headless UI — 样式和无障碍组件
  • Chart.js + react-chartjs-2 — 数据可视化
  • xterm.js — 终端模拟
  • react-router-dom v7 — 双轨路由

双轨路由

工作模式 (/work/*) — 所有用户:

  • 3 面板布局:会话列表 + 工作区(iframe)+ 辅助面板
  • 路由:sessions、prompts、usage、insights、workspace

管理模式 (/manage/*) — 仅管理员:

  • 侧边栏导航布局,20+ 管理页面
  • 路由:dashboard、analysis、messages、audit、quota、compliance、security、users、tenants、projects、remote machines、SSO settings

完整前端参考请参阅 FRONTEND-GUIDE.md

远程代理架构

┌──────────┐ HTTP Polling ┌──────────────┐
│ Agent │ ◄──────────────► │ Flask API │
│ (daemon) │ 1s interval │ │
└────┬─────┘ └──────────────┘
│ subprocess

┌──────────────────────────────────────────────┐
│ CLI Adapters │
│ Claude Code │ Qwen Code │ Codex │ OpenClaw │
└──────────────────────────────────────────────┘
│ WebSocket

┌──────────────────────────────────────────────┐
│ Terminal Server (PTY) │
│ 64KB output buffer │ HMAC auth │ reconnect │
└──────────────────────────────────────────────┘

远程代理作为 Python 守护进程运行在远程机器上,提供:

  • HTTP 轮询 — 注册机器,每 1 秒轮询命令,每 60 秒心跳
  • CLI 子进程管理 — 启动 Claude Code、Qwen Code、Codex 或 OpenClaw
  • WebSocket 终端 — 浏览器通过终端服务器连接 PTY
  • 会话同步 — 扫描 ~/.claude/~/.qwen/~/.codex/ 的会话历史,每 30 秒同步到服务器

客户端指南请参阅 REMOTE-AGENT.md,服务端指南请参阅 REMOTE-WORKSPACE.md

认证

app/auth/decorators.py 中的三个认证装饰器:

装饰器用途
@auth_required需要有效的 session token;可选 ownership='session''machine'
@admin_required需要 admin 角色
@public_endpoint标记为有意公开的端点

Token 提取顺序:session_token cookie → Authorization: Bearer 头 → token 查询参数。

完整权限模型请参阅 PERMISSION-MODEL.md