3.5 KiB
3.5 KiB
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 应保持职责单一：
只负责配置初始化与安全修改，不承担业务逻辑或编排职责。
控制范围，才能保证安全与稳定。