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 获取完整配置

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

响应示例：

{
  "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）

# 获取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 编辑配置

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

示例1：修改端口

curl -X POST "http://localhost:11438/api/v2/config/edit?key=server.port&value=8080"

响应：

{"ok": true}

副作用：

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

---

示例2：修改bcrypt_cost

curl -X POST "http://localhost:11438/api/v2/config/edit?key=authentication.bcrypt_cost&value=12"

---

示例3：修改日志级别

curl -X POST "http://localhost:11438/api/v2/config/edit?key=logging.level&value=debug"

---

示例4：修改PostgreSQL配置

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 验证配置

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

响应（配置有效）：

{"ok": true}

响应（配置无效）：

{
  "ok": false,
  "error": "Invalid server port: 80. Must be >= 1024"
}

---

1.5 错误处理示例

错误1：无效端口

curl -X POST "http://localhost:11438/api/v2/config/edit?key=server.port&value=80"

响应：

{
  "ok": false,
  "error": "Invalid server port: 80. Must be >= 1024"
}

---

错误2：无效bcrypt_cost

curl -X POST "http://localhost:11438/api/v2/config/edit?key=authentication.bcrypt_cost&value=2"

响应：

{
  "ok": false,
  "error": "Invalid bcrypt_cost: 2. Must be 4-31"
}

---

错误3：无效log_level

curl -X POST "http://localhost:11438/api/v2/config/edit?key=logging.level&value=invalid"

响应：

{
  "ok": false,
  "error": "Invalid logging.level: invalid. Must be one of: trace, debug, info, warn, error, off"
}

---

二、S3配置API

2.1 获取S3配置

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

响应示例：

{
  "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 获取特定参数

# 检查认证状态
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认证（生产部署）：

curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=s3.require_auth&value=true"

响应：

{"ok": true}

副作用：

• 创建备份：config/s3.toml.bak
• 写入审计日志
• 验证endpoint格式

---

修改endpoint：

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

---

修改region：

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

---

修改access key：

curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=keys.default_access_key&value=prod_access_key_001"

---

2.4 验证S3配置

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

响应：

{"ok": true}

---

2.5 S3配置错误示例

错误1：无效endpoint格式

curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=s3.endpoint&value=invalid_url"

响应：

{
  "ok": false,
  "error": "S3 endpoint must start with http:// or https://. Current: invalid_url"
}

---

错误2：无效权限

curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=permissions.default_permissions&value=[\"InvalidPerm\"]"

响应：

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

---

三、SFTP配置API

3.1 获取SFTP配置

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

响应示例（简化）：

{
  "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 获取特定参数

# 检查端口
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配置

修改端口：

curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=sftp.port&value=2022"

---

修改chunk_size（性能优化）：

curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=performance.chunk_size&value=131072"

---

修改max_connections：

curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=sftp.max_connections&value=200"

---

启用/禁用rsync：

curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=rsync.enabled&value=false"

---

3.4 验证SFTP配置

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

---

3.5 SFTP配置错误示例

错误1：chunk_size超过限制

curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=performance.chunk_size&value=2097152"

响应：

{
  "ok": false,
  "error": "performance.chunk_size 2097152 is too large. Max: 1048576 (1MB)"
}

---

错误2：无效rsync compression_level

curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=rsync.compression_level&value=10"

响应：

{
  "ok": false,
  "error": "rsync.compression_level 10 is invalid. Must be 1-9"
}

---

错误3：无效rsync protocol_version

curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=rsync.protocol_version&value=25"

响应：

{
  "ok": false,
  "error": "rsync.protocol_version 25 is invalid. Must be 27-31"
}

---

四、Python脚本示例

4.1 批量修改配置

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 监控配置变更

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 配置验证脚本

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 使用环境变量

# 定义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 批量操作脚本

#!/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 配置对比

# 对比当前配置和备份配置
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: 如何检查配置是否生效？

答：

# 重启服务器
cargo run -- display

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

---

Q3: 配置文件在哪里？

答：

• MarkBase: config/markbase.toml
• S3: config/s3.toml
• SFTP: config/sftp.toml

---

Q4: 如何查看审计日志？

答：

tail -f logs/config_audit.log | jq

---

九、生产部署最佳实践

9.1 配置初始化

# 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 配置备份策略

# 定期备份（建议每日）
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 监控脚本

#!/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