【AI路径代理与业务接入 — 成功失败感悟】

路径代理与业务接入 --- 成功失败感悟

本文档基于 doc/案例 目录下三个实战案例整理，供后续同类需求参考。

关联背景：WAF 端口收敛、Nginx 路径分流、IIS 替代尝试。

一、案例索引

案例	主题	结果	核心教训
案例1：在线委托单-接入简道云	简道云表单 CRUD + 前端弹窗	成功	先澄清接口与字段语义，前后端分层清晰
案例2：S3表单下载失败案例	订单详情「未找到完整订单数据」	定位成功	报错是业务校验链，不是前端写错一句文案
案例3：IIS配置代理失败	Nginx 方案迁到 IIS:8090	未完全成功	URL Rewrite ≠ 反向代理；路径要先映射再代理

二、整体背景（和 WAF 变更的关系）

邮件要求的方向是：少端口、多路径、统一 443 入口。

变更前（行业现状）：多域名 + 多端口，IIS 上一端口一前端、一端口一后端，WAF 站点膨胀。
已验证可行方向 ：Nginx 单端口 + location + 前端 VITE_APP_BASE 子路径打包。
本次 IIS 尝试：希望在 Windows 运维习惯下复现同一能力，暴露出一层「组件与心智模型」差异。

感悟：目标一致，载体不同，失败往往出在「以为装了 URL 重写就等于装了 Nginx」。

三、成功案例：我们做对了什么

3.1 案例1 --- 简道云接入

做对了：

先探索再写代码 ：确认后端已有 JdyFormData、前端走 axios 经后端中转，不直连简道云（避免 ApiKey 泄露）。
关键问题先问清：销售/客服字段从哪张表、哪个 widget 来，避免方案反复推倒。
配置可扩展：状态、实验室、客户等级等选项设计为可配置，减少以后改代码频率。
按层交付：后端 CRUD → 前端弹窗 → 联调，边界清楚。

可复用原则：

外部 SaaS：永远后端代理，前端只调自家 API。
多表、多字段映射：先画数据流，再写 UI。
文档里字段对照表（如简道云 widget list）要当成单一事实来源。

3.2 Nginx 路径方案（文档与实测）

做对了：

前端 base 与 Nginx location 字符串完全一致 （如 /fdd/、/fdd/test/）。
try_files 回退写当前系统子路径 的 index.html，不写根 /index.html。
更具体的 location 写在前面（/fdd/test/ 先于 /fdd/）。
接口与静态资源路径分开规划（/fdd/api/ 代理，不靠 Referer 长期硬扛）。

四、失败案例：我们踩了什么坑

4.1 案例2 --- S3 / 订单数据

现象： 数据加载失败：未找到完整订单数据

本质： 后端 GetOrderInfo 在 TemplateJson 与 FileStream 同时为空 时返回该文案。常见根因包括：GUID 无记录、版本/模板对不上、S3/FTP 拉取失败等。

感悟：

前端弹窗里的 err.message 往往是后端业务语义的透传，排查要顺藤摸到 Controller → Service → 存储/文件链路。
不要先怀疑 Nginx/IIS；这类问题与入口代理无关。

4.2 案例3 --- IIS 8090

现象：

访问 http://localhost:8090/fdd → 404.0 ，处理程序 StaticFile ，物理路径 C:\inetpub\wwwroot\fdd。
站点功能页有 URL 重写 ，但未见 ARR / 应用程序请求路由。

本质问题分层：

层级	问题	正确认知
组件	仅有 URL Rewrite，无 ARR 或未 Enable Proxy	反向代理必须 URL Rewrite + ARR
站点结构	`/fdd` 被当成磁盘子目录，非「应用程序」	应对应物理目录 + 应用别名，或根目录 `web.config` 规则
路径习惯	访问 `/fdd` 无尾斜杠	SPA 常要求 `/fdd/`，并配重定向
代理目标	IIS:8090 → 127.0.0.1:8090	自代理死循环，入口端口与后端端口必须分离
规则语义	`proxy_pass http://127.0.0.1:8883/` 与带前缀转发	IIS 需 `^third-party/(.*)` → `http://127.0.0.1:8883/{R:1}`

一句话： 404 不是因为「网站没启动」，而是 IIS 在错误的地方用错误的方式找静态文件。

五、Nginx vs IIS：对照心智图

IIS 8090 尝试 - 卡点
站点绑定 8090
URL Rewrite 已有
ARR 可能缺失
应用/虚拟目录未建
web.config 规则未生效或未写
Nginx 路径方案 - 已跑通思路
listen 单端口
location 前缀匹配
alias / root + try_files
proxy_pass 去前缀转发
前端 VITE_APP_BASE 一致
用户请求 /fdd /third-party/...

能力	Nginx	IIS
子路径静态站点	`alias` + `try_files`	应用程序 + 各目录 `web.config` SPA 规则
API 反向代理	`proxy_pass`	ARR + URL Rewrite `Rewrite`
去掉路径前缀	`proxy_pass` 末尾 `/` 语义	捕获组 `{R:1}` 拼到目标 URL
配置集中度	单文件 `nginx.conf` 为主	站点根 + 多个应用 + 多个 `web.config`
排错	`nginx -t`、access/error log 直观	模块、应用程序边界、ARR 开关都要查

感悟： 在 Windows 上若团队熟 IIS，可以落地 IIS；若目标是快速复现 Nginx 文档那套，优先 Nginx，IIS 要按「组件清单」逐项验收，不能假设「有重写就有代理」。

六、给后续同事的实操清单

6.1 选 Nginx 还是 IIS

优先 Nginx ：多系统路径分流、多 proxy_pass、和现有 doc/Nginx路径配置教程.md 一致。
选 IIS ：确认已安装并启用 ARR 、团队接受多 web.config、愿意维护应用程序别名与 SPA 回退规则。

6.2 新增一条路径（无论 Nginx / IIS）

定对外 URL：/fdd/xxx/（与前端 VITE_APP_BASE 一致）。
定静态目录：html/Cti_Online_XXX_Web/。
定接口前缀：/fdd/xxx/api/ → 后端端口（勿与 IIS 监听端口相同）。
打包前端 → 部署静态文件 → reload 前 nginx -t 或检查 IIS 规则。
浏览器 F12：看 Request URL 是否带正确前缀；JS/CSS 是否为 application/javascript / text/css，而不是 text/html。

6.3 IIS 专项（若继续案例3路线）

服务器节点：是否存在 Application Request Routing Cache。
Server Proxy Settings → Enable proxy 是否勾选。
站点：根物理路径、应用程序 /fdd、/fdd/test 是否建立。
根 web.config：API / third-party 规则顺序（具体路径在前）。
各前端目录 web.config：仅负责 SPA 回退，不与 API 规则混在一处。
本机先测：http://127.0.0.1:后端端口/ 通，再测经 IIS 入口。

6.4 业务类需求（案例1、2）

第三方表单/存储：后端封装 + 日志 + 失败语义明确。
订单/文件类报错：查 Service 返回空对象的链路，再查代理。

七、成功与失败的共性感悟

7.1 成功共性

需求先收敛：端口收敛、路径前缀、谁代理谁，先写在一张表里。
一层只干一件事 ：Nginx 管路由；后端管业务；前端只管 base 和 API 前缀。
可验证的小步 ：nginx -t → reload → 单 URL → 单个静态资源 → 单个接口。

7.2 失败共性

把「相似名词」当成「同一件事」 ：重写 vs 代理；/fdd 目录 vs /fdd 应用；8090 入口 vs 8090 后端。
用浏览器现象倒推架构：白屏、404 HTML 当 JS，多半是路径或 handler 错了，不是业务代码一行写错。
迁移载体时不迁移前提：Nginx 能跑通的前提是子路径打包；IIS 没做应用映射和 ARR 时，照搬 URL 仍会失败。

7.3 个人/协作感悟

文档要写「变更前真实架构」：案例3 若一开始写清「变更前无 Nginx、IIS 多端口」，排错会快很多。
失败案例同样有价值：案例3 明确了 IIS 落地 checklist，比只保留 Nginx 成功路径更利于团队避坑。
截图与错误页字段要保留：处理程序、物理路径、Requested URL 三连，往往一次就能定性。

八、和本仓库其他文档的关系

文档	关系
`doc/要求说明邮件`	变更动机（WAF / 多端口）
`doc/Nginx路径配置教程.md`	推荐的成功实施手册
`doc/waf网络变更说明.md`	对外说明变更前后网络形态
`doc/nginx-1.30.0/conf/nginx.conf`	当前 Nginx 配置样例（含 `/fdd/`、`/fdd/test/`、API、`/third-party/`）
`doc/在线委托单-Nginx代理路径改造处理方案.docx`	业务侧路径改造说明

建议阅读顺序： 邮件背景 → 本感悟 → Nginx 教程 → 按需回看案例1/2/3 原文。

九、后续行动建议

生产入口：以 Nginx 路径方案为主，IIS 8090 作为实验或特定客户环境备选，需补全 ARR 与应用程序结构后再验收。
案例3 若继续 ：按案例3 文档中的「完整 web.config + 应用程序结构」做一次从零搭建，避免在 C:\inetpub\wwwroot\fdd 上碰运气。
新增系统 ：统一命名 Cti_Online_<Name>_Web + URL /fdd/<name>/，不要新增裸 /assets 根路径依赖。
案例2 类问题：建立「后端返回文案 → 代码位置」排查表，减少前端背锅时间。

十、图片与记录预留（可补充）

序号	建议补充内容	用途
1	Nginx 下 `/fdd/`、`/fdd/test/` 访问与 Network 截图	成功案例归档
2	IIS 404 错误页（StaticFile + 物理路径）	案例3 失败定性
3	IIS 服务器级 ARR 是否存在	组件验收
4	简道云弹窗联调成功界面	案例1
5	订单详情报错与后端日志对照	案例2

十一、结语

案例1 说明：业务接入类需求，边界清晰 + 配置化 + 后端代理 容易成功。
案例2 说明：报错文案是线索，不是终点；和网关改造无关时要果断分层。
案例3 说明：同一套 URL 设计可以成功在 Nginx 上失败在 IIS 上，差在组件、站点结构和运维模型，不是差在「想法不对」。

把三次经历合在一起，最稳的路线仍然是：对外统一入口（WAF 443）→ Nginx 按路径分流 → 前端子路径打包 → 接口按前缀代理。IIS 不是不能做，而是要用另一套检查表，不能默认等价替换。

文档版本：v1 | 整理自 doc/案例目录案例1～3