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