203 lines
3.5 KiB
Markdown
203 lines
3.5 KiB
Markdown
# Abstract Wizard 开发计划
|
||
|
||
## 一、项目定位
|
||
|
||
Abstract Wizard 是一个面向通用 Web 应用的初始化与配置管理服务。
|
||
|
||
该服务以独立容器形式运行，通过受限 API 修改挂载卷中的配置文件（支持 JSON、YAML 等格式），并仅通过 SSH 隧道访问，不对公网开放。
|
||
|
||
目标是提供：
|
||
|
||
* 安全的初始化机制
|
||
* 可审计的配置变更能力
|
||
* 与现有 Web 应用解耦的配置管理方案
|
||
* 最小暴露面与最小权限原则
|
||
|
||
---
|
||
|
||
## 二、整体架构设计
|
||
|
||
### 1. 部署方式
|
||
|
||
* 使用 Go 实现
|
||
* 独立容器运行
|
||
* 与目标 Web 应用处于同一个 docker-compose 网络
|
||
* 共享配置卷（volume）
|
||
* 仅绑定宿主机 127.0.0.1
|
||
* 通过 ssh -L 进行访问
|
||
|
||
### 2. 核心组件
|
||
|
||
* HTTP API 服务层
|
||
* Token 鉴权中间件
|
||
* 配置解析与序列化模块
|
||
* 配置校验模块
|
||
* 原子写入模块
|
||
* 审计日志模块
|
||
|
||
---
|
||
|
||
## 三、功能需求
|
||
|
||
### 1. 配置读取
|
||
|
||
* 支持读取指定配置文件
|
||
* 自动识别 JSON / YAML
|
||
* 返回结构化数据
|
||
|
||
### 2. 配置修改
|
||
|
||
* 提供结构化更新接口
|
||
* 支持完整替换与局部更新
|
||
* 写入前进行语法校验
|
||
* 支持可选 Schema 校验
|
||
|
||
### 3. 原子写入机制
|
||
|
||
* 使用临时文件写入
|
||
* 成功后 rename 覆盖原文件
|
||
* 防止中途写入导致文件损坏
|
||
|
||
### 4. 版本备份
|
||
|
||
* 每次修改自动生成备份
|
||
* 保留最近 N 个版本
|
||
* 支持回滚
|
||
|
||
### 5. 初始化模式控制
|
||
|
||
* 默认启用初始化模式
|
||
* 初始化完成后可关闭写入功能
|
||
* 可切换为只读模式
|
||
|
||
---
|
||
|
||
## 四、安全设计
|
||
|
||
### 1. 网络隔离
|
||
|
||
* 端口仅绑定 127.0.0.1
|
||
* 不开放公网端口
|
||
* 不信任 X-Forwarded-For
|
||
|
||
### 2. 鉴权机制
|
||
|
||
* 必须提供 INIT_TOKEN
|
||
* 使用 Bearer Token 方式
|
||
* 不允许匿名访问
|
||
|
||
### 3. 容器安全
|
||
|
||
* 使用非 root 用户运行
|
||
* 不挂载 docker.sock
|
||
* 仅对配置卷开放写权限
|
||
* 其余文件系统只读
|
||
|
||
### 4. 审计日志
|
||
|
||
* 记录修改时间
|
||
* 记录修改来源 IP
|
||
* 记录变更内容摘要
|
||
|
||
---
|
||
|
||
## 五、非功能性要求
|
||
|
||
* 二进制体积尽量小
|
||
* 内存占用低
|
||
* 响应延迟可控
|
||
* 日志结构化输出
|
||
* 可通过环境变量配置
|
||
|
||
---
|
||
|
||
## 六、开发阶段划分
|
||
|
||
### 阶段一：基础框架
|
||
|
||
* 项目结构搭建
|
||
* HTTP 服务启动
|
||
* Token 中间件实现
|
||
* 配置读取接口
|
||
|
||
交付结果：只读配置服务
|
||
|
||
---
|
||
|
||
### 阶段二：写入能力
|
||
|
||
* 原子写入实现
|
||
* JSON / YAML 校验
|
||
* 备份机制实现
|
||
* 日志记录
|
||
|
||
交付结果：安全可写配置服务
|
||
|
||
---
|
||
|
||
### 阶段三：安全强化
|
||
|
||
* 初始化模式开关
|
||
* 只读模式
|
||
* 输入参数严格校验
|
||
* 错误处理完善
|
||
|
||
交付结果：生产可用版本
|
||
|
||
---
|
||
|
||
### 阶段四：容器化优化
|
||
|
||
* Multi-stage 构建
|
||
* 使用 distroless 或 scratch
|
||
* 非 root 运行
|
||
* docker-compose 集成测试
|
||
|
||
交付结果：可部署镜像
|
||
|
||
---
|
||
|
||
### 阶段五：扩展能力
|
||
|
||
* CLI 客户端
|
||
* Web 管理界面（可选）
|
||
* Git 版本控制集成
|
||
* 多应用支持
|
||
|
||
---
|
||
|
||
## 七、Compose 示例结构
|
||
|
||
* webapp
|
||
* database
|
||
* abstract-wizard
|
||
* 共享 volume：app_config
|
||
* 端口绑定：127.0.0.1:18080:8080
|
||
|
||
---
|
||
|
||
## 八、风险评估
|
||
|
||
* 配置误写风险 → Schema 校验
|
||
* 文件损坏风险 → 原子写入
|
||
* 未授权访问 → Token + 本地绑定
|
||
* 忘记关闭初始化接口 → 强制初始化状态机
|
||
|
||
---
|
||
|
||
## 九、成功标准
|
||
|
||
* 初始化流程可控
|
||
* 配置变更可追溯
|
||
* 不暴露公网攻击面
|
||
* 容器体积可控
|
||
* 与业务系统解耦
|
||
|
||
---
|
||
|
||
Abstract Wizard 应保持职责单一：
|
||
|
||
只负责配置初始化与安全修改，不承担业务逻辑或编排职责。
|
||
|
||
控制范围，才能保证安全与稳定。
|