---
name: edge-config-lifecycle
description: edge_collector 配置生命周期管理规范。用于新增、修改、打包、同步、动态生成或排除配置文件时，明确默认配置、运行态配置、用户保存配置、密钥配置、迁移保留、备份恢复和前端保存行为，防止覆盖现场配置。
---

# edge_collector 配置生命周期

## 适用配置

- 边缘运行配置：`runtime/edge/config/`
- 云端运行配置：`~/cloud_server/config/`
- AI 配置：`ai_config.json`
- 端口转发：`port_forward.json`
- frpc/内网穿透配置。
- 协议设备配置。
- WiFi/4G 辅助配置。
- 默认模板：`configurator/config/templates/`
- 用户可见协议描述：`configurator/config/protocols/`

## 配置分类

### 默认配置

随代码发布，提供初始结构和默认值。

### 运行态配置

目标主机运行后由用户、前端或服务生成。打包和同步不能覆盖。

### 密钥配置

包含 key、secret、password、token。必须脱敏、禁止提交真实值。

### 模板配置

协议模板、默认点位、用户可选参数。可随版本更新，但要考虑兼容已有设备。

## 新增配置文件检查

新增配置时必须回答：

- 默认文件放在哪里。
- 运行态文件放在哪里。
- 如果文件不存在，谁负责动态生成。
- 打包是否包含。
- 同步是否排除。
- 前端保存是否会覆盖其他字段。
- 是否包含密钥。
- 是否需要备份和迁移。

## 打包与同步

修改以下脚本时必须检查配置影响：

- `package.sh`
- `scripts/migrate_edge.sh`
- `deploy_cloud.sh`
- `scripts/install_all.sh`

原则：

- 默认配置可以进入包。
- 运行态配置不能被 `--delete` 同步清掉。
- 远端已有密钥配置必须保留。
- 删除配置文件前必须确认是否会自动再生成。

## 前端保存

- 保存配置时只更新相关字段。
- 不要用空对象覆盖整个配置文件。
- 保存失败要显示具体原因。
- 权限不足要按已有权限体系处理。

## 验证

至少验证：

```bash
jq empty <config.json>
```

同步/部署后验证：

- 目标主机已有配置仍存在。
- 新增默认配置可生成。
- 服务重启后能读取配置。
- 前端读取和保存正常。

## 风险信号

- `rsync --delete`
- `cp -r config`
- `cat > config.json`
- 前端保存整个 JSON。
- 后端启动时无条件重写配置。
- 示例配置中出现真实 key。