AI-Agent/socks-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: comprehensive README with architecture diagram

Browse Source
This commit is contained in:
Your Name
2026-07-16 17:33:00 +08:00
parent 558bd8153f
commit cea6c54e78
1 changed files with 91 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+91 -55
View File
@@ -1,25 +1,47 @@
# SOCKS Manager — SOCKS5 代理管理系统 # SOCKS Manager — SOCKS5 代理管理平台
基于 Flask + SQLite + Bootstrap 5 的 SOCKS5 代理管理平台，提供 Web 界面和 RESTful API。 内建 asyncio SOCKS5 服务器的完整代理管理平台，一个 Python 进程即可运行。
## 功能 ## 架构
- **仪表盘** — 代理总数 / 在线 / 离线统计，最近活跃代理，操作日志 ```
- **代理管理** — 添加 / 编辑 / 删除 SOCKS5 代理（支持用户名密码认证），启用 / 禁用 ┌──────────────────────────────────────────────┐
- **分组管理** — 按颜色分组组织代理，分组筛选 │ Web 管理面板 (Flask + Bootstrap 5 暗色主题) │
- **健康检测** — SOCKS5 隧道连通性检测（测试 URL httpbin.org），单代理 / 批量检测，延迟统计 ├──────────────────────────────────────────────┤
- **操作日志** — 增删改操作记录，分页查询 │ RESTful API (/api/*) │
- **RESTful API** — 全套 CRUD + 健康检测 + 统计接口 ├────────────┬──────────────┬──────────────────┤
- **管理员登录** — 密码保护后台 │ engine/ │ services/ │ │
│ └server.py │ └user_service│ 数据: SQLite │
│ asyncio │ 流量/认证 │ socks_manager.db│
│ SOCKS5 │ └stats_ │ │
│ 服务器 │ 监控/趋势 │ │
│ └instances │ └backup_ │ │
│ 多实例 │ 备份恢复 │ │
└────────────┴──────────────┴──────────────────┘
```
## 技术栈 ## 功能覆盖
| 层级 | 技术 | | 需求 | 实现 |
|------|------| |------|------|
| 后端 | Python 3.11 + Flask 3.0 + Flask-SQLAlchemy | | 多实例管理 | 每个实例独立事件循环，支持创建/启动/停止/重启 |
| 数据库 | SQLite（零配置，文件存储） | | 基础参数 | 监听地址(IPv4/IPv6)、端口、超时可视化配置 |
| 前端 | Jinja2 模板 + Bootstrap 5 + Bootstrap Icons（暗色主题） | | 底层引擎 | 内建 asyncio SOCKS5 服务器（RFC 1928/1929） |
| SOCKS5 | PySocks | | 配置热重载 | 修改参数后重启实例生效，不中断 Web 面板 |
| 多身份认证 | 无认证 / 账号密码认证 |
| 流量控制 | 总流量上限、月流量上限、超额自动停机 |
| 速度与并发 | 上下行带宽限制(Mbps)、最大并发连接数 |
| IP 白名单/黑名单 | 用户级逗号分隔配置 |
| 账号生命周期 | 生效时间、过期时间、一键封禁/解封 |
| 大盘控制台 | CPU/内存/网络吞吐量/活跃连接实时图表 |
| 实时连接追踪 | 源IP/目标域名/协议/持续时间，手动断开 |
| 流量统计报表 | 30 天折线/柱状图（Chart.js） |
| 详细审计日志 | 按事件/用户/IP 筛选，分页查询 |
| 级联代理 | 连接建立时自动代理至目标（可扩展 upstream） |
| 负载均衡 | 多实例配置后按端口轮询 |
| 管理员认证 | 环境变量 `SM_ADMIN_PASSWORD` 保护 |
| 自动备份 | 一键备份 SQLite，按份数清理 |
| RESTful API | 全部管理功能通过 `/api/` 暴露 |
## 快速开始 ## 快速开始
@@ -29,68 +51,82 @@ cd /root/socks-manager
# 安装依赖 # 安装依赖
pip install -r requirements.txt --break-system-packages pip install -r requirements.txt --break-system-packages
# 设置管理员密码（首次启动生效） # 设置管理员密码
export SM_ADMIN_PASSWORD=*** export SM_ADMIN_PASSWORD=***
# 启动 # 启动
python3 run.py python3 run.py
# 或: ./run.sh
``` ```
访问 `http://你的IP:5000`，默认用户 `admin`，密码为 `SM_ADMIN_PASSWORD` 的值。 访问 `http://你的IP:5000`，用户名 `admin`，密码为环境变量值。
## 环境变量 ## 环境变量
| 变量 | 默认值 | 说明 | | 变量 | 默认值 | 说明 |
|------|--------|------| |------|--------|------|
| `SM_ADMIN_USER` | `admin` | 管理员用户名 | | `SM_ADMIN_USER` | `admin` | 管理员用户名 |
| `SM_ADMIN_PASSWORD` | `""` | 管理员密码（必须设置，否则无法登录） | | `SM_ADMIN_PASSWORD` | `""` | 管理员密码（必须设置） |
| `SM_DB_URI` | `sqlite:///socks_manager.db` | 数据库连接串 | | `SM_DB_URI` | `sqlite:///socks_manager.db` | 数据库连接串 |
| `SM_HEALTH_TIMEOUT` | `10` | 健康检测超时（秒） | | `SM_PORT` | `5000` | Web 面板端口 |
| `SM_HEALTH_INTERVAL` | `300` | 建议的健康检测间隔（秒） | | `SM_HOST` | `0.0.0.0` | 监听地址 |
| `SM_BACKUP_DIR` | `./backups/` | 备份目录 |
| `SM_LOG_LEVEL` | `INFO` | 日志级别 | | `SM_LOG_LEVEL` | `INFO` | 日志级别 |
## 目录结构 ## 核心代码结构
``` ```
socks-manager/ ├── app.py # Flask 应用工厂
├── app.py # 启动入口 ├── config.py # 配置
├── config.py # 配置 + 工厂函数
├── auth.py # 登录认证 ├── auth.py # 登录认证
├── models.py # 数据模型 (Proxy/Group/Log) ├── models.py # SQLAlchemy 数据模型
├── health.py # SOCKS5 健康检测 ├── database.py # 数据库初始化
├── extensions.py # SQLAlchemy 实例 ├── run.py # 启动入口
├── run.py # 直接运行脚本 │
├── run.sh # 启动 shell 脚本 ├── engine/
├── requirements.txt # Python 依赖 │ ├── server.py # asyncio SOCKS5 服务器（核心引擎）
├── routes/ │ └── instances.py # 多实例管理器
│ ├── main.py # Web 路由（页面） │
│ └── api.py # RESTful API ├── services/
└── templates/ │ ├── user_service.py # 用户管理/认证/流量/防爆破
├── base.html # 基础布局（侧边栏 + 导航） │ ├── stats_service.py# 监控/统计/趋势
├── dashboard.html # 仪表盘 │ └── backup_service.py# 备份与恢复
├── proxies.html # 代理列表 │
├── proxy_form.html # 添加 / 编辑代理 ├── api/
├── groups.html # 分组管理 │ └── v1.py # RESTful API（实例/用户/日志/备份）
└── logs.html # 日志 │
├── web/
│ └── routes.py # Web 管理面板路由
│
└── templates/ # Jinja2 模板（暗色 Bootstrap 5）
├── base.html # 布局（侧边栏+导航+全局样式）
├── dashboard.html # 仪表盘（实时图表）
├── instances.html # 代理实例管理
├── users.html # 用户管理
├── stats.html # 流量统计
├── connections.html# 活跃连接
├── logs.html # 审计日志
└── system.html # 系统管理
``` ```
## API 参考 ## API 参考
| 方法 | 路径 | 说明 | | 方法 | 路径 | 说明 |
|------|------|------| |------|------|------|
| GET | `/api/proxies` | 代理列表（支持 `?group=N` 筛选） | | GET | `/api/dashboard` | 仪表盘汇总 |
| POST | `/api/proxies` | 创建代理 | | GET/POST | `/api/instances` | 实例列表/创建 |
| PUT | `/api/proxies/<id>` | 更新代理 | | PUT/DELETE | `/api/instances/<id>` | 更新/删除实例 |
| DELETE | `/api/proxies/<id>` | 删除代理 | | POST | `/api/instances/<id>/start` | 启动实例 |
| POST | `/api/proxies/<id>/check` | 检测单个代理 | | POST | `/api/instances/<id>/stop` | 停止实例 |
| POST | `/api/proxies/<id>/toggle` | 启用/禁用 | | GET/POST | `/api/users` | 用户列表/创建 |
| GET | `/api/groups` | 分组列表 | | PUT/DELETE | `/api/users/<id>` | 更新/删除用户 |
| GET | `/api/stats` | 统计摘要 | | GET | `/api/logs` | 审计日志（支持筛选） |
| GET | `/health/check-all` | 批量检测全部代理 | | GET/POST | `/api/backups` | 备份列表/创建 |
| GET | `/api/stats/system` | 实时系统指标 |
| GET | `/api/stats/connections` | 活跃连接 |
## 注意事项 ## 生产建议
- 健康检测通过建立 SOCKS5 隧道连接 httpbin.org 来验证代理可用性，会产生真实网络流量 - 使用 gunicorn/uwsgi 替代内置开发服务器
- 开发服务器不适合生产环境，生产请使用 gunicorn/uwsgi - 前置 Nginx 反向代理 + Let's Encrypt SSL
- SQLite 适合中小型部署（数千代理），超大规模建议切换到 PostgreSQL - 定期备份 `socks_manager.db`
- 配置 `SM_LOG_LEVEL=WARN` 减少日志量