264
README.md
264
README.md
@@ -1,146 +1,212 @@
|
||||
# Config-Man CLI 工具
|
||||
|
||||
Config-Man 是一个面向对象存储配置文件的 Python CLI，支持查看配置、建议更新、强制更新，以及配套的本地配置管理。项目已经整理为可直接通过 `uv tool` 运行和安装的命令行工具。
|
||||
## 项目概述
|
||||
|
||||
## 快速开始
|
||||
Config-Man 是一个Python CLI工具，用于管理存储在对象存储中的加密静态资源配置文件。该工具支持多版本管理，通过Cloudflare CDN进行分发，主要用于游戏应用的配置管理。
|
||||
|
||||
### 从源码直接运行
|
||||
### 项目目标
|
||||
- 简化多版本配置文件的查看和管理
|
||||
- 支持版本升级策略（建议更新和强制更新）
|
||||
- 确保配置文件的加密存储和CDN缓存同步
|
||||
- 提供直观的配置对比功能
|
||||
|
||||
在仓库根目录执行：
|
||||
## 系统架构
|
||||
|
||||
```bash
|
||||
uv tool run --from . config-man --help
|
||||
uv tool run --from . config-man show-config
|
||||
uv tool run --from . config-man view --version 0.30 --mock
|
||||
### 存储架构
|
||||
```
|
||||
对象存储服务器
|
||||
├── ab/
|
||||
│ ├── 0_29/
|
||||
│ │ ├── androidconfig.json (加密)
|
||||
│ │ └── iosconfig.json (加密)
|
||||
│ ├── 0_30/
|
||||
│ │ ├── androidconfig.json (加密)
|
||||
│ │ └── iosconfig.json (加密)
|
||||
│ └── 1_00/
|
||||
│ ├── androidconfig.json (加密)
|
||||
│ └── iosconfig.json (加密)
|
||||
```
|
||||
|
||||
这种方式适合本地验证和临时使用。
|
||||
### 技术栈
|
||||
- **开发语言**: Python 3.13+
|
||||
- **CLI框架**: Click 或 Typer
|
||||
- **存储同步**: rclone
|
||||
- **CDN服务**: Cloudflare
|
||||
- **文件加密**: AES-256
|
||||
- **配置格式**: JSON
|
||||
|
||||
### 安装为本地工具
|
||||
## 功能说明
|
||||
|
||||
如果需要长期使用，推荐安装：
|
||||
### 功能1: 查看配置文件
|
||||
|
||||
对比显示对象存储和CDN中的配置内容，支持Android和iOS平台。
|
||||
|
||||
```bash
|
||||
uv tool install --from . config-man
|
||||
config-man --help
|
||||
config-man show-config
|
||||
config-man view --version <版本号>
|
||||
```
|
||||
|
||||
卸载和升级：
|
||||
**参数说明**:
|
||||
- `--version`: 版本号，格式为 0.29, 0.30, 0.31 等
|
||||
|
||||
**功能特性**:
|
||||
- 同时显示Android和iOS平台的配置文件
|
||||
- 对比对象存储中的内容和CDN中的内容
|
||||
- 使用表格格式漂亮地展示配置差异
|
||||
- 支持JSON格式化输出
|
||||
|
||||
### 功能2: 建议更新
|
||||
|
||||
在目标版本的配置文件中添加 `Ver_New` 属性，提示用户有新版本可用。
|
||||
|
||||
```bash
|
||||
uv tool upgrade config-man
|
||||
uv tool uninstall config-man
|
||||
config-man suggest-update --platform <平台> --target-version <目标版本> --update-version <更新版本>
|
||||
```
|
||||
|
||||
## 运行前置条件
|
||||
**参数说明**:
|
||||
- `--platform`: 平台类型，支持 android 或 ios
|
||||
- `--target-version`: 目标版本号，如 0.29
|
||||
- `--update-version`: 更新版本号，如 0.30
|
||||
- `--storage-path`: 对象存储路径前缀（覆盖配置文件）
|
||||
- `--cdn-url`: CDN基础URL（覆盖配置文件）
|
||||
- `--mock`: 使用模拟环境进行测试
|
||||
|
||||
- Python 3.9+
|
||||
- `uv`
|
||||
- `rclone`
|
||||
- 可选的 Cloudflare 凭证与网络访问能力
|
||||
**功能特性**:
|
||||
- 在目标版本配置中添加 `Ver_New` 属性
|
||||
- `Ver_New` 的值设为更新版本的 `Ver` 属性值
|
||||
- 自动加密并上传到对象存储
|
||||
- 自动刷新CDN缓存
|
||||
|
||||
`config-man` 的真实存储操作依赖系统中的 `rclone`。如果只是本地验证 CLI，可优先使用 `--mock` 模式。
|
||||
**配置变更示例**:
|
||||
```json
|
||||
// 修改前
|
||||
{
|
||||
"Ver": "0.29.1abc123",
|
||||
"EventApiURL": "https://n3backend.azurewebsites.net/",
|
||||
"PlayFabTitle": "B066F"
|
||||
}
|
||||
|
||||
```bash
|
||||
rclone version
|
||||
// 修改后
|
||||
{
|
||||
"Ver": "0.29.1abc123",
|
||||
"Ver_New": "0.30.1def456",
|
||||
"EventApiURL": "https://n3backend.azurewebsites.net/",
|
||||
"PlayFabTitle": "B066F"
|
||||
}
|
||||
```
|
||||
|
||||
## 常用命令
|
||||
|
||||
### 查看配置
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
config-man view --version 0.30 --mock
|
||||
config-man view --version 0.30 --json --mock
|
||||
```
|
||||
# 基本用法
|
||||
config-man suggest-update --platform android --target-version 0.29 --update-version 0.30
|
||||
|
||||
### 建议更新
|
||||
# 指定存储路径和CDN URL
|
||||
config-man suggest-update --platform ios --target-version 0.29 --update-version 0.30 --storage-path custom/path --cdn-url https://custom.cdn.com
|
||||
|
||||
```bash
|
||||
# 使用模拟环境测试
|
||||
config-man suggest-update --platform android --target-version 0.29 --update-version 0.30 --mock
|
||||
```
|
||||
|
||||
### 强制更新
|
||||
### 功能3: 强制更新
|
||||
|
||||
直接更新目标版本的 `Ver` 属性，强制用户升级到新版本。
|
||||
|
||||
```bash
|
||||
config-man force-update --platform ios --target-version 0.29 --update-version 0.30 --mock
|
||||
config-man force-update --platform <平台> --target-version <目标版本> --update-version <更新版本>
|
||||
```
|
||||
|
||||
### 查看和写入本地配置
|
||||
**参数说明**:
|
||||
- `--platform`: 平台类型，支持 android 或 ios
|
||||
- `--target-version`: 目标版本号，如 0.29
|
||||
- `--update-version`: 更新版本号，如 0.30
|
||||
|
||||
## 配置文件结构
|
||||
|
||||
### 配置项说明
|
||||
```json
|
||||
{
|
||||
"EventApiURL": "https://n3backend.azurewebsites.net/",
|
||||
"Ver": "0.28.2ece920695",
|
||||
"PlayFabTitle": "B066F",
|
||||
"Google_Play_URL": "https://play.google.com/store/apps/details?id=com.arkgame.ft",
|
||||
"APP_Store_URL": "https://apps.apple.com/us/app/id6505145935",
|
||||
"HeartBeat": "60",
|
||||
"RTMPid": "80000586",
|
||||
"RTMServerEndpoint": "rtm-intl-frontgate.ilivedata.com:13321",
|
||||
"RTMHmacSecret": "57047697437f4f2c97a835e8d9a53358",
|
||||
"FuncUrl": "https://leaderboardcreate.azurewebsites.net",
|
||||
"FuncKey": "R5kU45fNBRd52Eqp3tEqfpZqrbFw53uSSEo7wraUSqIfAzFuRmLm_w=="
|
||||
}
|
||||
```
|
||||
|
||||
### 配置项分类
|
||||
- **API端点**: EventApiURL, FuncUrl
|
||||
- **版本信息**: Ver, Ver_New
|
||||
- **应用商店链接**: Google_Play_URL, APP_Store_URL
|
||||
- **实时通信**: RTMPid, RTMServerEndpoint, RTMHmacSecret
|
||||
- **功能配置**: PlayFabTitle, HeartBeat, FuncKey
|
||||
|
||||
## 技术要求
|
||||
|
||||
### 安全要求
|
||||
- 配置文件在对象存储中加密存储
|
||||
- 支持AES-256加密算法
|
||||
- 加密密钥安全管理
|
||||
- 操作日志记录
|
||||
|
||||
### 性能要求
|
||||
- 配置文件查看响应时间 < 3秒
|
||||
- 配置文件修改响应时间 < 5秒
|
||||
- CDN缓存刷新响应时间 < 10秒
|
||||
|
||||
### 兼容性要求
|
||||
- 支持Python 3.13+
|
||||
- 支持Windows、macOS、Linux
|
||||
- 支持rclone命令行工具
|
||||
|
||||
## 安装和使用
|
||||
|
||||
### 安装依赖
|
||||
```bash
|
||||
config-man show-config
|
||||
config-man set-config --key storage.path --value ab
|
||||
config-man set-config --key storage.rclone_remote --value remote
|
||||
config-man setup-cloudflare --api-token <token> --zone-id <zone_id>
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 附加命令
|
||||
|
||||
项目还提供交互式加密命令：
|
||||
|
||||
### 配置环境
|
||||
```bash
|
||||
uv tool run --from . config-man-encrypt
|
||||
# 配置rclone
|
||||
rclone config
|
||||
|
||||
# 配置Cloudflare CDN（可选）
|
||||
export CLOUDFLARE_API_TOKEN=your_api_token
|
||||
export CLOUDFLARE_ZONE_ID=your_zone_id
|
||||
```
|
||||
|
||||
## 配置加载规则
|
||||
|
||||
配置优先级如下：
|
||||
|
||||
1. 命令行参数
|
||||
2. 环境变量
|
||||
3. 用户配置文件 `~/.config/config-man/config-man.json`
|
||||
4. 项目默认配置
|
||||
|
||||
相关环境变量包括：
|
||||
|
||||
### 使用示例
|
||||
```bash
|
||||
export CONFIG_MAN_STORAGE_PATH=ab
|
||||
export CONFIG_MAN_STORAGE_RCLONE_REMOTE=remote
|
||||
export CONFIG_MAN_CDN_BASE_URL=https://cdn.example.com
|
||||
export CONFIG_MAN_CDN_CLOUDFLARE_API_TOKEN=your_api_token
|
||||
export CONFIG_MAN_CDN_CLOUDFLARE_ZONE_ID=your_zone_id
|
||||
# 查看配置
|
||||
config-man view --version 0.30
|
||||
|
||||
# 建议更新（自动刷新CDN缓存）
|
||||
config-man suggest-update --platform android --target-version 0.29 --update-version 0.30
|
||||
|
||||
# 强制更新
|
||||
config-man force-update --platform ios --target-version 0.29 --update-version 0.30
|
||||
```
|
||||
|
||||
## 存储结构
|
||||
### Cloudflare CDN 配置
|
||||
|
||||
对象存储中的目标结构大致如下：
|
||||
Config-Man 支持 Cloudflare CDN 缓存自动刷新。详细设置请参考：[Cloudflare CDN 设置指南](docs/cloudflare_setup.md)
|
||||
|
||||
```text
|
||||
ab/
|
||||
├── 0_29/
|
||||
│ ├── androidconfig.json
|
||||
│ └── iosconfig.json
|
||||
├── 0_30/
|
||||
│ ├── androidconfig.json
|
||||
│ └── iosconfig.json
|
||||
└── 1_00/
|
||||
├── androidconfig.json
|
||||
└── iosconfig.json
|
||||
```
|
||||
## 错误处理
|
||||
|
||||
版本号会自动从 `0.30` 转换为 `0_30` 这种路径形式。
|
||||
### 常见错误场景
|
||||
- 版本号不存在
|
||||
- 平台类型错误
|
||||
- 网络连接失败
|
||||
- 文件加密/解密失败
|
||||
- CDN刷新失败
|
||||
|
||||
## 构建与发布
|
||||
|
||||
如果你希望他人可以直接执行 `uv tool install config-man`，需要先构建并发布到包索引。
|
||||
|
||||
本地构建：
|
||||
|
||||
```bash
|
||||
uv build
|
||||
```
|
||||
|
||||
构建后的快速验证：
|
||||
|
||||
```bash
|
||||
uv tool run --from dist/*.whl config-man --help
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- `docs/uv-tool.md`: 面向 `uv tool` 的安装、配置、验证与发布说明
|
||||
- `docs/USAGE.md`: `view` 命令和配置方式说明
|
||||
- `docs/cloudflare_setup.md`: Cloudflare 配置说明
|
||||
- `PROJECT_STRUCTURE.md`: 项目结构与开发流程
|
||||
### 错误处理策略
|
||||
- 提供清晰的错误信息
|
||||
- 支持重试机制
|
||||
- 记录详细的操作日志
|
||||
- 提供回滚功能
|
||||
|
||||
Reference in New Issue
Block a user