diff --git a/README.md b/README.md index fd39ebc..c29ace7 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,47 @@ -# SOCKS Manager — SOCKS5 代理管理系统 +# SOCKS Manager — SOCKS5 代理管理平台 -基于 Flask + SQLite + Bootstrap 5 的 SOCKS5 代理管理平台,提供 Web 界面和 RESTful API。 +内建 asyncio SOCKS5 服务器的完整代理管理平台,一个 Python 进程即可运行。 -## 功能 +## 架构 -- **仪表盘** — 代理总数 / 在线 / 离线统计,最近活跃代理,操作日志 -- **代理管理** — 添加 / 编辑 / 删除 SOCKS5 代理(支持用户名密码认证),启用 / 禁用 -- **分组管理** — 按颜色分组组织代理,分组筛选 -- **健康检测** — SOCKS5 隧道连通性检测(测试 URL httpbin.org),单代理 / 批量检测,延迟统计 -- **操作日志** — 增删改操作记录,分页查询 -- **RESTful API** — 全套 CRUD + 健康检测 + 统计接口 -- **管理员登录** — 密码保护后台 +``` +┌──────────────────────────────────────────────┐ +│ Web 管理面板 (Flask + Bootstrap 5 暗色主题) │ +├──────────────────────────────────────────────┤ +│ RESTful API (/api/*) │ +├────────────┬──────────────┬──────────────────┤ +│ engine/ │ services/ │ │ +│ └server.py │ └user_service│ 数据: SQLite │ +│ asyncio │ 流量/认证 │ socks_manager.db│ +│ SOCKS5 │ └stats_ │ │ +│ 服务器 │ 监控/趋势 │ │ +│ └instances │ └backup_ │ │ +│ 多实例 │ 备份恢复 │ │ +└────────────┴──────────────┴──────────────────┘ +``` -## 技术栈 +## 功能覆盖 -| 层级 | 技术 | +| 需求 | 实现 | |------|------| -| 后端 | Python 3.11 + Flask 3.0 + Flask-SQLAlchemy | -| 数据库 | SQLite(零配置,文件存储) | -| 前端 | Jinja2 模板 + Bootstrap 5 + Bootstrap Icons(暗色主题) | -| SOCKS5 | PySocks | +| 多实例管理 | 每个实例独立事件循环,支持创建/启动/停止/重启 | +| 基础参数 | 监听地址(IPv4/IPv6)、端口、超时可视化配置 | +| 底层引擎 | 内建 asyncio SOCKS5 服务器(RFC 1928/1929) | +| 配置热重载 | 修改参数后重启实例生效,不中断 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 -# 设置管理员密码(首次启动生效) +# 设置管理员密码 export SM_ADMIN_PASSWORD=*** # 启动 python3 run.py -# 或: ./run.sh ``` -访问 `http://你的IP:5000`,默认用户 `admin`,密码为 `SM_ADMIN_PASSWORD` 的值。 +访问 `http://你的IP:5000`,用户名 `admin`,密码为环境变量值。 ## 环境变量 | 变量 | 默认值 | 说明 | |------|--------|------| | `SM_ADMIN_USER` | `admin` | 管理员用户名 | -| `SM_ADMIN_PASSWORD` | `""` | 管理员密码(必须设置,否则无法登录) | +| `SM_ADMIN_PASSWORD` | `""` | 管理员密码(必须设置) | | `SM_DB_URI` | `sqlite:///socks_manager.db` | 数据库连接串 | -| `SM_HEALTH_TIMEOUT` | `10` | 健康检测超时(秒) | -| `SM_HEALTH_INTERVAL` | `300` | 建议的健康检测间隔(秒) | +| `SM_PORT` | `5000` | Web 面板端口 | +| `SM_HOST` | `0.0.0.0` | 监听地址 | +| `SM_BACKUP_DIR` | `./backups/` | 备份目录 | | `SM_LOG_LEVEL` | `INFO` | 日志级别 | -## 目录结构 +## 核心代码结构 ``` -socks-manager/ -├── app.py # 启动入口 -├── config.py # 配置 + 工厂函数 +├── app.py # Flask 应用工厂 +├── config.py # 配置 ├── auth.py # 登录认证 -├── models.py # 数据模型 (Proxy/Group/Log) -├── health.py # SOCKS5 健康检测 -├── extensions.py # SQLAlchemy 实例 -├── run.py # 直接运行脚本 -├── run.sh # 启动 shell 脚本 -├── requirements.txt # Python 依赖 -├── routes/ -│ ├── main.py # Web 路由(页面) -│ └── api.py # RESTful API -└── templates/ - ├── base.html # 基础布局(侧边栏 + 导航) - ├── dashboard.html # 仪表盘 - ├── proxies.html # 代理列表 - ├── proxy_form.html # 添加 / 编辑代理 - ├── groups.html # 分组管理 - └── logs.html # 日志 +├── models.py # SQLAlchemy 数据模型 +├── database.py # 数据库初始化 +├── run.py # 启动入口 +│ +├── engine/ +│ ├── server.py # asyncio SOCKS5 服务器(核心引擎) +│ └── instances.py # 多实例管理器 +│ +├── services/ +│ ├── user_service.py # 用户管理/认证/流量/防爆破 +│ ├── stats_service.py# 监控/统计/趋势 +│ └── backup_service.py# 备份与恢复 +│ +├── api/ +│ └── v1.py # RESTful API(实例/用户/日志/备份) +│ +├── 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 参考 | 方法 | 路径 | 说明 | |------|------|------| -| GET | `/api/proxies` | 代理列表(支持 `?group=N` 筛选) | -| POST | `/api/proxies` | 创建代理 | -| PUT | `/api/proxies/` | 更新代理 | -| DELETE | `/api/proxies/` | 删除代理 | -| POST | `/api/proxies//check` | 检测单个代理 | -| POST | `/api/proxies//toggle` | 启用/禁用 | -| GET | `/api/groups` | 分组列表 | -| GET | `/api/stats` | 统计摘要 | -| GET | `/health/check-all` | 批量检测全部代理 | +| GET | `/api/dashboard` | 仪表盘汇总 | +| GET/POST | `/api/instances` | 实例列表/创建 | +| PUT/DELETE | `/api/instances/` | 更新/删除实例 | +| POST | `/api/instances//start` | 启动实例 | +| POST | `/api/instances//stop` | 停止实例 | +| GET/POST | `/api/users` | 用户列表/创建 | +| PUT/DELETE | `/api/users/` | 更新/删除用户 | +| GET | `/api/logs` | 审计日志(支持筛选) | +| GET/POST | `/api/backups` | 备份列表/创建 | +| GET | `/api/stats/system` | 实时系统指标 | +| GET | `/api/stats/connections` | 活跃连接 | -## 注意事项 +## 生产建议 -- 健康检测通过建立 SOCKS5 隧道连接 httpbin.org 来验证代理可用性,会产生真实网络流量 -- 开发服务器不适合生产环境,生产请使用 gunicorn/uwsgi -- SQLite 适合中小型部署(数千代理),超大规模建议切换到 PostgreSQL +- 使用 gunicorn/uwsgi 替代内置开发服务器 +- 前置 Nginx 反向代理 + Let's Encrypt SSL +- 定期备份 `socks_manager.db` +- 配置 `SM_LOG_LEVEL=WARN` 减少日志量