CentOS 7 + FastDFS 与 Nginx 整合完整技术文档

适用场景：在 CentOS 7 服务器上部署 FastDFS 单机或基础集群环境，并通过 fastdfs-nginx-module 提供 HTTP 文件访问能力。本文以 Tracker + Storage + Nginx + FastDFS Nginx 模块 为主线，整理安装、配置、验证、访问、Java 客户端接入与常见问题处理流程。

1. 文档依据与版本说明#

1.1 主要参考资料#

本文结合以下资料整理：

FastDFS 官方仓库与 README：FastDFS 是一个高性能分布式文件系统，主要提供文件存储、同步、访问能力，并面向高容量和负载均衡场景。
FastDFS 官方 INSTALL：新版 FastDFS 安装流程依赖 libfastcommon，较新的版本还依赖 libserverframe。
fastdfs-nginx-module 官方配置文件：mod_fastdfs.conf 中定义了 tracker_server、storage_server_port、url_have_group_name、store_path_count、store_path0、response_mode 等关键参数。
FastDFS HISTORY：从 4.05 版本开始，FastDFS 移除了内置 HTTP 支持，因此实际生产访问通常需要结合 Nginx 模块。
CentOS 7 生命周期信息：CentOS Linux 7 已于 2024-06-30 结束生命周期，生产环境建议迁移到受支持系统。

1.2 本文采用的示例版本#

你提供的原始内容使用的是较早版本：

组件	示例版本	说明
操作系统	CentOS 7 x86_64	最小化安装环境
libfastcommon	master / 旧版源码包	FastDFS 基础依赖库
FastDFS	5.11	老项目中常见版本
fastdfs-nginx-module	master / 旧版源码包	Nginx 访问 FastDFS 文件的模块
Nginx	1.12.0	示例版本较旧，生产建议使用安全维护版本
fastdfs-client-java	1.26 / 1.27	Java 客户端示例

注意：FastDFS 官方仓库已经发布到 6.x 系列。若是新项目，应优先采用新版本，并阅读对应版本的 INSTALL、README 与配置样例。若维护既有 CentOS 7 + FastDFS 5.11 环境，本文中的命令仍具有参考价值，但需要注意系统和组件均较旧，存在安全与兼容性风险。

2. FastDFS 架构理解#

2.1 FastDFS 的核心角色#

FastDFS 由三类角色组成：

角色	作用
Tracker Server	跟踪服务器，负责调度、负载均衡、管理 Storage Server 状态
Storage Server	存储服务器，负责文件存储、文件同步、文件访问接口
Client	客户端，调用 FastDFS API 完成上传、下载、删除、查询等操作

FastDFS 的文件标识通常由两部分组成：

text
group1/M00/00/00/xxxxxxxx.jpg

含义如下：

片段	含义
`group1`	文件所属组名
`M00`	存储路径映射编号，通常对应 `store_path0`
`00/00`	二级目录，FastDFS 自动按散列规则生成
`xxxxxxxx.jpg`	FastDFS 生成的文件名

2.2 Tracker 与 Storage 的关系#

一个 FastDFS 集群可以有多个 Tracker，多个 Tracker 之间通常是对等关系，不依赖主从选举。Storage 按 Group 组织，同一 Group 内的 Storage 节点会进行文件同步，用于冗余备份；不同 Group 之间文件相互独立，用于横向扩容。

2.3 为什么需要 Nginx 模块#

早期 FastDFS 曾有简单的 HTTP 支持，但官方历史记录显示，FastDFS 4.05 已经移除内置 HTTP 支持。因此，实际项目中通常通过 fastdfs-nginx-module 让 Nginx 读取 FastDFS Storage 上的文件。

fastdfs-nginx-module 的作用包括：

根据 URL 中的 group、M00、文件路径定位本地文件。
当本机 Storage 尚未同步到文件时，可通过 proxy 或 redirect 模式到源 Storage 获取文件。
利用 Nginx 的 HTTP 能力提供静态文件访问、缓存、反向代理、负载均衡等能力。

3. 部署规划#

3.1 单机部署结构#

适合开发、测试、小规模内部系统：

text
Client / Java 应用
        |
        | FastDFS TCP 协议，22122
        v
Tracker Server
        |
        | 调度 Storage
        v
Storage Server
        |
        | 本地文件存储
        v
Nginx + fastdfs-nginx-module
        |
        | HTTP 访问，80/9999
        v
Browser / 前端 / 业务系统

3.2 推荐目录规划#

为了避免路径混乱，建议统一规划如下：

text
/opt/src                         # 源码包目录
/opt/fastdfs                     # FastDFS 工作目录根路径
/opt/fastdfs/tracker             # Tracker 的 base_path
/opt/fastdfs/storage             # Storage 的 base_path
/data/fastdfs/storage_data       # Storage 实际文件存储路径
/usr/local/nginx                 # Nginx 安装目录
/etc/fdfs                        # FastDFS 配置文件目录

若沿用你原文中的路径，可对应为：

text
/usr/fastdfs/fastdfs_tracker
/usr/fastdfs/fastdfs_storage
/usr/fastdfs/fastdfs_storage_data

建议避免使用个人用户名路径作为生产环境部署目录，例如：

text
/usr/yong.cao/dev/fastdfs/...

生产环境中更推荐使用 /data、/opt、/srv 等稳定目录。

3.3 端口规划#

服务	默认端口	说明
Tracker	22122	FastDFS 调度端口
Storage	23000	Storage 服务端口
Storage Nginx	9999	直接访问 Storage 文件，可自定义
Tracker / 统一入口 Nginx	80 / 8080	对外访问入口

原配置中的 http.server_port 在新版部署中通常不是关键访问方式，因为 FastDFS 内置 HTTP 支持已移除。真正对外提供 HTTP 的一般是 Nginx。

4. 系统准备#

4.1 检查系统版本#

bash
cat /etc/centos-release
uname -a

4.2 安装基础工具#

CentOS 7 最小化安装通常缺少编译和解压工具，先安装：

bash
yum -y install epel-release

yum -y install \
  unzip zip tar wget curl git vim \
  gcc gcc-c++ make automake autoconf libtool \
  pcre pcre-devel zlib zlib-devel openssl openssl-devel

如果无法安装 EPEL，可先跳过 epel-release，只使用系统源安装必要包。

4.3 关闭或配置 SELinux#

开发测试环境可临时关闭：

bash
setenforce 0

查看状态：

bash
getenforce

永久关闭需要修改：

bash
vi /etc/selinux/config

设置：

text
SELINUX=disabled

生产环境不建议简单关闭 SELinux，应根据安全策略配置访问规则。但很多 FastDFS + Nginx 初次部署失败与 SELinux 权限有关，排查时需要关注。

4.4 创建目录#

bash
mkdir -p /opt/src
mkdir -p /opt/fastdfs/tracker
mkdir -p /opt/fastdfs/storage
mkdir -p /data/fastdfs/storage_data

5. 安装 libfastcommon#

5.1 下载源码#

推荐从官方仓库获取：

bash
cd /opt/src
git clone https://github.com/happyfish100/libfastcommon.git
cd libfastcommon

如果使用压缩包：

bash
cd /opt/src
unzip libfastcommon-master.zip
cd libfastcommon-master

5.2 编译安装#

bash
./make.sh clean
./make.sh
./make.sh install

安装后常见库文件位置：

text
/usr/lib64/libfastcommon.so
/usr/include/fastcommon/

5.3 创建兼容性软链接#

部分老版本 FastDFS 或 Nginx 模块会到 /usr/local/lib、/usr/local/include 查找库和头文件，因此可创建软链接：

bash
ln -svf /usr/lib64/libfastcommon.so /usr/local/lib/libfastcommon.so
ln -svf /usr/include/fastcommon /usr/local/include/fastcommon

刷新动态库缓存：

bash
ldconfig

6. 安装 FastDFS#

6.1 下载源码#

推荐从官方仓库获取：

bash
cd /opt/src
git clone https://github.com/happyfish100/fastdfs.git
cd fastdfs

如果使用你原文中的 5.11 压缩包：

bash
cd /opt/src
unzip fastdfs-5.11.zip
cd fastdfs-5.11

6.2 编译安装#

bash
./make.sh clean
./make.sh
./make.sh install

安装完成后，常见路径如下：

内容	路径
命令工具	`/usr/bin/fdfs_*`
配置文件	`/etc/fdfs/`
头文件	`/usr/include/fastdfs/`
库文件	`/usr/lib64/libfdfsclient.so`

6.3 拷贝配置样例#

进入 /etc/fdfs：

bash
cd /etc/fdfs
cp tracker.conf.sample tracker.conf
cp storage.conf.sample storage.conf
cp client.conf.sample client.conf

如果 http.conf、mime.types 尚未复制，可从源码目录复制：

bash
cp /opt/src/fastdfs/conf/http.conf /etc/fdfs/
cp /opt/src/fastdfs/conf/mime.types /etc/fdfs/

若使用 fastdfs-5.11 解压目录，则路径可能是：

bash
cp /opt/src/fastdfs-5.11/conf/http.conf /etc/fdfs/
cp /opt/src/fastdfs-5.11/conf/mime.types /etc/fdfs/

6.4 创建兼容性软链接#

bash
ln -svf /usr/lib64/libfdfsclient.so /usr/local/lib/libfdfsclient.so
ln -svf /usr/include/fastdfs /usr/local/include/fastdfs
ldconfig

7. 配置并启动 Tracker#

7.1 修改 tracker.conf#

bash
vi /etc/fdfs/tracker.conf

重点配置如下：

ini
disabled=false
port=22122
base_path=/opt/fastdfs/tracker

老版本配置中可能还有：

ini
http.server_port=6666

说明：

参数	说明
`disabled=false`	启用 Tracker
`port=22122`	Tracker TCP 服务端口
`base_path`	Tracker 数据和日志目录
`http.server_port`	老版本 HTTP 相关端口，新部署一般不作为文件访问入口

7.2 启动 Tracker#

bash
systemctl start fdfs_trackerd

查看状态：

bash
systemctl status fdfs_trackerd

如果系统未安装 systemd 服务，也可以使用：

bash
service fdfs_trackerd start

7.3 设置开机启动#

优先使用 systemd：

bash
systemctl enable fdfs_trackerd

不建议再使用 /etc/rc.d/rc.local。如果历史环境必须使用，需要确保有执行权限：

bash
chmod +x /etc/rc.d/rc.local

7.4 检查监听端口#

CentOS 7 上可使用：

bash
ss -lntp | grep 22122

或：

bash
netstat -lntp | grep 22122

如果缺少 netstat：

bash
yum -y install net-tools

8. 配置并启动 Storage#

8.1 修改 storage.conf#

bash
vi /etc/fdfs/storage.conf

重点配置：

ini
disabled=false
group_name=group1
port=23000
base_path=/opt/fastdfs/storage
store_path_count=1
store_path0=/data/fastdfs/storage_data
tracker_server=192.168.128.131:22122

老版本可保留：

ini
http.server_port=8888

参数说明：

参数	说明
`group_name`	Storage 所属组名，同组内文件互为备份
`port`	Storage 服务端口
`base_path`	Storage 自身数据和日志目录，不是实际文件存储目录
`store_path_count`	实际文件存储路径数量
`store_path0`	实际文件存储路径
`tracker_server`	Tracker 地址，可配置多个

注意：很多教程误写为 base_path0，正确参数通常是 store_path0。base_path 与 store_path0 含义不同，不能混用。

8.2 启动 Storage#

bash
systemctl start fdfs_storaged

查看状态：

bash
systemctl status fdfs_storaged

设置开机启动：

bash
systemctl enable fdfs_storaged

8.3 检查监听端口#

bash
ss -lntp | grep 23000

应能看到类似：

text
LISTEN 0 128 0.0.0.0:23000 0.0.0.0:* users:("fdfs_storaged",pid=...,fd=...)

8.4 检查 Storage 是否注册到 Tracker#

bash
/usr/bin/fdfs_monitor /etc/fdfs/storage.conf

重点看：

text
group name = group1
storage server port = 23000
storage HTTP port = 8888
ip_addr = 192.168.128.131 ACTIVE

其中 ACTIVE 表示 Storage 已经正常注册并保持心跳。

9. 配置客户端并测试上传#

9.1 修改 client.conf#

bash
vi /etc/fdfs/client.conf

配置：

ini
base_path=/opt/fastdfs/tracker
tracker_server=192.168.128.131:22122

老版本中可能还有：

ini
http.tracker_server_port=6666

9.2 准备测试文件#

bash
echo "hello fastdfs" > /tmp/hello.txt

9.3 上传文件#

bash
/usr/bin/fdfs_upload_file /etc/fdfs/client.conf /tmp/hello.txt

成功后返回：

text
group1/M00/00/00/xxxxxxxx.txt

9.4 查看实际存储目录#

进入：

bash
cd /data/fastdfs/storage_data/data

通常会看到大量十六进制目录，例如：

text
00 01 02 ... FF M00

FastDFS 会在 data 下生成 256 个一级目录，每个一级目录下再生成 256 个二级目录。文件根据散列规则写入某个子目录。

10. 安装 Nginx 与 fastdfs-nginx-module#

10.1 下载 fastdfs-nginx-module#

bash
cd /opt/src
git clone https://github.com/happyfish100/fastdfs-nginx-module.git

如果使用压缩包：

bash
unzip fastdfs-nginx-module-master.zip

10.2 下载并解压 Nginx#

示例使用 Nginx 1.12.0：

bash
cd /opt/src
tar -zxvf nginx-1.12.0.tar.gz
cd nginx-1.12.0

生产环境建议使用仍有安全维护的 Nginx 稳定版本。

10.3 编译 Nginx 并添加模块#

bash
./configure \
  --prefix=/usr/local/nginx \
  --add-module=/opt/src/fastdfs-nginx-module/src

make
make install

如果 ./configure 报找不到 FastDFS 或 fastcommon 头文件，需要检查：

bash
ls /usr/include/fastdfs
ls /usr/include/fastcommon
ls /usr/local/include/fastdfs
ls /usr/local/include/fastcommon

必要时创建软链接：

bash
ln -svf /usr/include/fastdfs /usr/local/include/fastdfs
ln -svf /usr/include/fastcommon /usr/local/include/fastcommon
ln -svf /usr/lib64/libfastcommon.so /usr/local/lib/libfastcommon.so
ln -svf /usr/lib64/libfdfsclient.so /usr/local/lib/libfdfsclient.so
ldconfig

10.4 验证 Nginx 是否编译进模块#

bash
/usr/local/nginx/sbin/nginx -V 2>&1 | grep fastdfs

应能看到：

text
--add-module=/opt/src/fastdfs-nginx-module/src

如果没有该信息，说明当前 Nginx 不是带模块编译的版本，配置 ngx_fastdfs_module 会报：

text
unknown directive "ngx_fastdfs_module"

11. 配置 fastdfs-nginx-module#

11.1 复制 mod_fastdfs.conf#

bash
cp /opt/src/fastdfs-nginx-module/src/mod_fastdfs.conf /etc/fdfs/

11.2 修改 mod_fastdfs.conf#

bash
vi /etc/fdfs/mod_fastdfs.conf

核心配置如下：

ini
connect_timeout=10
network_timeout=30
base_path=/opt/fastdfs/storage

tracker_server=192.168.128.131:22122
storage_server_port=23000

group_name=group1
url_have_group_name=true

store_path_count=1
store_path0=/data/fastdfs/storage_data

log_level=info
response_mode=proxy

#include http.conf

关键参数说明：

参数	说明
`base_path`	模块日志目录，建议与 Storage 的 `base_path` 保持一致
`tracker_server`	Tracker 地址，必须与实际 Tracker 端口一致
`storage_server_port`	Storage 端口，必须与 `storage.conf` 中的 `port` 一致
`group_name`	当前 Storage 所属组名
`url_have_group_name`	URL 是否包含 group 名，如 `/group1/M00/...` 时应为 `true`
`store_path_count`	必须与 `storage.conf` 保持一致
`store_path0`	必须与 `storage.conf` 的 `store_path0` 保持一致
`response_mode`	文件本机不存在时处理方式，常见为 `proxy` 或 `redirect`

11.3 关于 group_count 的配置#

单组部署时，建议：

ini
group_count = 0

或者不启用多组配置段。

如果配置：

ini
group_count = 3

则需要正确补充 [group1]、[group2]、[group3]，并保证每组配置真实存在。否则容易产生路径映射混乱。单机单组测试不建议随意配置多个 group。

11.4 创建 M00 软链接#

很多旧版教程会创建：

bash
ln -svf /data/fastdfs/storage_data/data /data/fastdfs/storage_data/data/M00

更常见写法是让 Nginx 的 root 指向 store_path0/data，然后用 /group1/M00/... 映射访问。是否必须创建 M00 软链接与版本、Nginx 配置、模块配置有关。若访问 404，可检查软链接是否存在。

推荐检查：

bash
ls -l /data/fastdfs/storage_data/data/M00

如果不存在，可创建：

bash
ln -svf /data/fastdfs/storage_data/data /data/fastdfs/storage_data/data/M00

12. 配置 Storage Nginx#

12.1 修改 nginx.conf#

bash
vi /usr/local/nginx/conf/nginx.conf

示例配置：

nginx
worker_processes  1;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       9999;
        server_name  localhost;

        location ~/group([0-9])/M00 {
            root /data/fastdfs/storage_data/data;
            ngx_fastdfs_module;
        }

        location = /50x.html {
            root html;
        }
    }
}

如果只使用 group1，也可以写成：

nginx
location ~/group1/M00 {
    root /data/fastdfs/storage_data/data;
    ngx_fastdfs_module;
}

12.2 检查配置#

bash
/usr/local/nginx/sbin/nginx -t

12.3 启动 Nginx#

bash
/usr/local/nginx/sbin/nginx

重新加载：

bash
/usr/local/nginx/sbin/nginx -s reload

停止：

bash
/usr/local/nginx/sbin/nginx -s stop

12.4 HTTP 访问测试#

上传文件返回：

text
group1/M00/00/00/xxxxxxxx.jpg

访问 URL：

text
http://192.168.128.131:9999/group1/M00/00/00/xxxxxxxx.jpg

如果能正常打开图片或下载文件，说明 Storage Nginx 配置成功。

13. 配置统一入口 Nginx，可选#

你原文中使用两个 Nginx：

Storage Nginx：监听 9999，加载 fastdfs-nginx-module。
Tracker / 入口 Nginx：监听 80，通过 upstream 转发到 Storage Nginx。

这种方式在单机环境不是必须，但在多 Storage、多入口场景中可以作为统一访问入口。

13.1 入口 Nginx 示例配置#

nginx
http {
    upstream fdfs_group1 {
        server 127.0.0.1:9999;
        # 多台 storage nginx 时可继续增加
        # server 192.168.128.132:9999;
        # server 192.168.128.133:9999;
    }

    server {
        listen 80;
        server_name file.example.com;

        location /group1/M00 {
            proxy_pass http://fdfs_group1;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
    }
}

访问：

text
http://file.example.com/group1/M00/00/00/xxxxxxxx.jpg

13.2 是否需要两个 Nginx#

场景	建议
单机测试	一个 Nginx 即可
单 Storage 小项目	一个 Nginx 即可
多 Storage，需要统一域名	可增加入口 Nginx 或使用负载均衡
生产高可用	推荐独立负载均衡入口 + 多 Storage Nginx

14. 防火墙配置#

14.1 查看防火墙状态#

bash
systemctl status firewalld

14.2 查看开放端口#

bash
firewall-cmd --zone=public --list-ports

14.3 开放端口#

bash
firewall-cmd --zone=public --add-port=22122/tcp --permanent
firewall-cmd --zone=public --add-port=23000/tcp --permanent
firewall-cmd --zone=public --add-port=9999/tcp --permanent
firewall-cmd --zone=public --add-port=80/tcp --permanent
firewall-cmd --reload

14.4 端口开放建议#

端口	是否对外开放	说明
22122	通常只对业务服务器开放	Tracker 端口
23000	通常只对 Tracker / Storage / 内网业务开放	Storage 端口
9999	可内网开放	Storage Nginx 端口
80 / 443	对外开放	文件访问入口

生产环境中不建议把 22122、23000 暴露到公网。

15. Java 客户端接入#

15.1 fastdfs-client-java 说明#

FastDFS 官方 README 中列出了 Java SDK：

text
https://github.com/happyfish100/fastdfs-client-java

老项目中常见版本是 1.26 或 1.27。如果 Maven 中央仓库不可用，可下载源码后本地安装。

15.2 Maven 本地安装#

bash
git clone https://github.com/happyfish100/fastdfs-client-java.git
cd fastdfs-client-java
mvn clean install

15.3 Maven 依赖示例#

根据本地安装版本调整：

xml
<dependency>
    <groupId>org.csource</groupId>
    <artifactId>fastdfs-client-java</artifactId>
    <version>1.27-RELEASE</version>
</dependency>

15.4 客户端配置文件#

在 Java 项目的 resources 下创建：

text
fdfs_client.conf

内容示例：

ini
connect_timeout = 5
network_timeout = 30
charset = UTF-8
http.tracker_http_port = 80
http.anti_steal_token = false
http.secret_key = FastDFS1234567890
tracker_server = 192.168.128.131:22122

15.5 上传示例代码#

java

public class FastDfsUploadDemo {
    public static void main(String[] args) throws IOException, MyException {
        ClientGlobal.init("fdfs_client.conf");

        TrackerClient trackerClient = new TrackerClient();
        TrackerServer trackerServer = trackerClient.getConnection();
        StorageServer storageServer = null;

        StorageClient1 storageClient = new StorageClient1(trackerServer, storageServer);

        String fileId = storageClient.upload_file1("/tmp/hello.txt", "txt", null);
        System.out.println(fileId);

        trackerServer.close();
    }
}

text
group1/M00/00/00/xxxxxxxx.txt

HTTP 地址拼接：

text
http://file.example.com/ + fileId

例如：

text
http://file.example.com/group1/M00/00/00/xxxxxxxx.txt

15.6 Spring MVC 上传注意事项#

传统 Spring MVC 需要配置 multipart 解析器：

xml
<bean id="multipartResolver" class="org.springframework.web.multipart.commons.CommonsMultipartResolver">
    <property name="defaultEncoding" value="UTF-8" />
    <property name="maxUploadSize" value="104857600" />
</bean>

Spring Boot 项目通常使用配置项：

yaml
spring:
  servlet:
    multipart:
      max-file-size: 100MB
      max-request-size: 100MB

16. 常见问题与排查#

16.1 `gcc: command not found`#

原因：最小化 CentOS 未安装编译工具。

解决：

bash
yum -y install gcc gcc-c++ make

16.2 `ngx_fastdfs_module` 未知指令#

报错：

text
nginx: [emerg] unknown directive "ngx_fastdfs_module"

原因：当前 Nginx 没有编译 fastdfs-nginx-module。

排查：

bash
/usr/local/nginx/sbin/nginx -V 2>&1 | grep fastdfs

解决：重新编译 Nginx：

bash
./configure --prefix=/usr/local/nginx --add-module=/opt/src/fastdfs-nginx-module/src
make
make install

16.3 Nginx 编译找不到 fastcommon 或 fastdfs 头文件#

解决：

bash
ln -svf /usr/include/fastcommon /usr/local/include/fastcommon
ln -svf /usr/include/fastdfs /usr/local/include/fastdfs
ln -svf /usr/lib64/libfastcommon.so /usr/local/lib/libfastcommon.so
ln -svf /usr/lib64/libfdfsclient.so /usr/local/lib/libfdfsclient.so
ldconfig

16.4 上传成功但 HTTP 访问 404#

依次检查：

文件是否真实存在：

bash
find /data/fastdfs/storage_data/data -name '*文件名片段*'

Nginx location 是否匹配：

nginx
location ~/group1/M00 {
    root /data/fastdfs/storage_data/data;
    ngx_fastdfs_module;
}

mod_fastdfs.conf 是否配置：

ini
url_have_group_name=true
store_path0=/data/fastdfs/storage_data

store_path0 是否与 storage.conf 一致。
是否需要创建 M00 软链接。
Nginx error log：

bash
tail -f /usr/local/nginx/logs/error.log

FastDFS storage 日志：

bash
tail -f /opt/fastdfs/storage/logs/storaged.log

16.5 `fdfs_monitor` 显示 Storage 非 ACTIVE#

检查：

bash
systemctl status fdfs_storaged
systemctl status fdfs_trackerd

检查端口：

bash
ss -lntp | egrep '22122|23000'

检查配置：

bash
grep -n 'tracker_server\|port\|base_path\|store_path' /etc/fdfs/storage.conf

常见原因：

tracker_server IP 配错。
防火墙未放行 22122。
Storage 无法写入 base_path 或 store_path0。
服务器时间差异较大。
Tracker 或 Storage 日志中存在权限或路径错误。

16.6 浏览器访问不了，但服务器本地 curl 正常#

检查：

防火墙是否放行 80 / 9999。
云服务器安全组是否放行。
Nginx 是否监听外网地址。
浏览器访问的 IP 是否正确。
是否被代理、防火墙、网关拦截。

命令：

bash
curl -I http://127.0.0.1:9999/group1/M00/00/00/xxx.jpg
curl -I http://服务器IP:9999/group1/M00/00/00/xxx.jpg

16.7 `service fdfs_stroaged start` 拼写错误#

正确服务名一般是：

bash
service fdfs_storaged start

或：

bash
systemctl start fdfs_storaged

注意是 storaged，不是 stroaged。

16.8 `base_path0` 配置错误#

Storage 实际文件路径参数应为：

ini
store_path0=/data/fastdfs/storage_data

不是：

ini
base_path0=...

base_path 是日志和元数据路径，store_path0 是实际文件存储路径。

16.9 单机环境 group_count 配错#

单机单组不建议配置：

ini
group_count=3

17. 生产环境建议#

17.1 操作系统建议#

CentOS 7 已结束生命周期，不再获得官方安全更新。生产系统建议迁移到以下之一：

Rocky Linux 8/9
AlmaLinux 8/9
RHEL 8/9
OpenCloudOS 9
Ubuntu LTS

如果必须继续使用 CentOS 7，应至少做好：

内网隔离。
最小端口暴露。
安全组限制来源 IP。
组件版本加固。
定期漏洞扫描。
备份与恢复演练。

17.2 存储与备份建议#

store_path0 建议使用独立数据盘。
数据盘应设置监控告警。
定期备份 /etc/fdfs、Nginx 配置、FastDFS 数据目录。
多 Storage 同组部署时，应验证文件同步延迟和故障切换。
不建议把 FastDFS 数据目录直接放到系统盘。

17.3 安全建议#

Tracker 和 Storage 端口不直接暴露公网。
对外只开放 Nginx 80/443。
启用 HTTPS。
大文件上传应限制大小、类型、频率。
业务系统保存 FastDFS fileId，不建议保存物理路径。
若涉及私有文件，应通过业务接口鉴权后再下载，不要直接暴露静态 URL。

17.4 运维监控建议#

建议监控：

指标	说明
Tracker 进程	`fdfs_trackerd` 是否运行
Storage 进程	`fdfs_storaged` 是否运行
Nginx 进程	`nginx` 是否运行
端口	22122、23000、80/9999
磁盘空间	`store_path0` 所在磁盘
文件同步状态	`fdfs_monitor` 输出
Nginx 访问日志	访问量、404、5xx
FastDFS 日志	错误、同步失败、连接失败

18. 快速部署命令汇总#

以下命令适合测试环境快速参考，生产环境请结合前文逐项检查。

bash
# 1. 基础依赖
yum -y install unzip zip tar wget curl git vim gcc gcc-c++ make automake autoconf libtool pcre pcre-devel zlib zlib-devel openssl openssl-devel net-tools

# 2. 创建目录
mkdir -p /opt/src /opt/fastdfs/tracker /opt/fastdfs/storage /data/fastdfs/storage_data

# 3. 安装 libfastcommon
cd /opt/src
git clone https://github.com/happyfish100/libfastcommon.git
cd libfastcommon
./make.sh clean && ./make.sh && ./make.sh install
ln -svf /usr/lib64/libfastcommon.so /usr/local/lib/libfastcommon.so
ln -svf /usr/include/fastcommon /usr/local/include/fastcommon
ldconfig

# 4. 安装 FastDFS
cd /opt/src
git clone https://github.com/happyfish100/fastdfs.git
cd fastdfs
./make.sh clean && ./make.sh && ./make.sh install
cd /etc/fdfs
cp tracker.conf.sample tracker.conf
cp storage.conf.sample storage.conf
cp client.conf.sample client.conf
cp /opt/src/fastdfs/conf/http.conf /etc/fdfs/
cp /opt/src/fastdfs/conf/mime.types /etc/fdfs/

# 5. 修改配置后启动
systemctl start fdfs_trackerd
systemctl start fdfs_storaged
systemctl enable fdfs_trackerd
systemctl enable fdfs_storaged

# 6. 检查
ss -lntp | egrep '22122|23000'
fdfs_monitor /etc/fdfs/storage.conf

# 7. 安装 fastdfs-nginx-module 与 Nginx
cd /opt/src
git clone https://github.com/happyfish100/fastdfs-nginx-module.git
tar -zxvf nginx-1.12.0.tar.gz
cd nginx-1.12.0
./configure --prefix=/usr/local/nginx --add-module=/opt/src/fastdfs-nginx-module/src
make && make install
cp /opt/src/fastdfs-nginx-module/src/mod_fastdfs.conf /etc/fdfs/

# 8. 修改 /etc/fdfs/mod_fastdfs.conf 与 /usr/local/nginx/conf/nginx.conf 后启动
/usr/local/nginx/sbin/nginx -t
/usr/local/nginx/sbin/nginx

19. 验收清单#

检查项	命令或方式	期望结果
Tracker 启动	`systemctl status fdfs_trackerd`	active
Storage 启动	`systemctl status fdfs_storaged`	active
Tracker 端口	`ss -lntp	grep 22122`
Storage 端口	`ss -lntp	grep 23000`
Storage 注册	`fdfs_monitor /etc/fdfs/storage.conf`	ACTIVE
文件上传	`fdfs_upload_file ...`	返回 fileId
Nginx 模块	`nginx -V	grep fastdfs`
Nginx 配置	`nginx -t`	successful
HTTP 访问	浏览器或 `curl -I`	200 OK
防火墙	`firewall-cmd --list-ports`	端口已放行

20. 结论#

CentOS 7 + FastDFS + Nginx 的核心部署逻辑是：先安装 FastDFS 依赖库与主程序，再配置 Tracker 和 Storage 完成文件上传能力，最后通过 fastdfs-nginx-module 将 Storage 文件暴露为 HTTP 服务。部署过程中最容易出错的环节包括路径参数混用、Nginx 未编译模块、mod_fastdfs.conf 与 storage.conf 不一致、防火墙端口未开放、M00 映射不正确等。只要按照“服务启动正常、Storage 注册 ACTIVE、上传返回 fileId、Nginx 模块加载成功、HTTP 能访问文件”这条链路逐步验证，就可以较稳定地完成部署。

参考资料#

FastDFS GitHub README：https://github.com/happyfish100/fastdfs
FastDFS Gitee INSTALL：https://gitee.com/fastdfs100/fastdfs/blob/master/INSTALL
fastdfs-nginx-module GitHub：https://github.com/happyfish100/fastdfs-nginx-module
mod_fastdfs.conf 示例：https://github.com/happyfish100/fastdfs-nginx-module/blob/master/src/mod_fastdfs.conf
FastDFS HISTORY：https://github.com/happyfish100/fastdfs/blob/master/HISTORY
Red Hat CentOS Linux EOL 说明：https://www.redhat.com/en/topics/linux/centos-linux-eol