zt-closet-backend/.codebuddy/plans/配置全面去环境变量化_3cc28783.md

name, overview, todos

name	overview	todos
配置全面去环境变量化	移除应用配置的环境变量注入机制（viper AutomaticEnv），将所有配置统一收敛到 configs/config.yaml 直接配置，并更新所有相关注释与校验逻辑。	id content status remove-viper-env 删除 pkg/setting/setting.go 中 SetEnvPrefix、SetEnvKeyReplacer、AutomaticEnv 三行及 strings import，更新函数注释为仅从 config 读取 completed id content status update-config-comments 将 configs/config.yaml 中 13 处环境变量注入注释统一改为直接填写说明，JWT 密钥处标注必填 completed id content status dependencies global-check-verify 执行 go build、go vet、lint 检查，全局搜索确认无 os.Getenv、AutomaticEnv、ZT_CLOSET_ 残留 completed remove-viper-env update-config-comments

产品概述

彻底移除后端配置的环境变量注入机制，所有配置一律从 configs/config.yaml 配置文件读取，环境变量不再参与任何配置项的赋值或覆盖。

核心功能

• 禁用 viper 环境变量覆盖：删除 pkg/setting/setting.go 中 SetEnvPrefix、SetEnvKeyReplacer、AutomaticEnv 三处环境变量绑定，配置仅来自 configs/config.yaml。
• 更新配置文件说明：将 configs/config.yaml 中 13 处「敏感信息通过环境变量 ZT_CLOSET_XXX 注入」注释统一改为「直接在此填写」说明，并在 JWT 密钥处标注必填要求。
• 全局清理与复查：确保 Go 代码与配置注释中无 os.Getenv、AutomaticEnv、ZT_CLOSET_ 残留引用（第三方 Python 推理服务的库级环境变量除外）。
• 保持现有校验：main.go 中 JWT SecretKey 为空的启动失败校验继续生效，提醒用户必须在配置文件中填写密钥才能启动。

技术栈

• 语言：Go
• 配置库：spf13/viper（保留 YAML 文件读取，移除环境变量绑定）
• 配置文件：configs/config.yaml（已被 .gitignore 忽略，不入库）

实现方案

总体策略

环境变量注入在 Go 侧仅存在于 pkg/setting/setting.go 的 NewSetting 中，且全仓库已无 os.Getenv 调用（CORS 中间件此前已改为读取 global.ServerSetting.Domain）。因此本次改动为「单点删除 + 注释更新 + 全局复查」，不引入新机制、不影响其余 viper 读取逻辑。

核心数据流（改造后）

启动 main.go init -> setting.NewSetting()
  -> viper 读取 configs/config.yaml（唯一来源）
  -> ReadSection 逐节解析到 global.*Setting

环境变量不再参与任何环节。

模块改动

1. pkg/setting/setting.go

• 删除 vp.SetEnvPrefix("ZT_CLOSET")、vp.SetEnvKeyReplacer(...)、vp.AutomaticEnv() 三行。
• 更新 NewSetting 顶部注释为「仅从 configs/config.yaml 读取配置，不支持环境变量覆盖」。
• 删除仅被 strings.NewReplacer 使用的 strings import（不删会导致 unused import 编译错误）。
• 保留 AddConfigPath / SetConfigName / SetConfigType / ReadInConfig 逻辑。

2. configs/config.yaml（13 处注释统一改写，值保持空串待用户填写）

• Mysql.Password、Redis.Password、Cos.CosSecretID、Cos.CosSecretKey、Cos.CdnDownloadSecretKey、Tokenhub.APIKey、WechatMini.AppSecret：注释改为「# 直接在此填写（config.yaml 已被 .gitignore 忽略，不会提交到仓库）」。
• JWT.SecretKey：同上，并追加「必填，为空则启动失败」。
• WechatPay.AppID / MchID / APIv3Key / SerialNo / NotifyURL / RefundNotifyURL：注释改为「# 直接在此填写（config.yaml 已被 .gitignore 忽略，不会提交到仓库）」。

3. configs/config.example.yaml：已确认为纯占位符示例、无环境变量表述，保持不动（该文件会入库，绝不可填真实密钥）。
4. main.go：启动校验逻辑（JWT.SecretKey 非空）无需改动，移除环境变量后仍有效。

范围边界

• thirdparty/matting_server/main.py、thirdparty/classification_server/main.py 中的环境变量是 huggingface/transformers 库运行要求（必须在 import 前设置），不属于本应用配置体系，本次不改动。
• README.md 为空文件，不涉及。

验证要点

• go build ./...、go vet ./...、read_lints 无新增错误。
• 全局搜索确认 Go 代码与配置文件中无残留 os.Getenv、AutomaticEnv、ZT_CLOSET_ 引用（thirdparty Python 除外）。

安全说明

• configs/config.yaml 已被 .gitignore 忽略，敏感信息写入不会入库；提醒用户注意本地文件权限与备份安全。
• configs/config.example.yaml 会随代码入库，必须保持占位符示例值。