proxy_pass不主动编解码，仅透传或字符串拼接uri：不带路径时全量转发原始uri；带路径时裁剪替换，不校验编码；变量拼接需避免解码后变量，rewrite捕获组默认不编码。
proxy_pass 本身不主动对 URL 进行编码或解码，它默认透传原始请求的 URI（已由客户端或 Nginx 解析器标准化后的形式）。真正影响编码行为的关键点，在于 proxy_pass 后是否携带 URI 路径，以及该路径是否参与 URI 替换逻辑——这会间接决定最终发送给后端的路径中，哪些字符被保留、哪些被重写、哪些可能因拼接而触发二次编码风险。
proxy_pass 不带 URI 路径时：URI 全量透传
当配置为 proxy_pass http://backend;（结尾无 / 或其他路径），Nginx 将客户端请求的完整 URI（包括已解码的路径和查询参数）直接拼接到后端地址后。此时：
- 客户端发送
GET /api/v1/users%2Fadmin?name=张%20三，后端收到的就是完全相同的路径和 query； - Nginx 不会对
%2F（即/）或%20（空格）做额外编码，也不强制解码——前提是客户端已按 RFC 3986 正确编码，且 Nginx 的解析未出错； - 注意：
location /api/匹配后，/api/前缀仍保留在转发 URI 中，即后端实际收到/api/v1/users%2Fadmin。
proxy_pass 带 URI 路径时：路径替换引发编码边界变化
当配置为 proxy_pass http://backend/api/;（结尾有 /）或 proxy_pass http://backend/v1;（结尾无 /），Nginx 会执行路径裁剪与拼接，这个过程发生在 URI 已被初步解析之后，但不重新编码剩余部分：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
-
location /v1/ { proxy_pass http://backend/api/v1/; }→ 请求/v1/users%2Flist转发为/api/v1/users%2Flist； -
location /old { proxy_pass http://backend/new; }→ 请求/old/path%20with%20space转发为/newpath%20with%20space（注意：/old 被替换成 new，无分隔符，导致 new 和 path 直接连写）； - 关键点：拼接动作是字符串级替换，不校验或修正编码格式；若原始 URI 含非法编码（如未编码的空格、控制字符），后端可能报错。
变量与动态 proxy_pass 中的编码注意事项
当 proxy_pass 使用变量（如 proxy_pass http://$backend_host$request_uri;），Nginx 在运行时拼接字符串，不会自动对变量值做 URI 编码：
- 若
$backend_host来自用户头（如$http_x_upstream），且含特殊字符（如@、:、/），必须确保其内容安全，否则可能破坏 URL 结构； -
$request_uri是原始未解码的全量 URI（含 query），可安全透传；但$uri是解码后的路径部分，若拼入 proxy_pass，会导致原本应编码的字符（如空格）变成裸字符，引发后端解析失败； - 推荐做法：仅用
$request_uri或固定路径，避免在 proxy_pass 中混用解码后变量。
rewrite 配合 proxy_pass 时的编码控制权转移
若 location 使用正则匹配（如 location ~ ^/api/.+），proxy_pass 不能自带路径，必须靠 rewrite 修改 URI：
-
rewrite ^/api/(.*)$ /v2/$1 break;→$1是捕获组，Nginx 默认不对捕获内容再编码； - 若
$1含%2F，rewrite 后仍保留，除非显式用encode标志（Nginx 1.19+ 支持rewrite ... encoded;）； - 更稳妥方式：用
return 307 /v2/$1;触发客户端重发，由客户端负责最终编码；或后端统一处理兼容性。
