开发日记
按时间回看每个项目做了什么、踩了什么坑、做了哪些取舍。共 12 条记录。
项目全部项目智慧乐活圈 lehuoquan乐活圈 OA 考勤 lehuoquan-oaMagicEngine 悦居魔法引擎如影随形 TraceMate悦居集团数字化 · 统一后台悦居智能 CRM悦居可视通话 yueju-call悦居存储管家 StorageMate悦居反诈专家 AntiFraud悦居智能NVR小红花 LittleBlossom悦居统计后台 DashboardFileBreeze悦居护眼卫士 EyeGuard宠物小程序贝芽妈(lovely-child)悦居智能官网悦居存储管家 AndroidSmartHome 安卓控制端适老智家 AgeHome悦居 AI 日历轻风快传官网 FileBreeze中航天业竞价小程序绿荫网球中心官网绿荫网球小程序青年公社小程序青年公社官网中羊坊村官网 Zhongyangfang自动化脚本集 automation我的减肥日记 WeightLoss画山别墅的旅行家 Travel画山别墅里的国学世界 GuoXue冰雪冬奥张山营延庆骑行网 YanqingBike延庆徒步网 GoHike智能门锁 SmartLock排队仿真 QueueSimulation悦居智能小程序 yueju-miniprogram智能会议室预约 meeting乡村文旅 VillageHub减肥日记小程序日常运维国学小程序 guoxue3D智慧城市 SmartCityLiveRobot 数字人应梦寺爬山smart_home_chat花间向导 SmartGuideWorkBuddy 指标看板T5AI 聊天机器人悦居AI相册(相册管家)
2026-10-27
补上版本控制:此前两周一直不是 git 仓库
- 项目从 10-15 起就一直不是 git 仓库。能跑、能部署,但没有任何「什么时候改了什么」的证据
- 补上时第一件事不是
git add .,而是先把排除规则写对:运行数据、数据库与 WAL、哈希盐、环境变量、日志全部排除 - 排除规则里最容易被漏的是备份目录:
data.bak-*这种名字不被data/规则覆盖,一不留神就把 7MB 演示数据悄无声息地收进仓库。第一次提交前逐条核对过一遍,确认没有库文件 / 密钥 / 依赖目录 - 因为补得晚,五笔提交全落在同一天,但实际开发跳了 13 天。这种「时间线失真」是无法事后修的 —— 能记录真实日期的地方是开发日记,不是提交时间
- 一个反思:版本控制不该等到「要交付了」才补。在它不是 git 仓库的那两周里,任何一次改坏都没有回退点,只是恰巧没出事
页面停留改用独立细桶:一把尺子量不了两种东西
- 现象:页面停留的 P50 恒等于 P90,每一行都是同一个数
- 根因:页面停留复用了会话时长的分桶。会话时长跨 5 秒到几十分钟,桶在 0~60 秒内只有 3 格;而页面停留集中在 0.3~60 秒,两个分位数直接落进同一格,取到同一个代表值
- 这不是算错,是尺子不对。改成给页面停留单独一套 8 格细桶后,分位数立刻分开
- 同时拆了会话桶的尾部:原来的「10 分钟以上」是个巨桶,会吞掉一切,导致 P75 与 P90 也常常相等
- 一个时机判断:现在是改桶边界的唯一窗口期。桶名是字符串存在表里的,线上还没有新口径数据时改边界零迁移成本;一旦积累几个月真实数据,就得处理新旧两套桶名混在同一张表里
- 演示数据也一并修了:原先所有页面共用一个均匀分布,导致每页停留一模一样。改成每页一个中位数 + 对数正态抽样 —— 真实停留是右偏的,少数长尾拉长平均,中位数才是那个「一般情况」
- 结论:分位数用直方图近似是省存储的正确做法,但「一套桶到处用」是错的。桶边界必须贴着每个指标的真实分布分别设计
多端不做 N 个 SDK,做一个协议 + N 个薄适配层
- 需要覆盖 Web、小程序、App、电视四类端。直觉是各写一个 SDK,但那是四条互相不知道对方存在的时间线
- 四份实现(JavaScript / Kotlin / Swift / Dart)迟早会在派生字段上漂移。最先出事的会是「会话累计时长」这种要计算的字段:一份从页面进入算、一份从会话开始算,两套口径就永久分叉了,而且没人会发现 —— 看板上只是两个数不一样
- 唯一有效的防线是契约测试:一套共享的 JSON 用例,每个实现都必须逐字节通过。原生实现只要写几十行执行器就能跑同一批
- 基线用「改造前的 Web 行为」生成,改造后逐字节一致 —— 这才证明重构没有改变任何现有行为,而不是「我觉得没改」
- 核心层同时做了能力化:必需接口 13 个,其余能力自动探测,缺能力只少一个字段而不是抛错。否则原生端要写一堆空实现,漏一个就崩
- 另一层设计:平台差异不在「怎么发 HTTP」,而在「什么算一次会话」。电视上一集剧 45 分钟,沿用 30 分钟超时会把一集切成两段,会话数直接翻倍、平均时长对半砍 —— 这种错在报表上看起来完全正常。所以会话超时、最短停留、离线队列都按平台分档,写进协议而不是写死成全局常量
- 电视端目前不做:没有真实项目,做出来就是没验证的代码,等真有项目时需求一定会变。协议里已预留客户端枚举和阈值覆盖,将来只需「写一个适配层」,不必「改协议」
- 服务端同步补了三个接收口径:客户端名归一化(多端一并入必然出现各种写法,不归一按端分组会碎成十几个桶)、设备维度允许自报(原生端没有 UA,否则设备分布图只能看见 Web)、协议版本收下并做版本自检(用来发现「某个端静默跑着半年前的老 SDK」)
生产迁移上线:v0.1 老库升级到 v0.3,历史数据全量重放
- 起点:生产库还是 v0.1 结构,19,878 条事件(10-09 到 10-15),只有页面浏览与离开两种事件,其中 1,771 条明文用户标识、19,878 条明文 UA
- 迁移顺序:备份(含 WAL checkpoint)→ 传代码 → 停服 → 按新口径从原始事件全量重放聚合 → 清明文字段 → 隐私门禁复验 → 启动
- 重建正确性不能靠感觉:先在本地用同一份数据重建一次,比对前后页面浏览数 / 会话数 / 访客数 / 停留桶计数完全一致,才敲在生产上跑
- 重放后「时长」有 3,938 个会话样本,页面停留 P50 45 秒、P90 120 秒 —— 两个分位数分开,说明细粒度桶在真实历史数据上真的生效了
- 上线后用真实浏览器逐页人眼复核,四个新模块的历史数据表现符合预期,无报错、无 NaN
- 一条提醒:迁移后看默认 7 天区间是空的,属正常 —— 真实数据在 10-09 到 10-15,要看就得手动改区间
- 根本判断:预聚合的真身是原始事件,所以可以「清空重算」而不是「增量兼容」—— 这比写两套兼容代码便宜得多
老库升级时 DDL 顺序错了,会让整批事件静默丢失(P0)
- 现象:生产启动日志里只有一行「存储域预热失败(将退回懒加载)」,很容易当成噪音跳过
- 实际后果:建表和建索引写在同一段 DDL 里,而「表已存在就跳过」这句话不会给已存在的表补列。老库的事件表没有新加的列,于是执行到建索引那行报「列不存在」,整段中断 —— 后面的补列一次都没跑,写入语句也建不出来,该月所有事件静默丢失
- 之所以一直没暴露,是因为站点还没真正嵌入 SDK,没触发过写入。一旦接入第一个站,第一颗真实埋点就会撞上
- 修法:DDL 拆两段,顺序固定为 建表 → 补列 → 建索引。索引创建是幂等的,每次启动重建代价可忽略
- 验证走生产库冷拷贝:修前预热报错,修后预热 24.4ms 通过,事件表自动补出 7 个列、索引建成、写入与聚合都正确
- 教训:这类错误不报错、不崩溃、不留痕,只在日志里留一行可以被忽略的失败。凡是「静默降级」的日志都该被当成 P0 排查,而不是优雅的兜底
- 同一类问题的另一面:懒加载看着更稳(启动不报错),实际只是把错误推到了第一个真实请求上,而那时候已经有人在线上了
一次页面离开产生 3 条 page_leave,停留时长虚高 3 倍
- 用真实浏览器实测:1 个 page_view 对应 3 个 page_leave,时长分别 2466 / 2482 / 2482ms
- 原因:Web 端同时监听了 pagehide、beforeunload、visibilitychange 三个事件,关页面时三个连续触发同一个回调,而结算函数没有幂等保护
- 后果比数字难看:页面停留样本量、会话时长、停留直方图的计数全部虚高 3 倍。这种错不报错、不崩溃,报表看起来完全正常,只是每个数都错了
- 修法:幂等锁加在核心层而不是适配层 —— 因为原生端有一模一样的问题(Android 的 onPause + onStop、iOS 的 viewWillDisappear + didEnterBackground 都是连续两个回调),一处修全部端
- 一个细节:短停留(低于最短停留阈值)既不结算也不上锁,留给下一次离开机会 —— 用户可能只是短暂切到后台又回来
- 修完复验:1 个 page_view → 1 个 page_leave
- 这类 bug 的特点:不会有人报障,因为界面全部正常,只是分母比分子胖了三倍
沉默页面必须双层数据源 —— 无人问津的页面在埋点里根本不存在
- 直觉做法是「查一下哪些页面很久没有访问记录」。这只覆盖了一半
- 它能找到的是「曾经活过、现在死了」的页面:这些页面留下过数据,所以能上榜单
- 但「上线之后一次都没人访问」的页面在埋点里连一条记录都没有 —— 它不会出现在任何榜单上,也就永远不会被发现该下线。这恰恰是最该下线的那些
- 解法:除被动埋点外,再开一条主动通道,由站点上报自己有哪些页面。两路交叉比对:清单里有、埋点里没有 = 上线即无人问津
- 附带一条必须显性化的结论:如果站点根本没上报清单,覆盖度就是 0,此时「沉默为零」不是好消息,是「还看不见」。界面上专门留了一块警告说明这件事,而不是让一个漂亮的 0 蒙混过去
- 现状:22 个站一个都没上报清单,所以那块警告一直在亮 —— 这是真的
- 另一条相关设计:功能名不做预登记。埋点随手命名,事后自动归集 + 一键合并同义名,改名不丢历史
M1b:导航按「要回答什么问题」重新分组,补上四个模块
- 导航从 3 个 tab 扩到 7 个,按「要回答什么问题」分三组:概览(总览 / 实时)、分析(流量 / 时长)、治理(沉默资产 / 崩溃 / 功能)
- 使用分析:会话时长分桶直方图 + P50/P75/P90 + 快速退出率 + 深度使用率 + 页面停留榜
- 沉默资产:阈值可调 30/60/90/180/365 天,双路数据源交叉比对
- 崩溃监控:崩溃率趋势双轴图 + 无崩溃率 + 按指纹分组 + 行内展开堆栈
- 功能归集:跨站排行 + 按站点勾选合并同义名 + 一键撤销
- 每个模块都能直接分享链接(hash 路由),不用教人怎么点进去
- 顺手修了一处显示:相邻分位数落进同一个桶时合并成一行(如 P50–P90)并说明「是分布集中,不是算错」。界面摆三个一模一样的数字,用户第一反应是系统坏了
- 折叠处理:沉默资产的覆盖度表默认铺满 19 行「缺失」会把整页占完,改成一行摘要 + 展开按钮
2026-10-22
性能门禁 25% 概率假失败,问题不在代码在测量
- 同一份没改过的代码,四次跑出 5.01 / 7.39 / 4.22 / 14.91ms,阈值 10ms —— 有一次直接判红
- 三个原因叠在一起:
① 单轮 500 样本算 P99 只有 5 个数据点,基本被操作系统调度主导
② 测量顶着上一轮自己造的队列积压(落盘上限约 750 行/秒,而压测远高于此)
③ 存储域懒加载,第一次写入把编译开销也算进了延迟
- 修法:三轮取中位、新增「服务端 handler P99 < 5ms」第二阈值、每轮前等队列排空、启动预热。连跑三次 5.51 / 4.31 / 4.09ms 稳定通过
- 教训:一个会随机报错的门禁比没有门禁更糟 —— 它教会所有人忽略红灯
- 同族的另一条:开着一个副本服务和浏览器时测出 9.4ms 贴着阈值,清场后立刻回到 4.5ms。看性能数字之前先看环境干不干净,否则测的是「谁在抢 CPU」
M1a:重构成 ingest / store / query 三分域,打点接口不再阻塞
- 原先是单进程双库,读写混在一起,查询一慢就拖到打点
- 重构成三域:ingest(脱敏后立即返回 204,永不阻塞)→ store(唯一落盘出口)→ query(只读,预聚合 + 30 秒缓存)
- 实测推翻了一个假设:存储不是瓶颈(每个事件约 321 字节),真正的瓶颈是同步 SQLite 接口把事件循环堵住
- 所以光做「内存微批」不够 —— 一批 750 行照样一口气写完,一次堵上百毫秒。改成每片 150 行 + 主动让出事件循环:不切片时 p99 59ms,切片后单片 8ms
- 崩溃明细单独一个库只留 30 天,但崩溃率的趋势聚合仍然留 12 个月 —— 明细是排查用的,趋势是决策用的,保留期不应一样长
- 存储域启动时预热:三库连接与语句预先备好,冷启动开销不摊给第一个访客(实测 14.4ms)
2026-10-15
隐私从「配置项」改成「架构约束」
- 常见做法是用一个配置开关控制「要不要记 IP」,但那只是承诺,不是约束 —— 一个手滑的日志、一次临时排查就能绕过去
- 改成结构性约束:IP 只在内存里查一次归属地,查完立刻置空,继续往下传的对象上根本不存在这个字段。存储域在代码结构上就拿不到 IP,不需要靠任何人不犯错
- 访客标识一律做带盐的单向哈希(32 位十六进制),并立为不变量:库里任何匿名标识都必须是哈希,不许直接把会话 id 塞进去当「匿名 id」—— 那只是把明文字段换了个名字
- UA 默认不落原文,只留操作系统 / 浏览器 / 设备类型三个分类值
- 这条不变量写成了自动化自检脚本并进发布门禁:跑不过就发不出去,不靠人看
- 理由:隐私一旦是「配置项」,它就会在某个赶进度的下午被打开,而且再也不会被关闭
v0.1 打通链路:埋点 → 落库 → 看板渲染全通
- 三个模块:总览 / 实时 / 流量。一套脚本嵌进站点就能出数
- 链路:浏览器采集 → 打点接口 → 落库 → 查询接口 → 看板渲染
- 当天定下三条底线:单租户自用(不做 SaaS,无注册 / 无计费 / 无多租户)、隐私优先、打点不能影响业务站
- 打点路径定在
/fbtrack而不是/api/track:各站自己的/api/已被业务后台占用,会抢先匹配。这个坑不看代码看不出来,接第二个站的时候才会炸 - 接入成本压到一行脚本 + 一行初始化,不用改 nginx
- 同时产出产品规划、架构设计与交付说明三份文档