config-man/docs/USAGE.md

Config-Man 使用说明

适用范围

本文档聚焦 config-man view 以及相关配置方式，默认推荐通过 uv tool 使用本项目。

启动方式

从源码临时运行

uv tool run --from . config-man --help
uv tool run --from . config-man view --version 0.30 --mock

安装为本地命令

uv tool install --from . config-man
config-man --help
config-man view --version 0.30 --mock

view 命令

基本用法

# 查看版本 0.30 的配置文件
config-man view --version 0.30

# 以 JSON 格式输出
config-man view --version 0.30 --json

# 使用模拟环境测试
config-man view --version 0.30 --mock

参数说明

• --version: 版本号，格式如 0.29、0.30
• --json: 使用 JSON 格式输出
• --storage-path: 覆盖配置中的对象存储路径前缀
• --cdn-url: 覆盖配置中的 CDN 基础 URL
• --mock: 启用模拟环境，避免依赖真实 rclone 和远端资源

查看帮助

config-man --help
config-man view --help

配置方式

Config-Man 支持三类外部配置来源：

1. 命令行参数
2. 环境变量
3. 配置文件

整体优先级为：命令行参数 > 环境变量 > 用户配置文件 > 项目默认配置。

配置文件位置

• 用户配置: ~/.config/config-man/config-man.json
• 项目默认配置: ./config-man.json

配置文件示例

{
  "storage": {
    "path": "ab",
    "rclone_remote": "remote",
    "timeout": 30
  },
  "cdn": {
    "base_url": "",
    "timeout": 10,
    "retry_count": 3,
    "cloudflare": {
      "api_token": "",
      "zone_id": ""
    }
  },
  "crypto": {
    "algorithm": "DES",
    "key": "tbambooz"
  },
  "display": {
    "table_format": "grid",
    "max_width": 80,
    "truncate_length": 25
  }
}

环境变量

环境变量	配置项	说明
CONFIG_MAN_STORAGE_PATH	storage.path	存储路径
CONFIG_MAN_STORAGE_RCLONE_REMOTE	storage.rclone_remote	rclone 远程名称
CONFIG_MAN_STORAGE_TIMEOUT	storage.timeout	存储操作超时时间
CONFIG_MAN_CDN_BASE_URL	cdn.base_url	CDN 基础 URL
CONFIG_MAN_CDN_TIMEOUT	cdn.timeout	CDN 请求超时时间
CONFIG_MAN_CDN_RETRY_COUNT	cdn.retry_count	CDN 重试次数
CONFIG_MAN_CDN_CLOUDFLARE_API_TOKEN	cdn.cloudflare.api_token	Cloudflare API Token
CONFIG_MAN_CDN_CLOUDFLARE_ZONE_ID	cdn.cloudflare.zone_id	Cloudflare Zone ID
CONFIG_MAN_CRYPTO_KEY	crypto.key	加密密钥
CONFIG_MAN_CRYPTO_ALGORITHM	crypto.algorithm	加密算法
CONFIG_MAN_LOG_LEVEL	logging.level	日志级别
CONFIG_MAN_DISPLAY_TABLE_FORMAT	display.table_format	表格格式
CONFIG_MAN_DISPLAY_MAX_WIDTH	display.max_width	最大宽度
CONFIG_MAN_DISPLAY_TRUNCATE_LENGTH	display.truncate_length	截断长度

示例：

export CONFIG_MAN_STORAGE_PATH=ab
export CONFIG_MAN_STORAGE_RCLONE_REMOTE=remote
export CONFIG_MAN_CDN_BASE_URL=https://cdn.example.com
config-man view --version 0.30 --mock

本地配置管理命令

config-man show-config
config-man set-config --key storage.path --value custom_path
config-man set-config --key cdn.base_url --value https://cdn.example.com
config-man set-config --key display.max_width --value 100
config-man setup-cloudflare --api-token <token> --zone-id <zone_id>

输出格式

表格格式

版本: 0.30 | 平台: Android
┌─────────────────┬─────────────────────┬─────────────────────┬──────────┐
│ 配置项          │ 对象存储内容        │ CDN内容             │ 状态     │
├─────────────────┼─────────────────────┼─────────────────────┼──────────┤
│ Ver             │ 0.30.2ghi789        │ 0.30.2ghi789        │ 一致     │
│ EventApiURL     │ https://n3backend…  │ https://n3backend…  │ 一致     │
│ NewFeature      │ enabled             │ N/A                 │ 不同     │
└─────────────────┴─────────────────────┴─────────────────────┴──────────┘

JSON 格式

{
  "version": "0.30",
  "platform": "android",
  "storage_config": {
    "EventApiURL": "https://n3backend.azurewebsites.net/",
    "Ver": "0.30.2ghi789"
  },
  "cdn_config": {
    "EventApiURL": "https://n3backend.azurewebsites.net/",
    "Ver": "0.30.2ghi789"
  }
}

模拟环境

推荐先用 --mock 验证 CLI、格式化输出和本地配置加载：

config-man view --version 0.30 --mock

模拟模式主要用于：

• 绕过真实 rclone
• 在无远端依赖时验证 CLI 流程
• 快速检查 uv tool 打包后的命令可用性

常见问题

rclone 未安装

真实环境模式下，如果系统找不到 rclone，命令将无法继续。请先确认：

rclone version

版本号格式

版本号会自动转换为存储路径格式：

• 0.29 -> 0_29
• 0.30 -> 0_30
• 1.00 -> 1_00

网络或权限问题

如果对象存储、CDN 或 Cloudflare 接口不可达，请检查：

• 网络连接
• 远端访问权限
• rclone 配置
• CDN 和 Cloudflare 相关参数是否完整