huang
45aa7deb87
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m33s
主要改动： - 新增交互式环境配置脚本 (scripts/setup-env.sh) - 新增本地启动快捷脚本 (scripts/run-local.sh) - 新增环境变量模板文件 (.env.example) - 部署模式改版：使用嵌入式配置 + 环境变量覆盖 - 添加对象存储功能支持 - 改进 IoT 卡片导入任务 - 优化 OpenAPI 文档生成 - 删除旧的配置文件，改用嵌入式默认配置
134 lines
3.6 KiB
Markdown
134 lines
3.6 KiB
Markdown
# embedded-config Specification
|
||
|
||
## Purpose
|
||
TBD - created by archiving change deployment-self-init. Update Purpose after archive.
|
||
## Requirements
|
||
### Requirement: 配置嵌入
|
||
|
||
系统 SHALL 使用 Go 的 `go:embed` 指令将默认配置文件嵌入二进制文件。
|
||
|
||
嵌入文件位置：`pkg/config/defaults/config.yaml`
|
||
|
||
#### Scenario: 加载嵌入配置
|
||
|
||
- **WHEN** 调用 `config.Load()`
|
||
- **THEN** 系统从嵌入的 `defaults/config.yaml` 读取默认配置
|
||
- **AND** 无需外部配置文件即可启动
|
||
|
||
#### Scenario: 嵌入配置包含完整结构
|
||
|
||
- **WHEN** 读取嵌入配置
|
||
- **THEN** 配置包含所有配置节：server、database、redis、storage、logging、queue、jwt、middleware
|
||
|
||
### Requirement: 环境变量覆盖
|
||
|
||
系统 SHALL 支持通过环境变量覆盖嵌入的默认配置值。
|
||
|
||
环境变量格式：`JUNHONG_{SECTION}_{KEY}`
|
||
|
||
#### Scenario: 环境变量覆盖配置
|
||
|
||
- **WHEN** 设置环境变量 `JUNHONG_DATABASE_HOST=myhost`
|
||
- **THEN** `config.Database.Host` 的值为 "myhost"
|
||
- **AND** 覆盖嵌入配置中的默认值
|
||
|
||
#### Scenario: 嵌套配置覆盖
|
||
|
||
- **WHEN** 设置环境变量 `JUNHONG_LOGGING_LEVEL=debug`
|
||
- **THEN** `config.Logging.Level` 的值为 "debug"
|
||
|
||
#### Scenario: 未设置环境变量
|
||
|
||
- **WHEN** 未设置某个配置的环境变量
|
||
- **THEN** 使用嵌入配置中的默认值
|
||
|
||
### Requirement: 配置优先级
|
||
|
||
系统 SHALL 按以下优先级应用配置（高到低）：
|
||
|
||
1. 环境变量 (JUNHONG_*)
|
||
2. 嵌入默认值 (go:embed)
|
||
|
||
#### Scenario: 优先级验证
|
||
|
||
- **WHEN** 嵌入配置中 `server.address` 为 ":3000"
|
||
- **AND** 设置环境变量 `JUNHONG_SERVER_ADDRESS=:8080`
|
||
- **THEN** 最终 `config.Server.Address` 为 ":8080"
|
||
|
||
### Requirement: 必填配置验证
|
||
|
||
系统 SHALL 在加载配置后验证必填配置项是否已设置。
|
||
|
||
必填配置项：
|
||
- `database.host`
|
||
- `database.user`
|
||
- `database.password`
|
||
- `database.dbname`
|
||
- `redis.address`
|
||
- `jwt.secret_key`
|
||
|
||
#### Scenario: 必填配置缺失
|
||
|
||
- **WHEN** 必填配置项为空且未通过环境变量设置
|
||
- **THEN** `config.Load()` 返回错误
|
||
- **AND** 错误信息明确指出缺失的配置项和对应的环境变量名
|
||
|
||
#### Scenario: 必填配置通过环境变量提供
|
||
|
||
- **WHEN** 所有必填配置通过环境变量设置
|
||
- **THEN** `config.Load()` 成功返回配置
|
||
|
||
### Requirement: 删除外部配置文件支持
|
||
|
||
系统 SHALL 移除对外部配置文件的支持。
|
||
|
||
#### Scenario: 不读取 configs 目录
|
||
|
||
- **WHEN** 应用启动
|
||
- **THEN** 不读取 `configs/*.yaml` 文件
|
||
- **AND** 不依赖 `CONFIG_PATH` 或 `CONFIG_ENV` 环境变量
|
||
|
||
### Requirement: 删除配置热重载
|
||
|
||
系统 SHALL 移除配置热重载功能。
|
||
|
||
#### Scenario: 不监听配置文件变化
|
||
|
||
- **WHEN** 应用运行中
|
||
- **THEN** 不使用 fsnotify 监听文件变化
|
||
- **AND** 删除 `pkg/config/watcher.go`
|
||
|
||
#### Scenario: 配置变更需重启
|
||
|
||
- **WHEN** 需要更改配置
|
||
- **THEN** 必须重启应用使新配置生效
|
||
|
||
### Requirement: 环境变量前缀
|
||
|
||
系统 SHALL 使用 `JUNHONG_` 作为环境变量前缀。
|
||
|
||
#### Scenario: 前缀隔离
|
||
|
||
- **WHEN** 存在环境变量 `DATABASE_HOST=other`
|
||
- **AND** 存在环境变量 `JUNHONG_DATABASE_HOST=correct`
|
||
- **THEN** `config.Database.Host` 为 "correct"
|
||
- **AND** 忽略无前缀的 `DATABASE_HOST`
|
||
|
||
### Requirement: 敏感配置处理
|
||
|
||
系统 SHALL 确保敏感配置不嵌入二进制文件。
|
||
|
||
敏感配置项（嵌入值为空）：
|
||
- `database.password`
|
||
- `redis.password`
|
||
- `jwt.secret_key`
|
||
- `storage.s3.access_key_id`
|
||
- `storage.s3.secret_access_key`
|
||
|
||
#### Scenario: 敏感配置默认为空
|
||
|
||
- **WHEN** 读取嵌入配置
|
||
- **THEN** 敏感配置项的值为空字符串
|
||
- **AND** 必须通过环境变量提供实际值
|
||
|