nav/AbstractWizard

Fork 0

Files

hzhang 72843442ac init

2026-02-15 08:49:27 +00:00

6.3 KiB

Raw Blame History

Abstract Wizard

English | 中文

English

Secure configuration file management service. Read, modify, and version-control JSON/YAML config files via REST API. Listens on localhost only — access remotely via SSH tunnel.

Quick Start

Docker Compose (Recommended)

docker compose up -d

The service listens on 127.0.0.1:18080.

Run Locally

go build -o abstract-wizard .
CONFIG_DIR=./configs ./abstract-wizard

Environment Variables

Variable	Default	Description
`CONFIG_DIR`	`/config`	Base directory for config files
`LISTEN_ADDR`	`127.0.0.1:8080`	HTTP listen address
`MAX_BACKUPS`	`10`	Max backup versions per file

API

Health Check

curl http://127.0.0.1:18080/health

Read Config

curl http://127.0.0.1:18080/api/v1/config/app.json

Full Replace

curl -X PUT http://127.0.0.1:18080/api/v1/config/app.json \
  -d '{"database": {"host": "localhost", "port": 5432}}'

A backup is created automatically before each write. The response includes backup_version.

Partial Update (Deep Merge)

curl -X PATCH http://127.0.0.1:18080/api/v1/config/app.json \
  -d '{"database": {"port": 3306}}'

Only the specified fields are updated; nested objects are merged recursively.

List Backups

curl http://127.0.0.1:18080/api/v1/backups/app.json

Rollback

# Get the version from the backup list, then:
curl -X POST http://127.0.0.1:18080/api/v1/rollback/app.json \
  -d '{"version": "20260215T120000Z"}'

Mode Switching

Get current mode:

curl http://127.0.0.1:18080/api/v1/mode

Switch to readonly (rejects all writes):

curl -X PUT http://127.0.0.1:18080/api/v1/mode \
  -d '{"mode": "readonly"}'

Switch back to init (read/write):

curl -X PUT http://127.0.0.1:18080/api/v1/mode \
  -d '{"mode": "init"}'

YAML Support

All endpoints support both JSON and YAML. The format is detected by file extension:

curl -X PUT http://127.0.0.1:18080/api/v1/config/app.yaml \
  -H "Content-Type: text/yaml" \
  -d '
database:
  host: localhost
  port: 5432
'

Security Model

The service binds to 127.0.0.1 by default and is not exposed externally. Use an SSH tunnel for remote access:

ssh -L 18080:127.0.0.1:18080 user@server

Then access via http://127.0.0.1:18080 locally.

Project Structure

├── main.go              # Entry point, env config, graceful shutdown
├── config/
│   ├── validation.go    # Path validation, traversal prevention
│   ├── parser.go        # JSON/YAML parse, serialize, deep merge
│   ├── atomic.go        # Atomic write (temp → fsync → rename)
│   └── backup.go        # Timestamped backups, pruning, rollback
├── audit/
│   └── logger.go        # Structured JSON audit log
├── server/
│   ├── server.go        # HTTP server, routing, mode state machine
│   ├── middleware.go     # Request logging middleware
│   └── handlers.go      # API handlers
├── Dockerfile           # Multi-stage build
└── docker-compose.yaml  # Example deployment

中文

安全的配置文件管理服务。通过 REST API 对 JSON/YAML 配置文件进行读取、修改和版本管理，仅监听 localhost，通过 SSH 隧道访问。

快速开始

Docker Compose（推荐）

docker compose up -d

服务启动后监听 127.0.0.1:18080。

本地运行

go build -o abstract-wizard .
CONFIG_DIR=./configs ./abstract-wizard

环境变量

变量	默认值	说明
`CONFIG_DIR`	`/config`	配置文件存放目录
`LISTEN_ADDR`	`127.0.0.1:8080`	监听地址
`MAX_BACKUPS`	`10`	每个文件保留的最大备份数

API

健康检查

curl http://127.0.0.1:18080/health

读取配置

curl http://127.0.0.1:18080/api/v1/config/app.json

完整替换配置

curl -X PUT http://127.0.0.1:18080/api/v1/config/app.json \
  -d '{"database": {"host": "localhost", "port": 5432}}'

写入前会自动创建备份，响应中包含 backup_version。

局部更新（深度合并）

curl -X PATCH http://127.0.0.1:18080/api/v1/config/app.json \
  -d '{"database": {"port": 3306}}'

仅更新指定字段，嵌套对象递归合并。

查看备份列表

curl http://127.0.0.1:18080/api/v1/backups/app.json

回滚到指定版本

# 先从备份列表获取版本号，然后：
curl -X POST http://127.0.0.1:18080/api/v1/rollback/app.json \
  -d '{"version": "20260215T120000Z"}'

模式切换

查看当前模式：

curl http://127.0.0.1:18080/api/v1/mode

切换为只读模式（拒绝所有写操作）：

curl -X PUT http://127.0.0.1:18080/api/v1/mode \
  -d '{"mode": "readonly"}'

切换回初始化模式（允许读写）：

curl -X PUT http://127.0.0.1:18080/api/v1/mode \
  -d '{"mode": "init"}'

YAML 支持

所有端点同时支持 JSON 和 YAML，格式由文件扩展名自动判断：

curl -X PUT http://127.0.0.1:18080/api/v1/config/app.yaml \
  -H "Content-Type: text/yaml" \
  -d '
database:
  host: localhost
  port: 5432
'

安全模型

服务默认仅监听 127.0.0.1，不暴露到外部网络。远程访问通过 SSH 隧道实现：

ssh -L 18080:127.0.0.1:18080 user@server

之后本地即可通过 http://127.0.0.1:18080 访问。

项目结构

├── main.go              # 入口：环境变量、初始化、优雅关闭
├── config/
│   ├── validation.go    # 路径校验，防止目录穿越
│   ├── parser.go        # JSON/YAML 解析、序列化、深度合并
│   ├── atomic.go        # 原子写入（temp → fsync → rename）
│   └── backup.go        # 时间戳备份、清理、回滚
├── audit/
│   └── logger.go        # 结构化 JSON 审计日志
├── server/
│   ├── server.go        # HTTP 服务、路由、模式状态机
│   ├── middleware.go     # 请求日志中间件
│   └── handlers.go      # API 处理函数
├── Dockerfile           # 多阶段构建
└── docker-compose.yaml  # 示例部署配置

6.3 KiB Raw Blame History Unescape Escape