必须启用 nocanon 标志，禁用 apache 自动 uri 解码，使含空格、中文、%2f 等特殊字符的原始编码路径原样透传后端；同时配合 allowencodedslashes nodecode 防止含 %2f 的请求被提前拒掉。
apache mod_proxy 处理含特殊字符（如空格、中文、%、+、/、?、# 等）的路径时，默认行为可能引发解码错误、404、重定向失败或后端接收乱码。根本原因在于 apache 在代理前会自动对 url 进行一次 uri 解码（canonicalization），而多数后端服务（如 node.js、spring boot、fastapi）期望接收原始编码路径——两者解码时机不一致，就会错位。
特殊字符路径出错的典型表现
- 请求
/api/search?q=hello%20world→ 后端收到q=hello world（空格被解码），但某些 API 要求保持%20格式 - 中文路径
/用户/列表浏览器发来的是/%E7%94%A8%E6%88%B7/%E5%88%97%E8%A1%A8，Apache 默认解成/用户/列表再转发，后端路由匹配失败（尤其用正则或字面量匹配时） -
ProxyPass /v1/ http://backend:8080/配合GET /v1/item%2F123→ 后端收到/item/123（%2F被转为/），若后端接口设计为接收 raw path segment，就可能 404
必须启用 nocanon 标志
这是解决该问题的核心配置：它禁用 Apache 对路径的自动 URI 解码和规范化，让原始编码字节原样透传给后端。
ProxyPass "/api/" "http://backend:8080/api/" nocanon ProxyPassReverse "/api/" "http://backend:8080/api/"
⚠️ 注意：
-
nocanon只作用于ProxyPass指令本身，不影响ProxyPassReverse（后者只改响应头中的 Location） - 必须写在
ProxyPass行末，且不能加引号（即nocanon，不是"nocanon"） - 仅对 HTTP/HTTPS 后端有效；WebSocket（
ws://）默认已跳过 canonicalization，无需加此参数
配合后端做好路径语义约定
Apache 不解析请求体或路径语义，所以关键在前后端协同：
- 若后端使用框架路由（如 Express 的
req.params、Spring 的@PathVariable），确保它能正确 decode 或 raw 接收路径段 - Spring Boot 用户需确认
server.tomcat.relaxed-path-chars包含特殊字符（如server.tomcat.relaxed-path-chars=|,） - Node.js + Express 可通过
app.set('strict routing', true)和自定义中间件保留原始req.originalUrl
其他辅助措施
-
禁用
AllowEncodedSlashes的默认拦截（仅当路径含未编码/时需要）：
CPA Update - Secure CLI Proxy API Maintenance下载安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
AllowEncodedSlashes NoDecode
此指令需放在全局或
<virtualhost></virtualhost>中，配合nocanon使用，防止 Apache 直接拒掉含%2F的请求 避免用
RewriteRule做路径重写后再 ProxyPass：RewriteRule默认会触发 canonicalization，即使加[NE]标志也无法完全绕过；应优先用nocanon+ProxyPass组合-
调试技巧：
开启 Apache 日志记录原始请求行：LogFormat "%h %l %u %t \"%r\" %>s %b" full CustomLog logs/access_log full
查看日志中
"GET /v1/item%2F123 HTTP/1.1"是否被记录为原始形式，可验证nocanon是否生效
本质上，nocanon 不是“修复”，而是明确告诉 Apache：别碰这个路径，交给后端处理。只要后端能接收并理解原始编码，转发就可靠。
