Zulip 自托管服务器 GIPHY GIF 集成配置指南【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulipZulip 内置了对 GIPHY 的 GIF 搜索与发送支持用户可以在撰写消息时直接搜索并插入动画 GIF。GIPHY 在 Zulip Cloud 中默认启用而自托管self-hosted服务器需要管理员申请 GIPHY API Key 并修改服务器配置后方可使用。本文以templates/zerver/integrations/giphy.md与 docs/production/gif-picker-integrations.md 为核心结合仓库源码完整讲解 GIPHY 集成的申请步骤、配置方法、运行原理与内容分级控制帮助自托管管理员一步到位完成部署。集成概览GIPHY 在 Zulip 中的角色GIPHY 是 Zulip 的 GIF 提供商之一。启用后用户在撰写消息时点击输入框中的 GIF 图标即可打开 GIF 选择器GIF picker浏览热门 GIF 或按关键词搜索选中后直接以图片形式插入消息。自托管服务器与 Zulip Cloud 的差别仅在于服务器端配置Zulip Cloud 已由官方预先配置好 GIPHY 集成而自托管服务器必须由管理员手动完成 API Key 申请与设置。相关的用户端使用说明可参考帮助中心文章《Using GIFs in Zulip》该文章在 templates/zerver/integrations/giphy.md 中被引用。需要特别说明的是Zulip 同时支持 GIPHY、Tenor 与 KLIPY 三种 GIF 提供商。按照 docs/production/gif-picker-integrations.md 的说明如果多个集成都配置了 API KeyZulip 会按Tenor → KLIPY → GIPHY的优先级顺序选择提供商。因此即使你配置了 GIPHY只要服务器上同时配置了 Tenor 或 KLIPY 的 Key实际生效的提供商可能不是 GIPHY这一点在排查为何 GIPHY 未生效时尤为重要。第一步申请 GIPHY API Key要启用 GIPHY 集成首先需要从 GIPHY 开发者平台 获取一个 beta 或 production 级别的 API Key。具体步骤如下注册 GIPHY 账号。登录 GIPHY Developer Dashboard点击Create an App创建一个应用。产品类型Product Type选择SDK然后点击Next Step。为应用填写名称与描述然后点击Create New App。官方建议直接用 Zulip 服务器的主机名作为应用名称便于日后识别。申请成功后你会收到一个带速率限制rate-limited的beta API Key。对于用户规模较小的 Zulip 服务器beta Key 通常已经够用。可选如果 beta Key 的速率限制无法满足组织需要可以按照 GIPHY 在发放 beta Key 时提供的说明申请production API Key。注意提交申请截图时GIPHY 要求截图展示完整页面包括 URL 地址栏否则可能被驳回。第二步在服务器上配置 GIPHY API Key修改/etc/zulip/settings.py自托管服务器的运行配置位于/etc/zulip/settings.py。打开该文件加入如下配置GIPHY_API_KEY Your API key from GIPHY关键设计为什么放在 settings.py 而非 zulip-secrets.conf这一点是理解 Zulip 配置哲学的关键。在 docs/production/gif-picker-integrations.md 中明确说明GIPHY API keys are not secrets — GIPHY expects every browser or other client connecting to your Zulip server will receive a copy — which is why they are configured insettings.pyand notzulip-secrets.conf.GIPHY 的 API Key 并非机密数据——GIPHY 官方设计上就允许甚至要求每个连接到服务器的浏览器客户端都能拿到这份 Key因为实际搜索请求是由用户浏览器直接向 GIPHY API 发起的详见下文前端实现原理。因此它被放在普通的settings.py中而不是用于存放密钥的zulip-secrets.conf。与此形成对比的是真正的敏感凭据如数据库密码、secret key 等都必须写入zulip-secrets.conf由get_secret()读取。仓库中的默认值与模板佐证在源码层面这一设计体现在 zproject/default_settings.py 中# GIPHY API key. GIPHY_API_KEY get_secret(giphy_api_key) # Tenor API key TENOR_API_KEY get_secret(tenor_api_key) # Klipy API key KLIPY_API_KEY get_secret(klipy_api_key)可以看到三个 GIF 提供商的 Key 在开发/默认配置中都通过get_secret()从开发环境的 secrets 文件中读取这便于开发者在本机调试。而在生产环境模板 zproject/prod_settings_template.py 中则以注释形式给出了直接写死的模板# GIPHY_API_KEY Your API key from GIPHY # TENOR_API_KEY Your API key from Tenor # KLIPY_API_KEY Your API key from KLIPY管理员只需复制对应行、取消注释并填入真实 Key 即可。生产环境/etc/zulip/settings.py正是zproject/prod_settings_template.py的落地实例。第三步重启服务器并验证修改配置后需要重启 Zulip 服务器使设置生效/home/zulip/deployments/current/scripts/restart-server重启完成后用户即可按帮助中心文章所述使用 GIF 集成可能需要在浏览器中刷新页面一次。建议从管理员账号与普通用户账号各验证一次打开撰写框 → 点击 GIF 图标 → 检查热门Trending列表能否加载、搜索关键词能否返回结果、选中 GIF 后能否正常插入消息。底层实现原理前端如何调用 GIPHY API为了让管理员更好地理解为什么 Key 不是秘密为什么改配置要重启这里结合仓库前端源码说明 GIPHY 集成的实际工作链路。浏览器直连 GIPHYKey 必然暴露给客户端GIF 搜索请求由用户的浏览器直接发送给 GIPHY而不是经由 Zulip 服务器转发。实现位于 web/src/giphy_network.ts其 API 基地址为const BASE_URL https://api.giphy.com/v1/gifs;两个核心请求如下见 giphy_network.ts热门 GIF请求GET /v1/gifs/trending搜索 GIF请求GET /v1/gifs/search附带关键词q与语言参数lang每次请求的基础载荷get_base_payload()见 giphy_network.ts包含{ api_key: realm.giphy_api_key, // 从 realm 数据中取出直接发送给 GIPHY limit: GiphyNetwork.LIMIT, // 15每页条数 rating: get_rating(), // 内容分级见下文 offset: 0, // 分页偏移 fields: images.downsized_medium,images.fixed_height, }其中api_key直接取自前端 realm 数据——这正是 GIPHY Key 必须配置在settings.py且必须能被所有客户端读取的根本原因。fields参数用于按需精简响应载荷选择器预览图使用fixed_height版本发送到消息中的正文图使用downsized_medium版本。分页通过pagination.offset GiphyNetwork.LIMIT即 15累加实现见 giphy_network.ts支持无限滚动加载更多。服务端如何把 Key 下发到前端Key 从服务器到浏览器的传递路径为/etc/zulip/settings.py中的GIPHY_API_KEY→ 服务端将其注入 realm 数据 → 前端从realm.giphy_api_key读取见 web/src/giphy_network.ts。这也解释了为何修改配置后需要重启并刷新浏览器——realm 数据是在页面加载时一次性下发的。三种提供商的统一抽象前端为三种提供商定义了统一抽象基类GifNetwork位于 web/src/abstract_gif_network.tsGIPHY、Tenor、KLIPY 各自实现一个子类GiphyNetwork、tenor_network.ts等。这样 GIF 选择器 UIweb/src/gif_picker_ui.ts只需面向统一接口编程无需关心底层是哪个提供商。内容分级控制gif_rating_policyGIPHY 集成并非开箱即发的全部——组织管理员还可以通过内容分级策略GIF rating policy控制允许展示的 GIF 内容。分级选项定义分级选项定义在 zerver/models/realms.py 的GIF_RATING_POLICY_OPTIONS中等级名称IDdisabled禁用 GIF 集成0g允许 G 级大众级GIF1pg允许 PG 级家长指引GIF2pg-13允许 PG-13 级13 岁以下需家长陪同GIF3r允许 R 级限制级GIF4该字段为PositiveSmallIntegerField默认值为GIF_RATING_POLICY_OPTIONS[g][id]即默认允许 G 级内容见 realms.py。分级选项来源在源码注释中明确标注GIPHY 官方文档的rating可选参数、Google Tenor 的内容过滤选项以及 KLIPY 的内容过滤文档。前端如何根据策略过滤前端在 web/src/gif_state.ts 中实现两级控制启用判断is_giphy_enabled()等见 gif_state.ts只有当realm.giphy_api_key ! 且realm.realm_gif_rating_policy ! disabled.id时GIPHY 才被视为启用。也就是说只配了 Key 但策略为 Disabled集成不会展示。评级映射get_rating()见 gif_state.ts把组织策略映射为 GIPHY API 的rating参数值g/pg/pg-13/r随搜索请求一并发送给 GIPHY 服务端进行内容过滤。此外当策略被设置为 Disabled 时前端会隐藏撰写框中的 GIF 图标update_gif_icon_visibility()见 gif_state.ts。注意修改 rating 策略只会立即显示/隐藏 GIF 图标但不会在运行期切换 GIF 提供商——提供商切换需要重启服务器源码注释明确说明It wont change the GIF provider without a server restart as of now.。分级策略的迁移历史GIPHY 评级策略在仓库中经历了多次迁移从迁移文件可看出其演进0319_realm_giphy_rating.py新增字段0763_migrate_realms_using_y_rating_to_use_a_g_rating_for_giphy.py将旧版yYouth评级迁移为g0773_rename_giphy_rating_realm_gif_rating_policy.py将其重命名为通用的gif_rating_policy以适配多提供商。这说明分级控制从仅服务 GIPHY演进为服务所有 GIF 提供商的通用机制。品牌与版权合规GIPHY 对集成方的品牌展示有明确要求。在 GIF 选择器底部Zulip 会显示 GIPHY 官方署名attribution标识见 web/templates/giphy_footer.hbsdiv classpopover-footer img src../images/giphy/GIPHY_attribution.png alt{{t GIPHY attribution }} / /div该署名图片资源位于 static/images/giphy/ 目录下。这一设计符合 GIPHY 官方集成规范管理员在自定义前端时不应移除该署名以免违反 GIPHY 品牌使用条款。常见问题排查配置后 GIF 图标不出现检查GIPHY_API_KEY是否已写入/etc/zulip/settings.py并重启服务器同时确认组织的 GIF rating policy 未被设置为 Disabledgif_state.ts 中两个条件缺一不可。GIPHY 配置了却不生效如果同时配置了 Tenor 或 KLIPY 的 KeyZulip 会优先使用 Tenor → KLIPY → GIPHY 中的前者。若确实想用 GIPHY需要移除或留空优先级更高的提供商 Key。搜索无结果 / 内容异常确认组织的 rating 策略与期望一致例如设置为 G 级就搜不到 R 级内容检查浏览器开发者工具中发往api.giphy.com的请求是否携带了正确的api_key与rating参数。beta Key 速率受限beta API Key 有速率限制流量较大时建议按第一步的可选步骤申请 production API Key。总结在自托管 Zulip 服务器上启用 GIPHY 集成核心就三步申请 GIPHY API Key → 在/etc/zulip/settings.py中写入GIPHY_API_KEY→ 重启服务器。理解GIPHY Key 不是秘密、搜索由浏览器直连 GIPHY 完成、评级策略由组织级gif_rating_policy控制这三个底层事实可以让你在配置和排障时事半功倍。若需要多提供商对比或考虑替换方案可继续阅读 docs/production/gif-picker-integrations.md 中关于 Tenor 与 KLIPY 的配置章节其 Key 同样写入settings.py配置流程与 GIPHY 一致。【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Zulip 自托管服务器 GIPHY GIF 集成配置指南
Zulip 自托管服务器 GIPHY GIF 集成配置指南【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulipZulip 内置了对 GIPHY 的 GIF 搜索与发送支持用户可以在撰写消息时直接搜索并插入动画 GIF。GIPHY 在 Zulip Cloud 中默认启用而自托管self-hosted服务器需要管理员申请 GIPHY API Key 并修改服务器配置后方可使用。本文以templates/zerver/integrations/giphy.md与 docs/production/gif-picker-integrations.md 为核心结合仓库源码完整讲解 GIPHY 集成的申请步骤、配置方法、运行原理与内容分级控制帮助自托管管理员一步到位完成部署。集成概览GIPHY 在 Zulip 中的角色GIPHY 是 Zulip 的 GIF 提供商之一。启用后用户在撰写消息时点击输入框中的 GIF 图标即可打开 GIF 选择器GIF picker浏览热门 GIF 或按关键词搜索选中后直接以图片形式插入消息。自托管服务器与 Zulip Cloud 的差别仅在于服务器端配置Zulip Cloud 已由官方预先配置好 GIPHY 集成而自托管服务器必须由管理员手动完成 API Key 申请与设置。相关的用户端使用说明可参考帮助中心文章《Using GIFs in Zulip》该文章在 templates/zerver/integrations/giphy.md 中被引用。需要特别说明的是Zulip 同时支持 GIPHY、Tenor 与 KLIPY 三种 GIF 提供商。按照 docs/production/gif-picker-integrations.md 的说明如果多个集成都配置了 API KeyZulip 会按Tenor → KLIPY → GIPHY的优先级顺序选择提供商。因此即使你配置了 GIPHY只要服务器上同时配置了 Tenor 或 KLIPY 的 Key实际生效的提供商可能不是 GIPHY这一点在排查为何 GIPHY 未生效时尤为重要。第一步申请 GIPHY API Key要启用 GIPHY 集成首先需要从 GIPHY 开发者平台 获取一个 beta 或 production 级别的 API Key。具体步骤如下注册 GIPHY 账号。登录 GIPHY Developer Dashboard点击Create an App创建一个应用。产品类型Product Type选择SDK然后点击Next Step。为应用填写名称与描述然后点击Create New App。官方建议直接用 Zulip 服务器的主机名作为应用名称便于日后识别。申请成功后你会收到一个带速率限制rate-limited的beta API Key。对于用户规模较小的 Zulip 服务器beta Key 通常已经够用。可选如果 beta Key 的速率限制无法满足组织需要可以按照 GIPHY 在发放 beta Key 时提供的说明申请production API Key。注意提交申请截图时GIPHY 要求截图展示完整页面包括 URL 地址栏否则可能被驳回。第二步在服务器上配置 GIPHY API Key修改/etc/zulip/settings.py自托管服务器的运行配置位于/etc/zulip/settings.py。打开该文件加入如下配置GIPHY_API_KEY Your API key from GIPHY关键设计为什么放在 settings.py 而非 zulip-secrets.conf这一点是理解 Zulip 配置哲学的关键。在 docs/production/gif-picker-integrations.md 中明确说明GIPHY API keys are not secrets — GIPHY expects every browser or other client connecting to your Zulip server will receive a copy — which is why they are configured insettings.pyand notzulip-secrets.conf.GIPHY 的 API Key 并非机密数据——GIPHY 官方设计上就允许甚至要求每个连接到服务器的浏览器客户端都能拿到这份 Key因为实际搜索请求是由用户浏览器直接向 GIPHY API 发起的详见下文前端实现原理。因此它被放在普通的settings.py中而不是用于存放密钥的zulip-secrets.conf。与此形成对比的是真正的敏感凭据如数据库密码、secret key 等都必须写入zulip-secrets.conf由get_secret()读取。仓库中的默认值与模板佐证在源码层面这一设计体现在 zproject/default_settings.py 中# GIPHY API key. GIPHY_API_KEY get_secret(giphy_api_key) # Tenor API key TENOR_API_KEY get_secret(tenor_api_key) # Klipy API key KLIPY_API_KEY get_secret(klipy_api_key)可以看到三个 GIF 提供商的 Key 在开发/默认配置中都通过get_secret()从开发环境的 secrets 文件中读取这便于开发者在本机调试。而在生产环境模板 zproject/prod_settings_template.py 中则以注释形式给出了直接写死的模板# GIPHY_API_KEY Your API key from GIPHY # TENOR_API_KEY Your API key from Tenor # KLIPY_API_KEY Your API key from KLIPY管理员只需复制对应行、取消注释并填入真实 Key 即可。生产环境/etc/zulip/settings.py正是zproject/prod_settings_template.py的落地实例。第三步重启服务器并验证修改配置后需要重启 Zulip 服务器使设置生效/home/zulip/deployments/current/scripts/restart-server重启完成后用户即可按帮助中心文章所述使用 GIF 集成可能需要在浏览器中刷新页面一次。建议从管理员账号与普通用户账号各验证一次打开撰写框 → 点击 GIF 图标 → 检查热门Trending列表能否加载、搜索关键词能否返回结果、选中 GIF 后能否正常插入消息。底层实现原理前端如何调用 GIPHY API为了让管理员更好地理解为什么 Key 不是秘密为什么改配置要重启这里结合仓库前端源码说明 GIPHY 集成的实际工作链路。浏览器直连 GIPHYKey 必然暴露给客户端GIF 搜索请求由用户的浏览器直接发送给 GIPHY而不是经由 Zulip 服务器转发。实现位于 web/src/giphy_network.ts其 API 基地址为const BASE_URL https://api.giphy.com/v1/gifs;两个核心请求如下见 giphy_network.ts热门 GIF请求GET /v1/gifs/trending搜索 GIF请求GET /v1/gifs/search附带关键词q与语言参数lang每次请求的基础载荷get_base_payload()见 giphy_network.ts包含{ api_key: realm.giphy_api_key, // 从 realm 数据中取出直接发送给 GIPHY limit: GiphyNetwork.LIMIT, // 15每页条数 rating: get_rating(), // 内容分级见下文 offset: 0, // 分页偏移 fields: images.downsized_medium,images.fixed_height, }其中api_key直接取自前端 realm 数据——这正是 GIPHY Key 必须配置在settings.py且必须能被所有客户端读取的根本原因。fields参数用于按需精简响应载荷选择器预览图使用fixed_height版本发送到消息中的正文图使用downsized_medium版本。分页通过pagination.offset GiphyNetwork.LIMIT即 15累加实现见 giphy_network.ts支持无限滚动加载更多。服务端如何把 Key 下发到前端Key 从服务器到浏览器的传递路径为/etc/zulip/settings.py中的GIPHY_API_KEY→ 服务端将其注入 realm 数据 → 前端从realm.giphy_api_key读取见 web/src/giphy_network.ts。这也解释了为何修改配置后需要重启并刷新浏览器——realm 数据是在页面加载时一次性下发的。三种提供商的统一抽象前端为三种提供商定义了统一抽象基类GifNetwork位于 web/src/abstract_gif_network.tsGIPHY、Tenor、KLIPY 各自实现一个子类GiphyNetwork、tenor_network.ts等。这样 GIF 选择器 UIweb/src/gif_picker_ui.ts只需面向统一接口编程无需关心底层是哪个提供商。内容分级控制gif_rating_policyGIPHY 集成并非开箱即发的全部——组织管理员还可以通过内容分级策略GIF rating policy控制允许展示的 GIF 内容。分级选项定义分级选项定义在 zerver/models/realms.py 的GIF_RATING_POLICY_OPTIONS中等级名称IDdisabled禁用 GIF 集成0g允许 G 级大众级GIF1pg允许 PG 级家长指引GIF2pg-13允许 PG-13 级13 岁以下需家长陪同GIF3r允许 R 级限制级GIF4该字段为PositiveSmallIntegerField默认值为GIF_RATING_POLICY_OPTIONS[g][id]即默认允许 G 级内容见 realms.py。分级选项来源在源码注释中明确标注GIPHY 官方文档的rating可选参数、Google Tenor 的内容过滤选项以及 KLIPY 的内容过滤文档。前端如何根据策略过滤前端在 web/src/gif_state.ts 中实现两级控制启用判断is_giphy_enabled()等见 gif_state.ts只有当realm.giphy_api_key ! 且realm.realm_gif_rating_policy ! disabled.id时GIPHY 才被视为启用。也就是说只配了 Key 但策略为 Disabled集成不会展示。评级映射get_rating()见 gif_state.ts把组织策略映射为 GIPHY API 的rating参数值g/pg/pg-13/r随搜索请求一并发送给 GIPHY 服务端进行内容过滤。此外当策略被设置为 Disabled 时前端会隐藏撰写框中的 GIF 图标update_gif_icon_visibility()见 gif_state.ts。注意修改 rating 策略只会立即显示/隐藏 GIF 图标但不会在运行期切换 GIF 提供商——提供商切换需要重启服务器源码注释明确说明It wont change the GIF provider without a server restart as of now.。分级策略的迁移历史GIPHY 评级策略在仓库中经历了多次迁移从迁移文件可看出其演进0319_realm_giphy_rating.py新增字段0763_migrate_realms_using_y_rating_to_use_a_g_rating_for_giphy.py将旧版yYouth评级迁移为g0773_rename_giphy_rating_realm_gif_rating_policy.py将其重命名为通用的gif_rating_policy以适配多提供商。这说明分级控制从仅服务 GIPHY演进为服务所有 GIF 提供商的通用机制。品牌与版权合规GIPHY 对集成方的品牌展示有明确要求。在 GIF 选择器底部Zulip 会显示 GIPHY 官方署名attribution标识见 web/templates/giphy_footer.hbsdiv classpopover-footer img src../images/giphy/GIPHY_attribution.png alt{{t GIPHY attribution }} / /div该署名图片资源位于 static/images/giphy/ 目录下。这一设计符合 GIPHY 官方集成规范管理员在自定义前端时不应移除该署名以免违反 GIPHY 品牌使用条款。常见问题排查配置后 GIF 图标不出现检查GIPHY_API_KEY是否已写入/etc/zulip/settings.py并重启服务器同时确认组织的 GIF rating policy 未被设置为 Disabledgif_state.ts 中两个条件缺一不可。GIPHY 配置了却不生效如果同时配置了 Tenor 或 KLIPY 的 KeyZulip 会优先使用 Tenor → KLIPY → GIPHY 中的前者。若确实想用 GIPHY需要移除或留空优先级更高的提供商 Key。搜索无结果 / 内容异常确认组织的 rating 策略与期望一致例如设置为 G 级就搜不到 R 级内容检查浏览器开发者工具中发往api.giphy.com的请求是否携带了正确的api_key与rating参数。beta Key 速率受限beta API Key 有速率限制流量较大时建议按第一步的可选步骤申请 production API Key。总结在自托管 Zulip 服务器上启用 GIPHY 集成核心就三步申请 GIPHY API Key → 在/etc/zulip/settings.py中写入GIPHY_API_KEY→ 重启服务器。理解GIPHY Key 不是秘密、搜索由浏览器直连 GIPHY 完成、评级策略由组织级gif_rating_policy控制这三个底层事实可以让你在配置和排障时事半功倍。若需要多提供商对比或考虑替换方案可继续阅读 docs/production/gif-picker-integrations.md 中关于 Tenor 与 KLIPY 的配置章节其 Key 同样写入settings.py配置流程与 GIPHY 一致。【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考