docs: comprehensive README with architecture diagram

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/<id>` | 更新代理 |
-| DELETE | `/api/proxies/<id>` | 删除代理 |
-| POST | `/api/proxies/<id>/check` | 检测单个代理 |
-| POST | `/api/proxies/<id>/toggle` | 启用/禁用 |
-| GET | `/api/groups` | 分组列表 |
-| GET | `/api/stats` | 统计摘要 |
-| GET | `/health/check-all` | 批量检测全部代理 |
+| GET | `/api/dashboard` | 仪表盘汇总 |
+| GET/POST | `/api/instances` | 实例列表/创建 |
+| PUT/DELETE | `/api/instances/<id>` | 更新/删除实例 |
+| POST | `/api/instances/<id>/start` | 启动实例 |
+| POST | `/api/instances/<id>/stop` | 停止实例 |
+| GET/POST | `/api/users` | 用户列表/创建 |
+| PUT/DELETE | `/api/users/<id>` | 更新/删除用户 |
+| 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` 减少日志量