x
This commit is contained in:
202
proj_plan.md
202
proj_plan.md
@@ -1,202 +0,0 @@
|
||||
# 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 应保持职责单一：
|
||||
|
||||
只负责配置初始化与安全修改，不承担业务逻辑或编排职责。
|
||||
|
||||
控制范围，才能保证安全与稳定。
|
||||
Reference in New Issue
Block a user