埋点分析系统 - 部署指南

版本：v1.1.0

更新日期：2026-07-31

一、系统要求

组件	最低版本	说明
Python	3.10+	后端运行环境
Node.js	18+	仅构建前端时需要（部署包已含构建产物）
ClickHouse	任意版本	数据源，需网络可达
Docker	20+	Docker 部署方式需要
Docker Compose	2.0+	Docker 部署方式需要

二、Docker 部署（推荐）

2.1 准备配置

# 进入部署目录
cd deploy

# 复制环境变量模板
cp .env.example .env

# 编辑 .env，修改 ClickHouse 连接信息
vi .env

2.2 构建并启动

# 构建镜像并后台启动
docker-compose up -d --build

# 查看日志
docker-compose logs -f

# 查看运行状态
docker-compose ps

2.3 验证

# 健康检查
curl http://localhost:5000/api/health

# 预期返回
# {"code":0,"data":{"status":"running","timestamp":"..."}}

2.4 停止与重启

# 停止
docker-compose down

# 重启
docker-compose restart

# 更新代码后重新构建
docker-compose up -d --build

2.5 数据持久化

系统用户数据（SQLite）存储在 Docker volume tracker_data 中，对应容器内路径 /app/backend/data。

备份用户数据：

docker cp tracker-analytics:/app/backend/data/users.db ./users.db.bak

恢复用户数据：

docker cp ./users.db.bak tracker-analytics:/app/backend/data/users.db
docker-compose restart

三、传统部署（非 Docker）

3.1 Linux

# 赋予脚本执行权限
chmod +x deploy/scripts/*.sh

# 后台启动（生产模式）
./deploy/scripts/start.sh daemon

# 前台启动（调试模式）
./deploy/scripts/start.sh

# 停止服务
./deploy/scripts/stop.sh

3.2 Windows

:: 后台启动
deploy\scripts\start.bat daemon

:: 前台启动
deploy\scripts\start.bat

:: 停止服务
deploy\scripts\stop.bat

3.3 配置说明

传统部署方式通过 deploy/.env 文件加载环境变量，脚本会自动读取。首次运行会自动创建 Python 虚拟环境并安装依赖。

四、环境变量说明

变量名	默认值	说明
`CLICKHOUSE_HOST`	114.80.38.24	生产环境 ClickHouse 地址
`CLICKHOUSE_PORT`	9000	ClickHouse TCP 端口（不是 8123）
`CLICKHOUSE_USER`	default	ClickHouse 用户名
`CLICKHOUSE_PASSWORD`	（需配置）	ClickHouse 密码
`CLICKHOUSE_DATABASE`	clklog	数据库名
`CLICKHOUSE_TABLE`	log_analysis	数据表名
`TESTCLICKHOUSE*`	192.168.20.147	测试环境 ClickHouse 配置（同上）
`AUTHADMINUSER`	admin	管理员登录名
`AUTHADMINPASSWORD`	clklog	管理员初始密码
`CORS_ORIGINS`	*	允许跨域的来源
`FLASK_PORT`	5000	服务监听端口

重要：CLICKHOUSE_PORT 必须使用 9000（TCP 原生协议端口），不能使用 8123（HTTP 端口）。clickhouse-driver 库仅支持 TCP 协议。

五、Nginx 反向代理（可选）

如果需要通过 80/443 端口访问或配置 HTTPS，可在前面加一层 Nginx：

server {
    listen 80;
    server_name analytics.example.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

六、功能模块

模块	路径	说明
概览看板	/	整体数据概览
事件分析	/events	事件趋势与分布
元素分析	/elements	元素点击分析
用户分析	/users	用户行为分析
留存分析	/retention	留存矩阵与曲线
漏斗分析	/funnel	转化漏斗
页面路径	/screens	页面流转分析
数据明细	/detail	原始事件查询与导出
系统用户	/sysusers	用户管理（仅管理员）

七、默认账号

角色	账号	密码	说明
管理员	admin	clklog	首次启动自动创建，可修改

首次登录后请及时通过右上角"修改密码"功能更新密码。

八、常见问题

Q1: 启动后页面空白？

A: 检查 frontend/dist/index.html 是否存在。传统部署需先执行 npm run build。

Q2: ClickHouse 连接失败？

A: 确认端口是 9000（TCP），不是 8123（HTTP）。检查网络连通性和密码。

Q3: 端口 5000 被占用？

A: 修改 .env 中的 FLASK_PORT，或停止占用端口的进程。

Q4: Docker 构建很慢？

A: Dockerfile 已配置清华 pip 源加速。如仍慢，可检查网络或使用代理。

Q5: 忘记管理员密码？

A: 删除 backend/data/users.db 后重启，系统会重新初始化默认 admin 账号。