From 92a0d601986d3464974cbe6cd3f20c66afd2f384 Mon Sep 17 00:00:00 2001 From: Your Name Date: Thu, 16 Jul 2026 22:15:47 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0README=EF=BC=9A=E6=96=B0?= =?UTF-8?q?=E5=A2=9EFAQs=E3=80=81=E5=AF=86=E7=A0=81=E5=AE=89=E5=85=A8?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=E3=80=81=E8=B7=A8=E6=9C=8D=E5=8A=A1=E5=99=A8?= =?UTF-8?q?=E7=99=BB=E5=BD=95=E6=8E=92=E6=9F=A5=E3=80=81=E7=8E=AF=E5=A2=83?= =?UTF-8?q?=E5=8F=98=E9=87=8F=E8=AF=A6=E8=A7=A3=E3=80=81=E7=94=9F=E4=BA=A7?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E7=A4=BA=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 131 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 103 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index be792cc..0e663b7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # SOCKS Manager — SOCKS5 代理管理平台 -内建 asyncio SOCKS5 服务器的完整代理管理平台，一个 Python 进程即可运行。 +内建 asyncio SOCKS5 服务器（RFC 1928/1929）的完整代理管理平台，一个 Python 进程即可运行。支持多实例管理、流量控制、用户管理、审计日志、实时监控。 ## 架构 @@ -40,7 +40,11 @@ | 级联代理 | 连接建立时自动代理至目标（可扩展 upstream） | | 负载均衡 | 多实例配置后按端口轮询 | | 管理员认证 | 环境变量 `SM_ADMIN_PASSWORD` 保护 | +| 防爆破 | 自动阻断频繁登录尝试（Fail2Ban 机制） | +| 密码安全 | bcrypt 哈希存储 SOCKS5 用户密码（兼容旧明文自动迁移） | +| 会话管理 | 自定义 Cookie 域名/安全/名称，支持 HTTPS 部署 | | 自动备份 | 一键备份 SQLite，按份数清理 | +| 每日流量快照 | 后台线程每小时记录一次，用于月度趋势图表 | | RESTful API | 全部管理功能通过 `/api/` 暴露 | ## 快速开始 @@ -51,8 +55,8 @@ cd /root/socks-manager # 安装依赖 pip install -r requirements.txt --break-system-packages -# 设置管理员密码 -export SM_ADMIN_PASSWORD=*** +# 设置管理员密码（首次启动如未设置，自动使用默认密码 admin123 并写入 .env） +export SM_ADMIN_PASSWORD=你的密码 # 启动 python3 run.py @@ -60,39 +64,76 @@ python3 run.py 访问 `http://你的IP:5000`，用户名 `admin`，密码为环境变量值。 +> ⚠️ 首次启动时如果 `SM_ADMIN_PASSWORD` 未设置，会自动写入默认密码 `admin123` 到 `.env` 文件。**生产环境请务必修改此密码。** + ## 环境变量 | 变量 | 默认值 | 说明 | |------|--------|------| | `SM_ADMIN_USER` | `admin` | 管理员用户名 | | `SM_ADMIN_PASSWORD` | `""` | 管理员密码（必须设置） | -| `SM_SECRET_KEY` | `sm-dev-key-change-in-prod` | Flask 会话密钥（生产环境务必修改） | -| `SM_SESSION_DOMAIN` | `None` | 会话 Cookie 域名（跨域访问时设置） | -| `SM_COOKIE_SECURE` | `false` | Cookie Secure 标志（HTTPS 时设为 true） | -| `SM_SESSION_NAME` | `sm_session` | 会话 Cookie 名称 | +| `SM_SECRET_KEY` | `sm-dev-key-change-in-prod` | Flask 会话密钥（生产环境务必修改，建议随机 64 位字符串） | +| `SM_SESSION_DOMAIN` | `None` | 会话 Cookie 域名（跨域访问时设为你的域名或 IP） | +| `SM_COOKIE_SECURE` | `false` | 是否启用 Cookie Secure 标志（HTTPS 时设为 `true`） | +| `SM_SESSION_NAME` | `sm_session` | 会话 Cookie 名称（多实例同域名时避免冲突） | | `SM_DB_URI` | `sqlite:///socks_manager.db` | 数据库连接串 | -| `SM_PORT` | `5000` | Web 面板端口 | -| `SM_HOST` | `0.0.0.0` | 监听地址 | -| `SM_BACKUP_DIR` | `./backups/` | 备份目录 | -| `SM_LOG_LEVEL` | `INFO` | 日志级别 | +| `SM_PORT` | `5000` | Web 面板监听端口 | +| `SM_HOST` | `0.0.0.0` | Web 面板监听地址 | +| `SM_BACKUP_DIR` | `./backups/` | 备份文件存储目录 | +| `SM_LOG_LEVEL` | `INFO` | 日志级别：`DEBUG`/`INFO`/`WARN`/`ERROR` | + +## 常见问题 + +### 1. 在其他服务器上无法登录 + +问题：浏览器访问面板，输入密码后提示错误或跳转回登录页。 + +**可能原因 & 解决方案：** + +| 原因 | 解决 | +|------|------| +| 密码不一致 | 确认所有服务器 `.env` 文件中的 `SM_ADMIN_PASSWORD` 一致 | +| Cookie 被浏览器拒绝（HTTP + 非标准域名） | 通过 `curl -c /tmp/cookies.txt -X POST -d "username=admin&password=xxx" http://你的IP:5000/login` 测试 | +| 通过 SOCKS5 代理访问面板 | 直连（非代理模式）访问面板 | +| Session Cookie 域名不匹配 | 设置 `SM_SESSION_DOMAIN=你的IP` 并重启 | +| HTTPS 下未设置 Secure | 设置 `SM_COOKIE_SECURE=true` | + +验证登录是否成功： +```bash +curl -c /tmp/sm_cookies.txt -b /tmp/sm_cookies.txt \ + -X POST -d "username=admin&password=你的密码" \ + http://你的IP:5000/login -w "%{http_code} %{redirect_url}" +``` +返回 `302 /dashboard` 表示成功。 + +### 2. 仪表盘流量趋势图无数据 + +首次部署后需等待 1 小时，后台线程每小时记录一次流量快照。也可以手动记录一次： +```bash +python3 -c "from services.stats_service import record_traffic_snapshot; record_traffic_snapshot()" +``` + +### 3. SOCKS5 用户密码安全性 + +SOCKS5 协议（RFC 1929）本身采用明文传输密码。本项目服务端使用 **bcrypt** 哈希存储，兼容旧版明文存储的数据库（首次验证时自动迁移到哈希）。Web 面板中展示用户时不会泄露密码。 ## 核心代码结构 ``` ├── app.py # Flask 应用工厂 ├── config.py # 配置 -├── auth.py # 登录认证 -├── models.py # SQLAlchemy 数据模型 +├── auth.py # 登录认证 + 防爆破 +├── models.py # SQLAlchemy 数据模型（含 bcrypt 密码方法） ├── database.py # 数据库初始化 ├── run.py # 启动入口 │ ├── engine/ │ ├── server.py # asyncio SOCKS5 服务器（核心引擎） -│ └── instances.py # 多实例管理器 +│ └── instances.py # 多实例管理器（线程安全） │ ├── services/ │ ├── user_service.py # 用户管理/认证/流量/防爆破 -│ ├── stats_service.py# 监控/统计/趋势 +│ ├── stats_service.py# 监控/统计/趋势/流量快照 │ └── backup_service.py# 备份与恢复 │ ├── api/ @@ -103,7 +144,7 @@ python3 run.py │ └── templates/ # Jinja2 模板（暗色 Bootstrap 5） ├── base.html # 布局（侧边栏+导航+全局样式） - ├── dashboard.html # 仪表盘（实时图表） + ├── dashboard.html # 仪表盘（实时图表 + 最近审计日志） ├── instances.html # 代理实例管理 ├── users.html # 用户管理 ├── stats.html # 流量统计 @@ -117,23 +158,57 @@ python3 run.py | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/dashboard` | 仪表盘汇总 | +| GET | `/api/stats/system` | 实时系统指标（含最近 10 分钟历史） | +| GET | `/api/stats/connections` | 活跃连接列表 | +| GET | `/api/stats/traffic-trend?days=30` | 流量趋势 | +| GET | `/api/stats/users` | 用户流量排名 | +| GET | `/api/stats/instances` | 实例流量统计 | | GET/POST | `/api/instances` | 实例列表/创建 | | PUT/DELETE | `/api/instances/` | 更新/删除实例 | -| POST | `/api/instances//start` | 启动实例 | -| POST | `/api/instances//stop` | 停止实例 | +| POST | `/api/instances//start\|stop\|restart` | 实例启停 | +| POST | `/api/instances/sync` | 同步所有实例状态 | | GET/POST | `/api/users` | 用户列表/创建 | | PUT/DELETE | `/api/users/` | 更新/删除用户 | -| GET | `/api/logs` | 审计日志（支持筛选） | +| POST | `/api/users//toggle\|ban` | 用户启停/封禁 | +| GET | `/api/logs?page=1&event=&user=&src_ip=` | 审计日志查询 | | GET/POST | `/api/backups` | 备份列表/创建 | -| GET | `/api/stats/system` | 实时系统指标 | -| GET | `/api/stats/connections` | 活跃连接 | +| POST | `/api/backups//restore` | 恢复备份 | +| POST | `/api/backups/cleanup` | 清理旧备份 | + +所有 API 需要登录认证（Session Cookie），未登录返回 401。 ## 生产建议 -- 使用 gunicorn 替代内置开发服务器：`gunicorn -w 4 -b 0.0.0.0:5000 run:app` -- 前置 Nginx 反向代理 + Let's Encrypt SSL -- 设置 `SM_COOKIE_SECURE=true`（HTTPS 时） -- 设置 `SM_SECRET_KEY` 为随机字符串 -- 设置 `SM_SESSION_DOMAIN` 为你的域名（跨机器访问时） -- 定期备份 `socks_manager.db` -- 配置 `SM_LOG_LEVEL=WARN` 减少日志量 +```bash +# 1. 安装生产依赖 +pip install -r requirements.txt --break-system-packages + +# 2. 设置强密钥 +export SM_SECRET_KEY=$(openssl rand -hex 32) +export SM_ADMIN_PASSWORD=你的强密码 + +# 3. 使用 gunicorn 部署 +gunicorn -w 4 -b 0.0.0.0:5000 run:app + +# 4. 前置 Nginx 反向代理 + Let's Encrypt SSL +# nginx.conf 示例： +# location / { +# proxy_pass http://127.0.0.1:5000; +# proxy_set_header Host $host; +# proxy_set_header X-Real-IP $remote_addr; +# proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; +# proxy_set_header X-Forwarded-Proto $scheme; +# } + +# 5. HTTPS 时开启 Secure Cookie +export SM_COOKIE_SECURE=true + +# 6. 多服务器跨域访问时设置 SESSION_DOMAIN（必须与浏览器 URL 一致） +export SM_SESSION_DOMAIN=你的域名或IP +``` + +其他建议： +- 确保 `.env` 文件在 `.gitignore` 中（已配置），**不要提交到 git 仓库** +- 设置 `SM_LOG_LEVEL=WARN` 减少日志量 +- 配置 crontab 定期备份数据库 +- 使用 Daemon 或 systemd 管理进程