配置说明

所有配置文件位于 configs/：

文件	配置内容
application.yaml	公共配置，所有进程共享。包含 datasource、redis、sa-token、xss、cors、captcha、mail、sms、social、oss、push、accesslog、traceId、repeatableBody、i18n、apiEncrypt、user.password 等全部业务开关。各进程独有的端口在 <模块>.yaml 中覆盖。
standalone.yaml	单体进程独有。server.name=standalone、addr=":8080"、snowflake.workerId=0。
auth.yaml	auth 模块进程。server.name=auth、addr=":8080"、snowflake.workerId=1。
system.yaml	system 模块进程。server.name=system、addr=":8080"、snowflake.workerId=2。
resource.yaml	resource 模块进程。server.name=resource、addr=":8080"、snowflake.workerId=3。
monitor.yaml	monitor 模块进程。server.name=monitor、addr=":8080"。

workerId 分配

必须互不相同 各进程共用同一数据库，snowflake.workerId 必须互不相同，否则雪花主键撞号。已分配：auth=1、

system=2、resource=3、standalone=0。同模块起多副本时，副本须挂载各自的 yaml 覆盖 workerId。

application.yaml 顶层段

Section	控制内容
datasource	MySQL 连接：driver/host/port/username/password/dbname/params、连接池 maxIdleConns/maxOpenConns/connMaxLifetime/connMaxIdleTime、logLevel、slowThresholdMs。
redis	Redis 连接：host/port/password/db/clientName（便于 CLIENT LIST 排查）、poolSize/minIdleConns/超时。
satoken	sa-token-go 鉴权：tokenName（读 token 的请求头名）、isConcurrent（多端在线）、isShare（多端是否共享同一 token）、jwtSecretKey。
user.password	密码错误重试：maxRetryCount（达到即锁定）、lockTime（锁定时长分钟）。
cors	跨域：allowCredentials、allowedOriginPatterns（支持 * 通配）、allowedMethods/allowedHeaders、exposedHeaders（X-Request-Id / Content-Disposition / download-filename）、maxAgeSeconds。
xss	XSS 清洗：excludeUrls（Ant 风格路径排除，如富文本公告 /system/notice）、skipMethods（GET/DELETE 不携带落库内容）。
accesslog	请求日志：maxParamLength（参数日志最大字符数 rune）、skipPaths（不打日志的路径）。
traceId	链路 id：header（X-Request-Id）、trustInbound（是否沿用上游 nginx/网关生成的 id；进程直接暴露公网时应关掉）。
repeatableBody	可重读请求体：contentTypes（需缓存的前缀，勿加 multipart/form-data 否则上传文件读进内存）、maxBodySize（超出直接拒绝不截断）。
i18n	国际化：header（content-language）、default（zh-cn）。
apiEncrypt	接口加密：enabled、headerFlag（encrypt-key）、publicKey（响应加密）、privateKey（请求解密）。
captcha	验证码：enable、type（math 算术 / char 字符）、numberLength、charLength。
push	消息推送：enabled、transport（sse / websocket，非法回落 sse）、path（相对部分 /message）、sseTimeoutSeconds、heartbeatSeconds、sendBuffer。跨域统一由 cors 管。
mail	邮件（/resource/email/code）：enabled、host、port（465 配 ssl=true，587 配 ssl=false STARTTLS）、ssl、from、user、password（QQ/163 填「授权码」）。enabled=false 时接口返回提示而非报错。
sms	短信（阿里云，/resource/sms/code）：enabled、accessKeyId、accessKeySecret、signName、templateCode（模板变量名须为 code）、endpoint、regionId。换厂商实现 pkg/sms 的 Sender 接口即可。
social	三方登录：type 下 gitee/github/maxkey/topiam；未填 clientId/clientSecret 的平台一律视为未启用，/auth/binding/{source} 返回「xx平台账号暂不支持」。redirectUri 指向前端回调页，须与平台控制台登记地址一致。

sa-token-go replace 指令

go.mod 末尾的 replace 块：

// sa-token-go 是多 module 仓库，goproxy 未缓存、github 直连受限，
// 故以本地检出版本 replace。
replace (
	github.com/sa-tokens/sa-token-go/core => E:/WorkSpace/sa-token-go-main/core
	github.com/sa-tokens/sa-token-go/integrations/gin => E:/WorkSpace/sa-token-go-main/integrations/gin
	github.com/sa-tokens/sa-token-go/storage/memory => E:/WorkSpace/sa-token-go-main/storage/memory
	github.com/sa-tokens/sa-token-go/storage/redis => E:/WorkSpace/sa-token-go-main/storage/redis
	github.com/sa-tokens/sa-token-go/stputil => E:/WorkSpace/sa-token-go-main/stputil
)

上线 / 换机时若可直连 proxy，删掉 replace 块并 go get 即可。require 版本统一 v0.2.4。

配置加载机制

pkg/config 用 viper 读取多份 yaml， 后者覆盖前者。Load 先用 DefaultXxx().setDefaults(v) 注入默认值再读 yaml，故缺失字段有兜底；validate() 串联校验所有子配置，任一失败即 panic（启动期 fail-fast）。Get() 取包级实例，未 Load 也 panic。

环境变量改不了配置

pkg/config 没开 viper.AutomaticEnv，改配置只能改 yaml（或容器部署时挂载覆盖）。

详见 pkg 参考 / config · database · redis · cache。