常见问题

安装部署、连接故障、功能配置与安全相关问题的解答。 更多细节请参阅快速开始与各安装指南。

本页目录

安装相关

一键安装命令从哪里获取域名？

落地页 index.php 由服务端 config.php 自动识别当前访问域名，并显示下载统计。

也可手动指定下载地址：

bash 
FHQ_BASE_URL=https://你的域名 curl -sSL https://你的域名/install.sh | bash
端口 33022 被占用怎么办？

安装时可指定其他端口，或使用环境变量：

bash 
FHQ_NONINTERACTIVE=1 FHQ_PORT=33023 curl -sSL http://fhq.x.kpt.cn/install.sh | bash -s server

安装后修改 /fhq/server.yaml 中的 server.port 并重启：systemctl restart fhq-server

同一台机器可以同时安装服务端和客户端吗？

可以。先安装服务端，再安装客户端，脚本会自动识别为 both 角色。客户端 server.url 可设为 http://127.0.0.1:33022。使用 fhq status 可同时查看两个服务状态。

非 root 用户能安装吗？

不能。安装脚本需要 root 权限以配置 systemd 服务、iptables 规则及 nginx 配置（UA/地区拦截）。请使用 sudo -i 或 root 账户执行安装命令。

连接与注册

客户端无法连接服务端 / 管理后台看不到客户端？

请依次检查：

  1. /fhq/client.yaml 中 server.url 是否正确（含协议和端口，如 http://192.168.1.100:33022）
  2. 服务端防火墙是否放行 33022 端口
  3. 客户端能否访问服务端：curl -I http://服务端IP:33022/
  4. 客户端服务是否运行：systemctl status fhq-client
  5. 查看日志：journalctl -u fhq-client -f
无法访问管理后台 http://IP:33022/admin/ ？

确认服务端运行：systemctl status fhq-server。检查 firewalld / 云安全组是否放行 33022。本地测试：curl -I http://127.0.0.1:33022/admin/

功能问题

UA 拦截不生效？

UA 拦截依赖 nginx map 模块，需满足：

  • 服务器已安装并运行 nginx
  • client.yaml 中 nginx_ua_block: true
  • 客户端以 root 运行（默认 systemd 服务即为 root）
  • 管理后台已配置 UA 规则且客户端在线

详见客户端 UA 拦截说明。

与宝塔面板冲突吗？

FHQ 使用独立 iptables 链 FHQ 和独立 nginx map 配置，与宝塔防火墙、nginx 配置和平共存。卸载时会自动清理 FHQ 链，不影响宝塔规则。

AI 助手无法使用？

页面显示「未配置」表示尚未设置 DeepSeek API Key。任选其一：

  • 管理后台「AI 安全助手」→「DeepSeek 配置」填写 Key 并保存（立即生效）
  • 编辑 /fhq/server.yaml 后重启：
server.yaml 
ai:
  enabled: true
  api_key: "YOUR_DEEPSEEK_API_KEY"
  base_url: "https://api.deepseek.com"
  model: "deepseek-chat"

修改 yaml 后执行 systemctl restart fhq-server。也可设置环境变量 DEEPSEEK_API_KEY。

fhq CLI

常用 fhq 命令有哪些？
bash 
fhq              # 交互式菜单
fhq status       # 查看服务状态（server/client/both）
fhq info         # 面板地址、端口、版本
fhq server       # 服务端详情
fhq client       # 客户端详情（ID、服务端 URL）
fhq uninstall    # 卸载向导
fhq uninstall server --purge -y   # 彻底卸载服务端
fhq uninstall client --purge -y   # 彻底卸载客户端
如何彻底卸载？
bash 
# 远程一键卸载
curl -sSL http://fhq.x.kpt.cn/install.sh | bash -s uninstall

# 本地彻底删除
cd /fhq && ./uninstall.sh --purge -y
# 或
fhq uninstall --purge -y

安全设置

安装后必须做哪些安全设置？
⚠️
请立即完成以下步骤 默认账号 admin / 19930425peng 为公开默认值，生产环境务必修改。
  1. 登录 http://IP:33022/admin/ 修改管理员密码
  2. 编辑 /fhq/server.yaml，将 jwt.secret 改为至少 32 位随机字符串
  3. 同步更新 admin.password 配置项
  4. 重启服务：systemctl restart fhq-server
  5. 限制 33022 端口仅内网或 VPN 可访问（如云安全组、firewalld）
一键安装脚本安全吗？

curl ... | bash 会远程下载并执行脚本。请确保：

  • 仅从自己可信的 FHQ 落地页域名下载
  • 生产环境可先 curl -sSL ... -o install.sh 审阅后再执行
  • 使用 HTTPS 域名

落地页

落地页需要什么环境？

落地页使用 index.php，需要 PHP 7.4 及以上（推荐 8.0+）及 PHP-FPM。主要功能：

  • config.php 自动识别当前访问域名，一键安装命令无需手动替换
  • api/download.php 下载部署包并统计次数
  • api/stats.php 返回 JSON 格式下载统计
install.sh 应该放在哪里？

一键安装命令从落地页根目录拉取 /install.sh。部署时需将项目中的 scripts/install.sh 复制或软链到 Web 根目录，确保 https://域名/install.sh 可访问。部署包文件放在 download/server/ 与 download/client/ 目录。

还有问题？