Buffalo 是 Go 语言的全栈 Web 框架，非 InsightFace 的 buffalo_l 模型；正确安装为 go install github.com/gobuffalo/buffalo/v2@latest，使用 buffalo new 创建项目，注意环境隔离、asset pipeline 兼容性及 context.Value 安全传递。
Buffalo 是一个 Go 语言 Web 框架，不是 InsightFace 的 buffalo_l 模型——这点必须先划清界限。你搜“Buffalo框架”大概率是冲着 Go 生态里的那个全栈 Web 框架来的，但很多人会和 InsightFace 的 buffalo_l 混淆，导致 pip install、模型加载、路径配置全错方向。下面说的全是 Go 的 buffalo。
确认你用的是 Go 的 buffalo CLI，不是 InsightFace 模型
常见错误现象：buffalo dev 报错 command not found，或装完 insightface 后试图运行 buffalo g resource user 却提示 module not found；更隐蔽的是在 go.mod 里误加 github.com/gobuffalo/buffalo 依赖却没配 BUFFALO_ENV，结果开发服务器启动但静态资源 404。
判断依据很简单：执行 which buffalo，输出路径含 /bin/buffalo 且版本号类似 v0.18.27 就对了；如果输出空或指向 Python site-packages，那你就进了 InsightFace 的坑。
- 安装正确命令是：
go install github.com/gobuffalo/buffalo/v2@latest（注意v2后缀） - 新建项目必须用
buffalo new myapp，不能mkdir && go mod init手动搭 -
buffalo dev启动后默认监听http://127.0.0.1:3000，不是8080或模型服务端口
避免 assets pipeline 编译卡死在 node_modules
Buffalo 默认集成 Webpack + Node.js 构建前端资源，但它的 webpack.config.js 是生成的、不透明，升级 Node 版本后常出现 Cannot find module 'webpack' 或 TypeError: compiler.plugin is not a function。这不是代码问题，是 Buffalo 自带的构建胶水层和现代 Webpack 不兼容。
实操建议：
- 优先关掉内置 asset pipeline：
buffalo new myapp --skip-yarn，然后手动用 Vite 或 esbuild 管理前端，后端只做 API - 若必须用内置 pipeline，锁定 Node 版本为
18.17.0（LTS），并在项目根目录加.nvmrc文件写死版本 - 删掉
node_modules后不要直接yarn install，改用buffalo fix——它会重置yarn.lock并校验依赖树
数据库迁移与测试环境分离不彻底
Buffalo 的 database.yml 默认把 development 和 test 共用一个数据库名（如 myapp_development），导致 buffalo test 一跑，开发库就被 TRUNCATE 掉——你刚录入的用户数据瞬间清零。
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
关键点在于：test 环境必须走独立 DB 实例或至少独立 DB 名，且 migration 要支持多环境回滚。
- 修改
database.yml，让test使用myapp_test，并确保 PostgreSQL/MySQL 用户有建库权限 - 每次写 migration 前先
buffalo db create -e test，再buffalo db migrate -e test - CI 中禁用
buffalo test的自动 migrate，改用显式命令：buffalo db migrate -e test && buffalo test
自定义中间件里 context.Value 泄露
Buffalo 的 context.Context 是请求生命周期载体，但很多人在中间件里用 c.Set("user_id", 123) 存值，然后在 handler 里 c.Get("user_id") 取——这看似方便，实际会导致内存无法释放：Buffalo 的 context 不会在请求结束时清空自定义 key，尤其在长连接或 WebSocket 场景下，map[string]interface{} 会越积越大。
真正安全的做法是用标准 context.WithValue 链式传递，并明确 key 类型：
- 定义私有 key 类型：
type userIDKey struct{}，而非字符串字面量 - 中间件中：
c.Request = c.Request.WithContext(context.WithValue(c.Request.Context(), userIDKey{}, id)) - handler 中：
id := c.Request.Context().Value(userIDKey{}).(int)
这个细节在本地小流量压测时完全看不出问题，但上生产后 GC 压力陡增、pprof 显示 runtime.mapassign 占比飙升，就是它在作祟。
