From 0c4a1a4d3f7e359ea51bb4bb1d12d274de84d8cf Mon Sep 17 00:00:00 2001 From: hzhang Date: Sun, 15 Feb 2026 08:51:58 +0000 Subject: [PATCH] x --- proj_plan.md | 202 --------------------------------------------------- 1 file changed, 202 deletions(-) delete mode 100644 proj_plan.md diff --git a/proj_plan.md b/proj_plan.md deleted file mode 100644 index 664cafc..0000000 --- a/proj_plan.md +++ /dev/null @@ -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 应保持职责单一： - -只负责配置初始化与安全修改，不承担业务逻辑或编排职责。 - -控制范围，才能保证安全与稳定。