uproxier 0.1.18

HTTP/HTTPS proxy with rules engine and web UI

UProxier · 代理服务器

基于 mitmproxy 的完整代理软件解决方案，支持 HTTP/HTTPS 代理、请求拦截、规则配置和 Web 界面。

功能特性

• 🔄 HTTP/HTTPS 代理: 完整代理，支持 HTTPS 解密开关（配置或 CLI 覆盖）
• 🛡️ 证书管理: 自动生成/校验/安装 mitmproxy CA 证书
• 📋 规则引擎: 多动作叠加、优先级、命中短路（stop_after_match）
  • mock_response（支持本地文件 file）/ modify_headers / modify_content / redirect
  • modify_response_headers / modify_response_content / modify_status
  • delay_response（真实延迟发送）/ conditional_response（条件分支）
  • 配置继承（extends）支持，相对路径自动解析
• 💾 持久化: 可将抓到的请求以 JSONL 持久化（--save，覆盖模式）
• 🌐 Web 界面: 实时流量、点击行查看详情、搜索、清空，完全离线化
• 🎯 CLI 工具: start/init/cert/version/examples/validate & 静默模式（--silent）
• 📊 抓包控制: 流媒体/大文件开关、阈值与二进制保存控制（通过 config.yaml 配置）
• 🔧 配置管理: 统一配置目录（~/.uproxier/），YAML 配置 + CLI 覆盖
• ✅ 配置验证: 完整的配置验证系统，检查语法、类型、文件存在性等

安装

pip install uproxier

依赖要求

• Python 3.8+
• OpenSSL (用于证书生成)

快速开始

1. 启动代理

uproxier start

首次启动会自动在用户目录生成 ~/.uproxier/certificates/ CA 证书；启动面板将显示证书路径与有效期。

2. 安装证书

Web 界面下载：打开 Web 界面右上角"扫码下载证书"，移动设备用浏览器访问下载链接安装（下载的是 DER 格式，文件名为 uproxier-ca.cer）。

命令行安装：

uproxier cert
# 选择安装到系统，或按提示手动安装

3. 配置代理

在需要抓包的设备/浏览器里设置 HTTP(S) 代理为本机 IP 与启动端口。

使用说明

命令行工具

帮助信息

uproxier --help
uproxier start --help      # 查看启动命令的所有参数
uproxier examples --help   # 查看示例管理命令的所有参数
uproxier cert --help       # 查看证书管理命令的所有参数
uproxier init --help       # 查看初始化命令的所有参数
uproxier info --help       # 查看版本信息命令的所有参数
uproxier validate --help   # 查看配置验证命令的所有参数

全局选项

uproxier --verbose          # 详细输出
uproxier --config <path>    # 指定配置文件路径
uproxier --version          # 显示版本信息

主要命令

启动代理服务器

uproxier start \
  --port 8001 \                   # 代理服务器端口
  --web-port 8002 \               # Web 界面端口
  --config <path> \               # 配置文件路径（可选，默认使用 ~/.uproxier/config.yaml）
  --save ./logs/traffic.jsonl \   # 保存请求数据到文件（JSONL格式）
  --enable-https \                # 启用 HTTPS 解密（覆盖配置）
  --disable-https \               # 禁用 HTTPS 解密（覆盖配置）
  --silent                        # 静默模式，不输出任何信息
  --daemon                        # 后台模式启动

证书管理

uproxier cert                     # 管理证书（生成、安装、清理）

服务器控制

uproxier status             # 查看服务器状态
uproxier stop               # 停止后台运行的服务器

初始化配置

uproxier init --config <path>                 # 指定配置文件路径

版本信息

uproxier info               # 显示版本信息

配置验证

uproxier validate <config_file>                    # 验证配置文件
uproxier validate <config_file> --validate-only    # 只进行验证，不生成完整报告
uproxier validate <config_file> --format json      # 输出 JSON 格式报告
uproxier validate <config_file> --output report.txt # 保存报告到文件

规则示例管理

uproxier examples --list                    # 列出所有可用示例
uproxier examples --readme                  # 显示示例说明文档
uproxier examples --show <文件名>           # 显示指定示例内容
uproxier examples --copy <文件名>           # 复制示例到当前目录

API 使用

UProxier 提供了完整的 Python API，支持阻塞和非阻塞两种启动方式。

快速示例

阻塞启动：

from uproxier.proxy_server import ProxyServer

proxy = ProxyServer("config.yaml")
proxy.start(8001, 8002)  # 阻塞启动，监听 0.0.0.0:8001

异步启动：

from uproxier.proxy_server import ProxyServer

proxy = ProxyServer("config.yaml", silent=True)
proxy.start_async(8001, 8002)  # 非阻塞启动，监听 0.0.0.0:8001
# 继续执行其他代码...
proxy.stop()

详细文档

完整的 API 使用指南请参考：API_USAGE.md

包含：

• 阻塞启动 vs 异步启动的使用场景
• 完整的参数说明和示例
• 进程管理和状态检查
• 错误处理和最佳实践
• 测试和自动化场景示例

规则配置

项目支持在 config.yaml 中定义规则，包含请求/响应修改、Mock、延迟等。

基本规则结构

- name: 规则名称
  enabled: true
  priority: 100
  stop_after_match: false
  match:
    host: "^api\\.example\\.com$"
    path: "^/v1/data$"
    method: "GET"
  request_pipeline: []  # 请求阶段动作
  response_pipeline:    # 响应阶段动作
    - action: mock_response
      params:
        status_code: 200
        content: '{"status": "success"}'

常用动作

请求阶段 (request_pipeline)

• set_header: 设置请求头
• remove_header: 删除请求头
• rewrite_url: URL 重写
• redirect: 重定向请求

响应阶段 (response_pipeline)

• mock_response: 完全替换响应
• set_status: 设置状态码
• set_header: 设置响应头
• replace_body: 响应体替换
• delay: 延迟响应

查看示例

uproxier examples --list          # 列出所有示例
uproxier examples --readme        # 查看示例说明
uproxier examples --copy 01_set_header.yaml  # 复制示例

Web 界面

访问 http://<本机IP>:8002 查看 Web 界面，功能包括：

• 📊 实时流量统计
• 📋 请求/响应详情
• 🔍 流量搜索
• 💾 数据导出（/api/export?format=json|jsonl|csv&limit=1000）

证书管理

自动安装

uproxier cert
# 选择 "安装证书到系统"

手动安装

⚠️ 重要提醒：只安装证书文件，不要安装包含私钥的文件！

证书文件位置：~/.uproxier/certificates/

• mitmproxy-ca-cert.pem - PEM 格式证书（推荐）
• mitmproxy-ca-cert.der - DER 格式证书

安装命令：

# macOS
security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain ~/.uproxier/certificates/mitmproxy-ca-cert.pem

# Windows
certutil -addstore -f ROOT ~/.uproxier/certificates/mitmproxy-ca-cert.der

# Linux
sudo cp ~/.uproxier/certificates/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca.crt
sudo update-ca-certificates

故障排除

常见问题

1. 安装后 uproxier 命令不可用

   # 如果使用 pyenv，检查版本设置
   pyenv global 3.10.6  # 替换为你的 Python 版本
   
   # 确保 Python bin 目录在 PATH 中
   export PATH="$(python3 -c "import sys; print(sys.executable.replace('python3', ''))"):$PATH"
   

2. 证书错误

   • 确保证书已正确安装到系统
   • 重新生成证书：uproxier cert

3. 端口被占用

   • 使用不同的端口：uproxier start --port 8003

4. 规则不生效

   • 检查规则配置是否正确
   • 确认规则已启用
   • 查看日志输出

5. HTTPS 连接失败

   • 确保证书已安装
   • 检查浏览器代理设置

许可证

MIT License

参考

• mitmproxy
• GitHub 仓库