markbase/docs/CONFIG_SYSTEM.md

# MarkBase配置系统完整文档

## 系统概述

MarkBase配置系统提供3个独立配置文件，支持CLI命令、REST API、环境变量三种管理方式。

**配置文件结构：**
```
config/
├── markbase.toml  (主配置，26参数，5个section)
├── s3.toml        (S3配置，19参数，4个section)
└── sftp.toml      (SFTP配置，41参数，7个section)
```

**配置优先级：**
```
默认值 → TOML配置文件 → 环境变量 → CLI参数/API调用
```

---

## 一、markbase.toml（主配置）

### 1.1 Server配置

```toml
[server]
host = "127.0.0.1"           # 服务器监听地址
port = 11438                 # HTTP端口（>=1024）
log_level = "info"           # 日志级别（trace/debug/info/warn/error/off）
auth_db_path = "data/auth.sqlite"  # 认证数据库路径
users_db_dir = "data/users"  # 用户数据库目录
```

**验证规则：**
- `port`: 必须>=1024（非root用户端口限制）
- `host`: 不能为空
- `log_level`: 必须是有效值（trace/debug/info/warn/error/off）
- `auth_db_path/users_db_dir`: 不能为空

**环境变量覆盖：**
- `MB_HOST` → server.host
- `MB_PORT` → server.port
- `MB_LOG_LEVEL` → server.log_level

---

### 1.2 PostgreSQL配置

```toml
[postgresql]
host = "127.0.0.1"           # PostgreSQL服务器地址
port = 5432                  # PostgreSQL端口
user = "sftpgo"              # PostgreSQL用户名
password = "sftpgo_pass_2026" # PostgreSQL密码
database = "sftpgo"          # PostgreSQL数据库
connection_pool_size = 5     # 连接池大小（>=1）
```

**验证规则：**
- `port`: 不能为0
- `host/user/database`: 不能为空
- `connection_pool_size`: 必须>=1

**环境变量覆盖：**
- `PG_HOST` → postgresql.host
- `PG_PORT` → postgresql.port
- `PG_USER` → postgresql.user
- `PG_PASSWORD` → postgresql.password
- `PG_DATABASE` → postgresql.database

---

### 1.3 Authentication配置

```toml
[authentication]
bcrypt_cost = 10                 # bcrypt加密强度（4-31）
token_validity_hours = 24        # Token有效期（小时，>=1）
session_storage = "memory"       # Session存储方式
max_sessions_per_user = 5        # 每用户最大Session数（>=1）
default_user = "demo"            # 默认用户名
default_password = "demo123"     # 默认密码
```

**验证规则：**
- `bcrypt_cost`: 必须4-31（推荐：10开发，12生产）
- `token_validity_hours`: 必须>=1
- `max_sessions_per_user`: 必须>=1
- `default_user/default_password`: 不能为空

**环境变量覆盖：**
- `MB_BCRYPT_COST` → authentication.bcrypt_cost
- `MB_TOKEN_VALIDITY_HOURS` → authentication.token_validity_hours

---

### 1.4 Test配置

```toml
[test]
users = ["warren", "momentry", "demo"]  # 测试用户列表
password = "demo123"                    # 测试统一密码
login_test_iterations = 10              # Login性能测试迭代次数
verify_test_iterations = 100            # Token验证测试迭代次数
api_test_iterations = 50                # Protected API测试迭代次数
performance_report = true               # 是否生成性能报告
output_format = "markdown"              # 输出格式
```

**验证规则：**
- `users`: 不能为空数组

---

### 1.5 Logging配置

```toml
[logging]
level = "info"                 # 日志级别
file_path = "logs/markbase.log"  # 日志文件路径
console_output = true          # 是否输出到控制台
structured_logging = false     # 是否使用结构化日志
```

**验证规则：**
- `level`: 必须是有效值（trace/debug/info/warn/error/off）

---

## 二、s3.toml（S3配置）

### 2.1 S3基础配置

```toml
[s3]
enabled = true                         # S3功能是否启用
endpoint = "http://localhost:11438/s3" # S3 endpoint URL
region = "us-east-1"                   # AWS region
service = "s3"                         # AWS service name
require_auth = false                   # 是否强制认证（false=开发模式）
```

**验证规则：**
- `endpoint`: 必须以http://或https://开头
- `region/service`: 不能为空
- `require_auth`: true启用AWS Signature V4认证，false允许无认证访问

**环境变量覆盖：**
- `MB_S3_REQUIRE_AUTH` → s3.require_auth（推荐生产设置true）
- `MB_S3_ENDPOINT` → s3.endpoint
- `MB_S3_REGION` → s3.region

---

### 2.2 Keys配置

```toml
[s3.keys]
default_access_key = "markbase_access_key_001"  # 默认Access Key
default_secret_key = "markbase_secret_key_xyz123" # 默认Secret Key
keys_db_path = "data/s3_keys.json"  # Keys数据库路径
```

**验证规则：**
- `default_access_key/default_secret_key`: 不能为空
- `keys_db_path`: 不能为空

**环境变量覆盖：**
- `MB_S3_ACCESS_KEY` → keys.default_access_key
- `MB_S3_SECRET_KEY` → keys.default_secret_key

---

### 2.3 Permissions配置

```toml
[s3.permissions]
default_permissions = ["GetObject", "ListBucket", "HeadObject"]
admin_permissions = ["GetObject", "PutObject", "DeleteObject", "ListBucket", "HeadObject"]
```

**验证规则：**
- 权限必须为有效值：GetObject, PutObject, DeleteObject, ListBucket, HeadObject, ListAllMyBuckets, CreateBucket, DeleteBucket
- `default_permissions/admin_permissions`: 不能为空数组

---

## 三、sftp.toml（SFTP配置）

### 3.1 SFTP基础配置

```toml
[sftp]
enabled = true                         # SFTP功能是否启用
port = 2023                            # SFTP端口（>=1024或22）
base_path = "/Users/accusys/momentry/var/sftpgo/data"  # 文件存储根目录
auth_db_path = "data/auth.sqlite"      # 认证数据库路径
max_connections = 100                  # 最大并发连接数（>=1）
```

**验证规则：**
- `port`: 必须>=1024或等于22（标准SSH端口）
- `base_path/auth_db_path`: 不能为空
- `max_connections`: 必须>=1

---

### 3.2 Performance配置

```toml
[performance]
path_cache_size = 10000        # 路径缓存大小（>=1）
chunk_size = 65536             # 数据块大小（字节，1-1048576）
connection_pool_size = 10      # 连接池大小（>=1）
max_open_files = 1000          # 最大打开文件数（>=1）
max_open_dirs = 100            # 最大打开目录数（>=1）
```

**验证规则：**
- `chunk_size`: 必须1-1048576（最大1MB）
- 其他参数: 必须>=1

---

### 3.3 Security配置

```toml
[security]
require_path_validation = true     # 路径验证（防路径遍历攻击）
audit_logging = true               # 审计日志
path_traversal_protection = true   # 路径遍历防护
symlink_check = true               # 符号链接检查
```

---

### 3.4 Resource配置

```toml
[resource]
file_timeout_seconds = 300         # 文件超时（秒，>=1）
dir_timeout_seconds = 600          # 目录超时（秒，>=1）
cleanup_interval_seconds = 60      # 清理间隔（秒，>=1）
```

**验证规则：**
- 所有参数: 必须>=1

---

### 3.5 Logging配置

```toml
[logging]
level = "debug"                    # 日志级别
audit_log_path = "logs/sftp_audit.log"  # 审计日志路径
```

**验证规则：**
- `level`: 必须是有效值（trace/debug/info/warn/error/off）

---

### 3.6 Rsync配置

```toml
[rsync]
enabled = true                     # Rsync功能是否启用
block_size = 4096                  # 块大小（>=1）
compression = true                 # 是否启用压缩
compression_level = 6              # 压缩级别（1-9）
checksum_algorithm = "md5"         # 校验算法
max_file_size_mb = 10240           # 最大文件大小（MB）
delta_enabled = true               # Delta算法
rolling_checksum = true            # 滚动校验
protocol_version = 30              # Rsync协议版本（27-31）
hash_table_size = 10000            # Hash表大小
max_block_count = 1000000          # 最大块计数
```

**验证规则（仅当enabled=true时）：**
- `block_size`: 必须>=1
- `compression_level`: 必须1-9
- `protocol_version`: 必须27-31

---

## 四、CLI命令使用

### 4.1 MarkBase配置命令

```bash
# 初始化配置文件
cargo run -- config init
cargo run -- config init --force  # 强制覆盖

# 查看配置
cargo run -- config show                    # 显示所有配置
cargo run -- config show --section server   # 显示server配置
cargo run -- config show --section postgresql
cargo run -- config show --section authentication

# 编辑配置
cargo run -- config edit --key server.port --value 8080
cargo run -- config edit --key authentication.bcrypt_cost --value 12
cargo run -- config edit --key postgresql.password --value new_pass

# 验证配置
cargo run -- config validate
```

---

### 4.2 S3配置（通过API）

```bash
# 获取S3配置
curl http://localhost:11438/api/v2/config/s3

# 编辑S3配置
curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=s3.require_auth&value=true"

# 验证S3配置
curl http://localhost:11438/api/v2/config/s3/validate
```

---

### 4.3 SFTP配置（通过API）

```bash
# 获取SFTP配置
curl http://localhost:11438/api/v2/config/sftp

# 验证SFTP配置
curl http://localhost:11438/api/v2/config/sftp/validate
```

---

## 五、REST API Endpoint

### 5.1 MarkBase配置API

| Endpoint | Method | 功能 | 参数 |
|----------|--------|------|------|
| `/api/v2/config` | GET | 获取MarkBase配置 | 无 |
| `/api/v2/config/edit` | POST | 编辑MarkBase配置 | key, value (Query) |
| `/api/v2/config/validate` | GET | 验证MarkBase配置 | 无 |

**示例：**
```bash
# 获取完整配置（JSON格式）
curl http://localhost:11438/api/v2/config | jq

# 编辑配置（自动验证+备份+审计日志）
curl -X POST "http://localhost:11438/api/v2/config/edit?key=logging.level&value=debug"
# 返回：{"ok":true}

# 验证配置有效性
curl http://localhost:11438/api/v2/config/validate
# 返回：{"ok":true} 或 {"ok":false,"error":"..."}
```

---

### 5.2 S3配置API

| Endpoint | Method | 功能 | 参数 |
|----------|--------|------|------|
| `/api/v2/config/s3` | GET | 获取S3配置 | 无 |
| `/api/v2/config/s3/edit` | POST | 编辑S3配置 | key, value (Query) |
| `/api/v2/config/s3/validate` | GET | 验证S3配置 | 无 |

**示例：**
```bash
# 获取S3配置
curl http://localhost:11438/api/v2/config/s3 | jq '.s3.require_auth'

# 启用S3认证（生产模式）
curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=s3.require_auth&value=true"

# 验证S3配置
curl http://localhost:11438/api/v2/config/s3/validate
```

---

### 5.3 SFTP配置API

| Endpoint | Method | 功能 | 参数 |
|----------|--------|------|------|
| `/api/v2/config/sftp` | GET | 获取SFTP配置 | 无 |
| `/api/v2/config/sftp/edit` | POST | 编辑SFTP配置 | key, value (Query) |
| `/api/v2/config/sftp/validate` | GET | 验证SFTP配置 | 无 |

---

## 六、配置变更审计日志

### 6.1 审计日志格式

**日志文件：** `logs/config_audit.log`

**格式：** JSON lines（每行一条记录）

**字段：**
```json
{
  "timestamp": "2026-06-09T23:45:00Z",
  "operation": "edit",
  "config_type": "markbase",
  "key": "server.port",
  "old_value": "11438",
  "new_value": "8080",
  "user": "system",
  "ip_address": null
}
```

---

### 6.2 审计日志示例

```bash
# 查看最近10条审计日志
tail -10 logs/config_audit.log | jq

# 搜索特定配置变更
grep "server.port" logs/config_audit.log | jq

# 统计配置变更次数
grep -c "operation" logs/config_audit.log
```

---

## 七、配置备份机制

### 7.1 自动备份

**触发时机：** 每次保存配置前自动创建备份

**备份文件：** `config/*.toml.bak`

**示例：**
```bash
# 查看备份文件
ls -lh config/*.bak
# 输出：config/markbase.toml.bak (747 bytes)

# 从备份恢复
cp config/markbase.toml.bak config/markbase.toml
```

---

### 7.2 手动备份建议

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

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

---

## 八、配置验证错误示例

### 8.1 MarkBase配置错误

```bash
# 无效端口
cargo run -- config edit --key server.port --value 80
# Error: Invalid server port: 80. Must be >= 1024

# 无效bcrypt_cost
cargo run -- config edit --key authentication.bcrypt_cost --value 2
# Error: Invalid bcrypt_cost: 2. Must be 4-31

# 无效log_level
cargo run -- config edit --key logging.level --value invalid
# Error: Invalid logging.level: invalid. Must be one of: trace, debug, info, warn, error, off
```

---

### 8.2 S3配置错误

```bash
# 无效endpoint格式
curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=s3.endpoint&value=invalid"
# Error: S3 endpoint must start with http:// or https://

# 无效权限
curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=permissions.default_permissions&value=[\"InvalidPerm\"]"
# Error: Invalid permission: InvalidPerm. Must be one of: GetObject, PutObject, ...
```

---

### 8.3 SFTP配置错误

```bash
# 无效chunk_size（超过1MB）
curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=performance.chunk_size&value=2097152"
# Error: performance.chunk_size 2097152 is too large. Max: 1048576 (1MB)

# 无效rsync compression_level
curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=rsync.compression_level&value=10"
# Error: rsync.compression_level 10 is invalid. Must be 1-9
```

---

## 九、生产部署建议

### 9.1 安全配置

```bash
# 1. 启用S3认证
export MB_S3_REQUIRE_AUTH=true
# 或
curl -X POST "http://localhost:11438/api/v2/config/s3/edit?key=s3.require_auth&value=true"

# 2. 增强bcrypt加密强度
cargo run -- config edit --key authentication.bcrypt_cost --value 12

# 3. 配置生产PostgreSQL
export PG_HOST=prod-db.example.com
export PG_PORT=5432
export PG_USER=markbase_prod
export PG_PASSWORD=<secure_password>
export PG_DATABASE=markbase_production
```

---

### 9.2 性能优化

```bash
# 1. 调整连接池大小
cargo run -- config edit --key postgresql.connection_pool_size --value 20

# 2. 调整SFTP chunk_size（提升吞吐量）
curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=performance.chunk_size&value=131072"

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

---

### 9.3 监控配置

```bash
# 1. 设置审计日志
curl -X POST "http://localhost:11438/api/v2/config/sftp/edit?key=security.audit_logging&value=true"

# 2. 配置日志级别
cargo run -- config edit --key logging.level --value info

# 3. 日志轮转（外部工具）
# logrotate配置示例：
/opt/markbase/logs/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
}
```

---

## 十、配置系统统计

### 10.1 参数统计

| 配置文件 | Section数 | 参数数 | 验证检查数 |
|----------|-----------|---------|-----------|
| markbase.toml | 5 | 26 | 23 |
| s3.toml | 4 | 19 | 13 |
| sftp.toml | 7 | 41 | 25 |
| **总计** | **16** | **86** | **61** |

---

### 10.2 环境变量统计

| 配置类型 | 环境变量数 | 前缀 |
|----------|-----------|------|
| MarkBase | 11 | MB_* |
| PostgreSQL | 5 | PG_* |
| S3 | 5 | MB_S3_* |
| SFTP | 0 | （无） |
| **总计** | **21** | - |

---

### 10.3 API Endpoint统计

| 配置类型 | Endpoint数 | 方法 |
|----------|-----------|------|
| MarkBase | 3 | GET/POST/GET |
| S3 | 3 | GET/POST/GET |
| SFTP | 3 | GET/POST/GET |
| **总计** | **9** | - |

---

## 十一、常见问题

### Q1: 配置文件不存在怎么办？

**答：** 运行 `cargo run -- config init` 创建默认配置文件

---

### Q2: 如何恢复错误配置？

**答：**
```bash
# 从备份恢复
cp config/markbase.toml.bak config/markbase.toml

# 或重新初始化（谨慎）
cargo run -- config init --force
```

---

### Q3: 配置修改后需要重启服务器吗？

**答：** 是的，当前版本配置修改需要重启生效。未来版本计划实现热加载功能。

---

### Q4: 审计日志在哪里？

**答：** `logs/config_audit.log`（JSON lines格式）

---

### Q5: 如何启用生产认证？

**答：**
```bash
export MB_S3_REQUIRE_AUTH=true
# 重启服务器生效
```

---

## 十二、版本信息

**文档版本：** 2.0
**最后更新：** 2026-06-09
**MarkBase版本：** Phase 2 Complete
**配置系统版本：** Full Implementation (CLI + API + Validation + Audit + Backup)

---

**相关文档：**
- AGENTS.md - MarkBase开发指南
- API_USAGE.md - REST API详细示例
- AUDIT_LOG_GUIDE.md - 审计日志使用指南