00 · 导读与环境准备

系列目录：README ｜ 下一篇：01 项目分析

这个项目最终长什么样

先看成品，再决定要不要花时间跟着做——这是最负责任的学习方式。

烽火台 Beacon Tower 是一个自研的全栈可观测运维监控平台。用一句大白话讲： 它是给你自己的服务器和 Web 应用装的"体检仪 + 心电图机 + 报警器"。

• 你的网站突然变慢了——它告诉你慢在哪条 SQL、哪个接口（APM 调用链瀑布图）；
• 服务器 CPU 飙了——它每 15 秒记一笔，还能把多台服务器的数据汇到一个页面（主机监控 + Agent）；
• 用户抱怨页面打不开——它从真实用户的浏览器采集加载耗时和 JS 报错（前端 RUM）；
• 半夜服务挂了——它自动发现、自动告警、自动记录恢复（告警中心 + 通知渠道）；
• 数据攒了一堆——它还自带异常检测、趋势预测、相关性分析（智能分析）。

对标的是腾讯云可观测平台的模块形态，但全部自研、数据不出你的服务器：

跑起来什么样？ 在线演示：https://beacon.lianghui.vip， 登录页直接展示了只读演示账号和密码，输入就能进（是"演示访客"组，只读， 看不到令牌等敏感页面——这本身就是项目的一个安全设计，第 10 篇会讲）。

跟着做完，你会得到什么

1. 一个能写进简历的完整项目：从需求分析到设计、开发、测试、部署全流程，面试时每一段都有话讲；
2. 一套可复用的工程方法： - 采集与写库解耦（批量缓冲，实测 p99 2190ms → 251ms）； - 后台任务的租约选主（多副本部署不重复采集）； - 整站登录门禁 + 接入令牌最小作用域 + SSRF 闸门等一整层安全工程； - 125 个测试用例 + CI 的工程化实践；
3. 对"可观测性"的真正理解：Metrics / Tracing / Logging 三支柱不再是名词，而是你亲手写出来的代码。

技术栈一览（以及为什么是它们）

特别说明：算法全部用 Python 标准库手写（滑动 3σ、最小二乘、皮尔逊、正则模板聚类）。 不是不知道有 numpy/scipy，而是教学项目要"可解释优先"——每个结论都能回溯到原始数据， 你也能看懂每一行数学是怎么变成代码的。

环境准备（Windows / macOS / Linux 都覆盖）

第 1 步：安装 Python 3.10+

Windows：去 https://www.python.org/downloads/ 下载最新安装包（3.10～3.13 都可以）。 安装时务必勾选 "Add python.exe to PATH"——90% 的"python 不是内部或外部命令"都是这一步漏了。

macOS：

# 用 Homebrew（没有先装 brew：https://brew.sh）
brew install [email protected]

Linux（Ubuntu/Debian）：

sudo apt update && sudo apt install -y python3 python3-venv python3-pip

验证（三个系统通用，Windows 注意 python 不带 3）：

python --version    # Windows；输出 Python 3.12.x 即可

python3 --version   # macOS / Linux

常见报错：Windows 下 python 弹出微软商店 → 是 PATH 没配好， 重装勾选 "Add to PATH"，或到"管理应用执行别名"里关掉两个 python 别名。

第 2 步：安装 VS Code（编辑器）

到 https://code.visualstudio.com/ 下载安装，然后装两个扩展（左侧扩展面板搜索）：

1. Python（Microsoft 官方）——代码提示、调试、测试发现；
2. SQLite Viewer——随时打开 db.sqlite3 看数据表，调试神器。

（你用 PyCharm 也完全可以，教程只依赖"能改文件、能跑命令"。）

第 3 步：安装 Git

Windows：https://git-scm.com/download/win，一路下一步。 macOS：brew install git 或 xcode-select --install。 Linux：sudo apt install -y git。

验证：

git --version     # git version 2.x.x

配一下身份（提交记录会用）：

git config --global user.name "你的名字"
git config --global user.email "[email protected]"

第 4 步：把参考仓库拉到本地（可选但推荐）

git clone https://github.com/lianghui32/beacon-tower.git
cd beacon-tower

重要心态：这个仓库是"完成态答案"。教程会带你自己从空文件夹重建， 卡住的时候去答案里对照同名文件（每篇教程都会标出对应路径），学习效果远好于直接读答案。

第 5 步：先把成品跑起来（建立"目标感"）

不等教程，5 分钟先让平台在你机器上转起来：

Windows（PowerShell）：

cd beacon-tower
python -m venv .venv
.\.venv\Scripts\Activate.ps1        # 若提示禁止运行脚本：Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
pip install -r requirements.txt
python manage.py migrate
python manage.py init_data           # 生成演示数据 + 管理员（凭据写入 admin_credentials.txt）
python manage.py runserver 8014

macOS / Linux：

cd beacon-tower
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py init_data
python manage.py runserver 8014

打开 http://127.0.0.1:8014/，用 admin_credentials.txt 里的账号密码登录。 花 10 分钟把 README 的"推荐体验路径"点一遍：总览 → 故障演练 → APM → 日志 → 主机 → 告警事件 → 智能分析 → RUM → 诊断 → 大盘。知道终点长什么样，后面的每一站才走得踏实。

看完了按 Ctrl+C 停掉服务，退出虚拟环境：

deactivate        # Windows / macOS / Linux 通用

第 6 步：建你自己的工作目录

从下一篇开始，我们不再用仓库目录，而是在自己的项目文件夹里从零开始：

# Windows
mkdir beacon-tower-lab; cd beacon-tower-lab; python -m venv .venv; .\.venv\Scripts\Activate.ps1

# macOS / Linux
mkdir beacon-tower-lab && cd beacon-tower-lab && python3 -m venv .venv && source .venv/bin/activate

永远记得：每篇教程开始写代码前，先激活这个虚拟环境——它保证你装的包只属于这个项目。

学习方法建议（重要，比环境更重要）

1. 敲，不要抄。代码自己敲一遍，手指会帮你记忆结构；报错了自己先读报错信息再搜；
2. 每篇的"检查点"必须亲眼确认。它是你和教程之间的对账单，对不上就停下排查，别带着问题往前跑；
3. "为什么"比"怎么做"值钱。教程里每个设计决策都写了取舍理由（比如为什么采集和写库要解耦、 为什么限速要"用户名超限不锁正确密码"），面试时能讲出 why 的人凤毛麟角；
4. 把答案仓库当字典，不当参考答案抄。先自己写，写不出来再看它怎么写，看完合上再自己写。

本篇检查点

• [ ] python --version（或 python3 --version）输出 3.10+
• [ ] git --version 有输出
• [ ] VS Code + Python 扩展装好
• [ ] 参考仓库已 clone（或已在 GitHub 上能打开）
• [ ] 成品在本地 8014 端口跑起来过，登录进过监控总览
• [ ] beacon-tower-lab 工作目录已建好，虚拟环境能激活

常见报错速查

下一篇，我们把"做一个监控平台"这句模糊的话，拆成一张明确的需求清单—— 01 · 项目分析。