背景本次联调场景后端机器192.168.2.237:5001前端同事机器192.168.2.218:3000前端 dev-proxy 预期地址192.168.2.218:5001出问题接口/console/api/account/profile前端最初访问http://192.168.2.218:5001/console/api/account/profile一直失败。最后确认不是后端接口代码问题而是联调环境里依次踩到了三个问题192.168.2.218:5001没有进程监听。dev-proxy 启动后 CORS 允许来源不对。登录成功后profile401本质是 cookie 登录态没有正确落到同一个访问链路。最终结论前端页面、API 代理、后端服务的关系要清楚浏览器 - http://192.168.2.218:3000 前端页面 - http://192.168.2.218:5001/console/api 前端 dev-proxy - http://192.168.2.237:5001/console/api 后端 Flask API如果前端配置让浏览器请求192.168.2.218:5001那么2.218 机器上必须真的启动 dev-proxy 并监听 5001。如果不想跑 dev-proxy就让前端直接请求后端http://192.168.2.237:5001/console/api不要让浏览器请求一个没人监听的地址。问题一192.168.2.218:5001根本没服务现象从后端机器访问Test-NetConnection192.168.2.218-Port 5001结果TcpTestSucceeded: False接口请求Invoke-WebRequesthttp://192.168.2.218:5001/console/api/account/profile报无法连接到远程服务器根因前端同事机器执行netstat-ano|findstr :5001返回空说明2.218:5001没有任何进程监听。而后端机器执行TCP 0.0.0.0:5001 LISTENING说明真正监听 5001 的是后端机器192.168.2.237不是前端机器192.168.2.218。解决前端同事需要启动 dev-proxypnpm-Cweb run dev:proxy并确保web/.env.local里是DEV_PROXY_HOST0.0.0.0 DEV_PROXY_PORT5001 DEV_PROXY_TARGEThttp://192.168.2.237:5001 DEV_PROXY_PUBLIC_TARGEThttp://192.168.2.237:5001再次执行netstat-ano|findstr :5001应该看到0.0.0.0:5001 LISTENING如果是127.0.0.1:5001 LISTENING说明只能本机访问局域网其他机器访问不了。问题二DEV_PROXY_HOST127.0.0.1只能本机访问含义DEV_PROXY_HOST127.0.0.1表示 dev-proxy 只监听本机回环地址。也就是说只有前端同事自己机器能访问http://127.0.0.1:5001其他机器访问http://192.168.2.218:5001会失败。正确配置DEV_PROXY_HOST0.0.0.0含义是监听所有网卡包括局域网 IP192.168.2.218:5001问题三system-features200但浏览器 CORS 报错现象接口http://192.168.2.218:5001/console/api/system-features命令行请求返回 200但浏览器仍报错。浏览器里看到Referrer Policy: strict-origin-when-cross-origin这行本身不是错误只是浏览器默认策略提示。真正的问题是 CORS。排查结果直接请求后端http://192.168.2.237:5001/console/api/system-features Origin: http://192.168.2.218:3000后端返回Access-Control-Allow-Origin: http://192.168.2.218:3000说明后端 CORS 是对的。但经过 dev-proxyhttp://192.168.2.218:5001/console/api/system-features Origin: http://192.168.2.218:3000返回变成Access-Control-Allow-Origin: http://192.168.2.237:5001这和浏览器页面来源不一致http://192.168.2.218:3000浏览器会拦截。解决前端同事需要在web/dev-proxy.config.ts里加cors:{allowedOrigins:[http://192.168.2.218:3000,],},注意NEXT_ALLOWED_DEV_ORIGINS192.168.2.218管的是 Next dev server不管langgenius/dev-proxy的 CORS。问题四登录接口 200但/account/profile401现象后端日志POST /console/api/login 200 GET /console/api/account/profile 401 POST /console/api/refresh-token 401含义登录接口成功了但后续请求没有带上有效的access_tokenrefresh_token所以/account/profile报 401。常见原因前端页面和 API 不是同一个 host。比如前端页面http://192.168.2.218:3000 后端 APIhttp://192.168.2.237:5001Dify 默认COOKIE_DOMAIN表示 cookie 绑定当前响应 host。如果登录请求和 profile 请求不在同一个稳定链路下浏览器可能不会把登录 cookie 带到后续请求里。推荐解决让浏览器统一请求前端同事机器上的 dev-proxy前端页面http://192.168.2.218:3000 API 请求http://192.168.2.218:5001/console/api dev-proxy 转发到http://192.168.2.237:5001/console/api这样浏览器看到的是统一的192.168.2.218cookie 更容易正常工作。前端需要做的事情1.web/.env.local推荐配置CONSOLE_API_URLhttp://192.168.2.237:5001 NEXT_PUBLIC_API_PREFIXhttp://192.168.2.218:5001/console/api NEXT_PUBLIC_PUBLIC_API_PREFIXhttp://192.168.2.218:5001/api NEXT_PUBLIC_SOCKET_URLws://192.168.2.218:5001 DEV_PROXY_TARGEThttp://192.168.2.237:5001 DEV_PROXY_PUBLIC_TARGEThttp://192.168.2.237:5001 DEV_PROXY_HOST0.0.0.0 DEV_PROXY_PORT50012.web/dev-proxy.config.ts需要允许前端页面来源exportdefault{server:{host:DEV_PROXY_HOST,port:DEV_PROXY_PORT,},cors:{allowedOrigins:[http://192.168.2.218:3000,],},routes:[// 原 routes 保持不变],}satisfies DevProxyConfig3. 重启服务修改 env 或 proxy config 后需要重启pnpm-Cweb run dev:proxypnpm-Cweb run dev4. 检查端口在前端机器执行netstat-ano|findstr :5001正确结果应该包含0.0.0.0:5001 LISTENING后端需要做的事情1. Flask 必须监听局域网地址后端启动需要类似flask run--host0.0.0.0--port5001--debug日志里看到Running on all addresses (0.0.0.0)说明不是只监听127.0.0.1。2. 后端.env推荐配置本次联调推荐CONSOLE_API_URLhttp://192.168.2.218:5001 CONSOLE_WEB_URLhttp://192.168.2.218:3000 APP_WEB_URLhttp://192.168.2.218:3000 CONSOLE_CORS_ALLOW_ORIGINShttp://192.168.2.218:3000,* WEB_API_CORS_ALLOW_ORIGINShttp://192.168.2.218:3000,* COOKIE_DOMAIN说明CONSOLE_WEB_URL后端认为 Console 前端页面在哪里。CONSOLE_API_URL后端对外暴露的 Console API 地址。使用 dev-proxy 时可以写前端同事的代理地址。CONSOLE_CORS_ALLOW_ORIGINS允许访问 Console API 的前端来源。COOKIE_DOMAIN保持空使用当前 host 绑定 cookie。3. 后端接口状态判断未登录直接请求Invoke-WebRequesthttp://192.168.2.237:5001/console/api/account/profile返回 401 是正常的。因为接口有登录要求/console/api/account/profile - setup_required - login_required - account_initialization_required只要不是“无法连接远程服务器”就说明网络链路已经通了。常用排查命令检查端口是否通Test-NetConnection192.168.2.218-Port 5001结果含义TcpTestSucceeded: False表示端口不通优先查监听、防火墙、进程是否启动。TcpTestSucceeded: True表示网络层通了再看 HTTP 状态码、CORS、cookie。检查本机监听netstat-ano|findstr :5001结果含义0.0.0.0:5001 LISTENING局域网可访问。127.0.0.1:5001 LISTENING只有本机可访问。空结果表示没有服务监听 5001。检查接口Invoke-WebRequesthttp://192.168.2.218:5001/console/api/system-features200表示基础接口通。Invoke-WebRequesthttp://192.168.2.218:5001/console/api/account/profile未登录返回401是正常的。配置项速查配置项属于作用NEXT_PUBLIC_API_PREFIX前端浏览器访问 Console API 的前缀NEXT_PUBLIC_PUBLIC_API_PREFIX前端浏览器访问 WebApp 公开 API 的前缀NEXT_PUBLIC_SOCKET_URL前端WebSocket 地址CONSOLE_API_URL前端/后端服务端侧 Console API origin或后端对外 API 地址DEV_PROXY_TARGET前端 dev-proxy代理最终转发到哪个后端DEV_PROXY_PUBLIC_TARGET前端 dev-proxy公开 API 代理目标DEV_PROXY_HOST前端 dev-proxydev-proxy 监听地址局域网联调用0.0.0.0DEV_PROXY_PORT前端 dev-proxydev-proxy 监听端口CONSOLE_WEB_URL后端后端认为 Console Web 页面地址是什么CONSOLE_CORS_ALLOW_ORIGINS后端允许哪些来源访问 Console APIWEB_API_CORS_ALLOW_ORIGINS后端允许哪些来源访问 WebApp APICOOKIE_DOMAIN后端cookie 域名空值表示绑定当前 host最终经验这类问题不要一上来改接口代码。按顺序排端口是否监听。局域网是否能连。dev-proxy 是否启动。CORS 头是否等于页面 origin。登录 cookie 是否被后续请求带上。最后才看后端接口逻辑。本次最终能登录说明后端/console/api/account/profile接口没问题。后端 CORS 配置没问题。主要问题在前端 dev-proxy 的启动、监听地址和 CORS 允许来源。