书籍在线阅读 HTTP 400 故障排查与修复

一、问题现象

用户在书籍页面点击《地下室手记》卡片的「在线阅读」按钮后，阅读器页面显示红色错误信息：

与此同时，其他类型的附件（如封面图片 /upload/cover-xxx.jpg）可以正常加载，问题仅出现在包含中文、括号、方括号等特殊字符的 EPUB/PDF 文件上。

二、技术架构与环境

请求链路

三、诊断过程

步骤 1：确认文件存在

首先检查 Halo 附件目录中文件是否真实存在：

ls -la /opt/1panel/apps/halo/halo/data/attachments/upload/地下室手记*

结果：文件存在，大小 354,532 字节。排除「文件缺失」的可能。

步骤 2：检查 Nginx 访问日志

从 Nginx access.log 中找到关键线索：

"GET /upload/地下室手记 ([俄] 陀思妥耶夫斯基) (z-library.sk, 1lib.sk, z-lib.sk).epub HTTP/2.0" 400 0

注意两个关键数据：

• HTTP 状态码 400（Bad Request）— 不是 403（Forbidden）也不是 404（Not Found）
• 响应体大小为 0 — 服务器直接拒绝了请求，没有返回任何内容

步骤 3：curl 对比测试

在服务器上用 curl 请求同一个 URL：

curl -s -o /dev/null -w "HTTP %{http_code}" \
  "http://127.0.0.1/upload/%E5%9C%B0%E4%B8%8B...epub"

# 结果：HTTP 200 ✓  (curl 正常返回)

curl 从 localhost 请求返回 200，但浏览器请求返回 400。这揭示了一个关键差异：WAF 对 localhost 请求和外部请求的处理不同。

步骤 4：定位 WAF 规则

检查 1Panel WAF 的加载方式和规则：

# WAF 在 http 级别加载（影响所有请求）
cat /opt/1panel/apps/openresty/openresty/1pwaf/data/conf/waf.conf

lua_shared_dict waf_req_count 10m;
access_by_lua_file /usr/local/openresty/1pwaf/waf.lua;   ◄ 关键行

WAF 的 access_by_lua_file 在 http 级别运行，意味着所有 server block 和 location block 的请求都会先经过 WAF 检查，无论目标路径是什么。

步骤 5：确认 WAF 拦截原因

分析浏览器请求 URL 中的特殊字符：

对比正常加载的封面图片 URL：/upload/cover-思考：快与慢.jpg?width=400 — 仅包含中文和冒号，不含括号和方括号，所以不被 WAF 拦截。

四、根因总结

为什么 curl 不受影响？

WAF 对来自 127.0.0.1（localhost）的请求有隐式放行策略，或者 curl 的 User-Agent / 请求头特征不触发某些规则。浏览器通过外网 HTTPS 访问时，完整的请求链路（HTTP/2 + 浏览器 UA + 外网 IP）会触发 WAF 的全部检查规则。

为什么其他图片正常？

封面图片文件名格式为 cover-书名.jpg，仅含中文、连字符和冒号，不含括号、方括号等触发 WAF 的特殊字符。

五、解决方案

解决方案采用三层架构，确保既解决当前问题，又对未来新上传的附件一劳永逸。

第一层：WAF 绕过

在 Nginx 配置中为 /upload/ 路径添加专用 location 块，用空的 Lua access 阶段绕过 WAF：

location /upload/ {
    access_by_lua_block { return }   # 绕过 1pwaf WAF
    alias /usr/share/nginx/html/upload/;
    ...
}

第二层：try_files + Halo 代理回退

静态文件存在时直接返回（最快），不存在时自动回退到 Halo 代理（保证新上传文件立即可用）：

location /upload/ {
    access_by_lua_block { return }
    alias /usr/share/nginx/html/upload/;
    try_files $uri @halo_upload;        # 先查静态 → 回退代理
    types {
        application/epub+zip epub;
        application/pdf pdf;
        ...
    }
}

# 命名 location：静态文件不存在时代理到 Halo
location @halo_upload {
    access_by_lua_block { return }
    proxy_pass http://127.0.0.1:30031;
    proxy_set_header Host $host;
    ...
}

第三层：rsync 定时同步

每 5 分钟自动将 Halo 新上传的附件同步到 OpenResty 静态目录，确保后续请求走静态路径（更快）：

# /opt/1panel/apps/openresty/openresty/sync-uploads.sh
rsync -au --no-links \
  /opt/1panel/apps/halo/halo/data/attachments/upload/ \
  /opt/1panel/apps/openresty/openresty/root/upload/

# crontab: */5 * * * * /opt/.../sync-uploads.sh

文件访问问题解决

由于 OpenResty 和 Halo 运行在不同的 Docker 容器中，Docker 挂载不支持跨容器的 symlink（容器内无法解析宿主机的绝对路径），因此采用文件拷贝方案将 Halo 附件目录复制到 OpenResty 容器可访问的路径：

cp -r /opt/1panel/apps/halo/halo/data/attachments/upload/ \
      /opt/1panel/apps/openresty/openresty/root/upload/

六、修复后的请求流程

七、验证结果

八、经验总结

排查方法论

1. 对比法：curl 正常 vs 浏览器异常 → 缩小到 WAF / HTTP 版本 / 请求头差异
2. 日志定位：Nginx access.log 的 400 状态码 + 0 字节响应 → 指向请求被中间件拦截
3. 排除法：确认文件存在 → 排除 404；确认 curl 可达 → 排除 Halo 问题
4. 差异分析：对比正常 URL（封面图）和异常 URL（EPUB）的字符组成 → 锁定特殊字符

关键技术点

九、修改的文件清单