# UVM (UV镜像源管理工具) 使用文档

## 🚀 快速开始

### 安装

```bash
# 安装UVM
pip install uvm

# 或从源码安装
git clone https://github.com/your-org/uvm.git
cd uvm
pip install -e .
```

### 基础使用

```bash
# 查看帮助
uvm --help
# 或使用简写
uvm -h

# 列出所有可用镜像源
uvm list
# 或使用简写
uvm ls

# 切换到清华大学镜像源
uvm use tsinghua
# 或使用简写
uvm u tsinghua

# 查看当前使用的镜像源
uvm current
# 或使用简写
uvm cur

# 测试镜像源速度
uvm test
# 或使用简写***
uvm t
```

## 📋 完整命令参考

### 命令简写对照表

| 完整命令 | 简写命令 | 功能描述 |
|---------|---------|---------|
| `uvm list` | `uvm ls` | 列出所有可用的镜像源 |
| `uvm current` | `uvm cur` | 显示当前使用的镜像源 |
| `uvm use <name>` | `uvm u <name>` | 切换到指定的镜像源 |
| `uvm test` | `uvm t` | 测试镜像源速度并排序 |
| `uvm reset` | `uvm r` | 恢复到官方默认镜像源 |
| `uvm add` | `uvm a` | 添加自定义镜像源 |
| `uvm remove` | `uvm rm` | 删除自定义镜像源 |
| `uvm search` | `uvm s` | 搜索镜像源 |
| `uvm --help` | `uvm -h` | 显示帮助信息 |
| `uvm --version` | `uvm -v` | 显示版本信息 |

> 💡 **提示**: 所有简写命令与完整命令功能完全相同，可以根据个人习惯选择使用。

### 1. 基础命令

#### `uvm list` - 列出镜像源
```bash
# 列出所有镜像源
uvm list
# 或使用简写
uvm ls

# 输出示例：
┌─────────────────────────────────────────────────────────────────────┐
│                         可用镜像源                              │
├──────┬─────────────┬──────────────────────────────────────┬──────┬────────┐
│ 状态 │    名称     │                  URL                   │ 地区 │ 类型  │
├──────┼─────────────┼──────────────────────────────────────┼──────┼────────┤
│  👉  │ tsinghua    │ https://pypi.tuna.tsinghua.edu.cn/simple │ CN   │ 内置  │
│      │ official    │ https://pypi.org/simple                 │ US   │ 内置  │
│      │ aliyun      │ https://mirrors.aliyun.com/pypi/simple   │ CN   │ 内置  │
└──────┴─────────────┴──────────────────────────────────────┴──────┴────────┘
```

#### `uvm current` - 查看当前镜像源
```bash
uvm current
# 或使用简写
uvm cur

# 输出示例：
📍 当前镜像源: tsinghua
🔗 URL: https://pypi.tuna.tsinghua.edu.cn/simple
📝 描述: 清华大学镜像源
```

#### `uvm use <name>` - 切换镜像源
```bash
# 切换到指定镜像源
uvm use tsinghua
uvm use aliyun
uvm use official

# 使用简写
uvm u tsinghua
uvm u aliyun
uvm u official

# 大小写不敏感
uvm use TSINGHUA
uvm use TsingHua

# 输出示例：
✅ 已切换到镜像源: tsinghua
🔗 URL: https://pypi.tuna.tsinghua.edu.cn/simple
```

#### `uvm test` - 测试镜像源速度
```bash
# 测试所有镜像源速度
uvm test
# 或使用简写
uvm t

# 不使用缓存
uvm test --no-cache
uvm t --no-cache

# 设置超时时间（秒）
uvm test --timeout 10
uvm t --timeout 10

# 输出示例：
🚀 开始测试镜像源速度...
测试 10 个镜像源
┌───┬─────────────┬──────────────────────────────────────┬─────────┬──────────┐
│ # │    名称     │                  URL                   │   时间  │  状态    │
├───┼─────────────┼──────────────────────────────────────┼─────────┼──────────┤
│ 1 │ tsinghua    │ https://pypi.tuna.tsinghua.edu.cn/simple │ 0.234s  │ ✅      │
│ 2 │ aliyun      │ https://mirrors.aliyun.com/pypi/simple   │ 0.456s  │ ✅      │
│ 3 │ official    │ https://pypi.org/simple                 │ 2.123s  │ ✅      │
└───┴─────────────┴──────────────────────────────────────┴─────────┴──────────┘

🏆 推荐镜像源 (前3名):
  1. tsinghua - 0.234s
  2. aliyun - 0.456s
  3. official - 2.123s
```

#### `uvm reset` - 恢复官方源
```bash
uvm reset
# 或使用简写
uvm r

# 确认提示：
⚠️  即将恢复到官方默认镜像源
确定要继续吗？ [y/N]: y
✅ 已恢复到官方默认镜像源
```

### 2. 自定义镜像源管理

#### `uvm add` - 添加自定义镜像源
```bash
# 基础用法
uvm add company https://pypi.company.com/simple
# 或使用简写
uvm a company https://pypi.company.com/simple

# 添加描述
uvm add company https://pypi.company.com/simple --description "公司内部镜像源"
uvm a company https://pypi.company.com/simple --description "公司内部镜像源"

# 指定地区
uvm add company https://pypi.company.com/simple --region US
uvm a company https://pypi.company.com/simple --region US

# 完整示例
uvm add company https://pypi.company.com/simple \
  --description "公司内部高速镜像源" \
  --region CN

# 使用简写的完整示例
uvm a company https://pypi.company.com/simple \
  --description "公司内部高速镜像源" \
  --region CN

# 输出示例：
✅ 已添加自定义镜像源: company
🔗 URL: https://pypi.company.com/simple
📝 描述: 公司内部镜像源
```

#### `uvm remove` - 删除自定义镜像源
```bash
# 删除自定义镜像源
uvm remove company
# 或使用简写
uvm rm company

# 确认提示：
⚠️  即将删除自定义镜像源: company
确定要继续吗？ [y/N]: y
✅ 已删除自定义镜像源: company
```

#### `uvm search` - 搜索镜像源
```bash
# 按名称搜索
uvm search tsinghua
# 或使用简写
uvm s tsinghua

# 按描述搜索
uvm search 清华
uvm s 清华

# 按地区搜索
uvm search CN
uvm s CN

# 输出示例：
🔍 搜索结果: 'tsinghua' (2 个)
┌──────┬─────────────┬──────────────────────────────────────┬──────┬────────┐
│ 状态 │    名称     │                  URL                   │ 地区 │ 类型  │
├──────┼─────────────┼──────────────────────────────────────┼──────┼────────┤
│      │ tsinghua    │ https://pypi.tuna.tsinghua.edu.cn/simple │ CN   │ 内置  │
└──────┴─────────────┴──────────────────────────────────────┴──────┴────────┘
```

### 3. 版本和帮助信息

```bash
# 查看版本
uvm --version
# 或
uvm -v

# 查看帮助
uvm --help

# 查看子命令帮助
uvm list --help
uvm use --help
```

## 🏢 企业级使用场景

### 1. 开发环境配置

#### 项目初始化脚本
```bash
#!/bin/bash
# setup-dev.sh

echo "🚀 配置开发环境..."

# 安装依赖
pip install uv uvm

# 配置公司镜像源
uvm add company https://pypi.company.com/simple \
  --description "公司内部镜像源" \
  --region CN

# 切换到公司镜像源
uvm use company

# 验证配置
uvm current

echo "✅ 开发环境配置完成！"
```

#### 团队配置文件
```toml
# team-config.toml
[project]
name = "my-project"
preferred_mirror = "company"

[mirrors.company]
url = "https://pypi.company.com/simple"
description = "公司内部镜像源"
region = "CN"
priority = 1

[mirrors.backup]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
description = "备用镜像源"
region = "CN"
priority = 2
```

### 2. CI/CD 集成

#### GitHub Actions 配置
```yaml
# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.8, 3.9, 3.10, 3.11, 3.12]

    steps:
    - uses: actions/checkout@v3

    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}

    - name: Install UV
      run: |
        curl -LsSf https://astral.sh/uv/install.sh | sh

    - name: Install UVM
      run: pip install uvm

    - name: Configure mirror
      run: |
        uvm use tsinghua  # 使用国内镜像加速依赖安装

    - name: Install dependencies
      run: |
        uv pip install -r requirements.txt

    - name: Run tests
      run: pytest
```

#### Jenkins Pipeline
```groovy
pipeline {
    agent any

    stages {
        stage('Setup') {
            steps {
                sh 'pip install uv uvm'
                sh 'uvm use tsinghua'
            }
        }

        stage('Install') {
            steps {
                sh 'uv pip install -r requirements.txt'
            }
        }

        stage('Test') {
            steps {
                sh 'pytest'
            }
        }
    }
}
```

### 3. Docker 环境配置

#### Dockerfile 优化
```dockerfile
FROM python:3.11-slim

# 安装UV和UVM
RUN pip install uv uvm

# 配置镜像源
RUN uvm use tsinghua

# 复制依赖文件
COPY requirements.txt .

# 安装依赖（使用配置的镜像源）
RUN uv pip install -r requirements.txt

# 复制应用代码
COPY . .

# 运行应用
CMD ["python", "app.py"]
```

#### docker-compose 配置
```yaml
version: '3.8'

services:
  app:
    build: .
    environment:
      - PYTHONUNBUFFERED=1
    volumes:
      - .:/app
    working_dir: /app
    command: python app.py

  init:
    image: python:3.11-slim
    volumes:
      - .:/app
    working_dir: /app
    command: |
      bash -c "
        pip install uv uvm &&
        uvm use tsinghua &&
        uv pip install -r requirements.txt
      "
```

## 🔧 高级配置

### 1. 配置文件位置

UVM 使用以下配置文件：

#### UV配置文件
- **Linux/macOS**: `~/.config/uv/uv.toml`
- **Windows**: `%APPDATA%\uv\uv.toml`

#### UVM配置文件
- **Linux/macOS**: `~/.config/uv-mirror/config.toml`
- **Windows**: `%APPDATA%\uv-mirror\config.toml`

#### 缓存文件
- **位置**: `~/.cache/uv-mirror/.uvm-cache.json`

### 2. 手动配置

#### 编辑UV配置
```bash
# 查看当前配置
cat ~/.config/uv/uv.toml

# 手动编辑
vim ~/.config/uv/uv.toml
```

配置示例：
```toml
[uv]
index_url = "https://pypi.tuna.tsinghua.edu.cn/simple"
timeout = 30
```

#### 编辑UVM配置
```bash
# 查看自定义镜像源
cat ~/.config/uv-mirror/config.toml
```

配置示例：
```toml
[meta]
version = 1

[mirrors.custom]
company = "https://pypi.company.com/simple"
backup = "https://pypi.tuna.tsinghua.edu.cn/simple"
```

### 3. 环境变量

```bash
# 设置UV配置目录
export UV_CONFIG_DIR="$HOME/.config/uv"

# 设置UVM配置目录
export UVM_CONFIG_DIR="$HOME/.config/uv-mirror"

# 临时禁用网络（测试用）
export UVM_OFFLINE=1
```

## 🚨 故障排除

### 1. 常见问题

#### 镜像源无法访问
```bash
# 测试镜像源连通性
uvm test

# 如果测试失败，尝试其他镜像源
uvm use aliyun
uvm use official

# 检查网络连接
curl -I https://pypi.tuna.tsinghua.edu.cn/simple
```

#### 配置文件损坏
```bash
# 重置配置
uvm reset

# 手动删除配置文件
rm ~/.config/uv/uv.toml
rm ~/.config/uv-mirror/config.toml

# 重新配置
uvm use tsinghua
```

#### 权限问题
```bash
# 检查配置目录权限
ls -la ~/.config/uv/
ls -la ~/.config/uv-mirror/

# 修复权限
chmod 755 ~/.config/uv/
chmod 644 ~/.config/uv/uv.toml
```

### 2. 调试模式

#### 启用详细日志
```bash
# 查看详细错误信息
uvm list --verbose
uvm use tsinghua --verbose

# 查看调试信息
uvm --debug list
```

#### 手动测试
```bash
# 测试UV配置
uv pip install --dry-run requests

# 测试镜像源URL
curl -s https://pypi.tuna.tsinghua.edu.cn/simple/requests/ | head -20
```

### 3. 性能优化

#### 缓存管理
```bash
# 清除UVM缓存
rm ~/.cache/uv-mirror/.uvm-cache.json

# 强制重新测试
uvm test --no-cache

# 查看缓存状态
ls -la ~/.cache/uv-mirror/
```

#### 并发设置
```bash
# 设置并发数（在测试时）
UVM_MAX_CONCURRENT=10 uvm test
```

## 📚 最佳实践

### 1. 开发工作流

```bash
# 1. 项目初始化
git clone <project>
cd <project>
pip install uv uvm

# 2. 配置镜像源
uvm use tsinghua  # 或公司内部源

# 3. 安装依赖
uv pip install -r requirements.txt

# 4. 定期测试镜像源
uvm test

# 5. 根据测试结果切换最优源
uvm use <fastest-mirror>
```

### 2. 团队协作

#### 共享配置脚本
```bash
#!/bin/bash
# setup-team.sh

# 团队标准配置
MIRRORS=(
    "company:https://pypi.company.com/simple:公司内部源"
    "tsinghua:https://pypi.tuna.tsinghua.edu.cn/simple:清华大学源"
    "aliyun:https://mirrors.aliyun.com/pypi/simple:阿里云源"
)

for mirror in "${MIRRORS[@]}"; do
    IFS=':' read -r name url desc <<< "$mirror"
    uvm add "$name" "$url" --description "$desc"
done

# 设置默认源
uvm use company
```

#### 文档更新
```markdown
# 项目README.md

## 环境配置

1. 安装工具：
   ```bash
   pip install uv uvm
   ```

2. 配置镜像源：
   ```bash
   uvm use company  # 公司内部源
   # 备用源：uvm use tsinghua
   ```

3. 验证配置：
   ```bash
   uvm current
   uvm test
   ```
```

### 3. 监控和维护

#### 定期检查脚本
```bash
#!/bin/bash
# check-mirrors.sh

echo "🔍 检查镜像源状态..."

# 测试所有镜像源
uvm test --timeout 10

# 检查当前源
echo "当前镜像源："
uvm current

# 建议最优源
echo "推荐使用最快的镜像源"
```

#### 自动化维护
```bash
# 添加到crontab，每周检查一次
# 0 9 * * 1 /path/to/check-mirrors.sh >> /var/log/mirror-check.log 2>&1
```

## 📖 进阶使用

### 1. 脚本集成

#### Python脚本中使用UVM
```python
import subprocess
import sys

def setup_mirror(mirror_name):
    """设置镜像源"""
    try:
        result = subprocess.run(['uvm', 'use', mirror_name],
                              capture_output=True, text=True, check=True)
        print(f"✅ 已切换到镜像源: {mirror_name}")
        return True
    except subprocess.CalledProcessError as e:
        print(f"❌ 切换镜像源失败: {e}")
        return False

def test_mirrors():
    """测试所有镜像源"""
    try:
        result = subprocess.run(['uvm', 'test'],
                              capture_output=True, text=True, check=True)
        print(result.stdout)
        return True
    except subprocess.CalledProcessError as e:
        print(f"❌ 测试失败: {e}")
        return False

if __name__ == "__main__":
    # 使用示例
    setup_mirror("tsinghua")
    test_mirrors()
```

### 2. 配置模板

#### 企业标准配置
```bash
#!/bin/bash
# enterprise-setup.sh

# 公司镜像源配置
COMPANY_MIRROR="https://pypi.company.com/simple"
BACKUP_MIRROR="https://pypi.tuna.tsinghua.edu.cn/simple"

# 添加公司镜像源
uvm add company "$COMPANY_MIRROR" \
  --description "公司内部镜像源" \
  --region CN

# 设置公司源为默认
uvm use company

# 验证配置
echo "配置验证："
uvm current

# 测试连通性
echo "连通性测试："
uvm test --timeout 5
```

### 3. 多环境管理

#### 开发/测试/生产环境
```bash
#!/bin/bash
# env-setup.sh

ENVIRONMENT=${1:-development}

case $ENVIRONMENT in
  "development")
    uvm use tsinghua
    echo "✅ 开发环境：使用清华大学镜像源"
    ;;
  "testing")
    uvm use company
    echo "✅ 测试环境：使用公司镜像源"
    ;;
  "production")
    uvm use official
    echo "✅ 生产环境：使用官方镜像源"
    ;;
  *)
    echo "❌ 未知环境: $ENVIRONMENT"
    echo "支持的环境: development, testing, production"
    exit 1
    ;;
esac

uvm current
```

---

## 📞 获取帮助

- **项目文档**: https://github.com/your-org/uvm
- **问题反馈**: https://github.com/your-org/uvm/issues
- **讨论社区**: https://github.com/your-org/uvm/discussions

如有问题，请查看故障排除部分或提交Issue。