From d59699b5cebf78f4f72020ed67e0d0b961c45403 Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Thu, 16 Jul 2026 16:41:17 +0800
Subject: [PATCH] docs: add README with setup guide and API reference

---
 README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fd39ebc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# 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