186 lines
4.3 KiB
Markdown
186 lines
4.3 KiB
Markdown
# Config-Man 的 UV Tool 用法
|
|
|
|
## 适用场景
|
|
|
|
`config-man` 已经通过 `pyproject.toml` 暴露了 CLI 入口，因此可以直接作为 `uv tool` 使用。
|
|
|
|
- 临时从源码运行，适合验证命令是否可用：`uv tool run --from . config-man ...`
|
|
- 安装为本地长期命令，适合需要持久配置的日常使用：`uv tool install --from . config-man`
|
|
- 发布到包索引后，可直接安装：`uv tool install config-man`
|
|
|
|
## 前置条件
|
|
|
|
使用本工具前，需要准备以下环境：
|
|
|
|
- Python 3.9+
|
|
- `uv`
|
|
- `rclone`
|
|
- 可选的 Cloudflare 凭证，用于自动刷新 CDN 缓存
|
|
|
|
安装 `rclone` 后，请先确认它在系统 `PATH` 中可用：
|
|
|
|
```bash
|
|
rclone version
|
|
```
|
|
|
|
如果命令无法执行，`config-man` 的非 `--mock` 模式也无法正常工作。
|
|
|
|
## 从源码运行
|
|
|
|
在仓库根目录执行：
|
|
|
|
```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
|
|
```
|
|
|
|
这种方式适合：
|
|
|
|
- 快速验证 CLI 是否能启动
|
|
- 本地开发时试跑单个命令
|
|
- 不需要保留用户级配置的临时操作
|
|
|
|
## 本地安装为工具
|
|
|
|
如果你会反复使用 `config-man`，更推荐安装为本地工具：
|
|
|
|
```bash
|
|
uv tool install --from . config-man
|
|
config-man --help
|
|
config-man show-config
|
|
```
|
|
|
|
常见维护命令：
|
|
|
|
```bash
|
|
uv tool upgrade config-man
|
|
uv tool uninstall config-man
|
|
```
|
|
|
|
安装后更适合使用以下会写入本地配置的命令：
|
|
|
|
```bash
|
|
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>
|
|
```
|
|
|
|
## 配置来源优先级
|
|
|
|
运行时配置优先级如下：
|
|
|
|
1. 命令行参数
|
|
2. 环境变量
|
|
3. 用户配置文件 `~/.config/config-man/config-man.json`
|
|
4. 项目默认配置
|
|
|
|
默认用户配置文件路径由 `src/config_man/utils/config.py` 定义；执行 `set-config` 和 `setup-cloudflare` 后，配置会保存到该文件。
|
|
|
|
## 常用环境变量
|
|
|
|
如果你不想把配置写入文件，可以使用环境变量：
|
|
|
|
```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
|
|
```
|
|
|
|
Windows PowerShell 可使用：
|
|
|
|
```powershell
|
|
$env:CONFIG_MAN_STORAGE_PATH="ab"
|
|
$env:CONFIG_MAN_STORAGE_RCLONE_REMOTE="remote"
|
|
$env:CONFIG_MAN_CDN_BASE_URL="https://cdn.example.com"
|
|
$env:CONFIG_MAN_CDN_CLOUDFLARE_API_TOKEN="your_api_token"
|
|
$env:CONFIG_MAN_CDN_CLOUDFLARE_ZONE_ID="your_zone_id"
|
|
```
|
|
|
|
## 命令示例
|
|
|
|
### 查看配置
|
|
|
|
```bash
|
|
config-man view --version 0.30 --mock
|
|
config-man view --version 0.30 --json --mock
|
|
```
|
|
|
|
### 建议更新
|
|
|
|
```bash
|
|
config-man suggest-update --platform android --target-version 0.29 --update-version 0.30 --mock
|
|
```
|
|
|
|
### 强制更新
|
|
|
|
```bash
|
|
config-man force-update --platform ios --target-version 0.29 --update-version 0.30 --mock
|
|
```
|
|
|
|
### 查看当前生效配置
|
|
|
|
```bash
|
|
config-man show-config
|
|
```
|
|
|
|
### 交互式加密原始配置
|
|
|
|
项目还提供一个附加命令：
|
|
|
|
```bash
|
|
uv tool run --from . config-man-encrypt
|
|
```
|
|
|
|
该命令为交互式脚本，更适合作为辅助工具，而不是主入口。
|
|
|
|
## 验证建议
|
|
|
|
建议至少验证以下命令：
|
|
|
|
```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
|
|
```
|
|
|
|
如果你计划长期使用，再验证安装后的行为：
|
|
|
|
```bash
|
|
uv tool install --from . config-man
|
|
config-man --help
|
|
config-man show-config
|
|
```
|
|
|
|
同时建议手动确认：
|
|
|
|
- `rclone` 在 tool 环境下可以被正常找到
|
|
- Cloudflare 相关配置能够从环境变量或配置文件加载
|
|
- 非 `--mock` 模式在目标网络环境中可访问对象存储与 CDN
|
|
|
|
## 构建与发布
|
|
|
|
如果目标是让其他人直接执行 `uv tool install config-man`，还需要先把包发布到索引。
|
|
|
|
本地构建：
|
|
|
|
```bash
|
|
uv build
|
|
```
|
|
|
|
构建完成后可验证产物：
|
|
|
|
```bash
|
|
uv tool run --from dist/*.whl config-man --help
|
|
```
|
|
|
|
发布到索引后，用户即可通过：
|
|
|
|
```bash
|
|
uv tool install config-man
|
|
```
|
|
|
|
如果当前项目的 `project.urls` 仍是占位地址，请在正式发布前补成真实仓库和文档链接。
|