feat: load explicit configuration references and remove implicit env overlays

2026-09-26 16:14:54 +08:00
parent 4bf6e88cfe
commit d598b2ebee
94 changed files with 1355 additions and 1759 deletions
--- a/cmd/go-omni/README.md
+++ b/cmd/go-omni/README.md
@@ -14,7 +14,7 @@ v0.14 新增 `api format [--check]`、`api upgrade [--dry-run|--preview <空目

 ```sh
 # 仓库读取权限与 PATH 配置见根目录 README
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.21.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.22.0-preview
 go-omni new --module example.com/hello ./hello

 # 从自己的契约生成；service.api 及其相对 import 文件需要在本地存在
@@ -49,14 +49,14 @@ main、Gen.go、OpenAPI 和 manifest 由生成器维护；业务文件按字节

 ## 版本与迁移

-CLI 与框架依赖固定使用 v0.20.0-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；`--framework-version` 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：
+CLI 与框架依赖固定使用 v0.22.0-preview。远程安装的 CLI 默认把自身版本写入 go.mod，不添加本地 replace；`--framework-version` 可显式指定已发布的兼容版本。仅在开发框架源码时使用本地替换：

 ```sh
 # 在 go-omni 源码仓库中执行
 go run ./cmd/go-omni new --module example.com/hello --framework-dir . ../hello
 ```

-当前模板与依赖以 v0.20.0-preview 为基线，继续使用 manifest v2；GORM 可选适配器从 v0.14.1-preview 提供。已有项目使用 [定点升级与预览](../../DEVELOPMENT.md#v013-项目升级)：原始模板可自动替换，含业务修改的基础文件按预览合并；通用清理由 Runtime 负责。独立工具命令不会被删除。受管理项目通过 `.api` 模块导入增加业务，不使用旧 `add` 命令的手动路由装配。
+当前模板与依赖以 v0.22.0-preview 为基线，继续使用 manifest v2；GORM 可选适配器从 v0.14.1-preview 提供。已有项目使用 [定点升级与预览](../../DEVELOPMENT.md#v013-项目升级)：原始模板可自动替换，含业务修改的基础文件按预览合并；通用清理由 Runtime 负责。独立工具命令不会被删除。受管理项目通过 `.api` 模块导入增加业务，不使用旧 `add` 命令的手动路由装配。

 ## 数据库迁移命令

@@ -70,6 +70,8 @@ go-omni migrate --dir migrations --apply

 SQL 命名示例 `0001_createUsers.up.sql`；预览只显示版本和 SHA-256，不连接数据库。失败保留 dirty 状态，不自动 down/force。细节见 [扩展模块](../../ADVANCED.md)。

-### v0.20 配置入口
+### v0.22 文件显式配置

-新生成 `internal/config/loadGen.go` 调用统一加载，纳入生成检查；项目 config.go 只维护字段、默认值和校验，loader.go 用于注册额外格式。JSON/YAML/XML 内置。旧手写 Load 会阻止生成，请先按 [迁移步骤](../../CONFIG.md#v019-及更早项目迁移) 整理，不会自动覆盖业务代码。
+新生成 `internal/config/loadGen.go` 调用统一加载，纳入生成检查；项目 config.go 只维护字段、默认值和校验，loader.go 用于注册额外格式。JSON/YAML/XML 内置。旧手写 Load 会阻止生成，请先按 [迁移步骤](../../CONFIG.md#v022-迁移旧模式已移除) 整理，不会自动覆盖业务代码。
+
+`go run . -config etc/config.test.yaml -check-config` 只做配置解析和校验，不初始化日志、数据库或监听。文件中的固定值不受环境自动覆盖；`${NAME}` 为必填引用，`${NAME:-fallback}` 提供备用值。
--- a/cmd/go-omni/apigen/configLoader_test.go
+++ b/cmd/go-omni/apigen/configLoader_test.go
@@ -26,8 +26,8 @@ func TestGeneratedConfigurationConsumer(t *testing.T) {
 	// The business only changes fields/defaults/validation, not the loading flow.
 	writeFile(t, filepath.Join(dir, "internal/config/config.go"), `package config
 import("git.yuntuo.hk/k2safe/go-omni/config";"git.yuntuo.hk/k2safe/go-omni/logx")
- type Config struct { Server config.Config `+"`json:\"server\"`"+`;Limit int `+"`json:\"limit\" envDefault:\"10\"`"+` }
- func Default()Config{ c:=config.Default();c.Log.File="./var/log/app.log";c.Log.Rotation=logx.RotationConfig{Enabled:true,MaxSizeMB:10};return Config{Server:c} }
+ type Config struct { Server config.Config `+"`json:\"server\"`"+`;Limit int `+"`json:\"limit\"`"+` }
+ func Default()Config{ c:=config.Default();c.Log.File="./var/log/app.log";c.Log.Rotation=logx.RotationConfig{Enabled:true,MaxSizeMB:10};return Config{Server:c,Limit:10} }
 func(c Config)Validate()error{if err:=c.Server.Validate();err!=nil{return config.AtField("server",err)};if c.Limit<0{return config.Invalid("limit","must not be negative")};return nil}
 `)
 	writeFile(t, filepath.Join(dir, "internal/config/loader.go"), `package config
@@ -111,3 +111,26 @@ func TestConfigLoadMigrationGuard(t *testing.T) {
 		}
 	}
 }
+
+func TestRemovedEnvironmentTagsRejectBeforeGeneration(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "app")
+	o := Options{Dir: dir, Module: "example.com/migrate", FrameworkDir: frameworkRoot(t)}
+	if _, err := New(o); err != nil {
+		t.Fatal(err)
+	}
+	o.API = filepath.Join(dir, "api/service.api")
+	path := filepath.Join(dir, "internal/config/config.go")
+	source := readFile(t, path)
+	writeFile(t, path, strings.Replace(source, "json:\"server\"", "json:\"server\" env:\"OLD_SERVER\"", 1))
+	before := snapshot(t, dir)
+	for _, mode := range []string{"dry", "generate", "check"} {
+		o.DryRun = mode == "dry"
+		o.Check = mode == "check"
+		if _, err := Generate(o); err == nil || !strings.Contains(err.Error(), "env/envDefault") {
+			t.Fatal(err)
+		}
+		if !sameFiles(before, snapshot(t, dir)) {
+			t.Fatal("migration rejection wrote files")
+		}
+	}
+}
--- a/cmd/go-omni/apigen/generate.go
+++ b/cmd/go-omni/apigen/generate.go
@@ -21,8 +21,8 @@ import (
 const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"

 // Runtime-only releases need not raise the managed template compatibility floor.
-const minimumVersion = "v0.20.0-preview"
-const currentVersion = "v0.21.0-preview"
+const minimumVersion = "v0.22.0-preview"
+const currentVersion = "v0.22.0-preview"
 const generatedHeader = "// Code generated by go-omni api. DO NOT EDIT.\n"

 type Options struct {
@@ -158,7 +158,7 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 					if !filepath.IsAbs(path) {
 						path = filepath.Join(directory, path)
 					}
-					if source, err := os.ReadFile(filepath.Join(path, "config", "loader.go")); err == nil && strings.Contains(string(source), "func NewLoader(") {
+					if source, err := os.ReadFile(filepath.Join(path, "config", "references.go")); err == nil && strings.Contains(string(source), "func WithLookupEnv(") {
 						localCurrent = true
 					}
 				}
--- a/cmd/go-omni/apigen/profile_test.go
+++ b/cmd/go-omni/apigen/profile_test.go
@@ -63,18 +63,23 @@ func TestAPIInfrastructureConsumers(t *testing.T) {
 					t.Fatal(err)
 				}
 				test := `package config
-import("testing";"os")
+import("testing";"os";"strings")
 func TestConfiguration(t *testing.T){
- t.Setenv("GO_OMNI_DB_DSN","test:test@tcp(127.0.0.1:1)/test")
+ t.Setenv("GO_OMNI_DB_DATABASE","test");t.Setenv("GO_OMNI_DB_USER","test");t.Setenv("GO_OMNI_DB_PASSWORD","test")
 t.Setenv("GO_OMNI_STORAGE_SIGNING_KEY","01234567890123456789012345678901")
 t.Setenv("GO_OMNI_STORAGE_ACCESS_KEY","test");t.Setenv("GO_OMNI_STORAGE_SECRET_KEY","test")
 t.Setenv("GO_OMNI_STORAGE_BUCKET","test");t.Setenv("GO_OMNI_STORAGE_ENDPOINT","ENDPOINT")
 t.Setenv("GO_OMNI_STORAGE_ACCOUNT_ID","01234567890123456789012345678901")
 cfg,err:=Load("../../etc/config.yaml");if err!=nil{t.Fatal(err)}
 if cfg.Server.Log.File==""{t.Fatal("file logger absent")}
- t.Setenv("GO_OMNI_LOG_OUTPUT","stdout");cfg,err=Load("");if err!=nil||cfg.Server.Log.File!=""{t.Fatalf("override: %v",err)}
- t.Setenv("GO_OMNI_SERVER_LOG_FILE","./explicit.log");cfg,err=Load("");if err!=nil||cfg.Server.Log.File!="./explicit.log"{t.Fatalf("canonical log file: %v",err)}
- t.Setenv("GO_OMNI_SERVER_LOG_OUTPUT","stderr");cfg,err=Load("");if err!=nil||cfg.Server.Log.Output!="stderr"{t.Fatalf("canonical output: %v",err)}
+ t.Setenv("GO_OMNI_LOG_OUTPUT","stdout");t.Setenv("GO_OMNI_SERVER_LOG_FILE","./implicit.log")
+ cfg,err=Load("../../etc/config.yaml");if err!=nil||cfg.Server.Log.File!=Default().Server.Log.File{t.Fatalf("implicit environment override: %v",err)}
+ raw,err:=os.ReadFile("../../etc/config.yaml");if err!=nil{t.Fatal(err)}
+ // Add explicit fields while keeping storage and DB requirements.
+ raw=[]byte(strings.Replace(string(raw),"server:\n","server:\n  log:\n    output: '${OUTPUT:-stdout}'\n    file: ''\n    rotation:\n      enabled: false\n",1))
+ path:="explicit.yaml";if err=os.WriteFile(path,raw,0600);err!=nil{t.Fatal(err)};defer os.Remove(path)
+ cfg,err=Load(path);if err!=nil||cfg.Server.Log.Output!="stdout"||cfg.Server.Log.File!=""||cfg.Server.Log.Rotation.Enabled{t.Fatalf("explicit file override: %v",err)}
+
 _=os.Getenv("unused")
 }`
 				endpoint := ""
--- a/cmd/go-omni/apigen/templates.go
+++ b/cmd/go-omni/apigen/templates.go
@@ -19,8 +19,10 @@ import (
 "MODULE/internal/svc"
 )
 func main(){
- path:=flag.String("config","etc/config.yaml","configuration file; empty uses defaults and environment")
+ path:=flag.String("config","etc/config.yaml","configuration file; empty uses only Default()")
+ check:=flag.Bool("check-config",false,"validate configuration and exit without starting dependencies")
 flag.Parse()
+ if *check {if _,err:=config.Load(*path);err!=nil{log.Fatal(err)};return}
 ctx,stop:=signal.NotifyContext(context.Background(),os.Interrupt,syscall.SIGTERM)
 defer stop()
 if err:=run(ctx,*path);err!=nil{log.Fatal(err)}
@@ -58,7 +60,7 @@ Unimplemented/nil factories fail startup and clean registered dependencies.
 Existing projects retain middleware: handlers until explicitly migrated.
 Ordinary Logic uses the generated Request/Response types directly. Where an
 independent business type is needed, use ordinary Go or the optional copyx package.
-Configuration loading is generator-managed in internal/config/loadGen.go. Extend fields/defaults/Validate in config.go; additional decoders belong in loader.go/NewLoader. JSON/YAML/XML use one pipeline. See the framework CONFIG.md.
+Configuration loading is generator-managed in internal/config/loadGen.go. Extend fields/defaults/Validate in config.go; additional decoders belong in loader.go/NewLoader. JSON/YAML/XML use explicit ${NAME} / ${NAME:-fallback} references; fixed values are never overridden by inferred environment names. Use -check-config to validate without opening dependencies. See the framework CONFIG.md.

 There are no mappings/mappingFiles settings or generated mapping files in v0.19.
 See COPY.md in the framework repository for copy policies and migration steps,
@@ -77,7 +79,7 @@ Configure server.endpoints to disable or move each built-in route. Health
 responseMode is app by default (project format), or raw for plain health data.
 Probe HTTP statuses remain 200/503 even when business errors use HTTP 200.
 OpenAPI remains an unwrapped document; disabled endpoints reserve no paths.
-Set GO_OMNI_TRANSPORT=native to select the native transport without changing services.
+The default file explicitly references GO_OMNI_TRANSPORT; set it to native or edit server.transport.
 The greeting starter works immediately; other new operation stubs return 501 until
 their business logic is implemented. Authentication hooks also fail closed with 501.

@@ -139,7 +141,7 @@ Full reference: https://git.yuntuo.hk/k2safe/go-omni/src/branch/main/DEVELOPMENT
 api/                         # editable contract and imported types
 main.go                      # GENERATED startup, lifecycle and route registration
 etc/config.yaml              # lowerCamelCase configuration
-internal/config/             # defaults -> file -> environment
+internal/config/             # defaults -> file references -> typed binding -> validation
 internal/svc/                # dependency initialization and cleanup
 internal/types/*Gen.go        # DTOs split by source API, one types package
 internal/svc/runtimeGen.go    # GENERATED lifecycle and infrastructure startup
@@ -240,13 +242,16 @@ func infrastructureREADME(o Options) string {

 Selected database: %s; storage: %s; logging: %s/%s.
 MySQL uses database/sql through deps.DB, including InTx and a readiness probe.
-Use structured database/mysql configuration and GO_OMNI_DB_PASSWORD. Other connection/pool/TLS settings live in etc/config.yaml and GO_OMNI_DB_*.
+Use structured database/mysql configuration. The generated etc/config.yaml explicitly
+references GO_OMNI_DB_PASSWORD and other required connection values; add fixed
+values or explicit references for pool/TLS fields. No implicit environment overlay.
 No tables are invented or migrated automatically from request/response DTOs.
 The none/memory selection opens no database; implement repositories per business.

 With storage enabled, services receive deps.Files, Uploads, Downloads and
 UploadLinks capability interfaces. Local signed GET/HEAD/PUT uses /storage/object;
-set GO_OMNI_STORAGE_SIGNING_KEY (32+ bytes) and GO_OMNI_STORAGE_PUBLIC_URL.
+the generated file references GO_OMNI_STORAGE_SIGNING_KEY (32+ bytes) and
+GO_OMNI_STORAGE_PUBLIC_URL. File values may instead be fixed explicitly.
 Cloud credentials use GO_OMNI_STORAGE_ACCESS_KEY/SECRET_KEY; set bucket and endpoint
 or R2 accountId as appropriate. Signed URLs grant temporary access: authenticate
 and authorize before issuing them. No public upload-link route is added.
--- a/cmd/go-omni/apigen/testdata/configuration/consumer_test.go
+++ b/cmd/go-omni/apigen/testdata/configuration/consumer_test.go
@@ -6,28 +6,26 @@ import (
 	"example.com/configuration/internal/config"
 	omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
 	"testing"
 )

 func TestGeneratedConfiguration(t *testing.T) {
-	for ext, source := range map[string]string{
-		"json": `{"limit":7}`, "yaml": "limit: 7\n", "xml": "<config><limit>7</limit></config>", "custom": `{"limit":7}`,
-	} {
+	for ext, source := range map[string]string{"json": `{"limit":"${LIMIT:-7}"}`, "yaml": "limit: '${LIMIT:-7}'\n", "xml": "<config><limit>${LIMIT:-7}</limit></config>", "custom": `{"limit":"${LIMIT:-7}"}`} {
 		t.Run(ext, func(t *testing.T) {
+			t.Setenv("LIMIT", "")
+			t.Setenv("GO_OMNI_LIMIT", "999")
 			path := filepath.Join(t.TempDir(), "app."+ext)
 			if err := os.WriteFile(path, []byte(source), 0600); err != nil {
 				t.Fatal(err)
 			}
 			cfg, err := config.Load(path)
-			if err != nil {
-				t.Fatal(err)
+			if err != nil || cfg.Limit != 7 {
+				t.Fatal(cfg.Limit, err)
 			}
-			if cfg.Limit != 7 {
-				t.Fatal(cfg.Limit)
-			}
-			t.Setenv("GO_OMNI_LIMIT", "0")
+			t.Setenv("LIMIT", "0")
 			cfg, err = config.Load(path)
 			if err != nil || cfg.Limit != 0 {
 				t.Fatal(cfg.Limit, err)
@@ -36,24 +34,60 @@ func TestGeneratedConfiguration(t *testing.T) {
 	}
 	t.Setenv("GO_OMNI_LOG_OUTPUT", "stderr")
 	cfg, err := config.Load("")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if cfg.Limit != 10 || cfg.Server.Log.File != "" || cfg.Server.Log.Rotation.Enabled {
-		t.Fatal("defaults/log normalization", cfg, err)
+	if err != nil || cfg.Limit != 10 || cfg.Server.Log.File != "./var/log/app.log" || !cfg.Server.Log.Rotation.Enabled {
+		t.Fatal("implicit overlay", err)
 	}
 	path := filepath.Join(t.TempDir(), "bad.yaml")
-	os.WriteFile(path, []byte("limit: -1\n"), 0600)
-	// Validation must run before svc.Initialize; the project initializer panics
-	// below if reached, so this also detects accidentally starting dependencies.
+	os.WriteFile(path, []byte("limit: '${LIMIT}'\n"), 0600)
+	t.Setenv("LIMIT", "-1")
+	// svc.Init panics if reached. Both invalid startup and successful check must
+	// stop before opening the configured file logger or project dependencies.
 	err = run(context.Background(), path)
-	var diagnostic *omniConfig.Error
-	if !errors.As(err, &diagnostic) || diagnostic.Field != "limit" || diagnostic.File != path || diagnostic.Line != 1 {
+	var d *omniConfig.Error
+	if !errors.As(err, &d) || d.Field != "limit" || d.File != path || d.Line != 1 || d.Env != "LIMIT" {
 		t.Fatal(err)
 	}
-	t.Setenv("GO_OMNI_LIMIT", "private-not-a-number")
+	t.Setenv("LIMIT", "private-invalid")
 	_, err = config.Load(path)
-	if !errors.As(err, &diagnostic) || diagnostic.Env != "GO_OMNI_LIMIT" || strings.Contains(err.Error(), "private-not-a-number") {
+	if !errors.As(err, &d) || d.Env != "LIMIT" || strings.Contains(err.Error(), "private-invalid") {
 		t.Fatal(err)
 	}
 }
+func TestConfigurationCheckProcess(t *testing.T) {
+	exe := filepath.Join(t.TempDir(), "server")
+	cmd := exec.Command("go", "build", "-o", exe, ".")
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatal(err, string(out))
+	}
+	dir := t.TempDir()
+	path := filepath.Join(dir, "selected.yaml")
+	if err := os.WriteFile(path, []byte("limit: '${LIMIT:-0}'\nserver:\n  address: 127.0.0.1:1\n"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	// A broken neighboring default/local/test file must never be layered in.
+	for _, name := range []string{"config.yaml", "config.local.yaml", "config.test.yaml"} {
+		os.WriteFile(filepath.Join(dir, name), []byte("broken: ["), 0600)
+	}
+	cmd = exec.Command(exe, "-config", path, "-check-config")
+	cmd.Dir = dir
+	if out, err := cmd.CombinedOutput(); err != nil || len(out) != 0 {
+		t.Fatal(err, string(out))
+	}
+	if _, err := os.Stat(filepath.Join(dir, "var")); !os.IsNotExist(err) {
+		t.Fatal("check opened logger/dependencies")
+	}
+	os.WriteFile(path, []byte("limit: '${MISSING_REQUIRED}'"), 0600)
+	cmd = exec.Command(exe, "-config", path, "-check-config")
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), "MISSING_REQUIRED=")
+	out, err := cmd.CombinedOutput()
+	if err == nil || !strings.Contains(string(out), "MISSING_REQUIRED") || strings.Contains(string(out), "panic") {
+		t.Fatal(err, string(out))
+	}
+	cmd = exec.Command(exe, "-config", path)
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), "MISSING_REQUIRED=")
+	if out, err := cmd.CombinedOutput(); err == nil || strings.Contains(string(out), "panic") {
+		t.Fatal(err, string(out))
+	}
+}
--- a/cmd/go-omni/apigen/testdata/managed/consumer_test.go
+++ b/cmd/go-omni/apigen/testdata/managed/consumer_test.go
@@ -123,7 +123,7 @@ func TestGeneratedTransfers(t *testing.T) {
 func configFile(t *testing.T, address string, fail bool) string {
 	t.Helper()
 	path := filepath.Join(t.TempDir(), "config.json")
-	data, _ := json.Marshal(map[string]any{"server": map[string]any{"address": address}, "failInit": fail})
+	data, _ := json.Marshal(map[string]any{"server": map[string]any{"address": address, "transport": "${GO_OMNI_TRANSPORT:-nethttp}"}, "failInit": fail})
 	if err := os.WriteFile(path, data, 0600); err != nil {
 		t.Fatal(err)
 	}
--- a/cmd/go-omni/apigen/testdata/managed/phases_test.go
+++ b/cmd/go-omni/apigen/testdata/managed/phases_test.go
@@ -24,7 +24,7 @@ func phasedConfig(t *testing.T, address, mode string, fail bool) string {
 	if mode == "stuck" {
 		drainTimeout = "50ms"
 	}
-	data, _ := json.Marshal(map[string]any{"backgroundMode": mode, "failInit": fail, "server": map[string]any{"address": address, "lifecycle": map[string]string{"stopTimeout": "1s", "drainTimeout": drainTimeout, "cancelTimeout": "50ms"}}})
+	data, _ := json.Marshal(map[string]any{"backgroundMode": mode, "failInit": fail, "server": map[string]any{"address": address, "transport": "${GO_OMNI_TRANSPORT:-nethttp}", "lifecycle": map[string]string{"stopTimeout": "1s", "drainTimeout": drainTimeout, "cancelTimeout": "50ms"}}})
 	if err := os.WriteFile(path, data, 0600); err != nil {
 		t.Fatal(err)
 	}
--- a/cmd/go-omni/apigen/upgrade.go
+++ b/cmd/go-omni/apigen/upgrade.go
@@ -14,7 +14,9 @@ import (
 	"golang.org/x/mod/semver"
 	"os"
 	"path/filepath"
+	"reflect"
 	"sort"
+	"strconv"
 	"strings"
 )

@@ -54,6 +56,22 @@ func checkConfigLoadExtension(root string) error {
 		if err != nil {
 			return fmt.Errorf("parse %s: %w", rel, err)
 		}
+		var removed bool
+		ast.Inspect(f, func(n ast.Node) bool {
+			field, ok := n.(*ast.Field)
+			if ok && field.Tag != nil {
+				if raw, e := strconv.Unquote(field.Tag.Value); e == nil {
+					tag := reflect.StructTag(raw)
+					_, a := tag.Lookup("env")
+					_, b := tag.Lookup("envDefault")
+					removed = removed || a || b
+				}
+			}
+			return true
+		})
+		if removed {
+			return fmt.Errorf("%s: env/envDefault tags were removed; migrate defaults and explicit file references before generating; see CONFIG.md", rel)
+		}
 		for _, decl := range f.Decls {
 			if fn, ok := decl.(*ast.FuncDecl); ok && fn.Recv == nil && fn.Name.Name == "Load" {
 				return fmt.Errorf("%s: migrate the project-owned Load function before generating internal/config/loadGen.go; retain Config/Default/Validate and move decoder options to NewLoader; see CONFIG.md", rel)
--- a/cmd/go-omni/main_test.go
+++ b/cmd/go-omni/main_test.go
@@ -8,7 +8,7 @@ import (
 )

 func TestNewWithRemoteFrameworkVersion(t *testing.T) {
-	for _, flag := range [][]string{{"--framework-version", "v0.21.0-preview"}, {"--framework-version=v0.21.0-preview"}} {
+	for _, flag := range [][]string{{"--framework-version", "v0.22.0-preview"}, {"--framework-version=v0.22.0-preview"}} {
 		project := filepath.Join(t.TempDir(), "billing")
 		args := append([]string{"--module", "example.com/billing"}, flag...)
 		if err := runNew(append(args, project)); err != nil {
@@ -18,7 +18,7 @@ func TestNewWithRemoteFrameworkVersion(t *testing.T) {
 		if err != nil {
 			t.Fatal(err)
 		}
-		if !strings.Contains(string(content), "go-omni v0.21.0-preview") || strings.Contains(string(content), "replace ") {
+		if !strings.Contains(string(content), "go-omni v0.22.0-preview") || strings.Contains(string(content), "replace ") {
 			t.Fatalf("CLI did not pin remote dependency: %s", content)
 		}
 	}
--- a/cmd/go-omni/scaffold/moduleProfiles_test.go
+++ b/cmd/go-omni/scaffold/moduleProfiles_test.go
@@ -66,9 +66,13 @@ func TestGenerateModuleProfiles(t *testing.T) {
 				t.Fatal("replacement does not resolve", err)
 			}
 			cfg, _ := os.ReadFile(filepath.Join(project, "etc/config.yaml"))
-			if strings.Contains(string(cfg), "secretKey:") || strings.Contains(string(cfg), "filesToken:") {
-				t.Fatal("secret defaults emitted")
+			for _, line := range strings.Split(string(cfg), "\n") {
+				key, value, ok := strings.Cut(strings.TrimSpace(line), ":")
+				if ok && (key == "secretKey" || key == "filesToken" || key == "signingKey") && !strings.Contains(value, "${GO_OMNI_") {
+					t.Fatal("secret must be an explicit reference")
+				}
 			}
+
 		})
 	}
 }
@@ -76,6 +80,7 @@ func TestModuleOptionsRejectBeforeWriting(t *testing.T) {
 	for _, options := range []Options{
 		{LogOutput: "invalid"}, {LogFormat: "xml"}, {Storage: "ftp"},
 		{Storage: "local", FrameworkVersion: "v0.6.0-preview"},
+		{FrameworkVersion: "v0.21.0-preview"},
 		{Module: "example.com/x\nrequire malicious v1.0.0"},
 	} {
 		options.Dir = filepath.Join(t.TempDir(), "project")
--- a/cmd/go-omni/scaffold/scaffold.go
+++ b/cmd/go-omni/scaffold/scaffold.go
@@ -34,9 +34,13 @@ type Options struct {
 }

 var files = map[string]string{
+	"internal/settings/config.go":      "templates/modules-settings.go.tmpl",
+	"internal/settings/config_test.go": "templates/modules-settings_test.go.tmpl",
+	"etc/config.yaml":                  "templates/modules-config.yaml.tmpl",
+
 	"go.mod":                             "templates/go.mod.tmpl",
 	"README.md":                          "templates/README.md.tmpl",
-	"cmd/server/main.go":                 "templates/cmd-server-main.go.tmpl",
+	"cmd/server/main.go":                 "templates/modules-main.go.tmpl",
 	"internal/model/user.go":             "templates/internal-model-user.go.tmpl",
 	"internal/model/errors.go":           "templates/internal-model-errors.go.tmpl",
 	"internal/repository/users.go":       "templates/internal-repository-users.go.tmpl",
@@ -109,7 +113,7 @@ func Generate(options Options) error {
 	if options.FrameworkDir != "" || options.FrameworkVersion == "" {
 		replace = frameworkReplace(directory, options.FrameworkDir)
 	}
-	if modules && replace == "" && semver.Compare(version, modulesFrameworkVersion) < 0 && version != installedFrameworkVersion() {
+	if replace == "" && semver.Compare(version, modulesFrameworkVersion) < 0 && version != installedFrameworkVersion() {
 		return fmt.Errorf("module templates require %s or newer; use --framework-dir for unpublished source", modulesFrameworkVersion)
 	}
 	data := templateData{
--- a/cmd/go-omni/scaffold/scaffold_test.go
+++ b/cmd/go-omni/scaffold/scaffold_test.go
@@ -39,7 +39,7 @@ func TestGenerateCreatesServiceLayout(t *testing.T) {
 	if err != nil {
 		t.Fatalf("read generated server: %v", err)
 	}
-	for _, expected := range []string{"config.LoadFromEnv(\"\")", "logx.SetDefault(logger)", "omni.WithConfig(settings)", "servicecontext.New(ctx, logger)", "services.Health.ReadinessHandler()", "application.RunContext(ctx, settings.Address)"} {
+	for _, expected := range []string{"settings.Load(path)", "logx.SetDefault(logger)", "omni.WithConfig(cfg.Server)", "servicecontext.New(ctx, logger, cfg)", "services.Health.ReadinessHandler()", "application.RunContext(ctx, cfg.Server.Address)"} {
 		if !strings.Contains(string(mainContent), expected) {
 			t.Fatalf("generated server missing %q: %s", expected, mainContent)
 		}
@@ -110,7 +110,7 @@ func TestFrameworkReplaceUsesCanonicalPaths(t *testing.T) {
 }

 func TestGenerateRemoteProjectPinsVersion(t *testing.T) {
-	for _, version := range []string{"v0.1.0", "v1.2.3-rc.1", "v0.0.0-20260920140624-8b19aa79eea0"} {
+	for _, version := range []string{"v0.22.0-preview", "v1.2.3-rc.1", "v0.22.1-0.20260926000000-8b19aa79eea0"} {
 		t.Run(version, func(t *testing.T) {
 			project := filepath.Join(t.TempDir(), "billing")
 			if err := Generate(Options{Dir: project, Module: "example.com/billing", FrameworkVersion: version}); err != nil {
--- a/cmd/go-omni/scaffold/templates/README.md.tmpl
+++ b/cmd/go-omni/scaffold/templates/README.md.tmpl
@@ -32,46 +32,44 @@ go mod tidy
 go run ./cmd/server
 ```

-运行时配置从 `GO_OMNI_*` 环境变量加载，例如：
+配置入口是 `internal/settings.Config`、`Default()`、`Validate()` 和 `etc/config.yaml`。
+只有文件里的 `${NAME}` / `${NAME:-fallback}` 会读取环境变量，固定值不受进程环境覆盖。生成的文件已声明地址、网络层，以及所选数据库/存储的必要引用；其他参数直接写进文件。

-```sh
-GO_OMNI_ENABLE_LOGGER=true GO_OMNI_LOG_LEVEL=debug go run ./cmd/server
+```yaml
+server:
+  address: "${GO_OMNI_HTTP_ADDR:-127.0.0.1:8080}"
+  transport: "${GO_OMNI_TRANSPORT:-nethttp}"
+  log:
+    level: debug
+  shutdownTimeout: 10s
 ```

-`GO_OMNI_HTTP_ADDR` 可以修改监听地址。生成项目默认提供 `/health/live` 和
-`/health/ready`，日志、请求 ID 和优雅退出等基础能力由 GoOmni 统一初始化；业务依赖集中放在项目自己的 `internal/servicecontext`。
-
-服务使用 `signal.NotifyContext` 处理 `SIGINT` / `SIGTERM`。部署时构建并运行服务二进制，
-使信号直接到达服务进程：
+用 `-config` 选择一个 YAML/JSON/XML 文件；`-config ''` 只使用 Default()；`-check-config` 仅加载和校验，不创建依赖或监听：

 ```sh
+go run ./cmd/server -config etc/config.yaml -check-config
 go build -o server ./cmd/server
-./server
+./server -config etc/config.yaml
 ```

-`GO_OMNI_SHUTDOWN_TIMEOUT` 控制等待请求完成的时间，默认 `10s`。
+服务通过 `signal.NotifyContext` 处理 `SIGINT` / `SIGTERM`，先排空 HTTP 请求，再关闭依赖和日志。生成项目默认提供 `/health/live` 和 `/health/ready`，业务依赖集中在 `internal/servicecontext`。

-使用支持统一网络配置的框架版本时，设置 `GO_OMNI_TRANSPORT=native` 即可切换为自研 HTTP/1.1；
-默认 `nethttp`。`GO_OMNI_TLS_CERT_FILE` 和 `GO_OMNI_TLS_KEY_FILE` 配对启用 HTTPS。
-实验版 HTTP/2 使用 `GO_OMNI_TRANSPORT=http2`，必须同时配置 TLS 证书和私钥。
-业务 Handler / Service / Repository 不需要修改；三种适配器共用上述退出等待时间。
+通过文件中的引用设置 `GO_OMNI_TRANSPORT=native` 可切换自研 HTTP/1.1，默认 nethttp。HTTPS 在文件的 `server.tls.certFile` / `server.tls.keyFile` 成对配置；实验 HTTP/2 选择 `http2` 且必须配置 TLS。不会自动读取未在文件声明的 TLS 环境变量。
 {{if eq .Database "mysql"}}
-`/health/ready` 已注册数据库探针：连接失败返回 `503`，数据库恢复后重新返回 `200`。
-`/health/live` 始终只检查服务存活。`GO_OMNI_DB_PING_TIMEOUT` 限制初始化检查和数据库探针的等待时间。
-退出时先排空 HTTP 请求，再关闭数据库连接池，最后关闭日志。
+`/health/ready` 已注册数据库探针，连接失败返回 503，恢复后返回 200；`/health/live` 只检查进程存活。连接池参数直接写入 `database`，缺失字段保留 Default()：

-数据库连接池参数：
-
-```text
-GO_OMNI_DB_MAX_OPEN_CONNS=10
-GO_OMNI_DB_MAX_IDLE_CONNS=5
-GO_OMNI_DB_CONN_MAX_LIFETIME=30m
-GO_OMNI_DB_CONN_MAX_IDLE_TIME=5m
-GO_OMNI_DB_PING_TIMEOUT=5s
+```yaml
+database:
+  driver: mysql
+  dsn: "${GO_OMNI_DB_DSN}"
+  maxOpenConns: 10
+  maxIdleConns: 5
+  connMaxLifetime: 30m
+  connMaxIdleTime: 5m
+  pingTimeout: 5s
 ```

-`MAX_IDLE_CONNS=0` 禁用空闲连接，`MAX_OPEN_CONNS=0` 表示不限制连接数。
-项目会启用 MySQL `parseTime` 并按 UTC 读取 DATETIME 字段，JSON 字段保持 lowerCamelCase。
+`maxIdleConns: 0` 禁用空闲连接；此项目要求 maxOpenConns 为正数。项目启用 MySQL parseTime，并按 UTC 读取 DATETIME；JSON 字段保持 lowerCamelCase。

 事务内复用 Repository（在业务代码中导入 `database/sql` 和项目的 `internal/repository`）：

--- a/cmd/go-omni/scaffold/templates/api-config.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/api-config.go.tmpl
@@ -11,8 +11,8 @@ import (
 )
 type Config struct {
 Server config.Config `json:"server"`
- {{if eq .Database "mysql"}}Database mysqladapter.Config `json:"database" env:"GO_OMNI_DB"`{{end}}
- {{if ne .Storage "none"}}Storage StorageConfig `json:"storage" env:"GO_OMNI_STORAGE"`{{end}}
+ {{if eq .Database "mysql"}}Database mysqladapter.Config `json:"database"`{{end}}
+ {{if ne .Storage "none"}}Storage StorageConfig `json:"storage"`{{end}}
 }
 func Default() Config {
 server:=config.Default()
@@ -54,12 +54,12 @@ type StorageConfig struct {
 ContentTypes []string `json:"contentTypes"`
 LinkTTL time.Duration `json:"linkTtl"`
 RequestTimeout time.Duration `json:"requestTimeout"`
- // Secrets are environment-only and cannot be populated by config files.
- FilesToken string `json:"-" env:"GO_OMNI_FILES_TOKEN,secret"`
- SigningKey string `json:"-" env:"GO_OMNI_STORAGE_SIGNING_KEY,secret"`
- AccessKey string `json:"-" env:"GO_OMNI_STORAGE_ACCESS_KEY,secret"`
- SecretKey string `json:"-" env:"GO_OMNI_STORAGE_SECRET_KEY,secret"`
- SessionToken string `json:"-" env:"GO_OMNI_STORAGE_SESSION_TOKEN,secret"`
+ // File values may explicitly reference environment variables. Never log this struct.
+ FilesToken string `json:"filesToken"`
+ SigningKey string `json:"signingKey"`
+ AccessKey string `json:"accessKey"`
+ SecretKey string `json:"secretKey"`
+ SessionToken string `json:"sessionToken"`
 }
 func (s StorageConfig) Policy()storage.UploadPolicy{return storage.UploadPolicy{MaxBytes:s.MaxBytes,ContentTypes:s.ContentTypes}}
 func (s StorageConfig) Validate()error {
@@ -67,14 +67,14 @@ func (s StorageConfig) Validate()error {
 if err:=s.Policy().Validate();err!=nil{return err}
 if s.LinkTTL<time.Second || s.LinkTTL>time.Hour{return errors.New("storage.linkTtl must be 1s..1h")}
 if s.RequestTimeout<=0 || s.RequestTimeout>5*time.Minute{return errors.New("storage.requestTimeout must be >0 and <=5m")}
- {{if not .API}}if len(s.FilesToken)<32 || strings.ContainsAny(s.FilesToken," \t\r\n") {return errors.New("set GO_OMNI_FILES_TOKEN to a token of at least 32 bytes without whitespace")}{{end}}
+ {{if not .API}}if len(s.FilesToken)<32 || strings.ContainsAny(s.FilesToken," \t\r\n") {return errors.New("storage.filesToken requires at least 32 bytes without whitespace")}{{end}}
 {{if eq .Storage "local"}}
 if s.Root=="" {return errors.New("storage.root is required")}
 u,err:=url.Parse(s.PublicURL)
 if err!=nil || u.Host=="" || u.Hostname()=="" || (u.Scheme!="http" && u.Scheme!="https") || u.User!=nil || u.RawQuery!="" || u.Fragment!="" || u.Path!="/storage/object" {return errors.New("storage.publicUrl must be an absolute HTTP(S) URL ending in /storage/object")}
- if len(s.SigningKey)<32 {return errors.New("set GO_OMNI_STORAGE_SIGNING_KEY to a stable secret of at least 32 bytes")}
+ if len(s.SigningKey)<32 {return errors.New("storage.signingKey requires a stable secret of at least 32 bytes")}
 {{else}}
- if s.Bucket=="" || s.Region=="" || s.AccessKey=="" || s.SecretKey=="" {return errors.New("storage bucket, region and GO_OMNI_STORAGE_ACCESS_KEY/SECRET_KEY are required")}
+ if s.Bucket=="" || s.Region=="" || s.AccessKey=="" || s.SecretKey=="" {return errors.New("storage bucket, region, accessKey and secretKey are required")}
 {{if eq .Storage "r2"}}
 if !regexp.MustCompile(`^[a-fA-F0-9]{32}$`).MatchString(s.AccountID) || s.Region!="auto" || !s.Secure {return errors.New("R2 requires a 32-hex accountId, region auto and secure=true")}
 if s.Endpoint!=""{return errors.New("this R2 profile derives endpoint from accountId; customize servicecontext for a jurisdiction-specific endpoint")}
--- a/cmd/go-omni/scaffold/templates/api-load.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/api-load.go.tmpl
@@ -1,13 +1,8 @@
 package config
-
 import omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
-
-// Load is maintained by the generator. Extend Config/Default/Validate in
-// config.go, or NewLoader in loader.go; do not duplicate the loading pipeline.
-func Load(path string) (Config, error) {
- loader,err:=NewLoader()
- if err!=nil{return Config{},err}
- return omniConfig.LoadProject(path,Default(),omniConfig.EnvOptions{
-  Prefix:"GO_OMNI_",Empty:"ignore",Aliases:omniConfig.ServerEnvAliases("GO_OMNI_","server"),
- },loader)
+// Load resolves explicit file references, binds onto Default and validates.
+// Ordinary projects only edit Config, Default, Validate and the selected file.
+func Load(path string)(Config,error){
+ loader,err:=NewLoader();if err!=nil{return Config{},err}
+ return omniConfig.LoadProject(path,Default(),loader)
 }
--- a/cmd/go-omni/scaffold/templates/cmd-server-main.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/cmd-server-main.go.tmpl
@@ -1,57 +0,0 @@
-package main
-
-import (
-	"context"
-	"log"
-	"os"
-	"os/signal"
-	"strings"
-	"syscall"
-
-	omni "git.yuntuo.hk/k2safe/go-omni"
-	"git.yuntuo.hk/k2safe/go-omni/config"
-	"git.yuntuo.hk/k2safe/go-omni/logx"
-	"{{.Module}}/internal/handler"
-	"{{.Module}}/internal/service"
-	"{{.Module}}/internal/servicecontext"
-)
-
-func main() {
-	if err := run(); err != nil {
-		log.Fatal(err)
-	}
-}
-
-func run() error {
-	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
-	defer stop()
-
-	settings, err := config.LoadFromEnv("")
-	if err != nil {
-		return err
-	}
-	if strings.TrimSpace(settings.Log.Service) == "" {
-		settings.Log.Service = "{{.Module}}"
-	}
-	logger, err := logx.New(settings.Log)
-	if err != nil {
-		return err
-	}
-	defer logger.Close()
-	// Access logs and business logs share the same configured sink.
-	logx.SetDefault(logger)
-
-	services, err := servicecontext.New(ctx, logger)
-	if err != nil { return err }
-	defer services.Close()
-	userService := service.NewUsers(services)
-	userHandler := handler.NewUsers(userService)
-
-	application := omni.New(omni.WithConfig(settings))
-	application.OnShutdown(logger.Close)
-	application.OnShutdown(services.Close)
-	application.GET("/health/live", services.Health.LivenessHandler())
-	application.GET("/health/ready", services.Health.ReadinessHandler())
-	userHandler.RegisterRoutes(application)
-	return application.RunContext(ctx, settings.Address)
-}
--- a/cmd/go-omni/scaffold/templates/databaseIntegration_test.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/databaseIntegration_test.go.tmpl
@@ -13,6 +13,7 @@ import (
 	"git.yuntuo.hk/k2safe/go-omni/database"
 	"git.yuntuo.hk/k2safe/go-omni/logx"
 	"{{.Module}}/internal/model"
+ "{{.Module}}/internal/settings"
 	"{{.Module}}/internal/repository"
 	"{{.Module}}/internal/servicecontext"
 )
@@ -23,15 +24,12 @@ func databaseContext(t *testing.T) *servicecontext.Context {
 	t.Helper()
 	dsn := os.Getenv("GO_OMNI_TEST_MYSQL_DSN")
 	if dsn == "" { t.Skip("set GO_OMNI_TEST_MYSQL_DSN to a dedicated test database") }
-	for _, key := range []string{"MAX_OPEN_CONNS", "MAX_IDLE_CONNS", "CONN_MAX_LIFETIME", "CONN_MAX_IDLE_TIME", "PING_TIMEOUT"} {
-		t.Setenv("GO_OMNI_DB_"+key, "")
-	}
 	t.Setenv("GO_OMNI_DB_DSN", dsn)
-	t.Setenv("GO_OMNI_DB_DRIVER", "mysql")
 	logger, err := logx.New(logx.Config{Writer: io.Discard})
 	if err != nil { t.Fatal(err) }
 	t.Cleanup(func() { _ = logger.Close() })
-	services, err := servicecontext.New(context.Background(), logger)
+	cfg,err:=settings.Load("../../etc/config.yaml");if err!=nil{t.Fatal(err)}
+ services, err := servicecontext.New(context.Background(), logger,cfg)
 	if err != nil { t.Fatal(err) }
 	t.Cleanup(func() { _ = services.Close() })
 	return services
--- a/cmd/go-omni/scaffold/templates/internal-servicecontext-context.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/internal-servicecontext-context.go.tmpl
@@ -2,6 +2,7 @@ package servicecontext

 import (
 	"context"
+ "{{.Module}}/internal/settings"
 {{if and .Modules (ne .Storage "none")}}"errors"
 "net/http"
 "sync"
@@ -38,16 +39,16 @@ type Context struct {

 // New initializes the project's dependencies before the HTTP listener opens.
 // The caller owns Logger; Close releases only resources created here.
-func New(ctx context.Context, logger *logx.Logger) (*Context, error) {
+func New(ctx context.Context, logger *logx.Logger, project settings.Config) (*Context, error) {
 	if ctx == nil { ctx = context.Background() }
 	if err := ctx.Err(); err != nil { return nil, err }
 	checker, err := health.New()
 	if err != nil { return nil, err }
 	services := &Context{Logger: logger, Health: checker}
 	{{if eq .Database "mysql"}}
-	cfg, err := database.ConfigFromEnv("")
-	if err != nil { return nil, err }
-	if cfg.Driver != "mysql" { return nil, fmt.Errorf("this project requires GO_OMNI_DB_DRIVER=mysql") }
+	cfg:=project.Database
+ if err:=cfg.Validate();err!=nil{return nil,err}
+	if cfg.Driver != "mysql" { return nil, fmt.Errorf("this project requires database.driver=mysql") }
 	dsn, err := mysql.ParseDSN(cfg.DSN)
 	if err != nil { return nil, fmt.Errorf("parse mysql connection settings: %w", err) }
 	if dsn.DBName == "" { return nil, fmt.Errorf("mysql connection settings require a database name") }
--- a/cmd/go-omni/scaffold/templates/modules-README.md.tmpl
+++ b/cmd/go-omni/scaffold/templates/modules-README.md.tmpl
@@ -2,7 +2,7 @@

 本项目选用日志输出 `{{.LogOutput}}`、格式 `{{.LogFormat}}`、对象存储 `{{.Storage}}`。数据库选择 `{{.Database}}` 独立于对象存储。

-配置入口为 `etc/config.yaml`，通过 `go run ./cmd/server -config /path/to/config.yaml` 指定其他 JSON/YAML 文件；`-config ''` 只用代码默认值和环境变量。优先级：默认值 → 文件 → 非空环境变量。未知字段、无效参数会在监听前拒绝。
+配置入口为 `etc/config.yaml`，通过 `go run ./cmd/server -config /path/to/config.yaml` 指定其他 JSON/YAML/XML 文件；`-config ''` 只用代码默认值。文件用 `${NAME}` 或 `${NAME:-fallback}` 显式引用变量，固定值不受隐式环境覆盖；`-check-config` 只检查、不初始化依赖。未知字段、无效参数会在监听前拒绝。

 ```sh
 go mod tidy
@@ -24,7 +24,7 @@ go run ./cmd/server

 {{if eq .Database "mysql"}}还需按 README 配置独立 MySQL 数据库并应用 schema.sql；应用不自动迁移。{{end}}

-默认仅监听 `127.0.0.1:8080`。`GO_OMNI_HTTP_ADDR` 覆盖地址；本地签名 URL 的外部地址通过 `GO_OMNI_STORAGE_PUBLIC_URL` 单独配置，始终以 `/storage/object` 结尾，不使用请求 Host 自动拼接可信链接。
+默认仅监听 `127.0.0.1:8080`。文件中的 `${GO_OMNI_HTTP_ADDR:-127.0.0.1:8080}` 设置地址；本地签名 URL 的外部地址通过 `GO_OMNI_STORAGE_PUBLIC_URL` 单独配置，始终以 `/storage/object` 结尾，不使用请求 Host 自动拼接可信链接。

 ## 日志

@@ -35,7 +35,7 @@ curl -H 'Content-Type: application/json' -H 'X-Request-ID: example-request' \
  -d '{"name":"Example","email":"example@example.com"}' http://127.0.0.1:8080/users
 ```

-`GO_OMNI_LOG_LEVEL`、`GO_OMNI_LOG_FORMAT`、`GO_OMNI_LOG_FILE` 覆盖对应项；显式设置 `GO_OMNI_LOG_OUTPUT=stdout` 且未设置 LOG_FILE 时，切换到控制台并关闭文件轮转。慢请求阈值为 500ms，可通过 `GO_OMNI_SLOW_REQUEST_THRESHOLD` 调整。字段脱敏不扫描 msg/error 中的自由文本；不要把凭据或签名 URL 拼到日志中。
+日志参数直接写在 `server.log`，例如 `level: debug`；也可显式写 `level: "${LOG_LEVEL:-info}"`。切换文件日志为控制台时，明确设置 `file: ""`、`output: stdout` 和 `rotation.enabled: false`，不会隐式重置其他字段。慢请求阈值使用 `server.slowRequestThreshold`，默认 500ms。字段脱敏不扫描 msg/error 自由文本；不要把凭据或签名 URL 拼到日志中。

 {{if ne .Storage "none"}}## 文件示例

@@ -66,18 +66,18 @@ curl -H "Authorization: Bearer $GO_OMNI_FILES_TOKEN" -H 'Content-Type: applicati

 响应包括随机 `data.key` 和 `data.request`（method/url/headers/expiresAt）。按返回的 method 和 headers 用原始文件字节上传到 URL；不能额外包 FormData。浏览器自动填写 Content-Length，其余签名 Header 原样发送；云桶需配置允许业务域名的 CORS。云端直传只绑定声明类型，实际内容需上传后验证；本地和 API 中转上传会检查允许类型及前缀嗅探结果。未完成内容验证前不要把暂存文件当作可信文件公开。

-| 参数 | 默认值 / 环境变量 |
+| 文件字段 | 默认值 / 含义 |
 | --- | --- |
-| 大小 | 32 MiB / GO_OMNI_STORAGE_MAX_BYTES |
-| 类型 | text/plain、image/png、image/jpeg、application/pdf / GO_OMNI_STORAGE_CONTENT_TYPES（逗号分隔） |
-| 链接有效期 | 5m / GO_OMNI_STORAGE_LINK_TTL（1s..1h） |
-| 请求超时 | 30s / GO_OMNI_STORAGE_REQUEST_TIMEOUT（>0 且 <=5m） |
-| 本地目录 | var/files / GO_OMNI_STORAGE_ROOT |
-| 本地外部 URL | http://127.0.0.1:8080/storage/object / GO_OMNI_STORAGE_PUBLIC_URL |
-| 云配置 | GO_OMNI_STORAGE_ENDPOINT、REGION、BUCKET、ACCOUNT_ID、SECURE |
-| 环境密钥 | GO_OMNI_FILES_TOKEN、GO_OMNI_STORAGE_SIGNING_KEY、GO_OMNI_STORAGE_ACCESS_KEY、SECRET_KEY、SESSION_TOKEN |
+| `storage.maxBytes` | 32 MiB |
+| `storage.contentTypes` | text/plain、image/png、image/jpeg、application/pdf；文件数组 |
+| `storage.linkTtl` | 5m，允许 1s..1h |
+| `storage.requestTimeout` | 30s，大于 0 且不超过 5m |
+| `storage.root` | var/files |
+| `storage.publicUrl` | http://127.0.0.1:8080/storage/object |
+| `storage.endpoint/region/bucket/accountId/secure` | 对应平台连接配置 |
+| `storage.filesToken/signingKey/accessKey/secretKey/sessionToken` | 文件显式引用环境变量提供凭据 |

-全部 JSON/YAML 字段使用 lowerCamelCase。密钥字段仅允许环境变量，配置文件中写入会报未知字段；不要把运行环境文件提交到仓库。S3 的 endpoint 为 host[:port]，OSS 的可选 endpoint 为 HTTPS origin；R2 从 accountId 派生官方 endpoint，region 为 auto。仅 S3/MinIO 的本地测试可设置 SECURE=false。
+全部 JSON/YAML/XML 字段使用 lowerCamelCase。文件可使用固定值或显式环境引用，不按字段名自动推导环境变量；凭据建议使用 `${NAME}`，不把含秘密的配置提交到仓库。S3 endpoint 为 host[:port]，OSS 可选 endpoint 为 HTTPS origin；R2 从 accountId 派生官方 endpoint，region 为 auto。仅 S3/MinIO 本地测试可设置 `storage.secure: false`。

 错误响应：未授权 401、无 Content-Length 411、超限 413、类型不允许 415、长度不符/非法 key 400、对象不存在 404、存储超时 504，其余内部错误统一隐藏细节。底层签名入口遵循存储协议返回 201/403 等状态，流式传输且访问日志保留实际状态。

--- a/cmd/go-omni/scaffold/templates/modules-config.yaml.tmpl
+++ b/cmd/go-omni/scaffold/templates/modules-config.yaml.tmpl
@@ -1,68 +1,29 @@
-# Non-secret settings only. Environment variables override these values.
+# Only fields listed here override Default(). Environment names are explicit.
 server:
-  address: '127.0.0.1:8080'
-  enableLogger: true
-  slowRequestThreshold: 500ms
-  shutdownTimeout: 10s
-{{if .API}}  lifecycle:
-    stopTimeout: 5s
-    drainTimeout: 10s
-    cancelTimeout: 5s
-  endpoints:
-    liveness:
-      enabled: true
-      path: /health/live
-      responseMode: app
-    readiness:
-      enabled: true
-      path: /health/ready
-      responseMode: app
-    openapi:
-      enabled: true
-      path: /openapi.json
-{{end}}
-  log:
-    service: {{printf "%q" .Module}}
-    level: info
-    format: {{.LogFormat}}
-{{if eq .LogOutput "file"}}    file: './var/log/server.log'
-    rotation:
-      enabled: true
-      maxSizeMb: 100
-      maxBackups: 10
-      maxAgeDays: 7
-      compress: true
-{{else}}    output: {{.LogOutput}}
-{{end}}    redactKeys: []
+  address: "${GO_OMNI_HTTP_ADDR:-127.0.0.1:8080}"
+  transport: "${GO_OMNI_TRANSPORT:-nethttp}"
 {{if ne .Storage "none"}}storage:
-  provider: {{.Storage}}
-  maxBytes: 33554432
-  contentTypes: ['text/plain', 'image/png', 'image/jpeg', 'application/pdf']
-  linkTtl: 5m
-  requestTimeout: 30s
-{{if eq .Storage "local"}}  root: './var/files'
-  publicUrl: 'http://127.0.0.1:8080/storage/object'
-{{else}}  bucket: '' # set GO_OMNI_STORAGE_BUCKET
-  secure: true
-{{if eq .Storage "r2"}}  accountId: '' # set GO_OMNI_STORAGE_ACCOUNT_ID
-  region: auto
-{{else if eq .Storage "s3"}}  endpoint: '' # set GO_OMNI_STORAGE_ENDPOINT (host[:port])
-  region: us-east-1
-{{else}}  region: cn-hangzhou
-  endpoint: '' # empty uses the official regional endpoint
+{{if not .API}}  filesToken: "${GO_OMNI_FILES_TOKEN}"
+{{end}}{{if eq .Storage "local"}}  root: "${GO_OMNI_STORAGE_ROOT:-var/files}"
+  publicUrl: "${GO_OMNI_STORAGE_PUBLIC_URL:-http://127.0.0.1:8080/storage/object}"
+  signingKey: "${GO_OMNI_STORAGE_SIGNING_KEY}"
+{{else}}  bucket: "${GO_OMNI_STORAGE_BUCKET}"
+  accessKey: "${GO_OMNI_STORAGE_ACCESS_KEY}"
+  secretKey: "${GO_OMNI_STORAGE_SECRET_KEY}"
+  sessionToken: "${GO_OMNI_STORAGE_SESSION_TOKEN:-}"
+{{if eq .Storage "r2"}}  accountId: "${GO_OMNI_STORAGE_ACCOUNT_ID}"
+{{else if eq .Storage "s3"}}  endpoint: "${GO_OMNI_STORAGE_ENDPOINT}"
+  region: "${GO_OMNI_STORAGE_REGION:-us-east-1}"
+{{else}}  region: "${GO_OMNI_STORAGE_REGION:-cn-hangzhou}"
 {{end}}{{end}}{{end}}
-
 {{if and .API (eq .Database "mysql")}}database:
-  host: 127.0.0.1
-  port: 3306
-  database: '' # GO_OMNI_DB_DATABASE
-  user: '' # GO_OMNI_DB_USER; password via GO_OMNI_DB_PASSWORD
-  tls:
-    mode: required
-  pool:
-    maxOpenConns: 10
-    maxIdleConns: 5
-    connMaxLifetime: 30m
-    connMaxIdleTime: 5m
-    pingTimeout: 5s
+  host: "${GO_OMNI_DB_HOST:-127.0.0.1}"
+  port: "${GO_OMNI_DB_PORT:-3306}"
+  database: "${GO_OMNI_DB_DATABASE}"
+  user: "${GO_OMNI_DB_USER}"
+  password: "${GO_OMNI_DB_PASSWORD}"
+{{end}}
+{{if and (not .API) (eq .Database "mysql")}}database:
+  driver: mysql
+  dsn: "${GO_OMNI_DB_DSN}"
 {{end}}
--- a/cmd/go-omni/scaffold/templates/modules-main.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/modules-main.go.tmpl
@@ -18,8 +18,10 @@ import (
 )

 func main(){
- path:=flag.String("config","etc/config.yaml","JSON/YAML settings; empty uses defaults and environment")
+ path:=flag.String("config","etc/config.yaml","configuration file; empty uses only Default()")
+ check:=flag.Bool("check-config",false,"validate without starting dependencies")
 flag.Parse()
+ if *check {if _,err:=settings.Load(*path);err!=nil{log.Fatal(err)};return}
 if err:=run(*path);err!=nil{log.Fatal(err)}
 }
 func run(path string)(runErr error){
@@ -31,7 +33,7 @@ func run(path string)(runErr error){
 if err!=nil{return err}
 defer func(){runErr=errors.Join(runErr,logger.Close())}()
 logx.SetDefault(logger)
- services,err:=servicecontext.New(ctx,logger)
+ services,err:=servicecontext.New(ctx,logger,cfg)
 if err!=nil{return err}
 defer func(){runErr=errors.Join(runErr,services.Close())}()
 {{if ne .Storage "none"}}if err=services.InitStorage(ctx,cfg.Storage);err!=nil{return err}{{end}}
--- a/cmd/go-omni/scaffold/templates/modules-settings.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/modules-settings.go.tmpl
@@ -3,21 +3,19 @@ package settings

 import (
 "errors"
- "os"
 "strings"
 "time"
- {{if ne .Storage "none"}}"fmt"
+ {{if ne .Storage "none"}}
 {{if ne .Storage "r2"}}"net/url"{{else}}"regexp"{{end}}
- "strconv"
 "git.yuntuo.hk/k2safe/go-omni/storage"{{end}}
- {{if and .API (eq .Database "mysql")}}"git.yuntuo.hk/k2safe/go-omni/database"{{end}}
+ {{if eq .Database "mysql"}}"git.yuntuo.hk/k2safe/go-omni/database"{{end}}
 "git.yuntuo.hk/k2safe/go-omni/config"
- "git.yuntuo.hk/k2safe/go-omni/logx"
+ {{if eq .LogOutput "file"}}"git.yuntuo.hk/k2safe/go-omni/logx"{{end}}
 )

 type Config struct {
 Server config.Config `json:"server"`
- {{if and .API (eq .Database "mysql")}}Database database.Config `json:"database"`{{end}}
+ {{if eq .Database "mysql"}}Database database.Config `json:"database"`{{end}}
 {{if ne .Storage "none"}}Storage StorageConfig `json:"storage"`{{end}}
 }

@@ -31,7 +29,8 @@ func Default() Config {
 {{if eq .LogOutput "file"}}server.Log.File="./var/log/server.log"
 server.Log.Rotation=logx.RotationConfig{Enabled:true,MaxSizeMB:100,MaxBackups:10,MaxAgeDays:7,Compress:true}
 {{else}}server.Log.Output={{printf "%q" .LogOutput}}{{end}}
- return Config{Server:server{{if and .API (eq .Database "mysql")}},Database:database.DefaultConfig(){{end}}{{if ne .Storage "none"}},Storage:StorageConfig{
+ {{if eq .Database "mysql"}}db:=database.DefaultConfig();db.Driver="mysql"{{end}}
+ return Config{Server:server{{if eq .Database "mysql"}},Database:db{{end}}{{if ne .Storage "none"}},Storage:StorageConfig{
  Provider:{{printf "%q" .Storage}}, Root:"./var/files", PublicURL:"http://127.0.0.1:8080/storage/object",
  Secure:true, MaxBytes:32<<20, ContentTypes:[]string{"text/plain","image/png","image/jpeg","application/pdf"},
  LinkTTL:5*time.Minute, RequestTimeout:30*time.Second,
@@ -41,27 +40,10 @@ func Default() Config {
 }{{end}}}
 }

-// Load uses defaults -> strict YAML/JSON -> nonempty environment variables.
-// Pass an empty path to use only defaults and environment.
-func Load(path string)(Config,error) {
- cfg:=Default()
- var err error
- if path!="" { cfg,err=config.DecodeFile(path,cfg);if err!=nil{return Config{},err} }
- cfg.Server,err=config.ApplyEnv(cfg.Server,"")
- if err!=nil{return Config{},err}
- // A stream explicitly selected by environment overrides a file profile.
- if output:=strings.TrimSpace(os.Getenv("GO_OMNI_LOG_OUTPUT"));output!="" && strings.TrimSpace(os.Getenv("GO_OMNI_LOG_FILE"))=="" {
-  cfg.Server.Log.File="";cfg.Server.Log.Rotation=logx.RotationConfig{}
- }
- {{if ne .Storage "none"}}
- if err=cfg.Storage.applyEnv();err!=nil{return Config{},err}
- {{end}}
- {{if and .API (eq .Database "mysql")}}cfg.Database,err=database.ApplyEnv(cfg.Database,"");if err!=nil{return Config{},err}{{end}}
- if err=cfg.Validate();err!=nil{return Config{},err}
- return cfg,nil
-}
+// Load uses Default(), the selected file's explicit references, and Validate.
+func Load(path string)(Config,error){return config.LoadProject(path,Default())}
 func (c Config) Validate()error {
- {{if and .API (eq .Database "mysql")}}
+ {{if eq .Database "mysql"}}
 if err:=c.Database.Validate();err!=nil{return err}
 if c.Database.Driver!="mysql" || c.Database.MaxOpenConns<1 {return errors.New("database requires driver mysql and a positive maxOpenConns")}
 {{end}}
@@ -85,45 +67,27 @@ type StorageConfig struct {
 ContentTypes []string `json:"contentTypes"`
 LinkTTL time.Duration `json:"linkTtl"`
 RequestTimeout time.Duration `json:"requestTimeout"`
- // Secrets are environment-only and cannot be populated by config files.
- FilesToken string `json:"-"`
- SigningKey string `json:"-"`
- AccessKey string `json:"-"`
- SecretKey string `json:"-"`
- SessionToken string `json:"-"`
+ // Use explicit environment references in the configuration file for secrets.
+ FilesToken string `json:"filesToken"`
+ SigningKey string `json:"signingKey"`
+ AccessKey string `json:"accessKey"`
+ SecretKey string `json:"secretKey"`
+ SessionToken string `json:"sessionToken"`
 }
 func (s StorageConfig) Policy()storage.UploadPolicy{return storage.UploadPolicy{MaxBytes:s.MaxBytes,ContentTypes:s.ContentTypes}}
-func (s *StorageConfig) applyEnv()error {
- values:=map[string]*string{
-  "GO_OMNI_STORAGE_ROOT":&s.Root,"GO_OMNI_STORAGE_PUBLIC_URL":&s.PublicURL,
-  "GO_OMNI_STORAGE_ENDPOINT":&s.Endpoint,"GO_OMNI_STORAGE_REGION":&s.Region,
-  "GO_OMNI_STORAGE_BUCKET":&s.Bucket,"GO_OMNI_STORAGE_ACCOUNT_ID":&s.AccountID,
-  "GO_OMNI_STORAGE_SIGNING_KEY":&s.SigningKey,"GO_OMNI_FILES_TOKEN":&s.FilesToken,
-  "GO_OMNI_STORAGE_ACCESS_KEY":&s.AccessKey,"GO_OMNI_STORAGE_SECRET_KEY":&s.SecretKey,
-  "GO_OMNI_STORAGE_SESSION_TOKEN":&s.SessionToken,
- }
- for name,target:=range values {if value:=strings.TrimSpace(os.Getenv(name));value!=""{*target=value}}
- for name,target:=range map[string]*time.Duration{"GO_OMNI_STORAGE_LINK_TTL":&s.LinkTTL,"GO_OMNI_STORAGE_REQUEST_TIMEOUT":&s.RequestTimeout} {
-  if value:=strings.TrimSpace(os.Getenv(name));value!="" {v,err:=time.ParseDuration(value);if err!=nil{return fmt.Errorf("%s must be a duration",name)};*target=v}
- }
- if value:=os.Getenv("GO_OMNI_STORAGE_MAX_BYTES");value!=""{v,err:=strconv.ParseInt(value,10,64);if err!=nil{return errors.New("GO_OMNI_STORAGE_MAX_BYTES must be an integer")};s.MaxBytes=v}
- if value:=os.Getenv("GO_OMNI_STORAGE_SECURE");value!=""{v,err:=strconv.ParseBool(value);if err!=nil{return errors.New("GO_OMNI_STORAGE_SECURE must be a boolean")};s.Secure=v}
- if value:=strings.TrimSpace(os.Getenv("GO_OMNI_STORAGE_CONTENT_TYPES"));value!="" {s.ContentTypes=strings.Split(value,",");for i:=range s.ContentTypes{s.ContentTypes[i]=strings.TrimSpace(s.ContentTypes[i])}}
- return nil
-}
 func (s StorageConfig) Validate()error {
 if s.Provider!={{printf "%q" .Storage}} {return errors.New("storage.provider must match the adapter selected at generation")}
 if err:=s.Policy().Validate();err!=nil{return err}
 if s.LinkTTL<time.Second || s.LinkTTL>time.Hour{return errors.New("storage.linkTtl must be 1s..1h")}
 if s.RequestTimeout<=0 || s.RequestTimeout>5*time.Minute{return errors.New("storage.requestTimeout must be >0 and <=5m")}
- {{if not .API}}if len(s.FilesToken)<32 || strings.ContainsAny(s.FilesToken," \t\r\n") {return errors.New("set GO_OMNI_FILES_TOKEN to a token of at least 32 bytes without whitespace")}{{end}}
+ {{if not .API}}if len(s.FilesToken)<32 || strings.ContainsAny(s.FilesToken," \t\r\n") {return errors.New("storage.filesToken requires at least 32 bytes without whitespace")}{{end}}
 {{if eq .Storage "local"}}
 if s.Root=="" {return errors.New("storage.root is required")}
 u,err:=url.Parse(s.PublicURL)
 if err!=nil || u.Host=="" || u.Hostname()=="" || (u.Scheme!="http" && u.Scheme!="https") || u.User!=nil || u.RawQuery!="" || u.Fragment!="" || u.Path!="/storage/object" {return errors.New("storage.publicUrl must be an absolute HTTP(S) URL ending in /storage/object")}
- if len(s.SigningKey)<32 {return errors.New("set GO_OMNI_STORAGE_SIGNING_KEY to a stable secret of at least 32 bytes")}
+ if len(s.SigningKey)<32 {return errors.New("storage.signingKey requires a stable secret of at least 32 bytes")}
 {{else}}
- if s.Bucket=="" || s.Region=="" || s.AccessKey=="" || s.SecretKey=="" {return errors.New("storage bucket, region and GO_OMNI_STORAGE_ACCESS_KEY/SECRET_KEY are required")}
+ if s.Bucket=="" || s.Region=="" || s.AccessKey=="" || s.SecretKey=="" {return errors.New("storage bucket, region, accessKey and secretKey are required")}
 {{if eq .Storage "r2"}}
 if !regexp.MustCompile(`^[a-fA-F0-9]{32}$`).MatchString(s.AccountID) || s.Region!="auto" || !s.Secure {return errors.New("R2 requires a 32-hex accountId, region auto and secure=true")}
 if s.Endpoint!=""{return errors.New("this R2 profile derives endpoint from accountId; customize servicecontext for a jurisdiction-specific endpoint")}
--- a/cmd/go-omni/scaffold/templates/modules-settings_test.go.tmpl
+++ b/cmd/go-omni/scaffold/templates/modules-settings_test.go.tmpl
@@ -21,18 +21,18 @@ func environment(t *testing.T){
 }
 func TestSettingsPrecedenceAndStrictness(t *testing.T){
 environment(t)
+ {{if eq .Database "mysql"}}t.Setenv("GO_OMNI_DB_DSN","test:secret@tcp(localhost)/demo"){{end}}
+ source,err:=os.ReadFile("../../etc/config.yaml");if err!=nil{t.Fatal(err)}
 path:=filepath.Join(t.TempDir(),"config.yaml")
- if err:=os.WriteFile(path,[]byte("server:\n  address: '127.0.0.1:8123'\n  log:\n    level: debug\n"),0600);err!=nil{t.Fatal(err)}
+ source=[]byte(strings.Replace(string(source),"${GO_OMNI_HTTP_ADDR:-127.0.0.1:8080}","127.0.0.1:8123",1))
+ if err=os.WriteFile(path,source,0600);err!=nil{t.Fatal(err)}
 t.Setenv("GO_OMNI_HTTP_ADDR","127.0.0.1:9123")
 t.Setenv("GO_OMNI_LOG_OUTPUT","stdout")
 cfg,err:=Load(path);if err!=nil{t.Fatal(err)}
- if cfg.Server.Address!="127.0.0.1:9123" || cfg.Server.Log.Level!="debug" || cfg.Server.Log.Output!="stdout" || cfg.Server.Log.File!="" || cfg.Server.Log.Rotation.Enabled {t.Fatal("configuration precedence failed")}
- for _,body:=range []string{"unexpected: true","server:\n  slowRequestThreshold: -1s","server:\n  log:\n    format: invalid"{{if ne .Storage "none"}},"storage:\n  filesToken: forbidden","storage:\n  maxBytes: -1","storage:\n  provider: unsupported"{{end}}}{
-  if err:=os.WriteFile(path,[]byte(body),0600);err!=nil{t.Fatal(err)}
-  if _,err:=Load(path);err==nil{t.Fatal("invalid configuration accepted")}
+ initial:=Default()
+ if cfg.Server.Address!="127.0.0.1:8123"||cfg.Server.Log.Output!=initial.Server.Log.Output||cfg.Server.Log.File!=initial.Server.Log.File {t.Fatal("implicit overwrite")}
+ for _,body:=range []string{"unexpected: true","server:\n  slowRequestThreshold: -1s","server:\n  log:\n    format: invalid"}{
+  if err=os.WriteFile(path,[]byte(body),0600);err!=nil{t.Fatal(err)}
+  if _,err=Load(path);err==nil{t.Fatal("invalid configuration accepted")}
 }
- {{if ne .Storage "none"}}
- t.Setenv("GO_OMNI_FILES_TOKEN","")
- if _,err:=Load("");err==nil{t.Fatal("missing file token accepted")}
- {{end}}
 }
--- a/cmd/go-omni/scaffold/version.go
+++ b/cmd/go-omni/scaffold/version.go
@@ -10,11 +10,11 @@ const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
 // Source builds can carry an unpublished VCS version (including +dirty).
 // Keep this fallback in sync with the next release; installed CLIs use their
 // downloaded module version, which also has a module checksum.
-const defaultFrameworkVersion = "v0.21.0-preview"
+const defaultFrameworkVersion = "v0.22.0-preview"

 // This target is not a claim that the release already exists. Source users
 // select a local framework checkout until the module templates are published.
-const modulesFrameworkVersion = "v0.7.0-preview"
+const modulesFrameworkVersion = "v0.22.0-preview"

 func installedFrameworkVersion() string {
 	info, _ := debug.ReadBuildInfo()