# SOCKS Manager — SOCKS5 代理管理系统

基于 Flask + SQLite + Bootstrap 5 的 SOCKS5 代理管理平台，提供 Web 界面和 RESTful API。

## 功能

- **仪表盘** — 代理总数 / 在线 / 离线统计，最近活跃代理，操作日志
- **代理管理** — 添加 / 编辑 / 删除 SOCKS5 代理（支持用户名密码认证），启用 / 禁用
- **分组管理** — 按颜色分组组织代理，分组筛选
- **健康检测** — SOCKS5 隧道连通性检测（测试 URL httpbin.org），单代理 / 批量检测，延迟统计
- **操作日志** — 增删改操作记录，分页查询
- **RESTful API** — 全套 CRUD + 健康检测 + 统计接口
- **管理员登录** — 密码保护后台

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Python 3.11 + Flask 3.0 + Flask-SQLAlchemy |
| 数据库 | SQLite（零配置，文件存储） |
| 前端 | Jinja2 模板 + Bootstrap 5 + Bootstrap Icons（暗色主题） |
| SOCKS5 | PySocks |

## 快速开始

```bash
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` 的值。

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SM_ADMIN_USER` | `admin` | 管理员用户名 |
| `SM_ADMIN_PASSWORD` | `""` | 管理员密码（必须设置，否则无法登录） |
| `SM_DB_URI` | `sqlite:///socks_manager.db` | 数据库连接串 |
| `SM_HEALTH_TIMEOUT` | `10` | 健康检测超时（秒） |
| `SM_HEALTH_INTERVAL` | `300` | 建议的健康检测间隔（秒） |
| `SM_LOG_LEVEL` | `INFO` | 日志级别 |

## 目录结构

```
socks-manager/
├── app.py              # 启动入口
├── 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       # 日志
```

## 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` | 批量检测全部代理 |

## 注意事项

- 健康检测通过建立 SOCKS5 隧道连接 httpbin.org 来验证代理可用性，会产生真实网络流量
- 开发服务器不适合生产环境，生产请使用 gunicorn/uwsgi
- SQLite 适合中小型部署（数千代理），超大规模建议切换到 PostgreSQL