用户隐私协议与模型服务协议

用户隐私协议与模型服务协议

【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG

用户隐私协议

…

模型服务协议

…

> **合并的文档必须自己署名。** 前端的兜底链接文字是通用的「隐私政策协议」。只要你的文件除了隐私政策还包含别的内容——模型服务协议、服务条款、可接受使用政策等——这个兜底就低估了访问者正在勾选的范围，请用 `consent_documents` 填上它真实的名称。 > > 这也包括该字段出现之前写好的 bundle：它们照常加载，但勾选框现在显示的是「隐私政策协议」。**如果你的 `agreements.md` 合并了多份文档，请在升级时补上 `consent_documents`。** #### 给链接命名 `consent_documents` 就是勾选框中被做成链接的那段文字——填写你的部署对这份文档的真实称呼即可： ```jsonc "consent_documents": "《示例公司服务条款》"

链接外围的那句话（「同意……」）仍然来自前端自身的翻译，因此在每种界面语言下都是自然的表达；可定制的只是文档的名称。不写这个字段时，链接的名称也由该翻译提供——即通用的「隐私政策协议」（中文为《隐私政策协议》）：它只适合"确实就是一份隐私政策"的文件，其它情况都会低估实际范围（见上面的提示）。

弹窗会显示什么

弹窗会原样渲染agreements.md，不会在其上方再打印一行标题。因此请给这个文件写上它自己的标题：该标题就是屏幕上这份文档的标题。

# 用户隐私协议与模型服务协议 ## 用户隐私协议 …

代码不会去读这份文档——弹窗只负责渲染它。读屏软件朗读的弹窗名称，取自勾选框自己的链接文字（consent_documents，未声明时为前端的兜底值），那也正是访问者刚刚勾选的东西。这个名称与文件标题是否一致、与文件实际内容是否相符，由你自己维护。

标题、段落、列表、表格、引用块、代码块、分隔线和链接都会以标准的文档排版渲染。Markdown 中的原始 HTML 会被丢弃——与其它所有 bundle 模板一致，见 §10。

6.2 需要知道的规则

• 要么都写，要么都不写。只写login会得到一个有品牌文案但没有门禁的登录页；只写agreements则是一份没有任何入口链接的文档。两者都不会开启门禁——半份配置就按半份配置处理，不会被当作已获得同意。
• 按 locale 生效。解析到的 locale 若两个字段都没声明，访问者就看不到勾选框。请为每个需要门禁的 locale 都声明这一对字段，或者用fallbacks把未覆盖的 locale 导向已声明的 locale。
• 声明了但内容为空的文件会导致启动失败。门禁绝不能指向一份空白文档。consent_documents为空白字符串同样会失败。
• 链接文字可选，文档不可选。单独写consent_documents永远不会开启门禁；某个 locale 只声明了login+agreements而没写它，勾选框照常工作，只是名称来自前端翻译。
• 勾选状态不会被记住。它只存活于登录页本身，并且绑定到屏幕上那份文档的确切文本，因此每次访问都需要重新勾选。中途切换界面语言会替换文档并清除勾选，除非新 locale 的文本逐字节相同。
• 仅作用于 WebUI，不覆盖 API。同上：POST /login没有同意相关字段，因此该门禁只约束前端登录表单，此外别无约束。
• 仅覆盖账号密码登录。未配置认证（AUTH_ACCOUNTS未设置）的部署会以 guest 身份直接放行，不受门禁约束。这是刻意设计而非缺口：没有认证就没有可被约束的用户身份，而免认证本就是开发/演示形态。若必须要求接受协议，请配置AUTH_ACCOUNTS（并配置TOKEN_SECRET）。
• 接口不可达只在「首次加载」时 fail-open。若第一次定制内容请求就失败，此时没有任何快照，前端回落到自带的默认内容，门禁保持关闭，而不是把所有人锁在部署之外。
• 而「语言切换失败」保留的是上一次成功的裁决。一旦已经加载过快照，切换到另一个 locale 的请求失败时，屏幕上仍是那份旧快照；重试耗尽后门禁重新按它执行。因此若先前加载的 locale 需要勾选，勾选框依然存在——访问者仍受其最后看到的那份协议约束，不会因为一次网络故障被放行。这是两者中更安全的一种，且是刻意为之：只有从未加载成功过的情况才会打开门禁。

7. 部署

7.1 模板目录放在哪里

部署方式	模板目录	UI_TEMPLATES_DIR
源码部署	lightrag_webui/ui_templates/（已 gitignore）	./lightrag_webui/ui_templates
Docker / Compose	宿主机./data/ui_templates/→ 容器/app/data/ui_templates	/app/data/ui_templates
Kubernetes	ConfigMap 或 PVC 挂载到/app/data/ui_templates	/app/data/ui_templates

相对路径以服务器进程的工作目录为基准解析，因此在不确定进程从哪里启动时，使用绝对路径更稳妥。

7.2 Docker Compose

docker-compose.yml和docker-compose-full.yml都已内置这两半配置：

services: lightrag: volumes: - ./data/ui_templates:/app/data/ui_templates:ro environment: UI_TEMPLATES_DIR: "/app/data/ui_templates"

在你写入模板包之前，两者都是惰性的。已配置但不含manifest.json的目录被视为「尚未填充的挂载点」，而不是「损坏的模板包」：服务器记录一条写明该目录的警告，继续提供内置品牌内容。因此默认部署可以正常启动，而启用该功能的全部步骤就是把模板包放进./data/ui_templates再重启——永远不需要改 compose。

这种宽容止步于 manifest：一旦manifest.json存在，模板包就会被完整校验，任何问题都会导致拒绝启动（见 §9）——复制到一半的模板包绝不会被悄悄降级成 LightRAG 内容。

三点实务提示：

• 首次up之前先创建该目录。如果交给 Docker 自动创建，目录属主会是root，之后往里复制文件需要sudo。
• 挂载落错位置现在表现为「品牌内容没变」，而不是启动失败——这是「开箱即可启动」的代价。区分它与「我还没写模板包」的手段是启动警告和/ui/customization的"customized": false，两者都会写明服务器实际读到的路径。
• :ro是刻意的——服务器只读取模板包，从不写入。
• Podman：docker-compose.podman.yml里挂载和UI_TEMPLATES_DIR都仍是注释掉的。Podman 对「宿主机源不存在」的绑定挂载比 Docker 更严格，无条件挂载会把该功能变成所有人的启动前置条件。在那里请先mkdir -p ./data/ui_templates，再同时取消注释两者。

这一条刻意压过.env。compose 的environment:条目优先级高于挂载进容器的.env中的同名 key，UI_TEMPLATES_DIR正是要利用这一点——与WORKING_DIR、INPUT_DIR、PROMPT_DIR完全一致。这个值是容器内路径，把它挡在.env之外，才能让同一份.env（里面写的是./lightrag_webui/ui_templates这类宿主机路径）同时服务源码运行与本部署。因此在.env里设置UI_TEMPLATES_DIR只影响源码运行，容器使用的是 compose 中的值。

若要让容器指向别处的模板包，请改 compose 中的这一条（向导会保留它，见 §7.3），或改挂载的宿主机一侧。

7.3 向导生成的 compose 文件

make env-base/make env-storage/make env-server会生成docker-compose.final.yml（这套向导的完整背景见 docs/InteractiveSetup.md）。生成器现在会在该挂载不存在时补上同样的只读挂载，因此重新生成已有文件即可获得：

make env-server # 或任意其他 make env-* 目标 grep ui_templates docker-compose.final.yml

向导同时会把UI_TEMPLATES_DIR: "/app/data/ui_templates"作为种子值写入lightrag服务的environment:块，因此向导生成的部署与仓库自带的 compose 文件行为完全一致：在./data/ui_templates出现模板包之前保持惰性。

只播种、不接管——向导绝不改动你填写的值。WORKING_DIR/INPUT_DIR/PROMPT_DIR每次运行都会被重写，手工改动不会保留；UI_TEMPLATES_DIR只在 compose 文件尚未声明该键时才写入：

• 你在docker-compose.final.yml中手工修改的值会在每次重新生成后原样保留——包括UI_TEMPLATES_DIR: ""（部署用它关闭该功能）以及 list 风格下的- UI_TEMPLATES_DIR。
• 若要从其它宿主机目录提供模板包，完全不需要改环境变量：改挂载的宿主机一侧即可（./my-branding:/app/data/ui_templates:ro）。
• 种子值同样压过.env，这正是让.env中的宿主机路径UI_TEMPLATES_DIR仍可用于源码运行的前提（见 §7.2）。

用户新增的绑定挂载和其它用户新增的环境变量，与之前一样在重新生成时被保留。

7.4 Kubernetes

自带的 Helm Chart 目前还没有专门的配置项，因此需要自行修改 Deployment 来挂载模板包（Chart 的位置在 k8s-deploy/lightrag/，可参考其deployment.yaml的结构做扩展）。

ConfigMap 没有目录结构。它的 key 是扁平的，每个 key 直接成为挂载点下的一个文件；--from-file=<目录>只会把该目录下的文件按其基本名打包，并跳过所有子目录。因此以 ConfigMap 方式交付的模板包必须是扁平的，且 manifest 中的路径要与这些 key 完全一致。直接照搬嵌套的示例布局会导致启动失败，报'locales/zh/welcome.md' does not exist or is not a file。

为这种部署单独写一份扁平的 manifest：

{ "schema_version": 1, "default_locale": "zh", "brand": { "logo": "logo.svg" }, "locales": { "zh": { "welcome": "welcome.zh.md", "query_empty": "query_empty.zh.md", "login": "login.zh.md", "agreements": "agreements.zh.md", "logo_alt": "示例公司" } } }

并逐个显式指定被引用的文件（包括 Logo）——key=路径的形式已经完成了扁平化，因此你的源码目录可以保持嵌套。manifest 引用了但 ConfigMap 中缺失的文件会导致启动失败：

kubectl create configmap lightrag-ui-templates \ --from-file=manifest.json=./k8s/ui-manifest.json \ --from-file=welcome.zh.md=./ui_templates/locales/zh/welcome.md \ --from-file=query_empty.zh.md=./ui_templates/locales/zh/query_empty.md \ --from-file=login.zh.md=./ui_templates/locales/zh/login.md \ --from-file=agreements.zh.md=./ui_templates/locales/zh/agreements.md \ --from-file=logo.svg=./ui_templates/assets/logo.svg \ --dry-run=client -o yaml | kubectl apply -f -

非 UTF-8 的 Logo（PNG、JPEG、WebP）会被kubectl自动放入 ConfigMap 的binaryData。但请注意 ConfigMap 总大小上限约为 1 MiB，低于本功能单个 Logo 2 MiB 的限制：Logo 较大的模板包需要改用 PVC，PVC 同时也允许保留嵌套目录结构。

然后在容器上添加：

volumeMounts: - name: ui-templates mountPath: /app/data/ui_templates readOnly: true env: - name: UI_TEMPLATES_DIR value: /app/data/ui_templates volumes: - name: ui-templates configMap: name: lightrag-ui-templates

mountPath要与UI_TEMPLATES_DIR保持一致。投射卷内部的..data符号链接始终指向挂载点内部，因此模板包的路径包含性校验可以通过——扁平的 ConfigMap 挂载与磁盘上的普通目录加载表现完全一致。更新 ConfigMap不会重新加载模板包，请重启 Pod（见 §7.5）。

7.5 让修改生效

没有热加载。整个模板包在启动时被一次性校验，并作为不可变的内存快照激活；此后处理请求不再访问磁盘。修改模板包后需要重启服务器——使用lightrag-gunicorn或任何多 worker 部署时，必须重启所有worker，否则部分 worker 仍在提供旧版本内容。

不需要手动清缓存：文案接口以Cache-Control: no-store返回，Logo 的 URL 内嵌文件内容哈希，字节变化就会产生新的 URL（资产响应为public, max-age=31536000, immutable的长期缓存，见 lightrag/api/routers/ui_customization_routes.py）。

8. 验证部署结果

启动日志。以下三行必有其一：

INFO: UI customization: no bundle configured (UI_TEMPLATES_DIR unset) WARNING: UI customization: UI_TEMPLATES_DIR=/app/data/ui_templates holds no manifest.json — serving the built-in LightRAG branding. … INFO: UI customization: bundle <sha256> ['en', 'zh']

中间那一行就是 Docker 默认状态：变量由自带的 compose 文件设置，而挂载的目录还是空的。它被记为 WARNING 而非 INFO，是因为「挂载指向了错误的宿主机目录」也会落到同一状态——日志中写明了服务器实际读取的目录，供你区分这两种情况。

bundle_revision是对所有被引用文件计算出的哈希。如果你改了文件后它没有变化，说明服务器读取的目录并非你以为的那个——或者根本没有真正重启。

接口。该接口是公开的（欢迎页在登录之前显示），因此直接curl即可：

curl -s 'http://localhost:9621/ui/customization?locale=zh' | jq

{ "customized": true, "requested_locale": "zh", "locale": "zh", "fallback_used": false, "direction": "ltr", "brand": { "title": "My Graph KB", "description": "Simple and Fast Graph Based RAG System", "logo_url": "/ui/customization/assets/9f2a…/brand-logo", "logo_alt": "示例公司", "copyright": "© 2025 示例公司 版权所有" }, "welcome": { "format": "markdown", "content": "## 欢迎…" }, "query_empty": { "format": "markdown", "content": "…" }, "login": { "format": "markdown", "content": "…" }, "agreements": { "format": "markdown", "content": "…" }, "consent_documents": "《用户隐私协议》和《模型服务协议》", "consent_required": true }

【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG