# PipProxy **Repository Path**: robbershen/PipProxy ## Basic Information - **Project Name**: PipProxy - **Description**: **PipProxy Python安装包缓存服务器**是一个功能完整的Python包缓存代理服务器，专为局域网内的Python开发环境设计。它能够缓存已下载的Python包，为内网用户提供快速、稳定的包下载服务，显著提升团队开发效率。 本项目采用模块化设计，包含GUI管理界面、HTTP服务器、数据库管理、多线程下载、镜像源代理等核心功能，适用于教育机构、企业内网、离线开发环境等场景。 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-31 - **Last Updated**: 2026-03-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # PipProxy Python安装包缓存服务器 ## 📖 项目概述 **PipProxy Python安装包缓存服务器**是一个功能完整的Python包缓存代理服务器，专为局域网内的Python开发环境设计。它能够缓存已下载的Python包，为内网用户提供快速、稳定的包下载服务，显著提升团队开发效率。 本项目采用模块化设计，包含GUI管理界面、HTTP服务器、数据库管理、多线程下载、镜像源代理等核心功能，适用于教育机构、企业内网、离线开发环境等场景。 ## ✨ 核心特性 ### 🚀 高性能缓存 - **智能缓存策略**：自动缓存下载的Python包，避免重复下载 - **多镜像源支持**：内置多个PyPI镜像源，自动故障转移和负载均衡 - **连接池管理**：HTTP连接复用，提升下载效率 - **流式下载**：支持大文件分块下载，降低内存占用 ### 🛡️ 可靠性与安全性 - **数据完整性验证**：支持MD5、SHA256等多种哈希校验 - **安全检查机制**：自动检测恶意包和异常文件 - **访问控制**：IP连接限制和请求频率控制 - **日志审计**：完整的操作日志和性能监控 ### 🖥️ 易用性 - **图形化管理界面**：基于Tkinter的GUI，操作直观简便 - **一键配置**：自动检测网络环境，生成最优配置 - **多种客户端支持**：兼容pip、conda、poetry、pipenv等工具 - **Web界面**：内置Web服务器，支持浏览器访问和包查询 ### 🔧 高级功能 - **包版本管理**：支持多版本共存和版本筛选 - **数据库优化**：SQLite数据库索引优化，快速查询 - **性能监控**：实时监控服务器状态和网络带宽 - **自定义镜像源**：支持添加私有或企业镜像源 ## 📋 系统要求 ### Python版本 - Python 3.7 或更高版本 - **推荐使用 Python 3.9+** ### 操作系统 - ✅ Windows 10/11 - ✅ macOS 10.14+ - ✅ Linux (Ubuntu 18.04+, CentOS 7+) ### 硬件要求 - **内存**：最低512MB，推荐2GB+ - **存储**：根据缓存需求，建议10GB+可用空间 - **网络**：局域网环境，建议100Mbps+网络带宽 ## 🚀 快速开始 ### 安装方法 #### 方法一：从PyPI安装（推荐） #### 方法二：从源码安装 ```bash # 克隆仓库 git clone https://github.com/robbershen/PipProxy.git cd PipProxy # 安装依赖 pip install -r requirements.txt # 安装包 pip install -e . ``` ### 快速启动 #### 启动GUI管理界面 ```bash main.py ``` ### 首次运行配置 首次运行程序时，系统会自动： 1. ✅ 检测本机IP地址 2. ✅ 创建默认配置文件 3. ✅ 初始化数据库 4. ✅ 建立缓存目录结构 ## 📖 详细使用指南 ### GUI界面操作 #### 1. 服务器管理 - **启动服务器**：点击"启动服务器"按钮，服务器将在后台运行 - **停止服务器**：点击"停止服务器"按钮，安全停止服务器 - **重启服务器**：点击"重启服务器"按钮，重启服务进程 - **查看状态**：主界面顶部显示服务器运行状态和基本统计信息 #### 2. 包管理 - **导入本地包**：支持.whl、.tar.gz、.zip等格式的本地包文件 - **远程下载包**：通过包名从镜像源下载指定版本的包 - **包列表管理**：查看、搜索、删除已缓存的包 - **包详情查看**：查看包的版本、大小、哈希值等详细信息 #### 3. 配置管理 - **网络配置**：修改服务器IP地址和端口号 - **缓存配置**：设置缓存目录和最大缓存大小 - **镜像源配置**：添加、删除或修改PyPI镜像源 - **高级配置**：调整线程池大小、超时设置等参数 #### 4. 日志查看 - **实时日志**：监控服务器运行日志 - **日志筛选**：按级别（INFO、WARNING、ERROR等）筛选日志 - **日志导出**：将日志导出为文本文件 - **日志清理**：清理过期的日志文件 #### 管理缓存 ### Web界面访问 启动服务器后，可以通过浏览器访问以下地址： - **主页**：`http://服务器IP:端口/` - **包列表**：`http://服务器IP:端口/simple/` - **包详情**：`http://服务器IP:端口/simple/包名/` - **统计信息**：`http://服务器IP:端口/stats` - **使用示例**：`http://服务器IP:端口/usage_examples.html` ## ⚙️ 配置说明 ### 配置文件位置 - **主配置文件**：`config/config.ini` - **推荐配置**：`config/config_recommended.ini` ### 主要配置项 #### [Server] 服务器配置 ```ini [Server] host = 172.17.187.120 ; 服务器监听地址 port = 8080 ; 服务器端口 cache_dir = ../.data ; 缓存目录 max_cache_size_gb = 10 ; 最大缓存大小（GB） mirrors = https://pypi.tuna.tsinghua.edu.cn/simple,https://mirrors.aliyun.com/pypi/simple/ ; 镜像源列表 thread_pool_size = 16 ; 线程池大小 max_download_workers = 8 ; 最大下载线程数 download_timeout = 3 ; 下载超时时间（秒） idle_timeout = 30 ; 空闲超时时间（秒） max_download_tasks = 200 ; 最大下载任务数 service_unit = ; 服务单位名称 ``` #### [Monitoring] 监控配置 ```ini [Monitoring] enable_bandwidth_monitoring = true ; 启用带宽监控 bandwidth_sampling_interval_seconds = 2 ; 带宽采样间隔 enable_performance_stats = true ; 启用性能统计 stats_history_size = 200 ; 统计历史大小 enable_http_monitoring = true ; 启用HTTP监控 slow_request_threshold_seconds = 1.0 ; 慢请求阈值 ``` #### [RateLimiting] 限流配置 ```ini [RateLimiting] enable_ip_rate_limiting = true ; 启用IP限流 max_connections_per_ip = 20 ; 每个IP最大连接数 max_bandwidth_mbps = 0 ; 最大带宽限制（0表示无限制） rate_limit_algorithm = token_bucket ; 限流算法 token_bucket_capacity = 200 ; 令牌桶容量 token_bucket_refill_rate = 20 ; 令牌桶补充速率 ``` ### 环境变量配置 可以通过环境变量覆盖配置文件中的设置： ```bash export PIPPROXY_HOST=192.168.1.100 export PIPPROXY_PORT=8000 export PIPPROXY_CACHE_DIR=/data/cache ``` ## 🔌 客户端配置 ### pip客户端配置 #### 方法一：设置全局索引源（推荐） ```bash # 设置pip使用缓存服务器作为默认源 pip config set global.index-url http://服务器IP:端口/simple/ # 设置信任该主机 pip config set install.trusted-host 服务器IP # 验证配置 pip config list ``` #### 方法二：临时使用 ```bash # 安装单个包时指定源 pip install 包名 -i http://服务器IP:端口/simple/ --trusted-host 服务器IP # 示例：安装requests包 pip install requests -i http://192.168.1.100:8080/simple/ --trusted-host 192.168.1.100 ``` #### 方法三：使用pip下载包文件 ```bash # 下载包但不安装 pip download 包名 -i http://服务器IP:端口/simple/ --trusted-host 服务器IP --no-deps ``` ### conda客户端配置 编辑`~/.condarc`文件： ```yaml channels: - http://服务器IP:端口/conda/ - defaults custom_channels: http://服务器IP:端口/conda/: custom channel_alias: http://服务器IP:端口/conda/ ``` ### poetry客户端配置 编辑`pyproject.toml`文件： ```toml [[tool.poetry.source]] name = "pip-proxy" url = "http://服务器IP:端口/simple/" secondary = true ``` ### pipenv客户端配置 编辑`Pipfile`文件： ```toml [[source]] url = "http://服务器IP:端口/simple/" verify_ssl = false name = "pip-proxy" ``` ## 📊 性能优化 ### 缓存优化建议 1. **使用SSD存储**：将缓存目录放在SSD上，显著提升读写速度 2. **合理设置缓存大小**：根据磁盘空间和用户数量调整缓存大小 3. **定期清理过期包**：使用`classproxy-cache clear`命令清理旧版本包 4. **启用压缩存储**：对于文本格式的包文件，可以考虑启用压缩 ### 网络优化建议 1. **选择优质镜像源**：优先选择地理位置近、速度快的镜像源 2. **调整线程池大小**：根据服务器硬件配置调整`thread_pool_size` 3. **合理设置超时时间**：根据网络状况调整`download_timeout`参数 4. **启用HTTP Keep-Alive**：减少连接建立的开销 ### 数据库优化建议 1. **定期重建索引**：当包数量较大时，定期优化数据库索引 2. **清理无效记录**：定期清理数据库中无效的包记录 3. **启用WAL模式**：提高SQLite数据库的并发性能 ## 🔧 故障排除 ### 常见问题及解决方案 #### 1. 服务器无法启动 **可能原因**： - 端口被其他程序占用 - 配置文件格式错误 - 权限不足 **解决方案**： ```bash # 检查端口占用 netstat -ano | findstr :8080 # 使用其他端口 classproxy-server --port 8000 # 检查配置文件语法 python -m configparser config/config.ini ``` #### 2. 客户端无法连接 **可能原因**： - 防火墙阻止访问 - 服务器IP地址错误 - 服务器未启动 **解决方案**： ```bash # 检查服务器状态 curl http://服务器IP:端口/stats # 检查防火墙设置 # Windows: 控制面板 -> Windows Defender 防火墙 -> 允许应用通过防火墙 # Linux: sudo ufw allow 8080/tcp # 验证网络连通性 ping 服务器IP ``` #### 3. 包下载失败 **可能原因**： - 镜像源不可用 - 网络连接问题 - 包不存在或拼写错误 **解决方案**： ```bash # 检查镜像源状态 curl https://pypi.tuna.tsinghua.edu.cn/simple/ # 添加备用镜像源 # 编辑config.ini，在mirrors中添加更多镜像源 # 查看详细错误日志 # 在GUI日志窗口或日志文件中查看具体错误信息 ``` #### 4. 缓存空间不足 ### 日志分析 日志文件位于程序运行目录的`logs/`文件夹中，按日期命名（如`2026-01-28.log`）。 日志级别说明： - **DEBUG**：调试信息，用于开发人员排查问题 - **INFO**：普通操作信息，记录正常流程 - **SUCCESS**：成功操作，如包下载完成、服务器启动成功 - **WARNING**：警告信息，需要关注但不会导致程序终止 - **ERROR**：错误信息，可能导致功能异常 - **CRITICAL**：严重错误，可能导致程序崩溃 ## 🏗️ 项目架构 ### 代码结构 ``` PipProxy-CacheServer/ ├── src/ # 源代码目录 │ ├── classproxy/ # 主包 │ │ ├── core/ # 核心模块 │ │ │ ├── server.py # 服务器主逻辑 │ │ │ ├── handler.py # HTTP请求处理器 │ │ │ ├── cache_manager.py # 缓存管理 │ │ │ ├── database.py # 数据库管理 │ │ │ ├── download_manager.py # 下载管理 │ │ │ ├── http_client.py # HTTP客户端 │ │ │ ├── mirror_manager.py # 镜像源管理 │ │ │ └── http_server.py # HTTP服务器封装 │ │ ├── managers/ # 管理模块 │ │ │ ├── config.py # 配置管理 │ │ │ └── log.py # 日志管理 │ │ ├── gui/ # 图形界面 │ │ │ └── main_window.py # 主窗口 │ │ ├── utils/ # 工具模块 │ │ │ ├── common.py # 通用工具 │ │ │ ├── paths.py # 路径处理 │ │ │ ├── port.py # 端口管理 │ │ │ ├── security.py # 安全检查 │ │ │ ├── system.py # 系统工具 │ │ │ └── teacher.py # 教师工具（遗留） │ │ ├── scripts/ # 命令行脚本 │ │ │ ├── start_server.py # 启动服务器 │ │ │ ├── clear_cache.py # 清理缓存 │ │ │ └── list_cache.py # 列出缓存 │ │ ├── client/ # 客户端配置 │ │ │ └── configurator.py # 配置工具 │ │ └── __init__.py # 包初始化 ├── static/ # 静态资源 │ ├── usage_examples.html # 使用示例页面 │ ├── footer_template.html # 页脚模板 │ └── favicon.ico # 网站图标 ├── config/ # 配置文件 │ ├── config.ini # 主配置文件 │ └── config_recommended.ini # 推荐配置 ├── main.py # 程序入口 ├── pyproject.toml # 项目配置 ├── requirements.txt # 依赖列表 └── readme.md # 项目文档 ``` ### 核心模块说明 #### 1. 服务器核心 (server.py) - **PackageCacheServer类**：服务器主控制器 - 管理所有子模块的初始化和协调 - 处理启动、停止、重启等生命周期操作 - 提供统计信息和状态监控 #### 2. HTTP处理器 (handler.py) - **CacheServerHandler类**：HTTP请求处理器 - 支持PyPI简单索引格式（Simple Repository API） - 处理包查询、下载、统计等HTTP请求 - 实现静态文件服务、错误处理等功能 #### 3. 下载管理器 (download_manager.py) - **DownloadManager类**：多线程下载管理器 - 支持并发下载和断点续传 - 镜像源故障转移和负载均衡 - 下载进度监控和性能统计 #### 4. 数据库管理器 (database.py) - **PackageDB类**：SQLite数据库管理 - 包信息存储和检索 - 文件哈希计算和验证 - 数据库索引优化和清理 #### 5. 配置管理器 (config.py) - **ConfigManager类**：线程安全配置管理 - 配置文件读取、验证和保存 - 环境变量支持和配置热加载 - 默认配置生成和错误恢复 ## 🤝 贡献指南 ### 开发环境搭建 1. **克隆仓库** ```bash git clone https://github.com/robbershen/PipProxy.git cd PipProxy ``` 2. **创建虚拟环境** ```bash python -m venv venv source venv/bin/activate # Linux/Mac venv\Scripts\activate # Windows ``` 3. **安装开发依赖** ```bash pip install -e ".[dev]" ``` ### 代码规范 1. **代码风格** - 遵循PEP 8编码规范 - 使用Black进行代码格式化 - 使用Flake8进行代码检查 2. **类型注解** - 所有公共函数和类方法都需要类型注解 - 使用MyPy进行类型检查 3. **文档要求** - 所有公共API都需要文档字符串 - 文档字符串使用Google风格 - 更新相关文档和示例 ### 提交贡献 1. **创建分支** ```bash git checkout -b feature/your-feature-name ``` 2. **提交代码** ```bash git add . git commit -m "feat: 描述你的功能" ``` 3. **代码检查** ```bash # 运行代码格式化 black src/ # 运行代码检查 flake8 src/ # 运行类型检查 mypy src/ # 运行测试 pytest ``` 4. **推送分支** ```bash git push origin feature/your-feature-name ``` ### 提交Pull Request 1. 在GitHub上创建Pull Request 2. 确保所有检查通过 3. 提供详细的描述和测试说明 4. 等待代码审查和合并 ## 🧪 测试 ### 运行测试套件 ```bash # 运行所有测试 pytest # 运行特定测试模块 pytest tests/test_core/ # 生成测试覆盖率报告 pytest --cov=classproxy --cov-report=html ``` ### 测试类型 1. **单元测试**：测试单个函数或类的功能 2. **集成测试**：测试模块之间的协作 3. **功能测试**：测试完整的用户场景 4. **性能测试**：测试系统性能和负载能力 ## 📄 许可证 本项目采用 **MIT许可证** - 详见 [LICENSE](LICENSE) 文件。 ### 许可证摘要 - ✅ 允许商业使用 - ✅ 允许修改和分发 - ✅ 允许私人使用 - ✅ 无责任担保 - ✅ 保留版权声明 ### 第三方库许可证 - **psutil**：BSD许可证 - **packaging**：BSD或Apache许可证 - **requests**：Apache 2.0许可证 ## 📞 联系方式 ### 项目维护者 - **姓名**：沈松华 - **邮箱**：2217847@qq.com - **QQ**：2217847 ### 问题反馈 - **GitHub Issues**：[问题跟踪](https://github.com/yourusername/pip-proxy-server/issues) - **电子邮件**：2217847@qq.com ### 社区支持 - **文档网站**：[待创建] - **QQ群**：[待创建] - **讨论论坛**：[待创建] ## 📈 版本历史 ### v0.1.0 (2026-01-28) - ✅ 初始版本发布 - ✅ 基础缓存功能 - ✅ GUI管理界面 - ✅ 多镜像源支持 - ✅ 数据库管理 ### 开发计划 - [ ] 支持Docker容器化部署 - [ ] 添加REST API接口 - [ ] 实现集群部署 - [ ] 添加WebSocket实时通知 - [ ] 支持更多包管理器（如npm、Maven等） --- **最后更新**：2026-03-24 **版本**：0.1.0 **Python版本**：3.9+ > 💡 **提示**：如果您在使用过程中遇到任何问题，请查阅[使用示例页面](usage_examples.html)或通过联系方式获取帮助。