FTP-Server/README.md

# 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