Go checksum database 怎样处理私有模块的校验边界

Go 私有模块的关键不是把 GOSUMDB 全局关闭，而是先把“从哪里下载”和“由谁校验”分开。直接访问私有仓库时，用 GOPRIVATE 让匹配路径绕过公共代理与公共 checksum database；如果公司已有可信私有代理，则保留代理路径，只用 GONOSUMDB 划出不交给公共校验库的范围。

Go 官方文档：https://go.dev/ref/mod

下面的命令是读者可执行的配置示例，本文没有在本机运行这些命令，也不把示例输出当作实际运行结果。

先区分下载路径与校验路径

默认情况下，Go 会先使用 https://proxy.golang.org,direct 获取模块；当 go.sum 中缺少对应哈希时，还可能向 sum.golang.org 查询公开模块的校验记录。私有模块的问题在于：它的完整模块路径可能被发送给不该看到它的公共服务，而且公共 checksum database 无法为非公开代码计算校验值。

直连私有仓库时用 GOPRIVATE

如果私有模块没有可用的公司代理，最小配置通常是把企业模块前缀写入 GOPRIVATE。它会作为 GONOPROXY 和 GONOSUMDB 的默认值，使匹配前缀的模块不请求公共代理，也不请求公共 checksum database；随后 Go 可以按版本库配置直接获取模块。

# 只把企业模块前缀标记为私有，公开依赖仍保留默认校验保护
go env -w GOPRIVATE=corp.example.com

# 检查持久化配置；不要把访问令牌写进仓库或文章
go env GOPRIVATE GONOPROXY GONOSUMDB GOPROXY GOSUMDB

这里的值是路径匹配模式，不是某一个具体版本。若私有模块分布在多个前缀，可用逗号分隔模式；不要为了省事写成全局 *，否则公开依赖也会失去原本的代理与校验边界。私有仓库的 Git 凭据仍需由构建环境配置，环境变量本身不会替代仓库认证。

私有代理场景只收窄校验边界

如果公司代理已经服务私有模块，就不应机械地让 GOPRIVATE 把代理也绕开。此时下载路径和校验路径要分别表达：GOPROXY 指向可信私有代理，GONOSUMDB 匹配企业前缀；若需要让所有模块都经过该代理，可以使用 GONOPROXY=none 这类代理策略，再按团队的代理回退规则配置 GOPROXY。

# 私有代理负责下载；企业模块不向公共 checksum database 查询
go env -w GOPROXY=https://proxy.corp.example.com
go env -w GONOSUMDB=corp.example.com

# 只有在团队明确要求所有匹配模块继续走代理时才这样设置
go env -w GONOPROXY=none

这组设置的重点是“代理可信”与“校验服务边界”同时成立。代理若只服务私有模块，也可以配置公开代理作为后续回退，但要确认私有代理对不存在的模块返回 404 或 410；若返回其他错误，Go 不会按预期继续回退，路径泄露和失败诊断就会混在一起。

最小检查：不要用 GOSUMDB=off 掩盖问题

GOSUMDB=off 会整体关闭 checksum database，对所有未在 go.sum 中的模块都降低认证保障。排查私有模块时，优先用精确的 GOPRIVATE 或 GONOSUMDB；只有团队明确接受全局取舍时，才讨论关闭全局服务。

# 显示最终生效值，先确认 CI 是否覆盖了本地设置
go env GOPRIVATE GONOPROXY GONOSUMDB GOPROXY GOSUMDB

# 读取模块图，观察失败路径涉及哪个模块前缀
go list -m all

# 检查缓存中的模块是否被改动；它不会替代网络下载或代理配置排查
go mod verify

检查时按三个问题记录结果：失败模块是否匹配私有前缀；下载请求是否只到达预期代理；公共模块是否仍能得到 checksum database 保护。CI 还要核对工作目录、变量注入顺序和凭据来源，避免本地的 go env -w 与流水线环境产生两套答案。

结论与常见问题

• 直连私有仓库：从精确的 GOPRIVATE 开始，保留公开依赖的默认校验。
• 使用私有代理：让 GOPROXY 表达下载来源，用 GONOSUMDB 表达公共校验边界。
• 不要把 GOSUMDB=off 当作私有模块的通用修复；它影响的范围远大于企业前缀。

只设置 GOPROXY 就能保护私有模块吗？

不能。它只表达下载来源，不能自动阻止 checksum database 请求；私有路径还应由 GOPRIVATE 或 GONOSUMDB 明确标记。

GOPRIVATE 和 GONOSUMDB 要同时写吗？

通常不必。GOPRIVATE 会为两者提供默认规则；只有代理路径与校验路径需要不同边界时，才单独设置更细的变量。

为什么私有代理返回错误后没有回退到公共代理？

Go 的代理列表回退依赖特定的 404 或 410 响应。代理返回其他错误码时，工具会把它当作明确失败，应该先修正代理的响应策略。

官方依据：模块私有路径、代理与 checksum database 规则见 https://go.dev/ref/mod#private-modules 和 https://go.dev/ref/mod#private-module-privacy。