# Config-Man 使用说明

## 适用范围

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

## 启动方式

### 从源码临时运行

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

### 安装为本地命令

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

## `view` 命令

### 基本用法

```bash
# 查看版本 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` 和远端资源

### 查看帮助

```bash
config-man --help
config-man view --help
```

## 配置方式

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

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

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

### 配置文件位置

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

### 配置文件示例

```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` | 截断长度 |

示例：

```bash
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
```

### 本地配置管理命令

```bash
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>
```

## 输出格式

### 表格格式

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

### JSON 格式

```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、格式化输出和本地配置加载：

```bash
config-man view --version 0.30 --mock
```

模拟模式主要用于：

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

## 常见问题

### `rclone` 未安装

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

```bash
rclone version
```

### 版本号格式

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

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

### 网络或权限问题

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

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