Your Name
421 lines
10 KiB
Markdown
421 lines
10 KiB
Markdown
# 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 和 Linux 的服务管理脚本，支持安装、卸载、启动、停止、重启、开机自启等操作。
|
||
|
||
### Windows - service-windows.bat
|
||
|
||
以**管理员身份**运行 `scripts/service-windows.bat`，进入交互式菜单：
|
||
|
||
```
|
||
========================================
|
||
FTP Server 服务管理工具
|
||
========================================
|
||
|
||
1. 安装服务 (注册为 Windows 服务)
|
||
2. 卸载服务
|
||
3. 启动服务
|
||
4. 停止服务
|
||
5. 重启服务
|
||
6. 查看服务状态
|
||
7. 开机自启 - 开启
|
||
8. 开机自启 - 关闭
|
||
9. 查看运行日志
|
||
0. 退出
|
||
```
|
||
|
||
使用前将 `scripts/service-windows.bat` 复制到 `ftp-server.exe` 同目录下，然后右键"以管理员身份运行"。
|
||
|
||
### Linux - service-linux.sh
|
||
|
||
```bash
|
||
# 添加执行权限
|
||
chmod +x scripts/service-linux.sh
|
||
|
||
# 交互式菜单
|
||
sudo ./scripts/service-linux.sh menu
|
||
|
||
# 或直接使用命令
|
||
sudo ./scripts/service-linux.sh install # 安装为 systemd 服务
|
||
sudo ./scripts/service-linux.sh start # 启动
|
||
sudo ./scripts/service-linux.sh stop # 停止
|
||
sudo ./scripts/service-linux.sh restart # 重启
|
||
sudo ./scripts/service-linux.sh status # 查看状态
|
||
sudo ./scripts/service-linux.sh enable # 设置开机自启
|
||
sudo ./scripts/service-linux.sh disable # 关闭开机自启
|
||
sudo ./scripts/service-linux.sh logs # 查看实时日志
|
||
sudo ./scripts/service-linux.sh uninstall # 卸载服务
|
||
```
|
||
|
||
脚本会自动在 `/etc/systemd/system/ftp-server.service` 创建 systemd 服务文件。
|
||
|
||
### Docker 运行
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t ftp-server .
|
||
|
||
# 运行容器
|
||
docker run -d \
|
||
--name ftp-server \
|
||
-p 2121:2121 \
|
||
-p 50000-50100:50000-50100 \
|
||
-p 8080:8080 \
|
||
-v ./data:/app/data \
|
||
-v ./ftp_root:/app/ftp_root \
|
||
-v ./config.json:/app/config.json \
|
||
ftp-server
|
||
|
||
# 查看日志
|
||
docker logs -f ftp-server
|
||
```
|
||
|
||
### 手动设置开机自启
|
||
|
||
<details>
|
||
<summary>Windows - 任务计划程序（点击展开）</summary>
|
||
|
||
```powershell
|
||
schtasks /create /tn "FTP Server" /tr "C:\path\to\ftp-server.exe" /sc onstart /ru SYSTEM
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>Linux - 手动创建 systemd 服务（点击展开）</summary>
|
||
|
||
创建 `/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
|
||
```
|
||
|
||
</details>
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
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 # 前端逻辑
|
||
├── scripts/
|
||
│ ├── service-windows.bat # Windows 服务管理脚本
|
||
│ └── service-linux.sh # Linux 服务管理脚本
|
||
├── Dockerfile # Docker 构建文件
|
||
├── 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
|