markbase/docs/API_USAGE.md

# MarkBase配置API使用指南

## API Endpoint总览

MarkBase提供9个配置管理API endpoint：

### MarkBase配置（3个）
- `/api/v2/config` - 获取配置
- `/api/v2/config/edit` - 编辑配置
- `/api/v2/config/validate` - 验证配置

### S3配置（3个）
- `/api/v2/config/s3` - 获取S3配置
- `/api/v2/config/s3/edit` - 编辑S3配置
- `/api/v2/config/s3/validate` - 验证S3配置

### SFTP配置（3个）
- `/api/v2/config/sftp` - 获取SFTP配置
- `/api/v2/config/sftp/edit` - 编辑SFTP配置
- `/api/v2/config/sftp/validate` - 验证SFTP配置

---

## 一、MarkBase配置API

### 1.1 获取完整配置

```bash
curl http://localhost:11438/api/v2/config
```

**响应示例：**
```json
{
  "server": {
    "host": "127.0.0.1",
    "port": 11438,
    "log_level": "info",
    "auth_db_path": "data/auth.sqlite",
    "users_db_dir": "data/users"
  },
  "postgresql": {
    "host": "127.0.0.1",
    "port": 5432,
    "user": "sftpgo",
    "password": "sftpgo_pass_2026",
    "database": "sftpgo",
    "connection_pool_size": 5
  },
  "authentication": {
    "bcrypt_cost": 10,
    "token_validity_hours": 24,
    "session_storage": "memory",
    "max_sessions_per_user": 5,
    "default_user": "demo",
    "default_password": "demo123"
  },
  "test": {
    "users": ["warren", "momentry", "demo"],
    "password": "demo123",
    "login_test_iterations": 10,
    "verify_test_iterations": 100,
    "api_test_iterations": 50,
    "performance_report": true,
    "output_format": "markdown"
  },
  "logging": {
    "level": "info",
    "file_path": "logs/markbase.log",
    "console_output": true,
    "structured_logging": false
  }
}
```

---

### 1.2 获取特定section配置（使用jq）

```bash
# 获取server配置
curl -s http://localhost:11438/api/v2/config | jq '.server'

# 获取postgresql配置
curl -s http://localhost:11438/api/v2/config | jq '.postgresql'

# 获取authentication配置
curl -s http://localhost:11438/api/v2/config | jq '.authentication'

# 获取单个参数
curl -s http://localhost:11438/api/v2/config | jq '.server.port'
# 输出：11438
```

---

### 1.3 编辑配置

```bash
# 基本格式
curl -X POST "http://localhost:11438/api/v2/config/edit?key=<KEY>&value=<VALUE>"
```

**示例1：修改端口**
```bash
curl -X POST "http://localhost:11438/api/v2/config/edit?key=server.port&value=8080"
```

**响应：**
```json
{"ok": true}
```

**副作用：**
- 自动创建备份：`config/markbase.toml.bak`
- 写入审计日志：`logs/config_audit.log`
- 自动验证配置有效性

---

**示例2：修改bcrypt_cost**
```bash
curl -X POST "http://localhost:11438/api/v2/config/edit?key=authentication.bcrypt_cost&value=12"
```

---

**示例3：修改日志级别**
```bash
curl -X POST "http://localhost:11438/api/v2/config/edit?key=logging.level&value=debug"
```

---

**示例4：修改PostgreSQL配置**
```bash
curl -X POST "http://localhost:11438/api/v2/config/edit?key=postgresql.connection_pool_size&value=20"

curl -X POST "http://localhost:11438/api/v2/config/edit?key=postgresql.password&value=new_secure_pass"
```

---

### 1.4 验证配置

```bash
curl http://localhost:11438/api/v2/config/validate
```

**响应（配置有效）：**
```json
{"ok": true}
```

**响应（配置无效）：**
```json
{
  "ok": false,
  "error": "Invalid server port: 80. Must be >= 1024"
}
```

---

### 1.5 错误处理示例

**错误1：无效端口**
```bash
curl -X POST "http://localhost:11438/api/v2/config/edit?key=server.port&value=80"
```

**响应：**
```json
{
  "ok": false,
  "error": "Invalid server port: 80. Must be >= 1024"
}
```

---

**错误2：无效bcrypt_cost**
```bash
curl -X POST "http://localhost:11438/api/v2/config/edit?key=authentication.bcrypt_cost&value=2"
```

**响应：**
```json
{
  "ok": false,
  "error": "Invalid bcrypt_cost: 2. Must be 4-31"
}
```

---

**错误3：无效log_level**
```bash
curl -X POST "http://localhost:11438/api/v2/config/edit?key=logging.level&value=invalid"
```

**响应：**
```json
{
  "ok": false,
  "error": "Invalid logging.level: invalid. Must be one of: trace, debug, info, warn, error, off"
}
```

---

## 二、S3配置API

### 2.1 获取S3配置

```bash
curl http://localhost:11438/api/v2/config/s3
```

**响应示例：**
```json
{
  "s3": {
    "enabled": true,
    "endpoint": "http://localhost:11438/s3",
    "region": "us-east-1",
    "service": "s3",
    "require_auth": false
  },
  "keys": {
    "default_access_key": "markbase_access_key_001",
    "default_secret_key": "markbase_secret_key_xyz123",
    "keys_db_path": "data/s3_keys.json"
  },
  "buckets": {
    "mappings": {}
  },
  "permissions": {
    "default_permissions": ["GetObject", "ListBucket", "HeadObject"],
    "admin_permissions": ["GetObject", "PutObject", "DeleteObject", "ListBucket", "HeadObject"]
  }
}
```

---

### 2.2 获取特定参数

```bash
# 检查认证状态
curl -s http://localhost:11438/api/v2/config/s3 | jq '.s3.require_auth'
# 输出：false

# 获取endpoint
curl -s http://localhost:11438/api/v2/config/s3 | jq '.s3.endpoint'
# 输出："http://localhost:11438/s3"

# 获取access key
curl -s http://localhost:11438/api/v2/config/s3 | jq '.keys.default_access_key'
```

---

### 2.3 编辑S3配置

**启用S3认证（生产部署）：**
```bash
curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=s3.require_auth&value=true"
```

**响应：**
```json
{"ok": true}
```

**副作用：**
- 创建备份：`config/s3.toml.bak`
- 写入审计日志
- 验证endpoint格式

---

**修改endpoint：**
```bash
curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=s3.endpoint&value=http://s3.example.com"
```

---

**修改region：**
```bash
curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=s3.region&value=ap-northeast-1"
```

---

**修改access key：**
```bash
curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=keys.default_access_key&value=prod_access_key_001"
```

---

### 2.4 验证S3配置

```bash
curl http://localhost:11438/api/v2/config/s3/validate
```

**响应：**
```json
{"ok": true}
```

---

### 2.5 S3配置错误示例

**错误1：无效endpoint格式**
```bash
curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=s3.endpoint&value=invalid_url"
```

**响应：**
```json
{
  "ok": false,
  "error": "S3 endpoint must start with http:// or https://. Current: invalid_url"
}
```

---

**错误2：无效权限**
```bash
curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=permissions.default_permissions&value=[\"InvalidPerm\"]"
```

**响应：**
```json
{
  "ok": false,
  "error": "Invalid permission: InvalidPerm. Must be one of: GetObject, PutObject, DeleteObject, ListBucket, HeadObject, ListAllMyBuckets, CreateBucket, DeleteBucket"
}
```

---

## 三、SFTP配置API

### 3.1 获取SFTP配置

```bash
curl http://localhost:11438/api/v2/config/sftp
```

**响应示例（简化）：**
```json
{
  "sftp": {
    "enabled": true,
    "port": 2023,
    "base_path": "/Users/accusys/momentry/var/sftpgo/data",
    "auth_db_path": "data/auth.sqlite",
    "max_connections": 100
  },
  "performance": {
    "path_cache_size": 10000,
    "chunk_size": 65536,
    "connection_pool_size": 10,
    "max_open_files": 1000,
    "max_open_dirs": 100
  },
  "security": {
    "require_path_validation": true,
    "audit_logging": true,
    "path_traversal_protection": true,
    "symlink_check": true
  },
  "resource": {
    "file_timeout_seconds": 300,
    "dir_timeout_seconds": 600,
    "cleanup_interval_seconds": 60
  },
  "logging": {
    "level": "debug",
    "audit_log_path": "logs/sftp_audit.log"
  },
  "rsync": {
    "enabled": true,
    "block_size": 4096,
    "compression": true,
    "compression_level": 6,
    "protocol_version": 30
  }
}
```

---

### 3.2 获取特定参数

```bash
# 检查端口
curl -s http://localhost:11438/api/v2/config/sftp | jq '.sftp.port'
# 输出：2023

# 检查chunk_size
curl -s http://localhost:11438/api/v2/config/sftp | jq '.performance.chunk_size'
# 输出：65536

# 检查rsync是否启用
curl -s http://localhost:11438/api/v2/config/sftp | jq '.rsync.enabled'
# 输出：true
```

---

### 3.3 编辑SFTP配置

**修改端口：**
```bash
curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=sftp.port&value=2022"
```

---

**修改chunk_size（性能优化）：**
```bash
curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=performance.chunk_size&value=131072"
```

---

**修改max_connections：**
```bash
curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=sftp.max_connections&value=200"
```

---

**启用/禁用rsync：**
```bash
curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=rsync.enabled&value=false"
```

---

### 3.4 验证SFTP配置

```bash
curl http://localhost:11438/api/v2/config/sftp/validate
```

---

### 3.5 SFTP配置错误示例

**错误1：chunk_size超过限制**
```bash
curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=performance.chunk_size&value=2097152"
```

**响应：**
```json
{
  "ok": false,
  "error": "performance.chunk_size 2097152 is too large. Max: 1048576 (1MB)"
}
```

---

**错误2：无效rsync compression_level**
```bash
curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=rsync.compression_level&value=10"
```

**响应：**
```json
{
  "ok": false,
  "error": "rsync.compression_level 10 is invalid. Must be 1-9"
}
```

---

**错误3：无效rsync protocol_version**
```bash
curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=rsync.protocol_version&value=25"
```

**响应：**
```json
{
  "ok": false,
  "error": "rsync.protocol_version 25 is invalid. Must be 27-31"
}
```

---

## 四、Python脚本示例

### 4.1 批量修改配置

```python
import requests

base_url = "http://localhost:11438/api/v2"

# 批量修改MarkBase配置
changes = [
    ("server.port", "8080"),
    ("logging.level", "debug"),
    ("postgresql.connection_pool_size", "20"),
]

for key, value in changes:
    response = requests.post(
        f"{base_url}/config/edit",
        params={"key": key, "value": value}
    )
    print(f"{key}: {response.json()}")
```

---

### 4.2 监控配置变更

```python
import requests
import json

# 获取配置并监控变化
def monitor_config():
    old_config = requests.get("http://localhost:11438/api/v2/config").json()
    
    # 等待一段时间
    import time
    time.sleep(60)
    
    new_config = requests.get("http://localhost:11438/api/v2/config").json()
    
    # 检测变化
    for section in old_config:
        for key in old_config[section]:
            old_value = old_config[section][key]
            new_value = new_config[section][key]
            
            if old_value != new_value:
                print(f"Config changed: {section}.{key}: {old_value} → {new_value}")

monitor_config()
```

---

### 4.3 配置验证脚本

```python
import requests

def validate_all_configs():
    configs = ["config", "config/s3", "config/sftp"]
    
    for config in configs:
        response = requests.get(f"http://localhost:11438/api/v2/{config}/validate")
        result = response.json()
        
        if result.get("ok"):
            print(f"✓ {config} is valid")
        else:
            print(f"✗ {config} invalid: {result.get('error')}")

validate_all_configs()
```

---

## 五、curl高级用法

### 5.1 使用环境变量

```bash
# 定义base URL
export MB_API="http://localhost:11438/api/v2"

# 使用变量
curl "$MB_API/config"
curl -X POST "$MB_API/config/edit?key=server.port&value=8080"
```

---

### 5.2 批量操作脚本

```bash
#!/bin/bash
# batch_config_update.sh

API="http://localhost:11438/api/v2"

# 生产部署配置
changes=(
  "server.port:8080"
  "authentication.bcrypt_cost:12"
  "postgresql.connection_pool_size:20"
  "s3.require_auth:true"
  "sftp.max_connections:200"
)

for change in "${changes[@]}"; do
  key=$(echo $change | cut -d: -f1)
  value=$(echo $change | cut -d: -f2)
  
  # 判断config类型
  if [[ $key == s3.* ]]; then
    endpoint="/config/s3/edit"
  elif [[ $key == sftp.* ]]; then
    endpoint="/config/sftp/edit"
  else
    endpoint="/config/edit"
  fi
  
  echo "Updating $key to $value..."
  curl -s -X POST "$API$endpoint?key=$key&value=$value" | jq
done

echo "Batch update completed"
```

---

### 5.3 配置对比

```bash
# 对比当前配置和备份配置
curl -s http://localhost:11438/api/v2/config > /tmp/current.json
cat config/markbase.toml.bak > /tmp/backup.toml

# 使用diff对比
diff <(jq -S . /tmp/current.json) <(toml2json /tmp/backup.toml | jq -S .)
```

---

## 六、Web UI使用（未来功能）

MarkBase计划提供Web UI配置面板（Settings Panel）：

**访问方式：**
```
http://localhost:11438/ → 点击底部⚙️Settings按钮
```

**功能：**
- 可视化配置编辑
- 实时验证提示
- 配置历史记录
- 一键备份/恢复

---

## 七、API响应状态码

| 状态码 | 含义 | 示例场景 |
|--------|------|----------|
| 200 OK | 成功 | 配置获取、编辑成功、验证通过 |
| 400 Bad Request | 参数错误 | 无效配置值、验证失败 |
| 404 Not Found | 文件不存在 | 配置文件未初始化 |
| 500 Internal Server Error | 服务器错误 | 文件读写失败、序列化错误 |

---

## 八、常见问题

### Q1: API修改配置后需要重启吗？

**答：** 是的，配置修改后需要重启服务器生效。

---

### Q2: 如何检查配置是否生效？

**答：**
```bash
# 重启服务器
cargo run -- display

# 检查端口是否改变
curl http://localhost:8080/api/v2/config
```

---

### Q3: 配置文件在哪里？

**答：**
- MarkBase: `config/markbase.toml`
- S3: `config/s3.toml`
- SFTP: `config/sftp.toml`

---

### Q4: 如何查看审计日志？

**答：**
```bash
tail -f logs/config_audit.log | jq
```

---

## 九、生产部署最佳实践

### 9.1 配置初始化

```bash
# 1. 创建默认配置
cargo run -- config init

# 2. 应用生产配置（批量脚本）
./batch_config_update.sh

# 3. 验证所有配置
curl http://localhost:11438/api/v2/config/validate
curl http://localhost:11438/api/v2/config/s3/validate
curl http://localhost:11438/api/v2/config/sftp/validate

# 4. 启动服务器
cargo run -- display
```

---

### 9.2 配置备份策略

```bash
# 定期备份（建议每日）
tar -czf config_backup_$(date +%Y%m%d).tar.gz config/*.toml logs/config_audit.log

# 保留最近7天
find . -name "config_backup_*.tar.gz" -mtime +7 -delete
```

---

### 9.3 监控脚本

```bash
#!/bin/bash
# config_monitor.sh

# 检查配置有效性
validate_all() {
  curl -s http://localhost:11438/api/v2/config/validate | jq -e '.ok' || echo "MarkBase config invalid"
  curl -s http://localhost:11438/api/v2/config/s3/validate | jq -e '.ok' || echo "S3 config invalid"
  curl -s http://localhost:11438/api/v2/config/sftp/validate | jq -e '.ok' || echo "SFTP config invalid"
}

# 检查审计日志大小
check_audit_log() {
  log_size=$(wc -l logs/config_audit.log | awk '{print $1}')
  if [ $log_size -gt 10000 ]; then
    echo "Warning: Audit log exceeds 10000 entries"
  fi
}

validate_all
check_audit_log
```

---

**文档版本：** 2.0
**最后更新：** 2026-06-09