junhong_cmp_fiber/openspec/changes/archive/2026-01-26-deployment-self-init/tasks.md

实施任务清单

1. 配置嵌入模块

• 1.1 创建 pkg/config/defaults/config.yaml 嵌入配置文件
• 1.2 创建 pkg/config/embedded.go，实现 go:embed 加载逻辑
• 1.3 重写 pkg/config/loader.go，使用嵌入配置 + 环境变量覆盖
• 1.4 更新 pkg/config/config.go 中的 Validate() 方法，添加必填配置验证
• 1.5 删除 pkg/config/watcher.go 配置热重载模块
• 1.6 编写配置加载单元测试

2. 目录初始化模块

• 2.1 创建 pkg/bootstrap/directories.go，实现 EnsureDirectories() 函数
• 2.2 实现权限降级策略（权限不足时使用临时目录）
• 2.3 编写目录初始化单元测试
• 2.4 移除 pkg/storage/s3.go 中的目录创建逻辑

3. 应用入口改造

• 3.1 更新 cmd/api/main.go，在配置加载后调用 bootstrap.EnsureDirectories()
• 3.2 更新 cmd/worker/main.go，同样调用目录初始化
• 3.3 调整 internal/bootstrap/ 中的初始化顺序（无需修改，顺序正确）

4. Docker 配置更新

• 4.1 更新 Dockerfile.api：预创建目录、移除 COPY configs
• 4.2 更新 Dockerfile.worker：预创建目录、移除 COPY configs
• 4.3 重写 docker-compose.prod.yml：纯环境变量配置
• 4.4 简化 docker/entrypoint-api.sh：移除配置相关逻辑

5. 清理旧文件

• 5.1 删除 configs/config.yaml
• 5.2 删除 configs/config.dev.yaml
• 5.3 删除 configs/config.staging.yaml
• 5.4 删除 configs/config.prod.yaml
• 5.5 删除 configs/ 目录（如果为空）

6. 文档更新

• 6.1 更新 README.md 部署说明
• 6.2 更新环境变量列表文档（创建 docs/environment-variables.md）
• 6.3 更新关键文档（auth-usage-guide, object-storage, add-default-admin-init）

7. 验证

• 7.1 本地运行测试：go test ./...（config 和 bootstrap 测试通过）
• 7.2 本地 Docker 构建测试（API 和 Worker 镜像构建成功）
• 7.3 本地 docker-compose 启动测试（需要外部 PostgreSQL/Redis，配置验证通过）
• 7.4 验证环境变量覆盖功能（TestLoad_EnvOverride 通过）

---

实施完成总结

完成日期: 2026-01-24

主要变更

1. 配置嵌入机制

   • 默认配置嵌入二进制文件 (pkg/config/defaults/config.yaml)
   • 环境变量覆盖使用 JUNHONG_ 前缀
   • 移除配置热重载功能

2. 目录自动初始化

   • pkg/bootstrap/directories.go 实现 EnsureDirectories()
   • 支持权限降级（无权限时使用临时目录）

3. Docker 部署简化

   • 移除 COPY configs 指令
   • 纯环境变量配置
   • 更新 docker-compose.prod.yml 和 entrypoint-api.sh

4. 文档更新

   • 创建 docs/environment-variables.md 完整环境变量文档
   • 更新 README.md 部署说明
   • 更新相关功能文档

后续工作（可选）

• 更新剩余的旧文档（rate-limiting.md, deployment-guide.md 等）