208 lines
5.5 KiB
Markdown
208 lines
5.5 KiB
Markdown
# 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 相关参数是否完整 |