43-模块六-架构演进与团队协作第43讲-模块实战 - CodeSentinel 完整部署与架构适应度看板上线

模块六-架构演进与团队协作 | 第43讲：模块实战 - CodeSentinel 完整部署与架构适应度看板上线

本讲目标：完成贯穿全课的 CodeSentinel 总装交付——把前序模块中的 FastAPI 网关、审查流水线、规则引擎、代码索引与 RAG、Git Webhook、适应度函数与可观测性层整合为 可一键启动的 docker-compose 拓扑，并上线 架构适应度看板、技术债追踪看板、团队协作度量 三类最小可用界面（HTML + API）。你将拿到 部署检查清单、端到端演示路径（GitHub PR → 自动审查报告），并对全课程的架构决策做系统性复盘。本文含大量 Mermaid 架构图/部署图 与可运行的配置草案，便于你在真实团队中改造落地。

开场：从「能跑的 Demo」到「能运营的平台」

前几讲我们分别实现了 CodeSentinel 的关键拼图：安全规则扫描、架构门禁、性能预算、质量评估、LangChain 编排、向量索引与检索增强、Webhook 驱动的异步流水线等。把它们拼在一起时，最常见的失败不是某段代码不工作，而是 服务边界不清、配置散落、观测不足、以及缺少面向团队的统一入口。

本讲站在 平台运营者 视角：你要回答三个问题——系统如何部署、如何证明它对架构治理有效、如何让团队愿意持续使用。因此，交付物不只是容器清单，还包括 适应度分数如何计算、技术债如何入账与消减、协作指标如何避免变成内卷 KPI。

下面先给出 最终系统架构总览，再展开 docker-compose 全服务编排、三个看板的 API 契约、部署检查清单与 GitHub 端到端演示，最后做课程级复盘。

最终系统架构：六大子系统合一（Mermaid）

flowchart TB
  subgraph Edge["入口与集成"]
    GH["GitHub / GitLab"]
    WH["Webhook Receiver"]
    GW["FastAPI Gateway\n/api/v1/*"]
  end

  subgraph Pipeline["审查流水线 Review Pipeline"]
    SEC["Security Scanner\n(bandit/semgrep/custom)"]
    ARC["Architecture Rules\n(AGENTS.md + AST/依赖图)"]
    PERF["Performance Budget\n(基准/复杂度)"]
    QUA["Quality Gates\n(coverage/lint/types)"]
    ORC["Pipeline Orchestrator\n(状态机+重试)"]
  end

  subgraph Rules["规则管理引擎"]
    CRUD["AGENTS.md CRUD API"]
    PAR["Parser/Validator\n(frontmatter+章节)"]
    VER["Version/Publish\n(按仓库/分支)"]
  end

  subgraph Index["代码索引服务"]
    IDX["Indexer Job\n(git clone/shallow)"]
    CH["ChromaDB\n(向量存储)"]
    META["元数据 DB\n(Postgres)"]
  end

  subgraph RAG["RAG + LLM 审查"]
    RET["Retriever\n(混合检索)"]
    LLM["LLM Service\n(LangChain)"]
    REP["Review Report Builder\n(证据链)"]
  end

  subgraph Fit["适应度与治理"]
    FF["Fitness Function Runner\n(定时+触发)"]
    DASH["Fitness Dashboard API"]
    DEBT["Tech Debt Tracker"]
    COLLAB["Collaboration Metrics"]
  end

  subgraph Obs["可观测性"]
    LOG["结构化日志"]
    MET["Prometheus Metrics"]
    TRC["Tracing\n(OpenTelemetry)"]
  end

  GH --> WH --> GW --> ORC
  ORC --> SEC & ARC & PERF & QUA
  ORC --> RET
  CRUD --> PAR --> VER
  IDX --> CH --> RET
  RET --> LLM --> REP
  REP --> META
  FF --> DASH
  ORC --> DEBT
  GW --> COLLAB
  GW --> LOG & MET & TRC

读图要点：

Gateway 是唯一对外 REST 入口；Webhook 只进入受控接收端，经签名校验后投递编排器。
流水线 并行执行多维度门禁，统一汇聚为 ReviewReport（含规则命中、严重级别、证据片段、建议补丁）。
规则引擎 与 索引/RAG 解耦：规则是确定性约束，RAG+LLM 负责语义解释与上下文引用，两者不可互相替代。
适应度函数 是慢变量治理：按周/按版本计算架构健康分，与 快变量 PR 门禁 形成互补。

部署拓扑：docker-compose 全服务编排（示例）

以下 docker-compose.yml 为 课程总装参考实现：将网关、Worker、Postgres、Redis、Chroma、（可选）OTel Collector、静态看板 Nginx 统一编排。实际生产请替换镜像源、密钥管理与 TLS 终止。

# docker-compose.codesentinel.full.yml（课程参考）
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: cs
      POSTGRES_PASSWORD: ${CS_DB_PASSWORD:-change-me}
      POSTGRES_DB: codesentinel
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U cs -d codesentinel"]
      interval: 5s
      timeout: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redisdata:/data

  chroma:
    image: chromadb/chroma:latest
    environment:
      ANONYMIZED_TELEMETRY: "false"
    volumes:
      - chromadata:/chroma/chroma

  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    volumes:
      - ./deploy/otel-collector.yaml:/etc/otelcol-contrib/config.yaml:ro
    ports:
      - "4317:4317"

  api:
    build:
      context: ./services/gateway
    environment:
      DATABASE_URL: postgresql+psycopg2://cs:${CS_DB_PASSWORD:-change-me}@postgres:5432/codesentinel
      REDIS_URL: redis://redis:6379/0
      CHROMA_URL: http://chroma:8000
      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4317
      WEBHOOK_SECRET: ${WEBHOOK_SECRET}
      LLM_API_KEY: ${LLM_API_KEY}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
      chroma:
        condition: service_started
    ports:
      - "8000:8000"

  worker:
    build:
      context: ./services/worker
    command: ["celery", "-A", "worker.app", "worker", "-l", "INFO"]
    environment:
      DATABASE_URL: postgresql+psycopg2://cs:${CS_DB_PASSWORD:-change-me}@postgres:5432/codesentinel
      REDIS_URL: redis://redis:6379/0
      CHROMA_URL: http://chroma:8000
      LLM_API_KEY: ${LLM_API_KEY}
    depends_on:
      - redis
      - postgres
      - chroma

  dashboard:
    image: nginx:alpine
    volumes:
      - ./ui/dashboard:/usr/share/nginx/html:ro
    ports:
      - "8080:80"
    depends_on:
      - api

volumes:
  pgdata: {}
  redisdata: {}
  chromadata: {}

配套 .env.example（务必单独管理密钥）：

CS_DB_PASSWORD=please-use-strong-secret
WEBHOOK_SECRET=github-webhook-hmac-secret
LLM_API_KEY=your-llm-vendor-key
CS_PUBLIC_BASE_URL=https://codesentinel.example.com

部署视图：网络、证书与数据流（Mermaid）

flowchart LR
  subgraph Public["公网"]
    U["开发者"]
    GIT["GitHub"]
  end

  subgraph DMZ["入口层（TLS 终止）"]
    LB["反向代理\n(Nginx/Caddy)"]
  end

  subgraph App["应用 VPC"]
    API["FastAPI"]
    W["Worker"]
    R["Redis 队列"]
    P["Postgres"]
    C["Chroma"]
  end

  subgraph Ops["运维"]
    PROM["Prometheus"]
    GRAF["Grafana"]
  end

  U --> LB --> API
  GIT -->|HTTPS Webhook| LB --> API
  API --> R --> W
  API --> P
  W --> P
  W --> C
  API --> C
  API --> PROM
  W --> PROM
  PROM --> GRAF

三大看板：职责、数据与 API 契约

1）架构适应度看板（Architecture Fitness Dashboard）

目标：把「架构健康」从直觉变成 可时间序列化的分数。适应度函数示例如下（可配置权重）：

边界清晰度：跨层依赖数、违规 import、循环依赖计数。
模块化度：热点文件变更频率、扇入扇出异常。
可测试性：关键路径测试覆盖率、flaky 测试比例。
可观测性：关键服务是否暴露统一指标、日志字段是否齐全。
安全基线：密钥扫描、依赖 CVE 计数（阈值以上扣分）。

最小 API：

GET /api/v1/fitness/summary?repo_id=&range=30d → 总分、维度分、趋势。
GET /api/v1/fitness/history?repo_id= → 时间序列点。
POST /api/v1/fitness/run → 手动触发（需权限）。

极简 HTML 片段思路：用 Chart.js 或 ECharts 拉取 JSON；首页展示「本周分数、环比、Top 违规类型」。

2）技术债追踪看板（Tech Debt Tracker）

目标：把债 入账—指派—偿还—验证 闭环化。债务来源包括：流水线规则、LLM 审查建议（经人工确认后入账）、适应度扣分项自动开单。

最小 API：

POST /api/v1/debt/items 创建（title、category、severity、owner、due）。
PATCH /api/v1/debt/items/{id} 更新状态（open/wip/done/wontfix）。
GET /api/v1/debt/aging 账龄分布（用于治理例会）。

原则：不要让看板变成羞辱工具；应强调「偿还计划」与「系统性改进」（规则/脚手架），而非个人排名。

3）团队协作度量（Collaboration Metrics）

目标：提升审查体验与信息流动效率，而非监控程序员键盘。

建议指标：

PR 首次响应时间 p50/p90、合并周期。
审查轮次 与 重大缺陷发现阶段（越早越好）。
规则误报率 与 人工纠正率（反映工具可用性）。
知识扩散 proxy：跨团队审查参与次数（谨慎使用，避免形式主义）。

最小 API：

GET /api/v1/collab/metrics?team_id=&range=14d

部署检查清单（生产前逐项勾选）

安全与合规

Webhook HMAC 签名校验 已启用；重放攻击防护（timestamp/nonce）。
LLM 调用密钥来自 KMS/Secret Manager，而非仓库明文。
日志 PII/密钥脱敏；prompt 全量存储是否符合公司政策。
对外仅暴露必要端口；管理接口 鉴权 + RBAC。

可靠性与性能

Worker 并发与限流 与 LLM 供应商配额匹配；具备退避重试与死信队列策略。
索引任务幂等；大仓库采用 shallow clone 与增量索引。
Postgres 迁移脚本版本化；备份与恢复演练完成。

可观测性

核心指标：review_latency_seconds、pipeline_fail_total、llm_token_usage、webhook_drop_total。
Trace 贯通：trace_id 从 Webhook 到 LLM Span。
告警：429/5xx 比例、队列堆积、磁盘与向量库异常。

治理与运营

AGENTS.md 发布流程（谁可改、如何评审、如何灰度）。
误报治理流程：标签化、周会复盘、规则版本记录。
灾难演练：Git 服务不可用、模型不可用时的降级策略（仅跑确定性规则）。

端到端演示：GitHub 真实仓库 → PR → 全自动审查

步骤 A：准备仓库与权限

在 GitHub 创建测试仓库（建议含一个故意违规分支：例如硬编码密钥、跨层 import）。
在 CodeSentinel 侧登记 repo_full_name，生成 Webhook URL 与 Secret。
在 GitHub → Settings → Webhooks 添加 push / pull_request 事件。

步骤 B：触发流水线

新建分支提交代码并打开 PR。
Webhook 接收端校验签名 → 投递 review_pipeline 任务到 Redis 队列。
Worker 拉取 diff、运行多门禁、检索 Chroma 中相关片段、调用 LLM 生成解释性评论（带引用）。
结果写回 Postgres，并通过 GitHub Checks API 或评论机器人回显。

步骤 C：看板验证

打开 http://localhost:8080（示例）查看适应度总分是否更新。
在「技术债」页确认自动开单是否生成、指派是否可用。
在「协作」页观察 PR 周期指标是否入库。

演示成功的判据：不是「模型说了什么」，而是 规则命中可追溯、报告可复现、指标可解释、失败可降级。

课程项目复盘：我们做了哪些架构决策？学到了什么？

关键决策（Representative ADR 摘要）

确定性规则优先，LLM 解释其次：避免把合规建立在不可复现的生成上。
RAG 与规则引擎解耦：向量检索解决「上下文」，规则解决「硬约束」。
异步 Worker 处理重任务：网关保持低延迟，审查耗时集中在队列可观测区间。
治理指标双循环：PR 级快反馈 + 适应度慢反馈，防止「短期全绿、长期腐烂」。
证据链优先：对业务与审计友好，也降低模型胡说的破坏面。

经验教训

没有度量就没有改进：误报率不统计，团队会自然放弃工具。
规则需要产品化运营：写一次规则不是结束，是开始。
文化比工具更难：Tech Lead 要把审查变成正反馈循环（见第 42 讲）。
成本与合规是设计输入：token、存储、日志保留从一开始就进架构图。

flowchart TB
  subgraph Course["全课能力闭环"]
    M1[模块1-角色与风险认知]
    M2[模块2-规则与脚手架]
    M3[模块3-流水线与门禁]
    M4[模块4-RAG与LLM审查]
    M5[模块5-可观测与质量运营]
    M6[模块6-治理看板与领导力]
  end

  M1 --> M2 --> M3 --> M4 --> M5 --> M6
  M6 -. 反馈到规范与培训 .-> M2

适应度看板最小实现参考（FastAPI 路由草图）

下列代码仅示意 API 层形状，便于你把「分数」从脚本搬进服务；具体计分逻辑应调用 FitnessFunctionRunner 聚合各探测器结果。

# services/gateway/app/routers/fitness.py（示意）
from fastapi import APIRouter, Depends
from pydantic import BaseModel

router = APIRouter(prefix="/api/v1/fitness", tags=["fitness"])


class FitnessSummary(BaseModel):
    repo_id: str
    score: float
    dimensions: dict[str, float]
    delta_7d: float


@router.get("/summary", response_model=FitnessSummary)
def fitness_summary(repo_id: str, range: str = "30d"):
    # TODO: 从 Postgres 读取最近一次 runner 结果
    return FitnessSummary(
        repo_id=repo_id,
        score=82.4,
        dimensions={"boundary": 90, "modularity": 78, "testability": 85, "observability": 80, "security": 79},
        delta_7d=+1.2,
    )

小结与课后作业

你已完成 CodeSentinel 从理念到总装的关键一跃：一体化部署 + 治理看板 + 可演示的端到端路径。请记住，平台价值不在于「评论了多少行」，而在于 是否持续减少架构方差与技术债增长速度。

作业（三选一）：

将本文 docker-compose 映射到你公司现状：哪些组件可替换为托管服务？列出风险与收益。
设计一套 适应度权重：为你当前负责的系统定义 5 个维度与阈值，并解释业务理由。
走通一次真实 PR 演示并录制 5 分钟复盘：失败点在哪里？下一版如何改进？

附录提示：生产环境请补充 WAF、双向 TLS、mTLS 内网、密钥轮换、以及多租户隔离；若使用私有化模型，还需加入模型网关与 A/B 评测流水线。此处不展开，以免与具体厂商绑定。

43-模块六-架构演进与团队协作 第43讲-模块实战 - CodeSentinel 完整部署与架构适应度看板上线

模块六-架构演进与团队协作 | 第43讲：模块实战 - CodeSentinel 完整部署与架构适应度看板上线

开场：从「能跑的 Demo」到「能运营的平台」

最终系统架构：六大子系统合一（Mermaid）

部署拓扑：docker-compose 全服务编排（示例）

部署视图：网络、证书与数据流（Mermaid）

三大看板：职责、数据与 API 契约

1）架构适应度看板（Architecture Fitness Dashboard）

2）技术债追踪看板（Tech Debt Tracker）

3）团队协作度量（Collaboration Metrics）

部署检查清单（生产前逐项勾选）

安全与合规

可靠性与性能

可观测性

治理与运营

端到端演示：GitHub 真实仓库 → PR → 全自动审查

步骤 A：准备仓库与权限

步骤 B：触发流水线

步骤 C：看板验证

课程项目复盘：我们做了哪些架构决策？学到了什么？

关键决策（Representative ADR 摘要）

经验教训

适应度看板最小实现参考（FastAPI 路由草图）

小结与课后作业

43-模块六-架构演进与团队协作第43讲-模块实战 - CodeSentinel 完整部署与架构适应度看板上线