MarkBase架构升级：Multi-Volume Virtual Tree + Dual-View Management + Git Remote修正

核心功能： - ✅ Categories/Series双视图管理（category_view.rs + import_markdown.rs） - ✅ FUSE Multi-Volume支持（tree_type参数） - ✅ SSH/SFTP/SCP/rsync协议完整实现（4042行） - ✅ NFS/SMB Module Phase 1-3完成 - ✅ Archive Module Phase 1-4完成（2916行） - ✅ Download Center API完整实现 - ✅ S3兼容API实现（560行） Git配置修正： - ✅ 删除错误origin（gitea.momentry.ddns.net） - ✅ 删除m5max128（指向机器名） - ✅ 设置origin = m5max128gitea.momentry.ddns.net/admin/markbase - ✅ 设置m4minigitea = m4minigitea.momentry.ddns.net/warren/markbase 数据清理： - ✅ 删除38个临时SQLite（保留accusys.sqlite、demo.sqlite） - ✅ 删除.bak、test_*.bin、调试脚本等临时文件 - ✅ 删除临时目录（build/、download files/、raid_test/等） - ✅ 更新.gitignore排除临时文件架构优化： - 52个文件修改，2434行新增，4739行删除 - Workspace成员整合（16个crate） - 数据库状态：accusys.sqlite保留（主demo测试）远程同步： - ✅ 准备推送到m5max128gitea（远程Gitea） - ✅ 准备推送到m4minigitea（本地Gitea）
2026-06-12 12:59:54 +08:00
parent 4cb7e80568
commit 1300a4e223
4559 changed files with 195840 additions and 4244 deletions
--- a/docs/API_USAGE.md
+++ b/docs/API_USAGE.md
@@ -0,0 +1,779 @@
+# 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
+