From f7310541e1fa34539dbca6550fd60b3bb3dca32d Mon Sep 17 00:00:00 2001
From: wzj <244142824@qq.com>
Date: Wed, 25 Jun 2025 11:59:04 +0800
Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0README.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e3e11a4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,182 @@
+# Squid 代理管理系统
+![徽章](https://img.shields.io/badge/proxy-squid-4caf50?logo=nginxproxymanager)
+![徽章](https://img.shields.io/badge/Python-3.8%2B-blue?labelColor=yellow&style=plastic&logo=python&logoColor=blue)
+![徽章](https://img.shields.io/badge/Flask-2-blue?labelColor=yellow&style=plastic&logo=flask&logoColor=blue)
+![徽章](https://img.shields.io/badge/github-jeazw-blue?labelColor=yellow&style=plastic&logo=github&logoColor=blue)
+
+基于 Flask 的 Squid 代理用户管理界面，提供 Web 界面管理 Squid 代理用户和配置。
+
+## 功能特性
+
+- 🛡️ 基于 Basic Auth 的管理员认证
+- 👥 代理用户管理（增删改查、启用/禁用）
+- ⚙️ 代理服务器配置管理
+- 📊 用户统计仪表盘
+- 🐳 Docker 容器化部署
+- 📝 配置文件持久化存储
+
+## 快速部署
+
+### 前提条件
+
+- Docker 20.10+
+- Docker Compose 2.0+
+- 开放端口 51822 (Squid) 和 51823 (Web UI)
+
+### 部署步骤
+
+1. **准备持久化目录**  
+   在项目根目录执行：
+   ```bash
+   mkdir -p config log
+   chown 31:31 log  # Squid 默认使用 squid 用户(UID 31)
+   ```
+
+2. **构建镜像**  
+   分别构建两个服务的镜像：
+   ```bash
+   # 构建 Web UI 镜像
+   docker build -t squid-ui:latest .
+   
+   # 构建 Squid 镜像
+   cd squid && docker build -t squid:latest .
+   cd ..
+   ```
+
+3. **初始化配置文件**  
+   首次运行前需要准备基础配置：
+   ```bash
+   touch config/squid_passwd
+   cat > config/config.json <<EOF
+   {
+     "admin_password": "admin123",
+     "proxy_address": "0.0.0.0",
+     "proxy_port": "3128"
+   }
+   EOF
+   ```
+
+4. **启动服务**  
+   通过 compose 启动服务：
+   ```bash
+   docker-compose up -d
+   ```
+
+5. **验证服务状态**  
+   ```bash
+   docker-compose ps
+   ```
+   应该看到两个服务状态均为 `running`
+
+### 访问管理界面
+
+```
+http://your-server-ip:51823
+```
+默认管理员凭证：
+- 用户名: `admin`
+- 密码: `admin123`
+
+### 配置代理客户端
+
+```
+代理地址: your-server-ip
+端口: 51822
+认证方式: 用户名/密码
+```
+
+## 持久化存储说明
+
+| 目录/文件 | 用途 | 权限要求 |
+|-----------|------|----------|
+| `./config` | 存储所有配置文件 | 默认 |
+| `./config/squid_passwd` | 用户认证文件 | 容器内可读写 |
+| `./log` | Squid 日志目录 | 必须设置为 31:31 (squid用户) |
+
+## 常见问题
+
+### 权限问题排查
+
+如果 Squid 容器启动失败，检查日志目录权限：
+```bash
+ls -ld log
+```
+正确输出应该类似：
+```
+drwxr-xr-x 2 31 31 4096 Jan 1 00:00 log
+```
+
+修复命令：
+```bash
+chown -R 31:31 log
+```
+
+### 重新构建镜像
+
+当代码更新后需要重新构建：
+```bash
+docker-compose down
+docker build -t squid-ui:latest .
+cd squid && docker build -t squid:latest .
+cd ..
+docker-compose up -d
+```
+
+## 升级指南
+
+1. 停止服务：
+   ```bash
+   docker-compose down
+   ```
+
+2. 备份配置：
+   ```bash
+   cp -r config config_backup_$(date +%Y%m%d)
+   ```
+
+3. 按上述步骤重新构建和启动
+
+## 管理指南
+
+### 添加新用户
+
+1. 登录管理界面
+2. 导航到 "客户端管理"
+3. 点击 "添加用户"
+4. 输入用户名和密码
+5. 点击保存
+
+### 修改代理设置
+
+1. 登录管理界面
+2. 导航到 "系统设置"
+3. 修改以下参数：
+   - 管理员密码
+   - 代理服务器地址
+   - 代理服务器端口
+4. 点击 "保存设置"
+
+### 查看日志
+
+Squid 日志位于主机上的 `./log` 目录：
+
+```bash
+tail -f ./log/access.log
+```
+
+## 常见问题
+
+**Q: 为什么我的代理连接被拒绝？**  
+A: 检查：
+- Squid 容器是否正常运行 (`docker ps`)
+- 用户是否已激活
+- 防火墙是否允许 51822 端口
+
+**Q: 如何重置管理员密码？**  
+A: 编辑 `config/config.json` 文件中的 `admin_password` 字段
+
+## 许可证
+
+MIT License
+
+Copyright (c) 2025 Jeazw
\ No newline at end of file