简介面向熟悉HTML、CSS、JavaScript并具备一定Vue基础的开发者这份方案围绕将Dify聊天窗口以iframe方式嵌入网页解决原生Dify不便传入用户ID导致的历史会话丢失、不同用户记录相互混淆的问题。文档先清晰说明整体设计思路通过URL参数传递应用编码与用户ID让中间页面与Dify服务保持同源再逐步演示如何调用接口获取登录token并写入iframe内部存储从而实现用户身份的稳定传递与独立会话隔离。资源中还提供了基于Vue.js的详细可运行示例包含拼接聊天地址、异步请求token、刷新iframe内容等关键代码片段并针对聊天窗口尺寸、按钮颜色等给出样式优化建议。压缩包内为1个docx文档整体大小为238KB已有347人学习适合需要将Dify集成到现有网站并增强会话管理能力的前端开发者直接参考。1. 两个用户撞出同一段聊天记录iframe 嵌入先过会话隔离这一关把 Dify 的聊天窗口通过 iframe 嵌进自己的主站门户是很多团队在两周内就能先跑通的一条路。真正让人半夜爬起来改代码的往往是第二周用户 A 反馈在页面右下角看到了用户 B 前两天的提问记录或者同一个浏览器里管理员和普通员工共用一条会话历史。根因在于聊天小部件默认用浏览器侧的匿名身份保存会话用户 ID 根本没有进入整个链路。下面要做的就是把这个断开的链路补完基于用户 ID 的 Token 传递与会话管理。一个签名 Token 从登录态携带 user_id经过 iframe 边界在后端网关验签再映射到独立的 conversation_id让每个用户拿到自己的会话历史、自己的开场问候、自己的快捷按钮。读完这篇文章你就能在自托管 Dify 上复现这套方案并且知道哪些参数不能省、哪些开关必须关。2. 把 Dify 聊天小部件装进 iframe两种嵌入方式和一组容易漏掉的参数2.1 嵌入前的三个前置判断自托管、同域代理与网关角色在动手写 iframe 之前先花十分钟回答三个问题它们决定了 Token 方案能走到哪一步。第一个问题你用的是云端共享域名还是自托管。自托管意味着域名、反向代理和响应头都在自己手里iframe 被浏览器拦截时有地方调云端共享域名虽然方便但响应头、路由、会话存储的控制权不在项目组手里后面每次想加自定义 user_id 都会撞墙。我的经验是凡是涉及“登录用户身份”的嵌入直接上自托管省掉一连串后端不可控的问题。第二个问题Dify 的服务端能不能在主站域下提供一个同域代理路径。iframe 里加载的页面如果和主站不同源浏览器会为它单独划分本地存储第三方 Cookie 被拦截的环境下聊天小部件会频繁把用户误判成“新访客”。常见做法是在主站 Nginx 或应用网关里加一条反向代理规则把 /dify-widget/ 开头的请求转发到 Dify 实例这样 iframe 在外观上是第三方实际上和主站同源。第三个问题聊天请求是直连 Dify 还是经过网关。用户浏览器只应接触到后端生成的短期操作凭证真正的 App 凭据放在网关。网关同时负责把 Dify 返回的 conversation_id 和 user_id 绑在同一张表里。这两个角色拆开后面的隔离与恢复才有依托。2.2 iframe 直嵌与脚本小部件嵌入两种姿势的差异与取舍Dify 聊天窗口嵌入主站常见有两套姿势。一套是在站点侧放一段 script 初始化小部件小部件内部自己创建 iframe另一套是直接在页面里写 iframe 标签。两者都能让用户聊起来区别在于对页面生命周期的控制粒度。我一般优先用 iframe 直嵌因为主站是 React 或 Vue 的单页应用时script 小部件会把全局状态、展开收缩逻辑、事件监听都挂到主站 DOM 上路由一切换偶尔会出现浮动按钮消失或连续弹出多个窗口的怪问题。iframe 直嵌把聊天界面完整隔离在一个独立文档里主站路由、样式、脚本都影响不到它隔离性天然更好。iframe 直嵌的最小写法大致是iframe srchttps://dify.example.com/chatbot/app-xxxxxxxx width100% height640 styleborder: 0; border-radius: 12px; /iframe注意 src 的路径在不同部署版本里有差异有的版本用 /chat/有的版本用 /chatbot/。建议以你实际安装版本提供的“嵌入站点”入口生成的地址为准不要硬编码自己猜出来的路径。如果团队习惯用脚本小部件常见初始化配置如下div iddify-chat-widget/div script window.difyChatbotConfig { token: app-xxxxxxxx, // App 访问 Token只允许由后端模板注入 apiBase: https://dify.example.com, // 自托管域名替换为实际域名 autoOpen: false, user: { // 某些小部件版本支持传显示名或自定义字段注意确认版本是否读取 name: placeholder-name } }; /script script srchttps://dify.example.com/embed.js defer/script这段脚本的关键点是 token 不要写死在前端仓库。把整段配置放到服务端模板里token 用环境变量注入前端仓库只留占位符。用户身份信息丢进 user 字段之后小部件可能展示它也可能压根不读取不要想当然先在自己部署的实例上验证一遍。2.3 小部件消息事件postMessage 的方向与校验两种嵌入方式都绕不开一组共用参数小部件的会话持久化和消息事件。运行时主站可以在 iframe 上监听来自小部件的消息常见的类型包括窗口开合、消息发送完成、错误提示等。事件名称在不同版本有差异但有一个共同规律它们都通过 postMessage 从 iframe 内部发出来。事件类型常见触发时机主站可以拿它做什么open / close小部件展开 / 收起统计点击行为联动主站 UImessage / send用户发送消息完成埋点更新未读角标error接口报错或鉴权失败记录 traceId弹出重试引导监听这些事件时重点是先校验 event.origin拒绝来自陌生来源的消息这是 iframe 嵌入的底线window.addEventListener(message, (event) { if (event.origin ! https://dify.example.com) return; const { type, data } event.data || {}; if (type open || type close) { // 用于统计用户点击行为或控制主站其他 UI 的联动 } if (type error data data.code) { // 后端网关日志里要有对应 traceId方便串联排查 } });到这一步聊天窗口已经能正常显示但会话还没有和用户 ID 绑定。下一章开始做正事生成携带 user_id 的签名 Token。3. 基于用户 ID 的 Token 传递登录态到 iframe 边界的一场安全接力3.1 为什么不用“把 App Token 直接塞进 iframe”这条捷径见过不少项目第一步是这样写的在 iframe src 里直接放一个 Dify App Token再拼上 user_id。iframe srchttps://dify.example.com/chatbot/app-abcdef123456?user_id10086 /问题很明显App Token 是应用级凭据所有用户共用一份。一旦被截获或者被用户从地址栏复制出来等于把整个应用的聊天能力全量暴露给对方别人拿到这个 Token 还能以任意 user_id 发起会话。更麻烦的是浏览器历史、代理日志、错误上报平台都会完整留下这个带 Token 的 URL事后清理非常被动。这条捷径的边界太薄不能作为正式方案。正确的链路是用户登录主站 → 主站后端生成一个绑定该用户的短期签名 Token → 前端把 Token 放进 iframe 的 query 或通过 postMessage 传递 → 小部件后端网关验签并取出 user_id → 网关用服务端保管的 App 凭据和 user_id 去访问 Dify。用户手里永远只有短期操作凭证拿不到应用级凭据。3.2 设计一个绑定 user_id 的短期签名 TokenToken 的有效期、携带内容、验签方式三件事要先定下来再写代码。有效期我通常给 10 到 15 分钟。iframe 页面加载时验签一次之后聊天会话主要靠已经建立的 conversation_id 维持没必要让 Token 活太久。过期后如果 iframe 还开着前端可以通过静默刷新接口换一个新的回传。携带内容建议精简为三段user_id、app_id、exp。user_id 用来隔离app_id 用来防止别的 Dify 应用误用这个 Tokenexp 用来限时。明文部分不要放敏感字段比如手机号、邮箱全量因为即便有签名明文部分在传输层仍然可能被记录。展示用的用户昵称可以从 user_id 到后端查不要写进 Token。签名算法用 HMAC-SHA256密钥只保存在主站后端进程里import base64 import hashlib import hmac import json import os import time SECRET os.environ[DIFY_USER_TOKEN_SECRET] DIFY_APP_ID os.environ[DIFY_APP_ID] def issue_user_token(user_id: str, ttl_seconds: int 900) - str: payload { user_id: user_id, app_id: DIFY_APP_ID, exp: int(time.time()) ttl_seconds, } encoded base64.urlsafe_b64encode( json.dumps(payload, separators(,, :)).encode() ).rstrip(b).decode() signature hmac.new(SECRET.encode(), encoded.encode(), hashlib.sha256).hexdigest() return f{encoded}.{signature} def resolve_user_token(token: str) - str: try: encoded, signature token.rsplit(., 1) expected hmac.new( SECRET.encode(), encoded.encode(), hashlib.sha256 ).hexdigest() if not hmac.compare_digest(expected, signature): raise ValueError(bad signature) raw encoded * (-len(encoded) % 4) payload json.loads(base64.urlsafe_b64decode(raw)) if payload.get(exp, 0) time.time(): raise ValueError(expired) if payload.get(app_id) ! DIFY_APP_ID: raise ValueError(app mismatch) return payload[user_id] except (ValueError, TypeError, json.JSONDecodeError): return 这段代码放在网关服务里主站前端只和“用 bearer token 换 user_id”的接口交互。比对签名一定要用 hmac.compare_digest不能用字符串相等判定防止时序侧信道。app_id 校验建议加上多应用部署时一个 Token 如果在另一个应用里也能通过会话会串线。3.3 前端接力query 传递还是 postMessage 传递验签逻辑就绪后Token 要过 iframe 边界。两种常见做法各有适用场景。第一种是直接放在 iframe 的 src query 里const token await fetch(/api/session/token).then(r r.json()); const iframe document.createElement(iframe); iframe.src https://dify.example.com/chatbot/app-xxxxxxxx?token${encodeURIComponent(token)};优点是可以直接用于服务端渲染场景后端拼页面时就能注入。缺点是会短暂出现在地址栏、浏览器历史、HTTP 日志里。即便 iframe 在视觉上不显示地址栏浏览器扩展和代理日志仍然可能记录。第二种是先用一个空白 iframe 建立连接再通过 postMessage 把 Token 送进去const iframe document.createElement(iframe); iframe.src https://dify.example.com/chatbot/app-xxxxxxxx; iframe.addEventListener(load, () { iframe.contentWindow.postMessage({ type: dify:auth, payload: { token } }, https://dify.example.com); });这种方式干净一些但要求小部件页面本身支持接收 postMessage auth 消息。部署版本是否支持要在控制台或接口文档里确认。我的建议是跨域部署且版本支持时用 postMessage版本不支持、或主站本身是服务端渲染时退回到 query 传递并在 iframe 加载后立即用 history.replaceState 把地址栏里的 Token 抹掉history.replaceState({}, , window.location.pathname);这行代码只能清理地址栏和浏览器历史。代理层日志、浏览器扩展日志清理不了所以 query 方案里 Token 的 ttl 要压得更短我一般压到 5 分钟以内。3.4 网关验签后把 user_id 放进 Dify 请求上下文前端把 Token 交给 iframe 之后不能让 iframe 直接去访问 Dify 的 APIDify 的会话接口需要真正的服务端凭据。网关在验签后要把 user_id 放进请求上下文再携带服务端保存的 App 凭据去访问 Dify这是会话隔离成立的关键边界。# 网关代理伪码FastAPI 风格 app.post(/proxy/chat-messages) async def proxy_chat_messages(request: Request): user_id resolve_user_token(request.headers.get(x-user-token, )) if not user_id: raise HTTPException(status_code401, detailinvalid token) conversation_id await get_conversation_for_user(user_id) response await dify_client.chat_messages( inputsrequest.json().get(inputs, {}), queryrequest.json().get(query, ), conversation_idconversation_id, useruser_id, ) return response这里的 user 参数是 Dify 侧用于标识调用方的字段看起来平淡但在会话隔离里是核心字段。它帮助服务端在日志和会话记录中区分每次调用来自哪个终端用户。更关键的是 conversation_id 的获取逻辑并不由前端上报而是由网关按 user_id 查出来这个机制在第四章展开。4. 用户会话隔离把 conversation_id 锁在 user_id 上再谈个性化窗口4.1 为什么默认行为会让用户共用同一段会话历史Dify 默认对“访问者”的区分本质上是浏览器侧的匿名用户标识。登录系统与聊天小部件是两套平行的身份体系主站里已经登录的张三、李四到了小部件眼里都只是“某访客甲”“某访客乙”。如果小部件把会话绑定在访客标识上而两个人在同一台电脑、同一个浏览器 profile 里切换后登录的人就会继承前一个人留下的会话聊天窗口一开第一屏就是上一个人的提问记录。这个问题在内部管理系统里尤其明显。所以要做的事情是把“访客标识”替换为“用户标识”。登录态到 iframe 的链路我们已经打通user_id 被签进 Token网关可以验出来。下面要让 conversation_id 的存取完全围绕 user_id 展开。4.2 维护 user_id → conversation_id 映射表而不是等前端回传隔离的核心原则是一句话conversation_id 只由后端分配前端不得自定义传入。Dify 新建会话时会返回 conversation_id后续请求依赖它如果让它在前端 localStorage 里自由流动复制和篡改都防不住。网关侧用一个简单的两列结构存映射字段类型说明user_idvarchar(64)主站登录用户的唯一 IDconversation_idvarchar(64)Dify 返回的会话 IDapp_idvarchar(32)对应哪个 Dify 应用updated_atdatetime最近一次会话更新时间每次代理聊天请求时网关按 user_id 查 conversation_idasync def get_or_create_conversation(user_id: str, app_id: str) - str: row await db.fetchone( SELECT conversation_id FROM user_conversations WHERE user_id$1 AND app_id$2, user_id, app_id ) if row: return row[conversation_id] conversation_id await dify_client.create_conversation() await db.execute( INSERT INTO user_conversations (user_id, app_id, conversation_id) VALUES ($1, $2, $3), user_id, app_id, conversation_id ) return conversation_id新建会话与继续会话的逻辑统一到一个函数里第一次提问时网关建会话后续提问时网关取回同一个会话。前端不需要知道 conversation_id 长什么样它的存在感被完全抹掉了。4.3 恢复历史会话刷新不丢上下文刷新不丢上下文是会话隔离在用户感知层面最直观的验收点。前端刷新后重新打开 iframe小部件第一句话必须能接上刷新前的话题。这个效果不依赖前端本地存储而依赖网关在拿到 user_id 后能查回老的 conversation_id。用户主动切换账号时同一个浏览器 profile 下的 user_id 变了查回来的 conversation_id 也就变了显示的内容自然新旧隔离。管理员从 A 账号切成 B 账号B 看到的内容和 A 的提问记录之间没有任何交集。为了给“刷新不丢”一个兜底接口我还会在网关加一个会话目录接口返回某个 user_id 对该应用的历史会话列表app.get(/proxy/conversations) async def list_conversations(request: Request): user_id resolve_user_token(request.headers.get(x-user-token, )) rows await db.fetchall( SELECT conversation_id, updated_at FROM user_conversations WHERE user_id$1 ORDER BY updated_at DESC LIMIT 20, user_id ) return {data: rows}这个接口不仅是隔离的验证点还是下面个性化窗口的数据基础。4.4 个性化聊天窗口让每个用户打开时看到自己的开场白会话隔离做完个性化就顺手了。我的经验是把“个性化设计”拆成两层表层是 CSS 和视觉效果深层是会话上下文数据。如果所有用户命中同一套开场白内部系统里就会出现“采购部门的用户看到‘请选择你的技术栈’”的尴尬场面。在网关做个性化不需要改动 iframe 样式只需要给 Dify 的输入参数加入当前用户的上下文inputs { username: user_profile.get(name, ), department: user_profile.get(department, ), welcome_topic: user_profile.get(welcome_topic, ), }这些 inputs 会作为上下文变量进入 Dify 的提示词编排。窗口的开场白、快捷提问和注入的业务字段由这份用户档案驱动。同一个 iframe样式相同但每个 user_id 打开时的第一屏内容不一样这就是“个性化”和“模板化”的区别。注意变量名需要在 Dify 应用配置里先把上下文变量定义好否则传了不生效。5. 避坑指南iframe 嵌入与 Token 传递的五个高频翻车现场5.1 iframe 一片空白控制台报 X-Frame-Options 拒绝现象把 Dify 页面地址直接拿来当 iframe src页面空白浏览器控制台报 “Refused to connect” 或 “X-Frame-Options: DENY”。原因Dify 的完整页面默认不允许被第三方站点套进 iframe聊天小部件专用入口才允许被嵌入。放错入口就会撞上这层防护。解决确认访问的是小部件嵌入地址而不是完整应用地址。自托管部署时在反代层检查响应头没有 X-Frame-Options: DENY更严格的做法是在 Nginx 统一加白名单只允许主站域名嵌入add_header Content-Security-Policy frame-ancestors https://portal.example.com always;5.2 用户刷新一次聊天记录“人间蒸发”现象iframe 里聊天正常按 F5 刷新刚才的对话只剩欢迎语之前的提问记录全部不见。原因小部件的匿名身份存在 iframe 对应源的本地存储里。当 iframe 和主站不同源时浏览器把它当第三方站点数据可能被隐私策略清理同时网关只负责转发前端刷新后重新请求但映射表里没有这个 user_id 的记录于是新建了会话。解决把映射表建好后前端刷新时不应重新发起会话而要先进入会话目录接口把已有 conversation_id 取回来透传给 Dify。同时关闭小部件“会话自动重置”类配置避免它每次加载都重置上下文。工程上我会对 gateway 的建会话逻辑做幂等处理同一 user_id 重复请求时不产生第二个 conversation_id。5.3 Token 出现在地址栏和浏览器历史里现象用 query 方式传递 Token用户右键查看 iframe 地址或者浏览器历史记录里看到完整 Token。原因iframe src 的 query 会被浏览器记录代理日志、错误上报、浏览器扩展也可能原样落库。解决优先把 Token 通过 postMessage 送进已经加载的 iframe如果版本不支持只能走 query那么在 iframe load 之后立即 history.replaceState 清掉地址栏同时把 Token 有效期压缩到 5 分钟内并限制单 Token 只能验签一次。Token 明文段里只放 user_id / app_id / exp不放任何敏感个人信息。5.4 切换账号后还能看到上一个账号的会话现象管理员在同一浏览器里退出账号 A、登录账号 B聊天窗口第一屏仍是账号 A 的问答记录。原因前端或 iframe 侧把 conversation_id 或访客会话标识存到了浏览器本地存储切换账号后没有清除导致新的 user_id 又挂到旧的 conversation_id 上。解决账号切换时由主站向 iframe 发送一条“重置会话”消息并同步清掉 iframe 源下的本地存储更稳妥的做法是不信任任何前端传递的 conversation_id网关每次都通过 user_id 查表查不到就新建前端提供的一律忽略。5.5 postMessage 事件来源没校验被陌生页面喂了脏数据现象主站收到来路不明的消息聊天小部件出现非预期行为比如自动弹出、切换了错误会话。原因小部件通过 postMessage 向父页面发事件父页面监听时没有做 event.origin 校验把任意外部页面塞过来的消息当成了小部件的指令。解决监听 postMessage 时必须校验 event.origin只接受来自你自己的 Dify 域名消息再校验 message type 白名单。任何来自未知 origin 的事件要么丢弃要么打进日志留痕。6. 用会话元数据驱动聊天窗口一个低成本个性化技巧个性化往往被理解为“给每个用户不同的 iframe 主题色、背景图”这当然直观但管理成本偏高为每个用户维护整套 CSS 会让主站代码越来越臃肿。我更推荐的打法是“同一套外观、不同的会话元数据”窗口的标题、欢迎语、快捷问题、首屏推荐按钮全部由服务端根据 user_id 关联的用户档案动态生成。落地不复杂网关在 get_or_create_conversation 时把用户档案中的部门、最近关注话题、语言偏好拼进 inputs 参数Dify 应用内的编排在开场白里引用这些变量。前端的 iframe 保持同一个地址不用为千人千面专门改版。验证分两条线。第一条是页面刷新验证隔离与持续性登录账号 A聊几句刷新确认刚才的对话还在切到账号 B确认看到的是 B 自己的开场白不是 A 的留言。第二条是同时开两个无痕窗口互不干扰。两个窗口指向同一个 Dify 应用但会话目录接口返回的数据必须互不相交。如果哪一边出现了对方的会话标题问题几乎一定出在网关Token 验签把 user_id 验串了或者映射表没加 user_id 条件。我自己的习惯是把映射表的 user_id 字段建索引接口层再做一份最小串联日志x-user-token 验签结果、映射到的 conversation_id、Dify 返回耗时三行打一条日志。排查问题时只看这张表就能定位九成。还有一点主观经验每次改完访问控制逻辑用同一个浏览器把 A/B 账号来回切换三遍比写十个单元测试更能暴露会话隔离的问题。这套方案真正的验收标准不是“能聊”而是“换了人之后聊天记录和开场白都换了”。希望帮到你。本文还有配套的精品资源点击获取
