客户端安装指南

FHQ 客户端是防火墙 Agent，安装在被保护的 Linux 服务器上，执行 iptables 规则。 支持 UA 拦截（需 nginx）与地区拦截（nginx geo）。默认安装路径 /fhq。

本页目录

系统要求

  • CentOS 7.9+（或其他支持 iptables 的 Linux）
  • Root 权限
  • iptables-services 已安装（脚本可自动安装）
  • 能访问 FHQ 服务端 HTTP 端口（默认 33022）
  • nginx（UA 拦截与地区拦截功能必需）

一键安装

客户端安装必须指定服务端地址。交互式安装会在向导中提示输入。

交互式 
FHQ_SERVER_URL=http://服务端IP:33022 curl -sSL http://fhq.x.kpt.cn/install.sh | bash -s client

非交互式安装：

bash 
FHQ_NONINTERACTIVE=1 \
  FHQ_SERVER_URL=http://192.168.1.100:33022 \
  FHQ_INSTALL_DIR=/fhq \
  FHQ_CLIENT_NAME=web-server-01 \
  curl -sSL http://fhq.x.kpt.cn/install.sh | bash -s client

手动安装（部署包）

下载部署包

从落地页 download/client/ 下载所有文件：

文件列表 
fhq-client-linux  fhq-linux  client.yaml  install.sh  uninstall.sh

执行安装

bash 
chmod +x install.sh fhq-client-linux fhq-linux
./install.sh              # 安装到 /fhq（默认）

安装脚本会自动：

  • 安装 iptables-services（如未安装）
  • 复制客户端二进制
  • 生成 client.yaml（自动生成 client id 和 token）
  • 创建 systemd 服务 fhq-client
  • 安装 fhq CLI

配置并启动

bash 
vi /fhq/client.yaml       # 修改 server.url
systemctl start fhq-client
systemctl status fhq-client
fhq status

客户端启动后会自动向服务端注册，在管理后台「客户端」页面可见。

配置文件

/fhq/client.yaml 主要配置项：

client.yaml 
server:
  url: "http://服务端IP:33022"    # 必填，改为实际服务端地址

client:
  id: "自动生成"
  token: "自动生成"
  name: ""                    # 可选，客户端显示名称
  heartbeat_sec: 30
  sync_rules_sec: 60
  report_logs_sec: 15

firewall:
  enabled: true
  chain_name: "FHQ"
  log_dropped: true
  monitor_ports:
    - 22
    - 80
    - 443
    - 8080
    - 3306

log_collector:
  conn_monitor: true
  kernel_log: true
  nginx_access_log: ""        # nginx 访问日志路径（可选）
  nginx_ua_block: true        # 启用 UA 拦截

UA 拦截

⚠️
UA 拦截功能需要 nginx 客户端通过 nginx map 模块实现 User-Agent 匹配与请求阻断，服务器必须安装并运行 nginx。

启用步骤：

  1. 确保服务器已安装 nginx
  2. 客户端以 root 运行（默认 systemd 服务即为 root）
  3. 在 client.yaml 中设置 nginx_ua_block: true
  4. 在管理后台配置 UA 规则，自动同步到 nginx map 配置

地区拦截

ℹ️
地区拦截通过 nginx geo 模块 实现。需确保 nginx 编译时包含 geo 模块（标准 nginx 均支持）。 在管理后台选择国家/地区后，规则自动同步到客户端 nginx 配置。

宝塔面板兼容

FHQ 客户端与宝塔面板和平共存：

  • 使用独立 iptables 链 FHQ，不影响宝塔防火墙规则
  • nginx UA 拦截写入独立 map 配置文件，不覆盖宝塔 nginx 配置
  • 建议在宝塔「安全」中放行 FHQ 管理端口 33022（如需从外网访问服务端）
  • 日志采集可配置宝塔 nginx 访问日志路径
💡
宝塔用户推荐先安装 FHQ 服务端，再在需要防护的站点服务器上安装客户端。 两者 iptables 规则互不冲突。

升级与卸载

升级

bash 
cp fhq-client-linux /fhq/
cd /fhq
./install.sh .

卸载

bash 
cd /fhq
./uninstall.sh              # 保留数据，清理 iptables
./uninstall.sh --purge -y   # 彻底删除

# 或使用 CLI
fhq uninstall client --purge -y

卸载会自动清理 FHQ iptables 链，不影响其他防火墙规则。

CLI 命令

bash 
fhq status       # 查看客户端服务状态
fhq client       # 客户端信息（ID、服务端地址）
fhq info         # 面板信息
journalctl -u fhq-client -f   # 查看实时日志