FTP Server 教程：Go 单文件 FTP 服务器与 Web 管理部署

局域网里传文件，搭个 FTP 服务器是最直接的办法，但传统 FTP 服务配起来琐碎：用户、权限、目录、被动端口、防火墙，一套下来半天过去了。FTP-Server 是 AI-Agent 组织下的 Go 开源项目，单个可执行文件自带 FTP 服务和 Web 管理界面，支持多用户隔离、权限配额、速率限制、操作日志和在线监控，Windows、Linux、Docker 都能一键跑起来。本文从编译部署讲到 Web 管理、防火墙和服务化。

一、项目简介

FTP-Server 是基于 Go 语言开发的 FTP 服务器，自带 Web 管理界面。编译后是一个可执行文件，无需额外依赖，双击或一条命令就能跑。启动后同时提供两个服务：FTP 服务默认监听 2121 端口，Web 管理界面默认在 8080 端口。浏览器打开 Web 界面登录后，可以完成用户管理、文件浏览、日志查询、在线监控和系统设置，日常运维基本不用碰命令行。

和系统自带的 FTP 服务（比如 vsftpd、FileZilla Server）相比，它的优势是部署形态：单文件、零依赖、配置自动生成，换台机器复制过去就能跑；劣势是功能聚焦在中小规模文件共享场景，没有集群和高可用设计，适合团队内部、家庭局域网、临时文件分发这些场景。

二、功能特性

模块	说明
FTP 服务	支持主动 / 被动模式、多用户隔离、权限控制、速率限制
Web 管理	仪表盘、用户管理、文件管理、日志查询、在线用户监控、系统设置
用户管理	添加 / 编辑 / 删除用户、独立主目录、读写权限、空间配额、速度限制
自动创建目录	添加用户时指定的主目录不存在会自动创建
操作日志	记录登录、上传、下载等操作，支持筛选和分页
单文件部署	编译后一个 exe / bin 文件即可运行，零依赖

三、技术栈与项目结构

部分	技术	说明
语言	Go 1.21+	单二进制编译，跨平台
FTP 服务	ftpserverlib + afero	ftpserverlib 提供 FTP 协议实现，afero 提供虚拟文件系统抽象
数据库	SQLite（modernc.org/sqlite 纯 Go 实现）	无需 CGO，数据存在 data/ftp.db
Web 认证	JWT	Web 管理界面登录鉴权
前端	原生 HTML / CSS / JavaScript	无框架依赖，静态文件直接内嵌或随程序分发

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               # 依赖校验

值得注意的是数据库选了 modernc.org/sqlite 的纯 Go 实现，不需要 CGO，这意味着交叉编译非常干净——在 Linux 上直接 GOOS=windows go build 就能出 Windows 版，不用折腾 mingw 交叉工具链。这一点对分发很友好。

四、适用场景

• 团队内部文件共享：每人一个账号、独立主目录，上传下载走 FTP 客户端，比在群里传文件可靠，也比临时搭网盘快；
• 家庭 / 办公室局域网共享：NAS 之外的轻量选择，旧电脑装个 Linux 跑起来就是文件服务器；
• 给客户或外包交付文件：建一个只读账号，配好配额和有效期，客户用 FileZilla 自取，不用再发网盘链接；
• 设备固件与日志收集：嵌入式设备、摄像头、工控机定时 FTP 上传日志和文件，服务端按用户隔离存放；
• 临时文件分发：发版、发安装包、发大文件时，起一个 FTP 服务加一个匿名或公开账号，用完就关。

五、快速开始

5.1 Windows

方式一是直接下载可执行文件：从 Releases 页面下载 ftp-server.exe，放到任意目录，双击运行或命令行启动：

.\ftp-server.exe

方式二是从源码编译，需要先装 Go 1.21 或更高版本：

git clone ssh://git@git.cnbugs.com:10022/AI-Agent/FTP-Server.git
cd FTP-Server
go build -o ftp-server.exe .
.\ftp-server.exe

5.2 Linux

# 安装 Go 语言环境（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

# 克隆项目并编译
git clone ssh://git@git.cnbugs.com:10022/AI-Agent/FTP-Server.git
cd FTP-Server
go build -o ftp-server .

# 运行
./ftp-server

5.3 交叉编译

# 在 Windows 上编译 Linux 版本（PowerShell）
$env:GOOS="linux"; $env:GOARCH="amd64"; go build -o ftp-server .

# 在 Linux / Mac 上交叉编译 Windows 版本
GOOS=windows GOARCH=amd64 go build -o ftp-server.exe .

5.4 Docker 运行

docker build -t ftp-server .
docker run -d -p 2121:2121 -p 50000-50100:50000-50100 -p 8080:8080 ftp-server

生产用 Docker 建议挂载数据卷，否则容器删了数据就没了：

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

六、启动与首次登录

启动成功后会显示：

========================================
  FTP Server with Web Management
========================================

  FTP端口: 2121
  Web管理: http://localhost:8080

  按 Ctrl+C 停止服务器

浏览器打开 http://localhost:8080，用默认管理员账号登录：用户名 admin，密码 admin123。请登录后立即在「系统设置」中修改管理员密码！默认密码留在生产环境等于没设防。

七、配置详解

首次运行会在当前目录自动生成 config.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
database.path	SQLite 数据库路径	./data/ftp.db

也可以通过 Web 管理界面的「系统设置」页面在线修改配置，改完需要重启服务生效。指定自定义配置文件路径用 -config 参数：

# 使用自定义配置文件路径
./ftp-server -config /etc/ftp/config.json

几个配置项值得多说两句：ftp.port 默认是 2121 而不是标准 21 端口，这是刻意为之——标准 21 端口在很多环境需要 root 权限且容易和系统自带 FTP 服务冲突，2121 避开了这些问题；passive_port_min/max 决定了被动模式的数据端口范围，防火墙必须放行整个范围，否则客户端能登录但拉不出目录列表；enable_anonymous 默认 false，临时分发场景可以打开，但要配合只读权限和独立目录，别让匿名用户写进别人的主目录。

八、Web 管理功能详解

8.1 仪表盘

展示系统概览：用户总数、启用用户、在线用户、今日登录 / 上传 / 下载统计、总传输量。每天先看一眼仪表盘，就知道服务是不是正常、谁在传大文件。

8.2 用户管理

这是最常用的页面：添加、编辑、删除 FTP 用户；设置用户主目录（不存在会自动创建）；配置权限（只读、只写、读写）；设置空间配额和文件数限制；设置上传 / 下载速率限制；启用 / 禁用账户；修改用户密码。

权限设计的建议是按最小权限来：只给对方下载就设只读，只收文件就设只写，读写只给自己人。空间配额和文件数限制要一起设，只设配额不设文件数，小文件一多照样能把磁盘 inode 占满。速率限制按场景给，对外分发的账号限速能防止一个人把带宽占满。

8.3 文件管理

在 Web 界面直接浏览 FTP 目录结构、上传文件、新建文件夹、删除文件和文件夹。适合管理员快速处理文件，不用再开 FTP 客户端。但注意 Web 上传大文件受浏览器和网络限制，GB 级别的文件还是用 FTP 客户端传更稳。

8.4 操作日志与在线用户

操作日志记录所有 FTP 操作（登录、上传、下载等），支持按用户名、操作类型筛选，分页浏览。出问题先查日志：谁、什么时候、从哪个 IP、做了什么，一目了然。在线用户页面实时查看当前连接的 FTP 用户，显示用户名、IP、登录时间、当前目录，发现异常连接可以直接处理。

九、FTP 客户端连接

使用任意 FTP 客户端连接：主机填 localhost（或服务器 IP），端口 2121，用户名和密码用在 Web 管理界面中创建的 FTP 用户。推荐的客户端：Windows 用 FileZilla、WinSCP；Linux 用 ftp 命令、FileZilla、lftp。

# Linux 命令行连接示例
ftp localhost 2121
# 或使用 lftp
lftp -p 2121 localhost

主动模式和被动模式的区别要搞清楚：主动模式是服务端反向连接客户端的数据端口，客户端在 NAT 或防火墙后面时基本连不上；被动模式是客户端主动连接服务端的被动端口（默认 50000-50100），绝大多数场景都应该用被动模式。FileZilla 默认就是被动模式，一般不用改。客户端连上后无法获取目录列表，十有八九是防火墙没放行被动端口范围，或者客户端被设成了主动模式。

十、防火墙配置

需要开放三个端口段：

端口	用途
2121	FTP 控制连接
50000-50100	FTP 被动模式数据传输
8080	Web 管理界面

# Windows 防火墙（以管理员身份运行 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 防火墙（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

注意 8080 只在内网放行就够了，Web 管理界面不要直接暴露到公网。如果必须远程管理，走 VPN 或 SSH 隧道，或者前面加一层带认证的反向代理。

十一、服务管理

项目提供了 Windows 和 Linux 的服务管理脚本，支持安装、卸载、启动、停止、重启、开机自启等操作。

11.1 Windows 服务管理脚本

以管理员身份运行 scripts/service-windows.bat，进入交互式菜单。使用前把 scripts/service-windows.bat 复制到 ftp-server.exe 同目录下，然后右键“以管理员身份运行”：

========================================
  FTP Server 服务管理工具
========================================

  1. 安装服务（注册为 Windows 服务）
  2. 卸载服务
  3. 启动服务
  4. 停止服务
  5. 重启服务
  6. 查看服务状态
  7. 开机自启 - 开启
  8. 开机自启 - 关闭
  9. 查看运行日志
  0. 退出

11.2 Linux 服务管理脚本

# 添加执行权限
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 服务文件。

11.3 手动设置开机自启

Windows 用任务计划程序：

schtasks /create /tn "FTP Server" /tr "C:\path\to\ftp-server.exe" /sc onstart /ru SYSTEM

Linux 手动创建 systemd 服务，写入 /etc/systemd/system/ftp-server.service：

[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

sudo systemctl daemon-reload
sudo systemctl start ftp-server
sudo systemctl enable ftp-server

十二、备份与恢复

备份三样东西就够了：data/ftp.db（数据库，用户、日志都在里面）、config.json（配置）、ftp_root/（用户文件）。恢复时把这三样放回原位置，重启服务即可。建议的备份方式：

# 停服务再备份数据库，避免 SQLite 写一半被拷走
sudo systemctl stop ftp-server
tar czf ftp-backup-$(date +%F).tar.gz -C /opt/ftp-server data config.json ftp_root
sudo systemctl start ftp-server

# 异地留一份
scp ftp-backup-*.tar.gz backup@backup-host:/backup/ftp/

注意备份前先停服务，SQLite 在写入过程中被直接拷贝可能导致备份文件损坏。如果不想停服务，至少要在业务低峰期备份，并且恢复后检查数据库能不能正常打开。

十三、常见问题

• FTP 客户端连接后无法获取目录列表：检查防火墙是否开放了被动模式端口（默认 50000-50100），FTP 客户端需要设置为被动模式（PASV）；
• 如何修改 FTP 端口或 Web 端口：编辑 config.json 文件或在 Web 管理界面的「系统设置」中修改，修改后需要重启服务；
• 忘记管理员密码怎么办：停止服务，编辑 config.json 中的 admin.password 字段，重新启动即可；
• 如何备份数据：备份 data/ftp.db（数据库）和 config.json（配置）以及 ftp_root/（用户文件）即可；
• 用户登录成功但看不到文件：检查用户主目录路径是否正确、权限是不是只读、主目录是不是空目录（添加用户时主目录不存在会自动创建，但如果路径写错就会建到别的地方）；
• 上传速度很慢：检查用户是否被设了速率限制，检查被动端口范围有没有被防火墙限速，内网传输优先排查客户端的限速设置。

十四、安全与运维建议

• 第一时间改默认密码：admin / admin123 是公开的默认密码，部署完立刻在系统设置里改掉；
• FTP 协议本身不加密：用户名、密码、文件内容都是明文传输，只在可信内网用；要过公网请走 VPN、SSH 隧道，或者换 SFTP 方案；
• 最小权限：只读账号只给读，只写账号只给写，读写只给自己人；匿名访问默认关闭，临时打开也要配独立目录和只读权限；
• 配额和限速：空间配额、文件数限制、上传 / 下载速率限制三件套都配上，防止一个账号把磁盘或带宽占满；
• Web 管理口别暴露公网：8080 只在内网放行，远程管理走 VPN 或反代加认证；
• 定期备份：data/ftp.db、config.json、ftp_root 三样定期备份，备份前停服务或选低峰期；
• 看日志：操作日志会记登录、上传、下载，定期检查有没有异常登录或异常大文件传输；
• 被动端口范围别放太大：默认 50000-50100 共 101 个端口，够几十个并发用，范围越大防火墙暴露面越大，按并发量调整。

总结一下：FTP-Server 把 FTP 服务做成了开箱即用的单文件形态——Go 编译零依赖、Web 界面管用户和权限、SQLite 存数据、脚本管服务。局域网文件共享、给客户交付文件、设备日志收集这类场景，复制过去就能跑。记住两个要点：部署完立刻改默认密码，FTP 只在可信内网用。