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

[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配置

[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配置

[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配置

[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配置

[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基础配置

[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配置

[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配置

[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基础配置

[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配置

[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配置

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

---

3.4 Resource配置

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

验证规则：

• 所有参数: 必须>=1

---

3.5 Logging配置

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

验证规则：

• level: 必须是有效值（trace/debug/info/warn/error/off）

---

3.6 Rsync配置

[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配置命令

# 初始化配置文件
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）

# 获取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）

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

示例：

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

示例：

# 获取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（每行一条记录）

字段：

{
  "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 审计日志示例

# 查看最近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

示例：

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

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

---

7.2 手动备份建议

# 定期备份策略（建议）
# 每日备份
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配置错误

# 无效端口
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配置错误

# 无效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配置错误

# 无效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 安全配置

# 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 性能优化

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

# 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: 如何恢复错误配置？

答：

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

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

---

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

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

---

Q4: 审计日志在哪里？

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

---

Q5: 如何启用生产认证？

答：

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 - 审计日志使用指南