深入 Metabase 平台后端专家 Agent：应用数据库、HTTP 中间件栈与配置系统的技术全景

Metabase 的仓库自带一套 Claude Code Agent 体系，其中 .claude/agents/platform-backend-expert.md 定义了专司 Metabase Clojure 平台基础设施的「平台后端专家」Agent。本文以该 Agent 定义文件为骨架，完整还原它所承载的领域知识图谱——应用数据库与应用数据库迁移、Jetty HTTP 服务器与 Ring 中间件栈、defendpoint API 框架、defsetting 配置系统、Quartz 任务调度、缓存、Toucan 2 模型基础设施与核心工具库——并逐一对照仓库源码，验证每个模块的真实文件布局与关键实现细节，帮助开发者理解 Metabase 平台层代码的组织方式与工程约束。

Agent 的角色定义与调度原则

Agent 文件以 YAML front matter 声明其身份：名为 platform-backend-expert，指定使用 opus 模型，并启用 project 级记忆。其 description 明确划定了职责边界：Metabase Clojure 后端的平台基础设施部分——应用数据库（application database）、HTTP 服务器、API 框架、配置系统、任务调度、迁移系统、缓存、模型基础设施或核心工具库。文件还给出了六组「用户问题 → Agent 选择」的示例，覆盖大规模 JSON 列迁移、多实例部署下的配置缓存竞态、API 响应性能退化、Malli schema 参数校验、大查询结果的流式响应、以及 Liquibase 迁移在 MySQL 与 PostgreSQL 上的行为差异等典型场景。

正文开头对 Agent 的工作方式定下了两条关键纪律：

1. 一次只处理一个自包含的问题或实现。如果任务横跨多个相互依赖的步骤，只做被调用的那一小片，然后返回结构化摘要交给 orchestrator 驱动下一步。文件直言不讳地指出原因：“Subagents drift on long, evolving work — keep your scope tight.”（子 Agent 在长而演化的工作上会漂移——保持范围紧凑）。
2. 角色设定：一位深谙 Metabase 平台基础设施的高级后端工程师，理解 JVM 内部机制、Clojure 并发、数据库操作、HTTP 服务器，以及“构建可靠基础设施的艺术”。

这套定义把 Agent 定位为平台层的“守门人”：凡是涉及被所有其他功能依赖的底层系统的改动，都由它把关。

领域知识一：应用数据库（metabase.app_db）

文档将 metabase.app_db 拆分为七个子域，仓库目录 src/metabase/app_db/ 与之一一对应：

子域	文档描述	源码位置
连接管理	到内嵌 H2、PostgreSQL 或 MySQL 的连接池；SSL、池调优、基于环境的配置	connection.clj、connection_pool_setup.clj、data_source.clj
迁移	Liquibase schema 迁移，含 H2/MySQL 特有逻辑	liquibase.clj、liquibase/h2.clj、liquibase/mysql.clj
自定义迁移	纯 SQL 无法完成的数据迁移：JSON 重构、回填、模型表示迁移（如 pulse_to_notification）。“增长最活跃的文件之一”	custom_migrations.clj、custom_migrations/
查询层	参数化查询工具、结果处理、查询取消	query.clj、query_cancelation.clj
加密	敏感配置的 AES-256 加密，支持密钥轮换	app_db/encryption.clj、util/encryption.clj
H2 管理	H2 版本迁移、H2 → PostgreSQL/MySQL 迁移	update_h2.clj、cmd/
集群锁	多实例协调的数据库级锁	cluster_lock.clj

两点值得从源码角度深入：

自定义迁移的模块化趋势。 文档称 custom_migrations.clj 是“增长最活跃的文件之一”，当前该文件约 2469 行。仓库中还有一个 custom_migrations/ 子目录，承载了按主题拆分的迁移模块，例如 pulse_to_notification.clj（正是文档点名的“模型表示迁移”）、metrics_v2.clj、llm_providers.clj、reserve_at_symbol_user_attributes.clj 及通用工具 util.clj。从源码结构看，大型迁移逻辑正从巨型单文件向按功能分文件的模式演进。

数据库差异化的 Liquibase 适配。 liquibase/ 目录下只有 h2.clj 和 mysql.clj 两个文件——从源码结构可以推断，PostgreSQL 走的是标准 Liquibase 行为，而 H2 与 MySQL 各自需要特殊的方言处理。这正呼应了文档「Important Caveats」中第一条：“H2 is not PostgreSQL”，锁语义、全文检索和性能特征都不同，优化一方时不能破坏另一方。

领域知识二：HTTP 服务器与中间件栈（metabase.server）

文档将 metabase.server 划分为四部分，src/metabase/server/ 的目录结构与描述吻合：

• 服务器生命周期（server.core、server.instance）：Jetty 的启动/关闭、端口配置、SSL。从 core.clj 可以看到该命名空间作为公共 API 门面，通过 potemkin 的 p/import-vars 统一导出 make-handler、instance、start-web-server!、stop-web-server!、make-routes 等符号，并显式声明了与 metabase.api 模块的边界——部分中间件（如绑定当前用户、limit/offset）在这里设置、在 API 模块消费。
• 请求中间件：文档列举了 middleware.session（会话解析与认证）、middleware.json（JSON 编解码）、middleware.security（CSP、X-Frame-Options、CORS）、middleware.log（结构化请求日志）、middleware.exceptions（异常格式化）、middleware.premium_features_cache、middleware.settings_cache、middleware.ssl、middleware.misc 等。实际 middleware/ 目录中共有 16 个中间件文件，还包括文档未逐一列出的 auth.clj、browser_cookie.clj、embedding_sdk_bundle.clj、metadata_provider_cache.clj、offset_paging.clj、request_id.clj、trace.clj 等。
• 流式响应（server.streaming_response + 线程池）：大结果集不经缓冲直接写入 HTTP 响应，使用独立的线程池。源码印证了这一点：streaming_response.clj 与专门的 streaming_response/thread_pool.clj。
• 路由（server.routes、api_routes.routes）：Compojure 路由组合，对应 routes.clj 与 src/metabase/api_routes/。

中间件栈中一个有代表性的实现是 settings_cache.clj：它读取名为 metabase.SETTINGS_LAST_UPDATED 的 Cookie，将 Cookie 中的时间戳与本实例缓存的时间戳比较，若 Cookie 更新则强制刷新缓存；当某个请求修改了配置（响应携带 :cookie/settings-cache-timestamp）时，又会在响应中写回最新的 Set-Cookie（max-age 为 5 分钟、SameSite=Lax）。这就是文档「Caveats」中“配置缓存失效基于时间戳，多实例部署存在传播延迟”的具体机制——跨实例的缓存一致性是靠 Cookie 里传递的时间戳在请求间“软同步”的，而非强一致协议。

领域知识三：API 框架（defendpoint 与 OpenAPI）

文档将 metabase.api 归纳为三块，src/metabase/api/ 中均有对应实现：

• 端点宏（macros.clj）：defendpoint 宏提供自动参数校验、schema 强制转换、OpenAPI 生成与权限检查。宏定义位于该文件 L842 处，配套的 OpenAPI 与 tools.manifest 生成逻辑在 api/macros/defendpoint/ 子目录下。值得注意的是 api/DO_NOT_ADD_NEW_FILES_HERE.txt——目录内已有显式的“禁止随意新增文件”约定，说明该目录结构是受严格管控的。
• OpenAPI 生成：从 Malli schema 生成 OpenAPI 3.0，对应 open_api.clj。
• 通用工具（common.clj）：校验、分页、错误响应、权限检查，该文件约 633 行。

文档同时给出了修改 API 框架的四条纪律，全部指向向后兼容：defendpoint 的改动会影响每一个端点，必须充分测试；OpenAPI 生成必须保持向后兼容；新参数类型需要 Malli schema 定义；权限检查应当是声明式的（写在端点定义里）而非命令式。此外「Caveats」中强调：端点中的 Malli schema 同时影响校验与文档，schema 变更可能破坏 API 消费者——校验与文档同源，这一设计决定了 schema 是不可随意改动的公共契约。

领域知识四：配置系统（defsetting）

文档称 settings/models/setting.clj（约 1804 行）是“最大的单文件之一”，并概述了 defsetting 的七项能力。阅读源码后，文档的描述比实际能力更保守——defsetting 宏（L1303）的 docstring 完整列出了可用选项，其中包含文档未展开的细节：

• 基础选项：:default（默认值，类型须与 Setting 类型一致）、:type（:string 默认，或任何实现了 get-value-of-type/set-value-of-type 的类型，非字符串类型自动做值转换）、:export?（是否纳入序列化导出）。
• :init：一个 0 参函数，首次访问时生成初始值并持久化保存，适用于昂贵或不确定性的初始化。
• :visibility：源码中的可见性表格比文档更细，共六档而非四档——:public（全世界可见）、:authenticated（登录用户可见）、:settings-manager（管理员与“Settings Manager”可见，即拥有 settings 权限的非管理员）、:admin-write-authed-read（登录用户可读、仅管理员可写）、:admin（仅管理员）、:internal（谁都不可见，通常专用于 env-var-only 设置）。
• :getter / :setter：自定义读写函数，setter 可传 :none 表示只读；自定义 setter 需处理 nil（清除值）的情形。
• :cache?：是否缓存（默认 true），docstring 明确警告关闭缓存“可能带来非常负面的性能影响”。
• :sensitive?：敏感配置（如密码）不以明文返回。源码特别说明：混淆不在 getter 层做，而在最终经由 API 返回值的路径（如 writable-settings）做——敏感性是纯用户侧属性，后端代码仍可正常消费这些值。
• :database-local：取值 :only / :allowed / :never（默认 :never），控制该配置能否按数据库维度本地化。

环境变量的类型化覆盖也得到源码确认：setting.clj 中 env-var-name 函数（L455）将配置名 munge 后加上 MB_ 前缀生成环境变量名（如 default-domain → MB_DEFAULT_DOMAIN），并带有 env-var-translation-cache 做翻译缓存；文档所述的“MB_SETTING_NAME 类型强制转换”即由这套机制实现。此外源码中还暴露了 :deprecated-name 选项——支持配置改名后旧环境变量（如 MB_OLD_NAME）与旧数据库值继续生效并记录弃用日志，这是文档没有提及但源码明确存在的向后兼容机制。

文档提到的其余子模块同样能在目录中找到：多配置支持 setting/multi_setting.clj、缓存生命周期 setting/cache.clj。

领域知识五：任务调度、缓存与模型基础设施

任务调度（metabase.task）。task/ 目录包含 impl.clj（约 386 行，Quartz 作业 + cron 触发器 + 类加载器感知的执行）、bootstrap.clj、core.clj、job_factory.clj，以及 secure_delegate.clj / secure_delegate_postgres.clj / secure_delegate_std.clj 三个委托实现——从命名可以推断这是针对“以受限权限执行任务”的后端差异化实现。task/QUARTZ.md 是一份面向开发者的 Quartz 使用指南，明确提醒：一次性启动任务在多实例部署中每个实例都会执行，且进程重启（如 OOM kill）后会重新执行，任务若不具备幂等性就会出问题。任务执行记录在 task_history/，其中 task/task_run_heartbeat.clj 正是文档点名的长任务“停顿检测”心跳机制。

缓存。文档列出的四层缓存体系对应：查询结果缓存（qp.middleware.cache，缓存键 = 查询 + 权限 + 配置）、可插拔缓存后端（query_processor/middleware/cache/ 下的 cache.clj 与 cache_backend 子目录，db 与 interface 两种实现）、缓存配置模型（cache.models.cache_config，按问题/仪表盘/数据库维度的 TTL，见 src/metabase/cache/）、企业版缓存策略（enterprise/backend/ 中的 metabase_enterprise.cache.strategies，基于调度的缓存预热）。

模型基础设施（metabase.models）。models/ 目录中有 interface.clj（Toucan 2 集成：模型定义、生命周期钩子、类型转换、IModel 扩展）、serialization.clj 及 serialization 子目录（实体序列化/导入导出：实体 ID 解析、跨实例引用、YAML 格式）、resolution.clj（实体引用解析）。仓库顶层的 test_resources/serialization_baseline/ 含 164 个 YAML 文件，是序列化行为回归基线的实物证据。该目录同样带有 DO_NOT_ADD_NEW_FILES_HERE.txt 的管控标记。

工具库（metabase.util）。util/ 目录约 88 个文件，文档点名的五个模块均存在：honey_sql_2.clj（标识符引用、类型转换、自定义子句）、date_2/（解析、格式化、时区、时间运算）、malli.cljc 与 malli/ 子目录（schema 定义、函数插桩、校验）、log.clj（命名空间级结构化日志）、i18n.clj（Gettext 翻译与复数形式，配合仓库根目录 locales/ 下 38 个 .po 语言文件）、encryption.clj（AES-256）。

工作方式：调查方法、迁移规范与质量红线

文档的「How You Work」一节沉淀了四条调查方法论，每一条都对应平台层的真实故障模式：

1. 先剖析再优化：性能问题先用 JVM profiling、中间件计时、查询日志定位瓶颈。
2. 检查多实例行为：许多平台问题在单实例与多实例部署下表现不同，要考虑缓存一致性、锁竞争、状态共享。
3. 按顺序追踪中间件栈：请求级问题要按 Ring 中间件顺序追踪——每个中间件都可能短路、改写请求或改写响应。
4. 确认应用数据库后端：H2、PostgreSQL、MySQL 行为各异，迁移、查询、锁语义都有差别。

编写迁移的五条铁律是全文实战价值最高的部分：

• 迁移期间绝不大表加写锁，必须批量更新；
• 迁移必须向后兼容——发布滚动期间旧代码仍要能工作；
• 自定义迁移需要进度跟踪，失败后可恢复；
• 在全部三种应用数据库后端（H2、PostgreSQL、MySQL）上测试；
• 数据迁移进 custom_migrations.clj，schema 迁移进 Liquibase XML——两类迁移的归属界限不容混淆。

代码质量红线：遵循 Metabase 的 Clojure 惯例（文档明确引用了 clojure-write 技能 与 clojure-review 技能 两份规范文档）；平台代码需要更高测试覆盖率（因为它被一切功能使用）；公共 API 要考虑向后兼容；改动要在负载下剖析验证；设置项要有清晰的描述与类型。

平台层的七条「已知陷阱」

文档以「Important Caveats You Know About」列出了七条资深工程师才容易意识到的平台陷阱，每条都值得逐条对照源码理解：

1. H2 不是 PostgreSQL：锁语义、全文检索、性能特征都不同，不要为一方优化而破坏另一方（对应 liquibase/h2.clj 与 liquibase/mysql.clj 存在的意义）。
2. 自定义迁移是只追加的：一旦发布就不能修改，只能新增。
3. 配置缓存失效基于时间戳：多实例部署存在传播延迟，不要依赖立即可见的一致性（机制即前文所述的 SETTINGS_LAST_UPDATED Cookie 同步）。
4. 流式响应的线程管理要格外小心：流式线程池独立于请求处理线程池，耗尽它会阻塞所有流式响应（对应独立的 thread_pool.clj）。
5. 加密密钥轮换是复杂操作：所有已加密配置必须重新加密，且过程必须原子且可恢复。
6. Quartz 触发器持久化在数据库里：修改 cron 表达式必须更新持久化的触发器，而不只是改代码——这正是 task/QUARTZ.md 反复强调任务幂等与多实例行为的原因。
7. 端点 Malli schema 同时影响校验与文档：schema 变更可能破坏 API 消费者。

REPL 驱动的验证手段

文档最后一节给出了 Agent 的验证工具链：优先使用 clojure-eval 技能（或 clj-nrepl-eval）在 REPL 中完成六类验证——在开发数据库上测试迁移、检查配置缓存状态、剖析中间件执行、测试 Malli schema 校验、验证加密/解密往返、检查 Quartz 触发器状态。对 REPL 之外的测试，使用 bin/test-agent 脚本（仓库中该可执行文件确实存在，输出干净、无进度条）。编辑 Clojure 文件后运行 clj-paren-repair 捕获括号失配。最后，Agent 被要求在发现迁移模式、配置缓存行为、中间件顺序依赖、应用数据库后端差异和 API 框架惯例时持续更新自己的 Agent 记忆——这与 front matter 中 memory: project 的声明形成闭环：该 Agent 不仅消费领域知识，还在实践中把新经验沉淀回项目级记忆。

小结

platform-backend-expert.md 表面上是一份 Agent 提示词，实质上是一份高度浓缩的 Metabase 平台基础设施地图：它把 app_db、server、api、settings、task、models、util 七大核心目录的职责、边界与陷阱压缩进 170 行，且每一条声明都能在仓库源码中找到落点——从 defsetting 的六档可见性与 :deprecated-name 兼容机制，到 Cookie 时间戳驱动的配置缓存失效，再到按数据库后端拆分的 Liquibase 适配与独立线程池的流式响应。对于希望参与 Metabase 平台层开发的工程师而言，这份 Agent 定义本身就是一份可读性极强的「平台层 onboarding 手册」：先读它建立模块地图，再按「Key Codebase Locations」一节进入具体源码深入。