KX-Verse：我为四个产品造的那个"底盘"，一套自研应用工程底盘的构造说明

摘要：当四个完全不同的产品——工时记录、宝贝记录、电子礼金簿、在哪儿——都需要账号、同步、后台、备份、监控这些同样的东西时，你有两个选择：抄四遍，或者造一次底盘。我选了后者。这篇讲讲这块底盘是怎么设计、怎么进化、又怎么在几次真实事故里被打磨成型的。

一、从一张下载页说起

事情的开端其实很小：我只想给自己的第一款产品做一个下载页和一个管理后台。

第一版做出来，能用，但每往里加一点东西都要绕开一堆历史决定。做到第二个产品时我开始抄自己——把第一个项目的用户体系、API 鉴权、备份脚本原样复制一份再改。抄到第三个的时候，我意识到一件不太舒服的事：每开一个新项目，真正"属于这个项目"的代码其实只占一小部分。 剩下的那些——登录态、云同步、版本发布、数据备份、异常告警、后台界面——全都是同样的东西换一层皮。

于是有个念头变得无法回避：这些重复的部分，本身就是一个产品。

我把它抽了出来，起了个名字：KX-Verse，中文名"开序域"。它不是某个 App，也不是某个网站，而是它们脚下共同的那块钢板。如今四个产品跑在同一块底盘上，任何一个新产品立项，剩下的工作就真的只有产品本身。

二、三层语义：底盘、整车、生态

KX-Verse 的架构里只有一句话是纲领，其余都是从它推出来的：

框架是底盘，项目是整车，扩展才是可插拔的生态。

这句话听着像废话，但它回答了一个很多自研框架都没想清楚的问题：业务代码到底放在哪？很多框架的答案是"plugins"或"modules"——业务被当成框架的一个挂件，升级框架时如履薄冰，删掉模块时提心吊胆。KX-Verse 的答案是：业务是整辆车的主体，框架只是它脚下可以整体更换的底盘。

落到实现上，是一条被严格执行的边界纪律：

• 框架只认识一份叫 project.json 的清单文件，和清单里登记的那个服务提供者类名。它绝不 import 任何项目代码——框架对项目的全部认知，就是清单里声明了什么；
• 项目想用框架的能力，只走注册表和钩子，不去改框架的文件。这条纪律让框架文件在所有实例之间保持逐字节一致，"五站同步"从一句口号变成了一条可以机器校验的纪律；
• 每个产品在底盘上是一个围栏完整的 project/ 目录：清单登记路由、权限、菜单和 App 页面源；源码走独立的命名空间；数据库迁移自动纳入全局；视图挂独立命名空间。目录围栏即产品边界。

这套边界的实际收益很具体：任何一个产品可以被打包成标准源码包、整体迁移到另一块底盘上；框架升级不会碰坏任何一个产品；想摘掉一个产品，拔掉清单里的一行就行。

三、四个整车

底盘造好之后，上面陆续装配了四辆车，形态完全不同：

• 工时记录——为趟次型工作设计的时间账本。六步打卡、站名管理、跨设备云同步，服务的是"几点出车、几点到站"这类以"趟"为计量单位的工作形态；
• 宝贝记录——十六类记录的成长日记。喂养、睡眠、疫苗、身高体重、照片时间线，配上一条为海量照片而生的缩略图管线，离线优先，全家共享一本账；
• 电子礼金簿——把人情往来记成清楚账。收送双线、还礼对冲、往来对账，配一台自建 OCR 微服务，把祖辈手写的礼簿一页页搬进手机；
• 在哪儿——家庭寻物收纳。三级空间树、防泄露二维码、条码识别、药箱食品柜效期提醒，还能蓝牙打印标签贴回柜子上。

四个产品共享同一套用户体系、同一条同步协议、同一个后台、同一条发布流水线。它们唯一的差别，就是各自的业务本身——这正是底盘的意义。

四、自己管自己的底盘

一个只提供业务骨架的框架不算底盘。KX-Verse 里我最满意的部分，是那套让它在四个生产环境里"自己管自己"的设施：

体检。一条 doctor 命令对运行环境做 42 项检查——缓存配置、路由缓存、文件属主、备份新鲜度、进程状态、跨实例一致性——任何一项异常都会明说原因。每次部署完跑一遍，全绿才收工。它抓过太多东西：属主残留、被烤进缓存的旧配置、漏跑的定时任务。

冒烟。一条 smoke 命令把全站所有路由请求一遍，任何 5xx 都会被点名。它防的是那种最阴险的问题：首页看起来好好的，某个犄角旮旯的接口其实早就炸了。配合"应用日志错误率巡检"，多数故障能在用户感知之前被发现。

看门狗。每五分钟巡检 HTTP 存活、磁盘水位、证书有效期、备份新鲜度。告警带节流——不会半夜给你刷一百封邮件；恢复带确认——抖动一次不会产生"告警、恢复、告警、恢复"的噪音循环。

备份。每日自动全量备份，支持加密后推送异地：AES-256 加密体加 HMAC 完整性校验，密钥独立存放。加解密的密钥曾经出过一次轮换缺陷——配置缓存的存在让密钥读不到，每次备份都重新生成密钥并覆盖旧的，历史附件全部变废纸。修复之后我又给它加了一条纪律：备份策略改动的验证方式不是"跑一遍成功"，而是"拿到备份文件、在一个干净环境里恢复出来、核对行数"。

能力开关。内容、商城、装修、数据源、AI……框架内置的能力全部开关化，每个产品按需裁剪，关掉的模块连路由都不注册。四个实例的框架文件保持逐字节一致，差异只存在于配置和项目目录——一致性本身也是体检项目。

五、后台与设计语言

管理后台是所有产品共用的驾驶舱：数据总览、用户管理、版本发布、备份管理、体检报告，全部集中在一处。

视觉上它经历过一次完整的设计语言收敛：早先各页面的样式散落在几十个视图里，内联样式、硬编码色值随处可见；后来统一收敛到一套共享样式表，抽出一层设计变量——圆角、间距、动效速度、焦点环——所有控件从同一套基类里长出来。深浅两套主题全量适配，移动端单独调过断点。这件事的收益不在好看，在于改一个变量等于改全站：后来加的每个页面自动继承同一套气质，设计漂移被结构性地杜绝了。

六、发布流水线

App 的发布是一条全自动的链：源码在底盘的项目目录里，一条导出命令打包成标准源码包——清单页自动注册、tabBar 自动重写、站点配置自动注入、关键文件逐一校验——本地云打包出 APK，传回后台的应用中心上架，老版本 App 启动时自动收到更新提示。

从"改一行代码"到"用户手机上弹更新框"，中间没有任何手工步骤。版本号本身也有一套纪律：小改进第三位、中改进第二位、大改进第一位，逢四跳过——因为"4"在中文语境里不吉利，这是一条用户亲手定的规矩，底盘负责执行。

七、官网：给底盘做的一张"蓝图"

框架自己的官网我改过三版。最新一版彻底告别了"SaaS 模板风"，走的是"工程底盘蓝图美学"：分节用工程图纸式的编号，注记用等宽字体标着"FIG.1 / SCALE / REV"；页首是一张底盘拓扑图，中心节点向四个产品连线，纯 CSS 画流动虚线和脉冲环；能力介绍排成编辑部式的全宽产品行，悬停时色洗、箭头转四十五度；技术栈做成规格表，产品编号一如零件目录。

细节上花了很多功夫：进场动画按阶梯错峰，数字滚动计数，卡片有跟随指针的聚光灯，导航带滚动高亮，顶部有阅读进度条——而所有动效在系统开启"减弱动态效果"时全部回退，一行不少地保证可访问性。深色模式下按钮渐变一度出现对比度不足，最后干脆把主按钮的渐变固定成不随主题变化的常量——有些东西就该是恒定的，这也是底盘哲学的一部分。

八、功能全景与技术栈

给底盘拍一张"全家福"，规格说明式的。

功能全景：

• 账号与安全——注册登录、双因素认证、QQ 互联登录、会话管理、操作日志（敏感信息递归脱敏）；
• 数据能力——自研云同步协议（幂等、墓碑、增量游标）、全站备份与加密异地推送、回收站语义；
• 发布链路——应用中心（版本发布、公告管理、源码包）、项目一键导出、应用内自更新；
• 运维体系——42 项环境体检、全路由冒烟、五分钟看门狗巡检（HTTP 存活、磁盘、证书、备份新鲜度、日志错误率）、分实例进程池隔离；
• 性能与缓存——全页缓存中间件、多级缓存失效钩子、数据库参数调优、静态资源治理；
• 产品化能力——能力开关（按产品裁剪模块）、多主题系统、后台设计变量层、项目层与围栏。

技术栈：

九、克制

最后说一个也许最不"技术"的决定。

整个底盘的第三方业务依赖，除了框架本身，只有一行——一个交互式调试工具。所有看似可以"找个现成库"的通用件——全页缓存、站点体检、看门狗、加密备份、项目导出、二维码生成——都是自己写的，有些甚至只是把一个成熟算法库单文件收编进来。

原因无他：底盘是要在多个生产环境里同时服役的东西，每一个第三方依赖都是一条必须长期供养的供应链。自己写的每一行，坏的时候我知道去哪修；别人写的黑盒，坏的时候我只有等待和祈祷。把四个产品的可靠性押在同一个底座上之后，克制是我唯一敢做的选择。

底盘会继续进化，四个整车会继续跑。下一站见。