288 lines
6.3 KiB
Markdown
288 lines
6.3 KiB
Markdown
# Abstract Wizard
|
||
|
||
[English](#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)
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
The service listens on `127.0.0.1:18080`.
|
||
|
||
#### Run Locally
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18080/health
|
||
```
|
||
|
||
#### Read Config
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18080/api/v1/config/app.json
|
||
```
|
||
|
||
#### Full Replace
|
||
|
||
```bash
|
||
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)
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18080/api/v1/backups/app.json
|
||
```
|
||
|
||
#### Rollback
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18080/api/v1/mode
|
||
```
|
||
|
||
Switch to readonly (rejects all writes):
|
||
|
||
```bash
|
||
curl -X PUT http://127.0.0.1:18080/api/v1/mode \
|
||
-d '{"mode": "readonly"}'
|
||
```
|
||
|
||
Switch back to init (read/write):
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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（推荐）
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
服务启动后监听 `127.0.0.1:18080`。
|
||
|
||
#### 本地运行
|
||
|
||
```bash
|
||
go build -o abstract-wizard .
|
||
CONFIG_DIR=./configs ./abstract-wizard
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `CONFIG_DIR` | `/config` | 配置文件存放目录 |
|
||
| `LISTEN_ADDR` | `127.0.0.1:8080` | 监听地址 |
|
||
| `MAX_BACKUPS` | `10` | 每个文件保留的最大备份数 |
|
||
|
||
### API
|
||
|
||
#### 健康检查
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18080/health
|
||
```
|
||
|
||
#### 读取配置
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18080/api/v1/config/app.json
|
||
```
|
||
|
||
#### 完整替换配置
|
||
|
||
```bash
|
||
curl -X PUT http://127.0.0.1:18080/api/v1/config/app.json \
|
||
-d '{"database": {"host": "localhost", "port": 5432}}'
|
||
```
|
||
|
||
写入前会自动创建备份，响应中包含 `backup_version`。
|
||
|
||
#### 局部更新（深度合并）
|
||
|
||
```bash
|
||
curl -X PATCH http://127.0.0.1:18080/api/v1/config/app.json \
|
||
-d '{"database": {"port": 3306}}'
|
||
```
|
||
|
||
仅更新指定字段，嵌套对象递归合并。
|
||
|
||
#### 查看备份列表
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18080/api/v1/backups/app.json
|
||
```
|
||
|
||
#### 回滚到指定版本
|
||
|
||
```bash
|
||
# 先从备份列表获取版本号，然后：
|
||
curl -X POST http://127.0.0.1:18080/api/v1/rollback/app.json \
|
||
-d '{"version": "20260215T120000Z"}'
|
||
```
|
||
|
||
#### 模式切换
|
||
|
||
查看当前模式：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:18080/api/v1/mode
|
||
```
|
||
|
||
切换为只读模式（拒绝所有写操作）：
|
||
|
||
```bash
|
||
curl -X PUT http://127.0.0.1:18080/api/v1/mode \
|
||
-d '{"mode": "readonly"}'
|
||
```
|
||
|
||
切换回初始化模式（允许读写）：
|
||
|
||
```bash
|
||
curl -X PUT http://127.0.0.1:18080/api/v1/mode \
|
||
-d '{"mode": "init"}'
|
||
```
|
||
|
||
### YAML 支持
|
||
|
||
所有端点同时支持 JSON 和 YAML，格式由文件扩展名自动判断：
|
||
|
||
```bash
|
||
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 隧道实现：
|
||
|
||
```bash
|
||
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 # 示例部署配置
|
||
```
|