董云舟先说个让我下定决心搞这套东西的现场。上个月排查一个线上故障，调用链查到一半我人都麻了——订单服务直接连了用户中心的MySQL，支付服务绕过了网关调内部接口，还有两个服务互相依赖出现了环。这些不是这次故障的根因，但它们在调用链里真实存在，而且谁都不知道它们是什么时候冒出来的。架构在演进，腐化也在同步发生，只是没人看见罢了。那之后我就开始认真调研CodeSentinel，把架构适应度看板纳入团队的技术债治理计划。这篇文章就是完整的部署记录，从环境准备到Agent接入，从指标设计到看板上线，以及中间踩过的坑，希望能让想搞架构可观测性的团队少走弯路。无论你是架构师、SRE，还是负责技术平台的后端开发，这篇都值得收藏。
1. 为什么需要CodeSentinel：架构腐化与适应度函数
架构演进这件事，最难的往往不是设计，而是让演进不偏离设计的轨道。我们团队从单体拆微服务，拆了两年，服务数量从十几个涨到六十多个。架构图画在文档里还规规矩矩，线上代码早就亲兄弟明算账了。我总结过团队踩过的坑，基本可以归成三类。
1.1 架构腐化的三种典型现场
第一是依赖失控。服务之间调用关系没人全程盯着，A依赖B、B依赖C，有一天C反过来调A，一个环就形成了。出现循环依赖后，发版顺序开始变得极其敏感，线上故障的爆炸半径被成倍放大。你排查调用链的时候，会看到数据在一个圈里转好几圈才落库，那是真的头皮发麻。
第二是契约漂移。接口的入参出参没有严格的兼容性检查。某个服务给接口加了一个必填字段，调用方不知道；或者某个内部接口悄悄改了个字段含义，消费方拿到的数据直接语义反转。这些问题在单元测试里测不出来，只有上了预发、联调或者线上告警的时候才暴露。
第三是边界突破。最典型的就是应用直连数据库。我们明明有统一的数据访问层，但某次紧急需求里，有同学图省事，在业务代码里写了个JDBC连接串，绕过中间层直接查库。这种事一旦开了头，后面就有第二个、第三个。很多人觉得“就这么一次没事”，但架构就是这么被蚕食的。
1.2 适应度函数：把架构规则变成可自动验证的断言
光靠代码评审去防这些问题，基本防不住。代码评审讨论的是实现细节，“这个循环依赖到底算不算引入新架构债”这种话题在评审会上根本聊不透。而且架构腐化是渐变过程，单次提交看起来都是合理的，累计到一个季度再看，整个架构已经歪了。
后来我们接触到“适应度函数”这个概念。它原本源自测试领域的断言思想：对某个架构特征定义一个可量化的指标，然后持续验证这个指标是否符合预期。比如“任意服务不允许反向依赖上层应用”就是一条架构规则，“服务间循环依赖数量必须为0”也是一条规则。把这些规则做成自动检查，每次发布后都跑一遍，有问题就告警，这就是适应度函数的落地形态。
1.3 CodeSentinel 到底干四件什么事
CodeSentinel从这个思想出发，做了一套完整的架构监控平台。我理解下来它做的事情就是四件：
- 持续采集：通过Agent从各个服务采集接口调用关系、依赖方向、发布事件、配置变更等数据，不需要业务代码侵入。
- 规则校验：内置了一批架构适应度函数，也支持用DSL自定义规则。采集到的数据会实时跑规则，命中就记录违规事件。
- 评分归档：按模块、按服务维度计算适应度得分，把架构健康度随时间的变化趋势存下来，方便追踪每次发布对架构的影响。
- 可视化与告警：把得分、违规事件、依赖图呈现在看板上，同时对接钉钉、邮件、Webhook做分级告警。
本质上它就是给架构装了一套“持续监控的仪表盘”，让我们能像盯CPU、内存一样盯架构健康度。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 部署前必须想清楚的三件事：拓扑、环境与数据链路
部署这套系统本身不算复杂，但如果你没想清楚架构拓扑、存储选型和数据链路，后面扩容和排障会很难受。我按我们最终敲定的方案来讲。
2.1 组件拓扑：Server、Agent 与看板怎么分工
CodeSentinel的部署模型是中心化Server加边缘Agent。核心组件有三个：
- codesentinel-server：主服务，负责接收Agent上报的数据、跑规则引擎、写存储、提供API。
- codesentinel-agent：部署在业务服务所在的主机上，以Sidecar或独立进程方式运行，采集服务的调用数据和元信息，然后批量上报给Server。
- codesentinel-web：看板前端，直接消费Server的API，展示适应度得分、依赖图谱和告警记录。
这三个组件可以全部部署在同一台机器上，也可以拆开。我们刚开始是单体部署，后面流量上来之后把Server和Web拆到了不同节点。如果你公司环境有Kubernetes，可以直接用Helm Chart，但我觉得刚开始没必要上K8s，先在一台4C8G的虚机上跑起来，比什么都强。
2.2 环境与版本选型：别再纠结“最新版”
环境这块，我们用的是Ubuntu 22.04 LTS + Docker 24.0 + Docker Compose v2，数据库先用PostgreSQL 15，缓存用的Redis 7。为什么选PostgreSQL而不是MySQL？因为CodeSentinel的规则引擎会产生很多JSON结构的数据，PG的JSONB做这类查询更顺手。当然MySQL也能跑，但配置里很多索引是面向PG优化的，别和自己过