LocalProxyServer - 智能代理服务端

轻量级智能代理管理服务端，为 LocalProxy 客户端提供配置分发、设备激活和静态资源服务。

---

📖 项目简介

LocalProxyServer 是 LocalProxy 代理管理工具的配套服务端组件，专为局域网环境设计。它通过 RESTful API 向客户端分发代理服务器配置、管理设备激活请求，并提供静态资源托管服务。

该服务端采用 Flask 框架构建，配合 Waitress 生产级 WSGI 服务器，确保在教室、办公室或实验室等场景下的稳定运行。管理员只需在服务端维护一份配置文件，所有客户端即可自动获取最新的代理服务器列表和浏览器配置。

核心应用场景

• 🏫 校园机房管理：集中管理所有学生机的代理配置，统一分发更新
• 🏢 企业内网部署：快速搭建代理配置中心，简化网络管理流程
• 🧪 实验室环境：便捷切换和测试不同的代理服务器配置

---

✨ 功能特性

功能	说明
📡 配置分发 API	提供 /get_config 接口，客户端可拉取最新的代理配置和浏览器设置
🔐 设备激活管理	通过 /post_activate 接口接收客户端设备 ID 上报，支持设备绑定机制
🛡️ HTTP 基础认证	支持对敏感路由进行用户名/密码保护，防止未授权访问
📂 静态资源托管	提供图标、公告板文件、安装包等静态资源的访问服务
📄 JSONC 配置支持	配置文件支持注释（JSON with Comments），便于管理员维护
🔄 版本控制机制	基于版本号参数返回不同配置文件，支持新旧版本共存
📋 完善的日志系统	彩色控制台输出 + 文件持久化，便于问题追踪和审计
🔌 即插即用	配合 HiddenRunServer.vbs 脚本可实现无窗口后台运行

---

🛠️ 技术栈

类别	技术
编程语言	Python 3.8+
Web 框架	Flask
WSGI 服务器	Waitress
日志系统	colorlog, logging
打包工具	PyInstaller
并发处理	threading

---

📋 前置条件

• 操作系统：Windows 7/10/11 (64位)
• Python 版本：Python 3.8 或更高版本
• 包管理工具：pip

---

🚀 快速开始

1. 克隆仓库

git clone https://github.com/yangsongh/LocalProxyServer.git
cd LocalProxyServer

2. 创建虚拟环境（推荐）

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

3. 安装依赖

pip install -r requirements.txt

4. 配置文件准备

在 assets/ 目录下创建或编辑 config_client.jsonc 配置文件：

{
  "version": {
    "latest_vercode": 202606171,
    "force_update": true,
    "update_content": "更新内容说明",
    "update_url": "http://your-server-ip/localproxy",
    "auto_update": true,
    "zip_url": "http://your-server-ip/localproxy/downloads/update.zip",
  },
  "browser": {
    "browser_path": "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
    "user_data_dir": "%APPDATA%/LocalProxyEdgeData",
    "browser_homepage": "http://your-server-ip:8888",
    "test_url": "http://connect.rom.miui.com/generate_204",
  },
  "proxy_servers": ["socks5://192.168.1.100:1080", "http://192.168.1.100:8080"],
  "activated_devices_passwords": {
    "DISK_SERIAL_123": "password123",
  },
  "expiry_date": "2026-12-31 23:59:59",
}

5. 修改认证配置

在 localproxy_server.py 中配置服务端认证信息：

LOCALPROXY_USERNAME = 'user'      # 修改为自定义用户名
LOCALPROXY_PASSWORD = '123456'    # 修改为自定义密码
VERSION_CODE = 202606171          # 当前配置版本号

6. 启动服务

python localproxy_server.py

服务默认监听 http://0.0.0.0:8888。

7. 后台运行（可选）

使用提供的 VBS 脚本实现无窗口后台运行：

# 将 LocalProxyServer.exe 放置在合适位置
# 编辑 HiddenRunServer.vbs 中的路径指向 exe 文件
wscript.exe HiddenRunServer.vbs

---

📁 项目结构

LocalProxyServer/
├── localproxy_server.py          # Flask 应用主入口，定义所有 API 路由
├── BUILD.BAT                      # Windows 构建批处理脚本
├── LocalProxyServer.spec          # PyInstaller 打包规格文件
├── requirements.txt               # Python 依赖列表
├── LICENSE                        # MIT 许可证
├── .gitignore                     # Git 忽略文件
├── assets/                        # 资源文件夹
│   ├── config_client.jsonc        # 主配置文件（JSON with Comments）
│   ├── HiddenRunServer.vbs        # VBS 无窗口运行脚本
│   ├── localproxy/                # Web 静态资源根目录（部署时创建）
│   │   ├── downloads/             # 下载文件存放目录（更新包等）
│   │   ├── icons/                 # 图标资源目录
│   │   └── noticeboard/           # 公告板文件目录
│   └── web_old.zip                # 旧版 Web 资源备份
├── utils/                         # 工具模块
│   └── utils_lib.py               # 通用工具库（日志管理、配置管理等）
├── build/                         # 构建输出目录
│   └── LocalProxyServer.zip       # 打包后的可执行文件压缩包
└── .vscode/                       # VSCode 开发配置
    ├── launch.json                # 调试配置
    └── settings.json              # 编辑器设置

核心模块说明

模块	功能描述
localproxy_server.py	Flask Blueprint 定义，包含配置分发、设备激活、静态资源服务等路由
utils_lib.py	日志管理（LoggerManager）、配置管理（ConfigManager）、系统工具函数
config_client.jsonc	服务端主配置，控制代理列表、浏览器设置、版本更新、设备白名单等

---

📡 API 文档

认证机制

部分路由受 HTTP Basic Authentication 保护：

• 用户名：LOCALPROXY_USERNAME（可在源码中配置）
• 密码：LOCALPROXY_PASSWORD（可在源码中配置）

端点列表

端点	方法	认证	说明
/localproxy/	GET	✅	返回 Web 主页（index.html）
/localproxy/get_config	GET	❌	获取配置文件，支持版本参数
/localproxy/post_activate	POST	❌	接收客户端设备激活请求
/localproxy/downloads/<filename>	GET	❌	下载指定文件（如更新包）
/localproxy/icons/<filename>	GET	❌	获取图标等静态资源
/localproxy/noticeboard/<filename>	GET	❌	获取公告板文件

---

1. 获取配置

GET /localproxy/get_config?ver={VERSION_CODE}

请求参数：

参数	类型	必填	说明
ver	string	否	客户端当前版本号。若与 VERSION_CODE 匹配则返回新配置，否则返回旧配置

响应示例：

{
  "proxy_servers": ["socks5://192.168.1.100:1080"],
  "browser": {
    "test_url": "http://connect.rom.miui.com/generate_204",
    "browser_homepage": "http://172.16.192.1:8888",
    "browser_path": "C:\\Program Files\\...\\msedge.exe",
    "user_data_dir": "%APPDATA%\\LocalProxyEdgeData"
  },
  "activated_devices_passwords": {
    "DISK_SERIAL_123": "password123"
  },
  "expiry_date": "2026-12-31 23:59:59",
  "version": {
    "latest_vercode": 202606171,
    "force_update": true,
    "update_url": "http://172.16.192.1/localproxy"
  }
}

---

2. 设备激活

POST /localproxy/post_activate
Content-Type: application/json

请求体：

{
  "device_id": "DISK_SERIAL_123"
}

响应：

{
  "status": "success"
}

---

3. 下载文件

GET /localproxy/downloads/{filename}

示例：

GET /localproxy/downloads/LocalProxyPortable.zip

---

4. 图标资源

GET /localproxy/icons/{filename}

---

5. 公告板文件

GET /localproxy/noticeboard/{filename}

---

⚙️ 配置说明

服务端配置（localproxy_server.py）

变量	说明
LOCALPROXY_USERNAME	HTTP 基础认证用户名
LOCALPROXY_PASSWORD	HTTP 基础认证密码
VERSION_CODE	当前配置版本号（用于版本控制）
WEB_FOLDER	Web 静态资源根目录
ICONS_FOLDER	图标资源目录
NOTICE_BOARD_FOLDER	公告板文件目录
CONFIG_FILE	主配置文件名称
CONFIG_OLD_FILE	旧配置文件名称（用于版本回退）

静态资源目录结构

assets/localproxy/
├── index.html              # 服务端主页
├── downloads/              # 下载文件目录
│   └── LocalProxyPortable.zip
├── icons/                  # 图标资源目录
│   └── favicon.ico
└── noticeboard/            # 公告板目录
    └── index.html

---

🤝 贡献指南

我们欢迎任何形式的贡献！请遵循以下流程：

1. Fork 本仓库

2. 创建特性分支

git checkout -b feature/amazing-feature

3. 提交代码

git commit -m 'Add some amazing feature'

4. 推送到分支

git push origin feature/amazing-feature

5. 提交 Pull Request

代码规范

• 遵循 PEP 8 编码规范
• 使用类型注解 (Type Hints) 提高代码可读性
• 为新增功能编写必要的注释和文档字符串
• 确保所有 API 路由包含适当的日志记录

本地开发环境

1. 克隆仓库并安装依赖
2. 使用 VSCode 打开项目，配置已包含在 .vscode/ 目录中
3. 调试配置已预设，按 F5 即可启动调试

---

📄 许可证

本项目采用 MIT License 进行许可。您可以自由使用、修改和分发本软件，但需保留版权声明。

---

🙏 致谢

• Flask - 轻量级 Python Web 框架
• Waitress - 生产级 WSGI 服务器
• PyInstaller - Python 应用打包工具

---

📞 联系方式

• 提交 GitHub Issue
• 邮件联系：18675864731@163.com

---