Beads 测试/生产隔离防火墙深度解析：isProductionPort 端口检测与数据库名双保险机制（AD-01 / be-c5p）

Beads 测试/生产隔离防火墙深度解析：isProductionPort 端口检测与数据库名双保险机制（AD-01 / be-c5p）

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

Beads 是一个为编码 Agent 提供记忆层的开源项目，其存储层以 Dolt SQL 服务器为底座。测试代码与生产数据共用同一套 Dolt 服务器时，最危险的事故莫过于测试数据库被创建或连接到了生产端口。本篇文章围绕仓库内发布门禁文档 release-gates/be-c5p-firewall-gate.md 所评审的 AD-01 功能，完整拆解 Beads 如何通过isProductionPort端口检测 + 数据库名模式匹配这套"双保险"防火墙，将测试流量与生产数据彻底隔离；读完你将对三条生产端口探测规则、BEADS_TEST_SERVER=1显式逃生口、以及三道防线在源码中的确切位置有完整认识，并能据此在自己的环境中安全配置生产端口与运行测试套件。

一、为什么要一道"防火墙"：测试污染事故的背景

Beads 的存储后端是 internal/storage/dolt/store.go 中实现的 DoltStore，它连接一个 Doltsql-server，按数据库（database）组织 IssueOps 业务数据。测试套件（集成测试、属性测试、版本往返测试、bd doctor自检等）也会在服务器上创建自己的数据库——它们以固定的前缀命名（如testdb_、beads_test、doctest_）。

问题在于：测试数据库名与生产数据库名都只是字符串。一旦配置漂移——比如测试进程拿到的端口解析成了生产端口，或者生产进程误用了测试命名约定——测试数据就会写入生产库，或者生产代码被"影子数据库"污染。门禁文档将其归纳为 Clown Shows #12-#18 这一系列事故类型。

be-c5p（AD-01）要解决的问题正是：不依赖人的自律，在代码层面用两道互相独立的检查把测试命名与生产端口钉死。评审结论为PASS，改动规模为单个 commit064a9fa9（15 个文件，+195 / −10），干净地 cherry-pick 到origin/main之上。

二、整体架构：三道防线而非一道

从 internal/storage/dolt/store.go 的源码结构看，这套隔离体系由三道独立防线组成，每道防线都有独立的判定逻辑与逃生口：

三道防线共享两个判定原语：isTestDatabaseName（模式匹配）与isProductionPort（端口探测）。下面逐一拆解。

三、端口探测：productionPortReasons的三条规则

isProductionPort(cfg)的完整实现位于 internal/storage/dolt/store.go#L130-L176，它本身只是一个包装：return len(productionPortReasons(cfg)) > 0。真正承载逻辑的是productionPortReasons，它按顺序检查三个信号，命中即追加一条可读的原因标签（最终用于拼装 panic/error 消息，方便排障）。

规则 1：等于默认 SQL 端口 3307 —— 无条件、不可豁免

const DefaultSQLPort = 3307 // store.go:56

只要cfg.ServerPort == DefaultSQLPort，立即判定为生产端口。这条规则在任何情况下都不被抑制——包括BEADS_TEST_SERVER=1。理由在源码注释中写得很直白：3307 是 Dolt 众所周知的默认端口，是"单一置信度最高的生产信号"，一个专门跑测试的服务器即便通过BEADS_TEST_SERVER=1退出了其他启发式规则，也绝不允许绑定到这个众所周知的默认端口。

对应的单元测试 store_unit_test.go#L316-L356（TestApplyConfigDefaults_TestModeBlocksProdPort_EvenWithTestServerOptIn）专门验证了这一点：即使设置了BEADS_TEST_SERVER=1，只要BEADS_TEST_MODE=1且端口解析回 3307，测试模式端口仍被改写（源码注释称其为 "Rule 1 is unconditional"）。

规则 2：BEADS_PRODUCTION_PORT环境变量

如果环境变量BEADS_PRODUCTION_PORT能被解析为大于 0 的整数，且恰好等于cfg.ServerPort，则判定为生产端口：

if env := os.Getenv("BEADS_PRODUCTION_PORT"); env != "" { if p, err := strconv.Atoi(env); err == nil && p > 0 && p == cfg.ServerPort { reasons = append(reasons, fmt.Sprintf("BEADS_PRODUCTION_PORT=%d matches", p)) } }

这为非 3307 的自定义生产部署提供了显式声明手段：生产环境把实际端口写入该变量，即可让通用化的isProductionPort覆盖到任何端口。

规则 3：BeadsDir/dolt-server.port磁盘端口文件

如果cfg.BeadsDir非空，且该目录下的端口文件（doltserver.PortFileName，读取函数doltserver.ReadPortFile）内容与cfg.ServerPort一致，则判定为生产端口。

这条规则有一个非常值得学习的边界设计：当BeadsDir为空时，绝不回退到filepath.Dir(cfg.Path)去推断目录。原因注释解释得很清楚：端口解析链（applyConfigDefaults）确实会做这个回退，但用于生产判定时，回退会把"恰好包含一个游离dolt-server.port文件的目录"（例如/tmp/dolt-server.port来自某个泄漏的 dev server）误判为生产。而测试夹具经常把cfg.Path放在/tmp下、并没有真正的BeadsDir——只有显式设置的BeadsDir才被当作生产判定的权威依据。

规则 2/3 的统一豁免：BEADS_TEST_SERVER=1

三条规则并非同等权重。规则 1 无条件；规则 2、3 是"启发式"（环境变量或磁盘文件都可能过期或误配），因此当BEADS_TEST_SERVER=1时被跳过：

if os.Getenv("BEADS_TEST_SERVER") == "1" { return reasons }

也就是说，操作者显式选择"专用测试服务器通道"（如每测试一个容器、独立外部测试端口）时，系统尊重这一选择，但固定默认端口仍然不可触碰。同时注意严格的=='1'比较——文档与源码都强调这是严格 opt-in，不是"truthy"判断，杜绝了BEADS_TEST_SERVER=yes这类意外放行。

四、数据库名防火墙：testDatabasePrefixes与isTestDatabaseName

前缀清单

internal/storage/dolt/store.go#L79-L87 定义了七个测试前缀：

var testDatabasePrefixes = []string{ "testdb_", // applyConfigDefaults 为 BEADS_TEST_MODE=1 且未显式指定 Database 时派生（cfg.Path 的 FNV 哈希） "beads_test", // 手写集成测试的命名约定 "beads_pt", // 属性测试夹具 "beads_vr", // 版本往返 / 迁移夹具 "doctest_", // bd doctor 自检夹具 "doctortest_", // 较旧的 bd doctor 夹具名（向后兼容保留） "benchdb_", // 基准测试临时库（格式 benchdb_<unixnano>），由 AD-01 (be-c5p) 新增 }

其中benchdb_正是本门禁新增的一行：基准测试（cmd/bd/template_test.go的newTemplateBenchmarkStore）每次跑出的临时库形如benchdb_<unixnano>，此前不在防火墙清单内。

模式匹配：纯前缀、不依赖环境变量

func isTestDatabaseName(name string) bool { for _, prefix := range testDatabasePrefixes { if strings.HasPrefix(name, prefix) { return true } } return false }

源码注释特别强调这是pattern-based 防火墙，不依赖环境变量——因为环境变量可能被误配或缺失，而数据库名本身是既成事实。前缀匹配能避免SHOW DATABASES LIKE把_、%当通配符的问题（建库路径中用精确匹配遍历SHOW DATABASES的原因之一）。

单元测试 dolt_test.go#L1756-L1786（TestIsTestDatabaseName）给出了关键边界：beads_test、beads_test_123、testdb_foo、doctest_bar、beads_pt_xyz、beads_vr_abc均为true；而真正的生产库前缀beads_ta、beads_tabula、beads_tr、beads_tools、beads_vulcan必须为false——这保证像beads_vulcan这样的真实项目库不会被误伤。

五、第二道防线细节：New()拒绝测试名数据库

在 internal/storage/dolt/store.go#L1568-L1582，New()打开任意服务器（生产或测试）前执行：

if isTestDatabaseName(cfg.Database) && os.Getenv("BEADS_TEST_SERVER") != "1" { addr := net.JoinHostPort(cfg.ServerHost, strconv.Itoa(cfg.ServerPort)) if cfg.ServerSocket != "" { addr = cfg.ServerSocket } return nil, fmt.Errorf( "refusing to connect test database %q to server %s: "+ "set BEADS_TEST_SERVER=1 on a dedicated test server, "+ "or use test helpers in internal/storage/dolt/testserver", cfg.Database, addr) }

要点：

• 返回error而非panic：门禁文档明确此为设计选择——让测试可以断言错误路径。
• 错误信息自解释：同时给出被拒的库名与目标地址（host:port或 socket），并给出两条出路：在专用测试服务器上设BEADS_TEST_SERVER=1，或使用internal/storage/dolt/testserver的测试辅助。
• 独立于端口判定：isProductionPort的BEADS_TEST_SERVER=1豁免不影响此处的独立 opt-out——注释明确二者是 AD-01 的两个独立防线，互不牵连。

六、第三道防线：建库路径上的最终拦截

在真正的CREATE DATABASE执行前（store.go#L2439-L2449），有最后一层拦截：

if isTestDatabaseName(cfg.Database) && isProductionPort(cfg) { return nil, "", serverConnFacts{}, fmt.Errorf( "REFUSED: will not CREATE DATABASE %q on production port %d — "+ "this is a test database name on the production server (see DOLT-WAR-ROOM.md)", cfg.Database, cfg.ServerPort) }

它是"最后防线"（last line of defense）：即使前面的New()防火墙被绕过（例如通过CreateIfMissing建库路径直达），只要测试命名 + 生产端口同时成立，建库即被 REFUSED。这里再次强调 pattern-based 而非 env-var-based，并把生产端口判定通用化为isProductionPort，从而覆盖非 3307 的生产部署（AD-01 的通用化目标）。此拦截位于ValidateDatabaseName防注入校验之后、databaseExistsOnServer存在性检查之前，与beads_ta/beads_vulcan等项目前缀互不冲突。

七、配套硬守卫：BEADS_TEST_MODE=1下的端口 panic

除了上面三条生产路径防线，还有一条测试路径上的硬守卫（store.go#L1564-L1566）：

if os.Getenv("BEADS_TEST_MODE") == "1" && isProductionPort(cfg) { panic(buildTestModeProductionPortPanic(cfg)) }

applyConfigDefaults在BEADS_TEST_MODE=1时会把生产端口改写成 1（fail-loud-but-continue），这里的 panic 是纵深防御（defense-in-depth）：捕获任何绕过或事后篡改改写结果的路径。panic 消息由buildTestModeProductionPortPanic（store.go#L1622-L1634）构建，遵循 AD-01 Wireframe 1 格式：可扫描的头部 + database/path/server 字段 + 命中的规则列表 + 命名每个逃生口的修复块。当 panic 消息中规则列表为空时（理论不可达）也有兜底文案。

八、测试基础设施的适配：13 个 TestMain 全部显式 opt-in

新增防火墙之后，所有会连接测试服务器的测试套件都必须显式设置BEADS_TEST_SERVER=1，否则一律被New()拒绝。门禁文档确认全部 13 个 testmain 文件已更新（grep 验证）。

以 internal/storage/dolt/testmain_test.go#L76-L79 为例：

// AD-01 (be-c5p): the test/bench harness opens a process-local dolt // sql-server (testcontainer or external port). The new database-name // firewall in dolt.New refuses test-named DBs unless this opt-in is set. os.Setenv("BEADS_TEST_SERVER", "1")

该 TestMain 还展示了配套的隔离细节：设置BEADS_TEST_PDEATHSIG=1保证服务器进程生命周期绑定、为孤儿服务器清扫创建 suite 独有的临时根目录、把熔断状态隔离到专属目录。cmd/bd/doctor/fix/testmain_cgo_test.go在清理阶段主动 unset 该变量；cmd/bd/context_binding_integration_test.go则因为该测试套件会过滤BEADS_*环境变量，需要把该变量显式放进子进程Cmd.Env。

九、前缀三表汇聚：防火墙、清理与公式必须收敛

防火墙清单不是孤立的一张表。testDatabasePrefixes与清理侧的staleDatabasePrefixes（cmd/bd/dolt.go#L1407-L1415）以及 formula 侧的 stale-prefix 列表必须保持收敛，否则新增前缀会导致陈旧夹具逃过清理：

• 防火墙侧：internal/storage/dolt/store.go:testDatabasePrefixes（SQL 侧拦截）；
• 清理侧：cmd/bd/dolt.go:staleDatabasePrefixes，由bd dolt clean-databases（cmd/bd/dolt_clean_databases.go）使用；cmd/bd/doctor/server.go的bd doctor也有同名列表；
• 公式侧：gc dolt cleanup的 stale-prefix 列表（门禁文档提及，由 be-avn 处理汇聚）。

三个列表的注释相互引用（如dolt.go:1387-1407明确写出"防火墙列表、清理列表、公式列表必须收敛"），并且benchdb_已同步加入两边 Go 列表。任何新测试前缀都应遵循同一纪律：三处同时更新。

十、测试验证矩阵

门禁与源码共同确认的测试覆盖：

门禁文档给出的发布证据中，最高风险用例TestApplyConfigDefaults_TestModeBlocksProdPort在干净环境下于internal/storage/dolt包内通过（ok 0.092s）。另有评审遗留的中等级 follow-upbe-z62（为规则 2/3、BEADS_TEST_SERVER=1短路、New()返回 error 路径补 8 个建议单元测试）与低等级描述性 nit，均不阻塞发布。

十一、发布门禁评审结论与环境说明

门禁文档的 Verdict 为PASS，六项判据全部满足：

1. 评审 PASS 存在（0 blocker / 0 high / 1 medium / 1 low）；
2. 四项验收条件全部达成（见下文）；
3. 测试通过且零回归——make test（gms_pure_go）在release/be-c5p-firewall与origin/main上产生完全一致的 35 个失败集合；
4. 无 HIGH 级未关闭问题；
5. 最终分支git status干净（未跟踪的.gc/、.gitkeep属于 gc 管理基础设施）；
6. 分支干净分叉：单个 commit064a9fa9cherry-pick 到origin/main@8694c535上，零冲突。

四项验收条件即前文所述机制的可执行版本：

1. isProductionPort同时尊重BEADS_PRODUCTION_PORT环境变量、BeadsDir/dolt-server.port端口文件、以及遗留DefaultSQLPort；
2. New()拒绝测试命名库，除非BEADS_TEST_SERVER=1（严格=='1'opt-in）；
3. testDatabasePrefixes新增benchdb_；
4. 全部 13 个测试套件在TestMain中设置BEADS_TEST_SERVER=1。

关于那 35 个"失败"的说明（环境耦合，非本改动引入）

门禁文档特别澄清：deployer 工作树 rig 环境下make test报告的 35 个失败在origin/main上同样存在，属于工作树/HOME 耦合的配置类测试，集中在internal/config、cmd/bd、internal/beads——它们会拾取 rig 会话配置与BEADS_DIR。internal/storage/dolt在环境未清洗时也会因 rig 自身 dolt 服务器注入的BEADS_DOLT_SERVER_PORT而使端口解析测试受影响。清洗BEADS_DOLT_SERVER_PORT、BEADS_DOLT_AUTO_START、BEADS_DIR、GC_DOLT_PORT、GC_BEADS_SCOPE_ROOT、BEADS_ACTOR即可清除该子集；这些失败在 builder/reviewer rig 上不出现（builder 报告 source 分支 build/vet/tests 干净，reviewer 确认make testPASS）。判据 #3 真正要求的是零新增失败，而非绝对零失败。

十二、落地后的操作指引

配置生产端口：生产部署中，若 Dolt 端口不是默认 3307，设置BEADS_PRODUCTION_PORT=<端口>环境变量，或在BeadsDir下维护dolt-server.port文件，isProductionPort即可覆盖到该端口；默认 3307 无需任何配置即被识别。

运行测试套件：任何打开进程内/容器化 Dolt 测试服务器的套件，必须在TestMain（或等效入口）中设置BEADS_TEST_SERVER=1，且该变量会从父进程环境被过滤时需显式注入子进程Cmd.Env。生产服务器上绝不设置此变量。

新增测试库前缀：向testDatabasePrefixes（internal/storage/dolt/store.go#L79）追加前缀时，必须同步更新清理侧staleDatabasePrefixes（cmd/bd/dolt.go#L1407、cmd/bd/doctor/server.go#L168）与公式侧列表，保证防火墙与bd dolt clean-databases、gc dolt cleanup语义一致。

十三、小结

AD-01（be-c5p）为 Beads 的 Dolt 存储层装上了一套不依赖纪律的隔离机制：productionPortReasons用三条规则（固定默认端口 + 环境变量 + 端口文件）识别生产端口，isTestDatabaseName用七个前缀识别测试库名，二者组合出New()拒绝连接、建库路径 REFUSED、测试模式端口 panic 三道防线，配合 13 个测试套件的BEADS_TEST_SERVER=1显式 opt-in 与前后缀三表收敛纪律，从代码层面根除了"测试库连上生产服务器"这一类事故。对需要在自己项目中建立测试/生产数据隔离的开发者而言，这套"模式匹配 + 多信号探测 + 独立逃生口 + 纵深防御"的组合拳，是一个可以直接借鉴的参考范式。

延伸阅读：发布评审全文见 release-gates/be-c5p-firewall-gate.md；核心实现见 internal/storage/dolt/store.go；清理侧汇聚见 cmd/bd/dolt.go；端口文件读取与共享服务器模式见 internal/doltserver。

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads