Mustapha/config-man
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[U] Wrap into uv tool.

Browse Source
This commit is contained in:
tianbo.shan
2026-03-20 20:19:33 +08:00
parent db20b739cd
commit ca9e32763e
14 changed files with 844 additions and 433 deletions
Download Patch File Download Diff File Expand all files Collapse all files

302
docs/USAGE.md
View File

@@ -1,68 +1,73 @@
# Config-Man 查看功能使用说明
# Config-Man 使用说明
## 功能概述
## 适用范围
Config-Man 的查看功能允许您对比显示对象存储和CDN中的配置内容，支持Android和iOS平台。
本文档聚焦 `config-man view` 以及相关配置方式，默认推荐通过 `uv tool` 使用本项目。
## 安装依赖
## 启动方式
首先安装项目依赖：
### 从源码临时运行
```bash
pip install -e .
uv tool run --from . config-man --help
uv tool run --from . config-man view --version 0.30 --mock
```
## 基本用法
### 安装为本地命令
### 1. 查看配置文件
```bash
uv tool install --from . config-man
config-man --help
config-man view --version 0.30 --mock
```
## `view` 命令
### 基本用法
```bash
# 查看版本 0.30 的配置文件
python main.py view --version 0.30
config-man view --version 0.30
# 以JSON格式输出
python main.py view --version 0.30 --json
# 以 JSON 格式输出
config-man view --version 0.30 --json
# 使用模拟环境进行测试
python main.py view --version 0.30 --mock
# 使用模拟环境测试
config-man view --version 0.30 --mock
```
### 2. 查看帮助信息
### 参数说明
- `--version`: 版本号，格式如 `0.29`、`0.30`
- `--json`: 使用 JSON 格式输出
- `--storage-path`: 覆盖配置中的对象存储路径前缀
- `--cdn-url`: 覆盖配置中的 CDN 基础 URL
- `--mock`: 启用模拟环境，避免依赖真实 `rclone` 和远端资源
### 查看帮助
```bash
# 查看主命令帮助
python main.py --help
# 查看view命令帮助
python main.py view --help
config-man --help
config-man view --help
```
## 参数说明
## 配置方式
### view 命令参数
Config-Man 支持三类外部配置来源：
- `--version`: 版本号，格式为 0.29, 0.30, 0.31 等（必需）
- `--json`: 以JSON格式输出（可选）
- `--storage-path`: 对象存储路径前缀（覆盖配置文件）
- `--cdn-url`: CDN基础URL（覆盖配置文件）
- `--mock`: 使用模拟环境进行测试（可选）
1. 命令行参数
2. 环境变量
3. 配置文件
### 配置管理命令
整体优先级为：命令行参数 > 环境变量 > 用户配置文件 > 项目默认配置。
- `show-config`: 显示当前配置
- `set-config`: 设置配置值
### 配置文件位置
## 配置文件
Config-Man 支持多种配置方式：
### 1. 配置文件
默认配置文件位置：
- 用户配置: `~/.config/config-man/config-man.json`
- 项目配置: `./config-man.json`
- 项目默认配置: `./config-man.json`
### 配置文件示例
配置文件格式：
```json
{
"storage": {
@@ -73,7 +78,11 @@ Config-Man 支持多种配置方式：
"cdn": {
"base_url": "",
"timeout": 10,
"retry_count": 3
"retry_count": 3,
"cloudflare": {
"api_token": "",
"zone_id": ""
}
},
"crypto": {
"algorithm": "DES",
@@ -87,45 +96,60 @@ Config-Man 支持多种配置方式：
}
```
### 2. 环境变量
支持以下环境变量：
### 环境变量
| 环境变量 | 配置项 | 说明 |
|---------|--------|------|
| --- | --- | --- |
| `CONFIG_MAN_STORAGE_PATH` | `storage.path` | 存储路径 |
| `CONFIG_MAN_STORAGE_RCLONE_REMOTE` | `storage.rclone_remote` | rclone远程名称 |
| `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_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` | 截断长度 |
### 3. 命令行参数
示例：
命令行参数会覆盖配置文件和环境变量的设置。
```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 │ ❌ 不同 │
│ ... │ ... │ ... │ ... │
│ Ver │ 0.30.2ghi789 │ 0.30.2ghi789 │ 一致 │
│ EventApiURL │ https://n3backend… │ https://n3backend… │ 一致 │
│ NewFeature │ enabled │ N/A │ 不同 │
└─────────────────┴─────────────────────┴─────────────────────┴──────────┘
```
### JSON格式
### JSON 格式
```json
{
@@ -133,8 +157,7 @@ Config-Man 支持多种配置方式：
"platform": "android",
"storage_config": {
"EventApiURL": "https://n3backend.azurewebsites.net/",
"Ver": "0.30.2ghi789",
"NewFeature": "enabled"
"Ver": "0.30.2ghi789"
},
"cdn_config": {
"EventApiURL": "https://n3backend.azurewebsites.net/",
@@ -143,160 +166,43 @@ Config-Man 支持多种配置方式：
}
```
## 模拟环境测试
## 模拟环境
为了方便测试，项目提供了模拟环境：
推荐先用 `--mock` 验证 CLI、格式化输出和本地配置加载：
```bash
# 使用模拟环境测试
python main.py view --version 0.30 --mock
config-man view --version 0.30 --mock
```
模拟环境会：
1. 自动创建测试配置文件
2. 模拟rclone命令
3. 提供完整的测试数据
模拟模式主要用于：
## 错误处理
- 绕过真实 `rclone`
- 在无远端依赖时验证 CLI 流程
- 快速检查 `uv tool` 打包后的命令可用性
### 常见错误
## 常见问题
1. **版本号格式错误**
```
错误: 无效的版本号格式: 1.2.3
```
### `rclone` 未安装
2. **rclone未安装**
```
错误: rclone 未安装或不可用。请先安装 rclone。
```
真实环境模式下，如果系统找不到 `rclone`，命令将无法继续。请先确认：
3. **文件不存在**
```
警告: 无法从对象存储下载 ab/0_30/androidconfig.json: 文件不存在
```
```bash
rclone version
```
4. **网络连接失败**
```
警告: 无法从CDN获取 https://cdn.example.com/ab/0_30/androidconfig.json
```
## 配置说明
### 配置文件结构
配置文件包含以下主要字段：
- **EventApiURL**: API端点URL
- **Ver**: 版本信息
- **PlayFabTitle**: PlayFab标题
- **Google_Play_URL**: Google Play商店链接
- **APP_Store_URL**: App Store链接
- **HeartBeat**: 心跳间隔
- **RTMPid**: RTM进程ID
- **RTMServerEndpoint**: RTM服务器端点
- **RTMHmacSecret**: RTM HMAC密钥
- **FuncUrl**: 功能URL
- **FuncKey**: 功能密钥
### 版本号转换
### 版本号格式
版本号会自动转换为存储路径格式：
- `0.29` → `0_29`
- `0.30` → `0_30`
- `1.00` → `1_00`
## 高级用法
- `0.29` -> `0_29`
- `0.30` -> `0_30`
- `1.00` -> `1_00`
### 配置管理
### 网络或权限问题
```bash
# 显示当前配置
python main.py show-config
如果对象存储、CDN 或 Cloudflare 接口不可达，请检查：
# 设置配置值
python main.py set-config --key storage.path --value custom_path
python main.py set-config --key cdn.base_url --value https://cdn.example.com
python main.py set-config --key display.max_width --value 100
```
### 环境变量配置
```bash
# 使用环境变量设置配置
export CONFIG_MAN_STORAGE_PATH=custom_path
export CONFIG_MAN_CDN_BASE_URL=https://cdn.example.com
export CONFIG_MAN_DISPLAY_MAX_WIDTH=120
# 运行命令
python main.py view --version 0.30
```
### 命令行参数覆盖
```bash
# 命令行参数会覆盖配置文件设置
python main.py view --version 0.30 --storage-path custom_path --cdn-url https://cdn.example.com
```
### 组合使用
```bash
python main.py view --version 0.30 --json --mock --storage-path test_data/ab
```
## 故障排除
### 1. 安装问题
确保安装了所有依赖：
```bash
pip install click pycryptodome tabulate requests rich
```
### 2. rclone配置
如果使用真实环境，需要配置rclone：
```bash
rclone config
```
### 3. 权限问题
确保有足够的权限访问对象存储和CDN。
### 4. 网络问题
检查网络连接和防火墙设置。
## 开发说明
### 项目结构
```
config-man/
├── main.py # 主程序入口
├── appconfig_tool.py # 加密解密工具
├── config_manager.py # 配置管理器
├── display_manager.py # 显示管理器
├── view_command.py # 查看命令处理器
├── mock_rclone.py # 模拟rclone环境
└── test_configs.py # 测试配置生成器
```
### 扩展功能
要添加新的查看功能，可以：
1. 在 `config_manager.py` 中添加新的方法
2. 在 `display_manager.py` 中添加新的显示格式
3. 在 `view_command.py` 中添加新的处理逻辑
4. 在 `main.py` 中添加新的CLI命令
## 联系支持
如果遇到问题，请检查：
1. 版本号格式是否正确
2. 网络连接是否正常
3. rclone配置是否正确
4. 依赖是否完整安装
- 网络连接
- 远端访问权限
- `rclone` 配置
- CDN 和 Cloudflare 相关参数是否完整