埋点分析系统 - 后端技术架构

代码路径：e:\AI工作台\埋点分析系统\backend\

---

技术栈

组件	技术
框架	Flask 3.0
数据库驱动	clickhouse-driver 0.2.6
生产服务器	Gunicorn 23.0 (4 workers)
认证	Token-based（内存存储，12h TTL）
缓存	内存缓存，5 分钟 TTL
CORS	Flask-CORS

---

API 模块架构

app.py (Flask 入口)
├── before_request → Token 鉴权 + 环境切换
├── auth_bp      → /api/auth       (登录/登出/信息/修改密码)
├── overview_bp  → /api/overview   (KPI/趋势/事件类型/TOP事件/设备/地域)
├── events_bp    → /api/events     (分布/趋势对比/列表/类型枚举)
├── users_bp     → /api/users      (KPI/趋势/设备/来源/OS/网络/活跃用户)
├── screens_bp   → /api/screens    (流转/列表/入口/出口)
├── flow_bp      → /api/flow       (流量概览/新老访客/搜索词/来源网站)
├── elements_bp  → /api/elements   (KPI/热门内容/类型分布/热力图/趋势)
├── detail_bp    → /api/detail     (明细查询/CSV导出/筛选项)
├── retention_bp → /api/retention  (留存KPI/矩阵/曲线)
├── funnel_bp    → /api/funnel     (漏斗分析)
├── channel_bp   → /api/channel    (渠道分析)
└── sysusers_bp  → /api/sysusers   (系统用户管理，@admin_required)

---

请求处理链

before_request
  → 从 X-Env Header 获取环境
  → 切换 ClickHouse 连接
  → Token 鉴权（白名单: login/health/info）

@cached(ttl=300) 装饰器
  → 5 分钟内存缓存

get_project_filter_params()
  → 注入 project_name IN (...) 过滤

ClickHouse 参数化查询
  → %(param)s 占位符，防 SQL 注入

---

数据库连接

配置项	值
协议	TCP (端口 9000)
连接池刷新	5 分钟
并发控制	threading.Lock()
重试机制	2 次（首次失败后重置连接）
生产地址	114.80.38.24:9000
测试地址	192.168.20.147:9000

---

核心文件

文件	功能
app.py	Flask 应用入口，蓝图注册，全局鉴权
config.py	多环境配置（生产/测试），环境变量注入
database.py	ClickHouse 连接池 + 线程锁 + 重试机制
utils.py	工具函数（日期、项目过滤、响应格式、缓存装饰器）
user_store.py	SQLite 用户存储（SHA-256 密码哈希）
gunicorn.conf.py	Gunicorn 生产配置

---

安全措施

• SQL 参数化查询（防注入）
• Token 鉴权 + 白名单机制
• @admin_required 保护系统管理 API
• CORS 限制为指定来源
• 密码 SHA-256 哈希存储
• 不能删除/禁用最后一个管理员