Files

tianbo.shan 1bc74cbd1b Revert "[U] Wrap into uv tool."

This reverts commit ca9e32763e.

2026-04-15 13:05:45 +08:00

7.1 KiB

Raw Permalink Blame History

Config-Man CLI 工具需求文档

1. 项目概述

1.1 项目背景

开发一个Python CLI工具，用于管理存储在对象存储中的加密静态资源配置文件。该工具支持多版本管理，通过Cloudflare CDN进行分发，主要用于游戏应用的配置管理。

1.2 项目目标

简化多版本配置文件的查看和管理
支持版本升级策略（建议更新和强制更新）
确保配置文件的加密存储和CDN缓存同步
提供直观的配置对比功能

2. 系统架构

2.1 存储架构

对象存储服务器
├── ab/
│   ├── 0_29/
│   │   ├── androidconfig.json (加密)
│   │   └── iosconfig.json (加密)
│   ├── 0_30/
│   │   ├── androidconfig.json (加密)
│   │   └── iosconfig.json (加密)
│   └── 1_00/
│       ├── androidconfig.json (加密)
│       └── iosconfig.json (加密)

2.2 技术栈

开发语言: Python 3.13+
CLI框架: Click 或 Typer
存储同步: rclone
CDN服务: Cloudflare
文件加密: AES-256
配置格式: JSON

3. 功能需求

3.1 功能1: 查看配置文件

3.1.1 功能描述

对比显示对象存储和CDN中的配置内容，支持Android和iOS平台。

3.1.2 命令行格式

config-man view --version <版本号>

3.1.3 参数说明

--version: 版本号，格式为 0.29, 0.30, 0.31 等

3.1.4 功能特性

同时显示Android和iOS平台的配置文件
对比对象存储中的内容和CDN中的内容
使用表格格式漂亮地展示配置差异
支持JSON格式化输出

3.1.5 输出示例

版本: 0.30
平台: Android
┌─────────────────┬─────────────────────┬─────────────────────┐
│ 配置项          │ 对象存储内容        │ CDN内容             │
├─────────────────┼─────────────────────┼─────────────────────┤
│ Ver             │ 0.30.1abc123       │ 0.30.1abc123       │
│ EventApiURL     │ https://...        │ https://...        │
│ PlayFabTitle    │ B066F              │ B066F              │
│ ...             │ ...                 │ ...                 │
└─────────────────┴─────────────────────┴─────────────────────┘

平台: iOS
┌─────────────────┬─────────────────────┬─────────────────────┐
│ 配置项          │ 对象存储内容        │ CDN内容             │
├─────────────────┼─────────────────────┼─────────────────────┤
│ Ver             │ 0.30.1def456       │ 0.30.1def456       │
│ ...             │ ...                 │ ...                 │
└─────────────────┴─────────────────────┴─────────────────────┘

3.2 功能2: 建议更新

3.2.1 功能描述

在目标版本的配置文件中添加 Ver_New 属性，提示用户有新版本可用。

3.2.2 命令行格式

config-man suggest-update --platform <平台> --target-version <目标版本> --update-version <更新版本>

3.2.3 参数说明

--platform: 平台类型，支持 android 或 ios
--target-version: 目标版本号，如 0.29
--update-version: 更新版本号，如 0.30

3.2.4 功能特性

在目标版本配置中添加 Ver_New 属性
Ver_New 的值设为更新版本的 Ver 属性值
自动加密并上传到对象存储
自动刷新CDN缓存

3.2.5 配置变更示例

// 修改前
{
  "Ver": "0.29.1abc123",
  "EventApiURL": "https://n3backend.azurewebsites.net/",
  "PlayFabTitle": "B066F"
}

// 修改后
{
  "Ver": "0.29.1abc123",
  "Ver_New": "0.30.1def456",
  "EventApiURL": "https://n3backend.azurewebsites.net/",
  "PlayFabTitle": "B066F"
}

3.3 功能3: 强制更新

3.3.1 功能描述

直接更新目标版本的 Ver 属性，强制用户升级到新版本。

3.3.2 命令行格式

config-man force-update --platform <平台> --target-version <目标版本> --update-version <更新版本>

3.3.3 参数说明

--platform: 平台类型，支持 android 或 ios
--target-version: 目标版本号，如 0.29
--update-version: 更新版本号，如 0.30

3.3.4 功能特性

将目标版本的 Ver 属性值改为更新版本的 Ver 属性值
自动加密并上传到对象存储
自动刷新CDN缓存

3.3.5 配置变更示例

// 修改前
{
  "Ver": "0.29.1abc123",
  "EventApiURL": "https://n3backend.azurewebsites.net/",
  "PlayFabTitle": "B066F"
}

// 修改后
{
  "Ver": "0.30.1def456",
  "EventApiURL": "https://n3backend.azurewebsites.net/",
  "PlayFabTitle": "B066F"
}

4. 配置文件结构

4.1 配置项说明

{
  "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=="
}

4.2 配置项分类

API端点: EventApiURL, FuncUrl
版本信息: Ver, Ver_New
应用商店链接: Google_Play_URL, APP_Store_URL
实时通信: RTMPid, RTMServerEndpoint, RTMHmacSecret
功能配置: PlayFabTitle, HeartBeat, FuncKey

5. 技术要求

5.1 安全要求

配置文件在对象存储中加密存储
支持AES-256加密算法
加密密钥安全管理
操作日志记录

5.2 性能要求

配置文件查看响应时间 < 3秒
配置文件修改响应时间 < 5秒
CDN缓存刷新响应时间 < 10秒

5.3 兼容性要求

支持Python 3.13+
支持Windows、macOS、Linux
支持rclone命令行工具

6. 错误处理

6.1 常见错误场景

版本号不存在
平台类型错误
网络连接失败
文件加密/解密失败
CDN刷新失败

6.2 错误处理策略

提供清晰的错误信息
支持重试机制
记录详细的操作日志
提供回滚功能

7. 非功能性需求

7.1 可用性

提供清晰的命令行帮助信息
支持命令自动补全
提供详细的错误提示

7.2 可维护性

模块化设计
完善的日志记录
清晰的代码注释

7.3 可扩展性

支持新的配置文件格式
支持新的存储后端
支持新的CDN服务商

7.1 KiB Raw Permalink Blame History Unescape Escape