SOCKS Manager 教程：自建 SOCKS5 代理管理平台
要给团队搭一个带账号管理的 SOCKS5 代理，是自己写脚本管用户，还是找个现成平台？SOCKS Manager 是后者：一个 Python 进程同时跑 SOCKS5 代理服务和 Web 管理面板，支持多实例、流量控制、带宽限速、三级角色权限、审计日志和实时监控，还能用 systemd + Gunicorn + Nginx 落到生产环境。本教程从快速开始、环境变量、面板操作讲到 API 和生产部署，照着做就能搭出一套可用的代理管理平台。
一、项目简介
SOCKS Manager 是 AI-Agent 组织下的开源项目（Python，master 分支），内建 asyncio SOCKS5 服务器（RFC 1928/1929）的完整代理管理平台，一个 Python 进程即可运行。它的设计思路是“代理引擎 + 管理服务”合一：底层用 asyncio 跑高性能 SOCKS5，上层用 Flask + Bootstrap 5 暗色主题做 Web 面板，所有管理功能同时暴露为 RESTful API，数据存在 SQLite（socks_manager.db）里。
┌──────────────────────────────────────────────┐
│ Web 管理面板 (Flask + Bootstrap 5 暗色主题) │
├──────────────────────────────────────────────┤
│ RESTful API (/api/*) │
├────────────┬──────────────┬──────────────────┤
│ engine/ │ services/ │ │
│ └server.py│ └user_service│ 数据: SQLite │
│ asyncio │ 流量/认证 │ socks_manager.db│
│ SOCKS5 │ └stats_ │ │
│ 服务器 │ 监控/趋势 │ │
│ └instances│ └backup_ │ │
│ 多实例 │ 备份恢复 │ │
└────────────┴──────────────┴──────────────────┘核心代码结构一目了然：
├── app.py # Flask 应用工厂
├── config.py # 配置
├── auth.py # 登录认证 + 防爆破
├── models.py # SQLAlchemy 数据模型（含 bcrypt 密码方法）
├── 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）二、功能特性
| 类别 | 功能 | 说明 |
|---|---|---|
| 代理引擎 | 内建 SOCKS5 服务器 | asyncio 实现，RFC 1928/1929 |
| 代理引擎 | 多实例管理 | 每个实例独立事件循环，创建/启动/停止/重启 |
| 代理引擎 | 级联代理 | 连接建立时自动代理至目标（可扩展 upstream） |
| 代理引擎 | 负载均衡 | 多实例配置后按端口轮询 |
| 用户管理 | 多身份认证 | 无认证 / 账号密码认证 |
| 用户管理 | 流量控制 | 总流量上限、月流量上限、超额自动停机 |
| 用户管理 | 速度与并发 | 上下行带宽限制（Mbps）、最大并发连接数 |
| 用户管理 | IP 白名单/黑名单 | 用户级逗号分隔配置 |
| 用户管理 | 账号生命周期 | 生效时间、过期时间、一键封禁/解封 |
| 监控统计 | 大盘控制台 | CPU/内存/网络吞吐量/活跃连接实时图表 |
| 监控统计 | 实时连接追踪 | 源 IP/目标域名/协议/持续时间，手动断开 |
| 监控统计 | 流量统计报表 | 30 天折线/柱状图（Chart.js） |
| 监控统计 | 详细审计日志 | 按事件/用户/IP 筛选，分页查询 |
| 安全 | 三级角色权限 | superadmin / admin / viewer，细粒度权限位 |
| 安全 | 防爆破 | 自动阻断频繁登录尝试（Fail2Ban 机制） |
| 安全 | 密码安全 | bcrypt 哈希存储，兼容旧明文自动迁移 |
| 运维 | 自动备份 | 一键备份 SQLite，按份数清理 |
| 运维 | 每日流量快照 | 后台线程每小时记录一次，用于月度趋势图表 |
| 运维 | RESTful API | 全部管理功能通过 /api/ 暴露 |
仓库里还附带 tools/forwarder/（SOCKS5 TLS 转发器，含 Go 源码和 Windows 可执行文件）以及 e2e / 冒烟测试脚本（tests/），具体用法见各自目录下的说明文件。
三、适用场景
- 团队共享代理出口：给每个成员开独立账号，按流量和带宽限速，超额自动停机，用多少算多少。
- 多区域代理节点：多实例管理，多个端口对应多个出口，按端口轮询做负载均衡。
- 临时授权访问：给外部协作方开带生效时间和过期时间的账号，到期自动失效，不用事后清理。
- 审计合规：所有连接、登录、配置变更都有审计日志，能按用户、IP、事件筛选，满足内控要求。
- 个人 VPS 代理：单机部署，一个进程同时提供代理和管理面板，资源占用小。
需要注意的是 SOCKS5 协议本身（RFC 1929）的密码是明文传输的，本项目服务端用 bcrypt 哈希存储密码，传输层面的明文问题需要靠部署方式弥补（内网使用或走 TLS 隧道），详见第十一节。
四、快速开始
cd /root/socks-manager
# 安装依赖
pip install -r requirements.txt --break-system-packages
# 设置管理员密码（首次启动如未设置，自动使用默认密码 admin123 并写入 .env）
export SM_ADMIN_PASSWORD=你的密码
# 启动
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 会话密钥（生产环境务必修改，建议随机 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 | Web 面板监听地址 |
| SM_BACKUP_DIR | ./backups/ | 备份文件存储目录 |
| SM_LOG_LEVEL | INFO | 日志级别：DEBUG / INFO / WARN / ERROR |
生产环境最少要改三项：SM_ADMIN_PASSWORD（管理员密码）、SM_SECRET_KEY（会话密钥，用 openssl rand -hex 32 生成一个随机的）、SM_LOG_LEVEL（改成 WARN 减少日志量）。HTTPS 部署时还要把 SM_COOKIE_SECURE 设为 true。
六、Web 面板使用：实例、用户、连接、统计
6.1 仪表盘
登录后首先看到仪表盘：CPU/内存/网络吞吐量/活跃连接的实时图表，加上最近的审计日志。流量趋势图依赖后台线程每小时记录一次的流量快照，首次部署后需要等待 1 小时才有数据，也可以手动记录一次：
python3 -c "from services.stats_service import record_traffic_snapshot; record_traffic_snapshot()"6.2 代理实例管理
每个实例独立事件循环，支持创建、启动、停止、重启。实例的基础参数包括监听地址（IPv4/IPv6）、端口、超时，均可可视化配置。修改参数后重启实例生效，不中断 Web 面板。多个实例配置后可以按端口轮询做负载均衡。
6.3 用户管理
每个 SOCKS5 用户可以配置：认证方式（无认证 / 账号密码）、总流量上限、月流量上限（超额自动停机）、上下行带宽限制（Mbps）、最大并发连接数、IP 白名单/黑名单（逗号分隔）、生效时间、过期时间。用户异常时可以一键封禁或解封。
6.4 实时连接与流量统计
活跃连接列表显示源 IP、目标域名、协议、持续时间，异常连接可以手动断开。流量统计页提供 30 天折线/柱状图（Chart.js）和用户流量排名，方便看出谁在大量消耗流量。
七、三级角色权限与管理员管理
Web 后台管理员账户存在数据库（admin_users 表），支持多账户与角色权限，通过系统管理 → 管理员账户管理（也可用 REST API /api/admins）。
| 角色 | 权限 |
|---|---|
| superadmin 超级管理员 | 全部权限，含管理员账户管理（增删改/启停/改角色/重置密码） |
| admin 管理员 | 用户/实例/系统管理，可查看管理员账户但不能修改 |
| viewer 只读用户 | 仅查看仪表盘/实例/用户/日志，无任何写操作 |
每个角色对应一组权限位（users:read、users:write、instances:read、instances:write、system:read、system:write、admins:read、admins:write、logs:read、stats:read），可在 models.py 的 ROLE_PERMISSIONS 中扩展。
安全保护有三条硬规则：不能删除/禁用当前登录账户；至少保留一个启用的超级管理员（删除最后一位 superadmin 会被拒绝）；账户禁用后立即失效（权限校验实时检查）。登录密码 bcrypt 哈希存储。
# 管理员 REST API
GET /api/admins # 列出管理员
POST /api/admins # 创建 {username, password, role}
PUT /api/admins/<id> # 更新 {role?, password?, enabled?}
DELETE /api/admins/<id> # 删除（带保护校验）八、RESTful API 参考
全部管理功能都通过 /api/ 暴露，所有 API 需要登录认证（Session Cookie），未登录返回 401。
| 方法 | 路径 | 说明 |
|---|---|---|
| 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/<id> | 更新/删除实例 |
| POST | /api/instances/<id>/start|stop|restart | 实例启停 |
| POST | /api/instances/sync | 同步所有实例状态 |
| GET/POST | /api/users | 用户列表/创建 |
| PUT/DELETE | /api/users/<id> | 更新/删除用户 |
| POST | /api/users/<id>/toggle|ban | 用户启停/封禁 |
| GET | /api/logs?page=1&event=&user=&src_ip= | 审计日志查询 |
| GET/POST | /api/backups | 备份列表/创建 |
| POST | /api/backups/<id>/restore | 恢复备份 |
| POST | /api/backups/cleanup | 清理旧备份 |
用 curl 调 API 时先登录拿到 Cookie，再带着 Cookie 调：
# 登录并保存 Cookie
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 表示成功
# 查仪表盘汇总
curl -b /tmp/sm_cookies.txt http://你的IP:5000/api/dashboard
# 查活跃连接
curl -b /tmp/sm_cookies.txt http://你的IP:5000/api/stats/connections九、客户端接入示例
代理实例启动后，任何支持 SOCKS5 的客户端都能用：服务器地址填实例的监听地址，端口填实例端口，认证方式按实例配置选择无认证或账号密码。下面是最常用的几种接法：
# curl 走 SOCKS5 代理（无认证）
curl --socks5 你的IP:1080 http://example.com -I
# curl 走 SOCKS5 代理（账号密码认证）
curl --socks5 你的IP:1080 -U 用户名:密码 http://example.com -I
# 全终端会话走代理（需要代理客户端工具支持，仅示例思路）
export ALL_PROXY=socks5://用户名:密码@你的IP:1080图形客户端（Shadowrocket、v2rayNG、Clash 等）按各自的 SOCKS5 节点格式填写：类型选 SOCKS5，地址、端口、用户名、密码与实例和用户配置保持一致。注意：通过 SOCKS5 代理访问管理面板本身可能导致 Cookie 问题，访问面板请直连，不要走代理。
十、生产部署：Gunicorn + systemd + Nginx
Flask 内置开发服务器不适合生产环境，生产部署分三步：Gunicorn 跑 Web 面板、systemd 托管、Nginx 反代加 SSL。
10.1 Gunicorn 启动
# 安装 gunicorn
pip install gunicorn --break-system-packages
# 最小启动（不推荐生产，worker 数量 = CPU 核心数，单核机器用 -w 1）
gunicorn -w 1 -b 0.0.0.0:5000 run:app
# 推荐参数：30s 超时 + 优雅关闭 + 周期性回收 worker 防内存泄漏
gunicorn -w 1 -b 0.0.0.0:5000 \
--timeout 30 \
--graceful-timeout 30 \
--max-requests 1000 \
--max-requests-jitter 100 \
--limit-request-line 8190 \
--limit-request-fields 100 \
run:app注意：SOCKS5 代理实例运行在独立的 asyncio 线程中，不受 Gunicorn worker 数量影响。生产请用 systemd 托管，裸 gunicorn 没有开机自启和崩溃重启。
10.2 systemd 服务（推荐）
服务单元文件的唯一权威源在仓库 deploy/socks-manager.service，所有参数、调优注释、MemoryMax 限制都集中在那一份，生产机只放一份拷贝。关键参数：-w 1 / --timeout 30 / --graceful-timeout 30 是 1 核 + 1GB 内存机型的基线，按 nproc 调整 -w；--max-requests 1000 + jitter 周期性回收 worker 防内存泄漏；MemoryMax=512M 是 cgroup 硬上限，防整台 VPS 被拖死；LimitNOFILE=65535 是 SOCKS5 大并发客户端连接需要。
# 1. 在本地修改 deploy/socks-manager.service
# 2. git commit + push
# 3. 在生产机（/opt/socks-manager）拉取并执行：
git pull
sudo bash deploy/install.sh
# install.sh 做的事：复制 unit 到 /etc/systemd/system/ → daemon-reload → enable（开机自启）→ restart → 等 15s 验证 active
# 常用命令
systemctl status socks-manager
journalctl -u socks-manager -f # 实时日志
systemctl restart socks-manager # 改完代码后重启10.3 Nginx 反向代理 + SSL
server {
listen 80;
server_name 你的域名;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name 你的域名;
ssl_certificate /etc/letsencrypt/live/你的域名/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/你的域名/privkey.pem;
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;
proxy_buffering off;
proxy_request_buffering off;
proxy_http_version 1.1;
}
}十一、常见问题
11.1 在其他服务器上无法登录
浏览器访问面板，输入密码后提示错误或跳转回登录页，可能的原因和解决办法：
| 原因 | 解决 |
|---|---|
| 密码不一致 | 确认所有服务器 .env 文件中的 SM_ADMIN_PASSWORD 一致 |
| Cookie 被浏览器拒绝（HTTP + 非标准域名） | 用 curl 登录测试（见第八节命令） |
| 通过 SOCKS5 代理访问面板 | 直连（非代理模式）访问面板 |
| Session Cookie 域名不匹配 | 设置 SM_SESSION_DOMAIN=你的 IP 并重启 |
| HTTPS 下未设置 Secure | 设置 SM_COOKIE_SECURE=true |
11.2 仪表盘流量趋势图无数据
首次部署后需等待 1 小时，后台线程每小时记录一次流量快照。也可以手动记录一次（命令见 6.1 节）。
11.3 SOCKS5 用户密码安全性
SOCKS5 协议（RFC 1929）本身采用明文传输密码。本项目服务端使用 bcrypt 哈希存储，兼容旧版明文存储的数据库（首次验证时自动迁移到哈希）。Web 面板中展示用户时不会泄露密码。传输层面的明文问题需要靠部署方式弥补：内网使用、或走 TLS 隧道、或使用仓库附带的 SOCKS5 TLS 转发器。
十二、安全与运维建议
生产环境检查清单，部署完逐项核对：
- 强制修改默认密码：
SM_ADMIN_PASSWORD和SM_SECRET_KEY都要改，密钥用openssl rand -hex 32生成。 - 数据库备份：配置 crontab 每日备份
socks_manager.db，定期测试恢复流程；平台也支持一键备份和按份数清理。 - 日志级别：生产环境设置
SM_LOG_LEVEL=WARN减少日志量。 - HTTPS：启用 Let's Encrypt SSL 证书，设置
SM_COOKIE_SECURE=true。 - 防火墙：只开放需要的端口：Web 面板（5000）+ SOCKS5 代理端口；SOCKS5 端口建议限制源 IP。
- 优雅关闭：v1.1+ 版本已修复 SOCKS5 实例的优雅关闭逻辑，停止服务时最多等待 5 秒让活跃连接正常关闭，避免
GeneratorExit和Task was destroyed警告。
十三、总结
SOCKS Manager 把“搭一个带管理的 SOCKS5 代理”这件事收敛到了一个 Python 进程里：asyncio 引擎负责高性能转发，Flask 面板负责实例、用户、流量、日志的可视化管理，三级角色权限和审计日志又补上了多人使用时的管控能力。个人用可以直接 python3 run.py 跑起来；团队用走 Gunicorn + systemd + Nginx 的生产部署，再把默认密码、密钥、HTTPS 这三项改掉，就能长期稳定运行。记住最关键的两点：SOCKS5 密码本身是明文传输的，公网部署一定要配合 TLS 或 IP 白名单；流量上限和带宽限制要在用户创建时就配好，事后补救不如事前规划。
