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 文档生成 - 删除旧的配置文件，改用嵌入式默认配置
105 lines
3.9 KiB
Markdown
105 lines
3.9 KiB
Markdown
# 提案：部署自初始化
|
||
|
||
## Why
|
||
|
||
当前应用部署需要手动创建目录结构、拷贝配置文件，过程繁琐且容易出错。临时目录创建逻辑分散在各组件中，非 root 用户可能因权限问题导致启动失败。配置文件必须外部提供，无法实现"开箱即用"的部署体验。
|
||
|
||
本变更旨在实现**应用自初始化**，让应用启动时自动创建所需目录、使用嵌入的默认配置，大幅简化部署流程。
|
||
|
||
## What Changes
|
||
|
||
### 1. 集中化目录初始化
|
||
- 新增 `pkg/bootstrap/directories.go`，在应用启动时统一创建所有必需目录
|
||
- 移除各组件（如 `s3.go`）中分散的目录创建逻辑
|
||
- 提供降级策略：权限不足时自动使用备用路径
|
||
|
||
### 2. 配置嵌入机制
|
||
- 使用 `go:embed` 将默认配置嵌入二进制文件
|
||
- 配置优先级：**环境变量 > 嵌入默认值**（移除外部配置文件依赖）
|
||
- 敏感配置（数据库密码等）通过环境变量提供
|
||
- **移除** configs/ 目录和配置文件热重载机制（开发阶段不需要）
|
||
|
||
### 3. Docker 部署简化
|
||
- Dockerfile 预创建关键目录并设置正确权限
|
||
- **移除** configs 目录挂载，全部使用环境变量
|
||
- docker-compose 只挂载日志目录（持久化需求）
|
||
|
||
### 4. 环境变量规范化
|
||
- 统一环境变量前缀：`JUNHONG_`
|
||
- 支持嵌套配置：`JUNHONG_DATABASE_HOST`、`JUNHONG_REDIS_ADDRESS`
|
||
- 配置验证：必填配置未设置时启动失败并给出明确提示
|
||
|
||
### 5. 清理冗余
|
||
- **删除** `pkg/config/watcher.go`（配置热重载）
|
||
- **删除** `configs/*.yaml` 外部配置文件
|
||
- **删除** docker-compose 中的 configs 卷挂载
|
||
- **简化** `pkg/config/loader.go`
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `bootstrap-init`: 应用启动时的集中化初始化机制，包括目录创建、配置加载、验证等
|
||
- `embedded-config`: 配置嵌入机制，使用 go:embed + 环境变量覆盖，无需外部配置文件
|
||
|
||
### Modified Capabilities
|
||
|
||
- `dependency-injection`: 调整 bootstrap 流程，在组件初始化前完成目录和配置的准备
|
||
|
||
## Impact
|
||
|
||
### 代码变更
|
||
|
||
| 文件/目录 | 变更类型 | 说明 |
|
||
|-----------|----------|------|
|
||
| `pkg/bootstrap/directories.go` | 新增 | 目录初始化逻辑 |
|
||
| `pkg/config/embedded.go` | 新增 | 配置嵌入和加载逻辑 |
|
||
| `pkg/config/defaults/config.yaml` | 新增 | 嵌入的默认配置文件 |
|
||
| `pkg/config/loader.go` | 重写 | 简化为嵌入配置 + 环境变量 |
|
||
| `pkg/config/watcher.go` | **删除** | 不再需要热重载 |
|
||
| `pkg/storage/s3.go` | 修改 | 移除目录创建逻辑 |
|
||
| `cmd/api/main.go` | 修改 | 调用目录初始化 |
|
||
| `cmd/worker/main.go` | 修改 | 调用目录初始化 |
|
||
| `internal/bootstrap/` | 修改 | 调整初始化顺序 |
|
||
| `configs/*.yaml` | **删除** | 配置嵌入后不再需要 |
|
||
|
||
### Docker 变更
|
||
|
||
| 文件 | 变更类型 | 说明 |
|
||
|------|----------|------|
|
||
| `Dockerfile.api` | 修改 | 预创建目录、删除 COPY configs |
|
||
| `Dockerfile.worker` | 修改 | 预创建目录、删除 COPY configs |
|
||
| `docker-compose.prod.yml` | 重写 | 纯环境变量配置、删除 configs 挂载 |
|
||
| `docker/entrypoint-api.sh` | 简化 | 只保留迁移逻辑 |
|
||
|
||
### 部署流程变更
|
||
|
||
**变更前**（5 步）：
|
||
```bash
|
||
# 1. SSH 到服务器
|
||
# 2. 创建目录 mkdir -p /opt/junhong_cmp/{configs,logs}
|
||
# 3. 复制 docker-compose.prod.yml
|
||
# 4. 复制配置文件到 configs/
|
||
# 5. docker-compose up -d
|
||
```
|
||
|
||
**变更后**（1 步）：
|
||
```bash
|
||
# docker-compose up -d（CI/CD 自动部署，或手动拉取 compose 文件）
|
||
```
|
||
|
||
### 依赖
|
||
|
||
- Go 1.16+（`go:embed` 支持）
|
||
- 无新增外部依赖
|
||
|
||
## 预期收益
|
||
|
||
| 指标 | 变更前 | 变更后 |
|
||
|------|--------|--------|
|
||
| 首次部署步骤 | 5 步 | 1 步 |
|
||
| 配置文件 | 4 个外部文件 | 0 个（嵌入） |
|
||
| 权限失败风险 | 高 | 低（降级策略） |
|
||
| 环境可移植性 | Docker only | Docker/K8s/裸机 |
|
||
| 配置热重载 | 支持 | 移除（开发阶段不需要） |
|