From 98e00c1f32935a9f4802cd0985a17b7a75dfadbb Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Wed, 6 May 2026 17:38:57 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20README=20=E4=BD=BF?=
 =?UTF-8?q?=E7=94=A8=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3018605
--- /dev/null
+++ b/README.md
@@ -0,0 +1,348 @@
+# FTP Server with Web Management
+
+一个基于 Go 语言开发的 FTP 服务器，自带 Web 管理界面。支持多用户管理、文件浏览、操作日志、在线监控等功能。编译为单个可执行文件，无需额外依赖。
+
+## 功能特性
+
+- **FTP 服务**：支持主动/被动模式、多用户隔离、权限控制、速率限制
+- **Web 管理**：仪表盘、用户管理、文件管理、日志查询、在线用户监控、系统设置
+- **用户管理**：添加/编辑/删除用户、独立主目录、读写权限、空间配额、速度限制
+- **自动创建目录**：添加用户时指定的主目录不存在会自动创建
+- **操作日志**：记录登录、上传、下载等操作，支持筛选和分页
+- **单文件部署**：编译后一个 exe/bin 文件即可运行，零依赖
+
+## 快速开始
+
+### Windows
+
+#### 方式一：直接下载可执行文件
+
+1. 从 Releases 页面下载 `ftp-server.exe`
+2. 放到任意目录，双击运行或命令行启动：
+
+```powershell
+.\ftp-server.exe
+```
+
+#### 方式二：从源码编译
+
+1. 安装 [Go 语言环境](https://go.dev/dl/)（1.21 或更高版本）
+
+2. 克隆项目并编译：
+
+```powershell
+git clone ssh://git@git.cnbugs.com:10022/AI-Agent/FTP-Server.git
+cd FTP-Server
+go build -o ftp-server.exe .
+```
+
+3. 运行：
+
+```powershell
+.\ftp-server.exe
+```
+
+### Linux
+
+#### 从源码编译
+
+1. 安装 Go 语言环境：
+
+```bash
+# Ubuntu/Debian
+sudo apt install golang-go
+
+# CentOS/RHEL
+sudo yum install golang
+
+# 或从官网下载安装
+wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
+sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz
+export PATH=$PATH:/usr/local/go/bin
+```
+
+2. 克隆项目并编译：
+
+```bash
+git clone ssh://git@git.cnbugs.com:10022/AI-Agent/FTP-Server.git
+cd FTP-Server
+go build -o ftp-server .
+```
+
+3. 运行：
+
+```bash
+./ftp-server
+```
+
+#### 交叉编译（在 Windows 上编译 Linux 版本）
+
+```powershell
+$env:GOOS="linux"; $env:GOARCH="amd64"; go build -o ftp-server .
+```
+
+```bash
+# Linux/Mac 上交叉编译 Windows 版本
+GOOS=windows GOARCH=amd64 go build -o ftp-server.exe .
+```
+
+### 使用 Docker 运行（可选）
+
+```bash
+docker build -t ftp-server .
+docker run -d -p 2121:2121 -p 50000-50100:50000-50100 -p 8080:8080 ftp-server
+```
+
+## 启动后访问
+
+启动成功后会显示：
+
+```
+========================================
+  FTP Server with Web Management
+========================================
+
+  FTP端口: 2121
+  Web管理: http://localhost:8080
+
+  按 Ctrl+C 停止服务器
+```
+
+### Web 管理界面
+
+浏览器打开 `http://localhost:8080`，使用默认管理员账号登录：
+
+- 用户名：`admin`
+- 密码：`admin123`
+
+> **请登录后立即在「系统设置」中修改管理员密码！**
+
+### FTP 连接
+
+使用任意 FTP 客户端连接：
+
+- 主机：`localhost`（或服务器 IP）
+- 端口：`2121`
+- 用户名/密码：在 Web 管理界面中创建的 FTP 用户
+
+推荐的 FTP 客户端：
+- Windows：[FileZilla](https://filezilla-project.org/)、WinSCP
+- Linux：`ftp` 命令、FileZilla、lftp
+
+```bash
+# Linux 命令行连接示例
+ftp localhost 2121
+# 或使用 lftp
+lftp -p 2121 localhost
+```
+
+## 配置说明
+
+首次运行会在当前目录自动生成 `config.json`：
+
+```json
+{
+  "ftp": {
+    "host": "0.0.0.0",
+    "port": 2121,
+    "passive_port_min": 50000,
+    "passive_port_max": 50100,
+    "root_dir": "./ftp_root",
+    "enable_anonymous": false,
+    "max_connections": 50,
+    "idle_timeout": 300
+  },
+  "web": {
+    "host": "0.0.0.0",
+    "port": 8080
+  },
+  "admin": {
+    "username": "admin",
+    "password": "admin123"
+  },
+  "database": {
+    "path": "./data/ftp.db"
+  }
+}
+```
+
+### 配置项说明
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `ftp.host` | FTP 监听地址 | `0.0.0.0` |
+| `ftp.port` | FTP 端口 | `2121` |
+| `ftp.passive_port_min` | 被动模式端口范围起始 | `50000` |
+| `ftp.passive_port_max` | 被动模式端口范围结束 | `50100` |
+| `ftp.root_dir` | FTP 根目录 | `./ftp_root` |
+| `ftp.enable_anonymous` | 允许匿名访问 | `false` |
+| `ftp.max_connections` | 最大连接数 | `50` |
+| `ftp.idle_timeout` | 空闲超时（秒） | `300` |
+| `web.host` | Web 管理界面监听地址 | `0.0.0.0` |
+| `web.port` | Web 管理界面端口 | `8080` |
+| `admin.username` | 管理员用户名 | `admin` |
+| `admin.password` | 管理员密码 | `admin123` |
+
+也可以通过 Web 管理界面的「系统设置」页面在线修改配置。
+
+### 指定配置文件
+
+```bash
+# 使用自定义配置文件路径
+./ftp-server -config /etc/ftp/config.json
+```
+
+## Web 管理功能
+
+### 仪表盘
+
+展示系统概览：用户总数、启用用户、在线用户、今日登录/上传/下载统计、总传输量。
+
+### 用户管理
+
+- 添加/编辑/删除 FTP 用户
+- 设置用户主目录（不存在会自动创建）
+- 配置权限：只读、只写、读写
+- 设置空间配额和文件数限制
+- 设置上传/下载速率限制
+- 启用/禁用账户
+- 修改用户密码
+
+### 文件管理
+
+- 浏览 FTP 目录结构
+- 上传文件
+- 新建文件夹
+- 删除文件/文件夹
+
+### 操作日志
+
+- 记录所有 FTP 操作（登录、上传、下载等）
+- 按用户名、操作类型筛选
+- 分页浏览
+
+### 在线用户
+
+- 实时查看当前连接的 FTP 用户
+- 显示用户名、IP、登录时间、当前目录
+
+## 防火墙配置
+
+需要开放以下端口：
+
+| 端口 | 用途 |
+|------|------|
+| 2121 | FTP 控制连接 |
+| 50000-50100 | FTP 被动模式数据传输 |
+| 8080 | Web 管理界面 |
+
+### Windows 防火墙
+
+```powershell
+# 以管理员身份运行 PowerShell
+netsh advfirewall firewall add rule name="FTP Server" dir=in action=allow protocol=TCP localport=2121
+netsh advfirewall firewall add rule name="FTP Passive" dir=in action=allow protocol=TCP localport=50000-50100
+netsh advfirewall firewall add rule name="FTP Web" dir=in action=allow protocol=TCP localport=8080
+```
+
+### Linux 防火墙
+
+```bash
+# firewalld
+sudo firewall-cmd --permanent --add-port=2121/tcp
+sudo firewall-cmd --permanent --add-port=50000-50100/tcp
+sudo firewall-cmd --permanent --add-port=8080/tcp
+sudo firewall-cmd --reload
+
+# iptables
+sudo iptables -A INPUT -p tcp --dport 2121 -j ACCEPT
+sudo iptables -A INPUT -p tcp --dport 50000:50100 -j ACCEPT
+sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
+```
+
+## 开机自启（可选）
+
+### Windows - 任务计划程序
+
+```powershell
+# 创建开机自启任务
+schtasks /create /tn "FTP Server" /tr "C:\path\to\ftp-server.exe" /sc onstart /ru SYSTEM
+```
+
+### Linux - systemd
+
+创建服务文件 `/etc/systemd/system/ftp-server.service`：
+
+```ini
+[Unit]
+Description=FTP Server with Web Management
+After=network.target
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=/opt/ftp-server
+ExecStart=/opt/ftp-server/ftp-server -config /opt/ftp-server/config.json
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+启动并设置开机自启：
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl start ftp-server
+sudo systemctl enable ftp-server
+
+# 查看状态
+sudo systemctl status ftp-server
+
+# 查看日志
+sudo journalctl -u ftp-server -f
+```
+
+## 项目结构
+
+```
+ftp-server/
+├── main.go              # 主入口
+├── config/config.go     # 配置管理
+├── database/db.go       # SQLite 数据库层
+├── ftp/server.go        # FTP 服务器
+├── web/server.go        # Web 管理 API
+├── static/
+│   ├── index.html       # 管理界面
+│   ├── css/style.css    # 样式
+│   └── js/app.js        # 前端逻辑
+├── go.mod               # Go 模块定义
+└── go.sum               # 依赖校验
+```
+
+## 技术栈
+
+- **语言**：Go 1.21+
+- **FTP 服务**：[ftpserverlib](https://github.com/fclairamb/ftpserverlib) + [afero](https://github.com/spf13/afero)
+- **数据库**：SQLite（[pure Go 实现](https://modernc.org/sqlite/)，无需 CGO）
+- **Web 认证**：JWT
+- **前端**：原生 HTML/CSS/JavaScript
+
+## 常见问题
+
+**Q: FTP 客户端连接后无法获取目录列表？**
+A: 检查防火墙是否开放了被动模式端口（默认 50000-50100），FTP 客户端需要设置为被动模式（PASV）。
+
+**Q: 如何修改 FTP 端口或 Web 端口？**
+A: 编辑 `config.json` 文件或在 Web 管理界面的「系统设置」中修改，修改后需要重启服务。
+
+**Q: 忘记管理员密码怎么办？**
+A: 停止服务，编辑 `config.json` 中的 `admin.password` 字段，重新启动即可。
+
+**Q: 如何备份数据？**
+A: 备份 `data/ftp.db`（数据库）和 `config.json`（配置）以及 `ftp_root/`（用户文件）即可。
+
+## License
+
+MIT