meme-search Search API v1完整指南创建作用域令牌、OpenAPI契约与curl实战示例【免费下载链接】meme-searchThe open source Meme Search Engine and Finder. Free and built to self-host locally with Python, Ruby, and Docker.项目地址: https://gitcode.com/gh_mirrors/me/meme-searchmeme-search 是一个可以自托管的开源 Meme 搜索引擎它用 AI 为表情包建立索引让你能用关键词或语义向量检索自己的图库。从 v2.3.0 开始它新增了带令牌认证的 Search API v1你的本地工具、CLI 或脚本可以像网页应用一样搜索图库、下载原图而完全不需要接触数据库、文件系统路径或 Docker 内部网络。本文带你从零创建作用域令牌读懂 OpenAPI 契约并用 curl 完成一次完整的搜索与下载。为什么需要 Search API v1 以前想把 Meme 库接入自己的启动器、Slack 机器人或 Shell 脚本你只能绕开 Web 界面直连 PostgreSQL既危险又脆弱。Search API v1 提供了一个稳定的兼容边界版本化 JSON客户端与 Rails 内部结构彻底解耦只读契约v1 永久只读未来写入能力需要独立的 v2最弱权限令牌哈希存储、按作用域授权、可设过期时间、可单独吊销媒体流式传输授权后按原字节流式返回绝不泄露本地挂载路径。⚠️ 官方支持边界为 loopback本机回环。令牌只保护 API 端点不能保护 Web UI请勿将应用直接暴露到公网。一键创建作用域令牌的步骤 进入网页应用Settings → API tokens创建一个命名令牌勾选一个或两个只读作用域可选地设置过期时间。原始令牌只在创建时的即时响应中出现一次——系统只保存其 SHA-256 摘要刷新页面就无法再看到所以请立即复制保存。不想用网页界面项目内置的 Rails 任务可以直接在终端创建。Docker 环境下docker compose exec meme_search bin/rails api_tokens:create \ NAMELocal CLI SCOPESsearch:read,media:read原生检出则先进入meme_search/meme_search_app再执行同一条bin/rails api_tokens:create ...命令。EXPIRES_AT必须是带时区的 ISO-8601 时间戳如2030-01-15T12:30:00-07:00无时区会被直接拒绝。v1 可用作用域只有两个作用域权限search:read搜索并获取单个 meme 的元数据media:read流式下载原始媒体字节v1 没有任何写入、上传、改标签或管理作用域。建议每个集成客户端使用独立令牌这样吊销某一个客户端时不会牵连其他工具。管理已有令牌不会暴露密钥# 列出安全前缀与作用域 docker compose exec meme_search bin/rails api_tokens:list # 按前缀吊销 docker compose exec meme_search bin/rails api_tokens:revoke PREFIXms_abcd1234读懂 OpenAPI 契约与本地校验 机器可读的 OpenAPI 3.1 契约位于 search-api-openapi.yml。它在文档层面就写清了所有约束/api/v1/searchq必填且最长 200 字符mode只接受keyword默认或vectortag可重复最多 10 个每个是一个精确标签limit范围 1–20限流每个令牌每分钟 60 次搜索兼容性策略changes: additive-only破坏性变更必须升/api/v2写操作never-in-v1。安装根目录依赖后无需联网即可本地校验整份契约npm run contract:openapiCLI 与浏览器扩展的测试套件还会共同消费 search-response-conformance.json 契约测试夹具包括“新增可选字段”夹具保证客户端对必填字段的校验始终与契约对齐。curl 实战搜索、取回与下载 第一步发起搜索curl --get http://127.0.0.1:3000/api/v1/search \ --header Authorization: Bearer $MEME_SEARCH_API_TOKEN \ --data-urlencode qproduction incident \ --data modekeyword \ --data limit5 \ --data-urlencode tagreaction成功时返回结构化 JSON每条结果包含id、filename、description、tags、media_type和content_url{ data: [ { id: 42, filename: ship-it.gif, description: A celebratory reaction after a successful deploy, tags: [reaction, work], media_type: image/gif, content_url: /api/v1/memes/42/content } ], meta: { query: production incident, mode: keyword, tags: [reaction], limit: 5, count: 1 } }注意content_url是相对路径这是有意为之请从同一实例、用同一个 Bearer 令牌去取回。客户端必须忽略未知响应字段以便未来无感增加新字段。第二步下载原始媒体curl http://127.0.0.1:3000/api/v1/memes/42/content \ --header Authorization: Bearer $MEME_SEARCH_API_TOKEN \ --output ship-it.gif媒体响应头携带Cache-Control: private和X-Content-Type-Options: nosniff字节原样保留。文件缺失、是符号链接或不在图库内时都会返回统一的 404 JSON 信封而不是暴露文件系统路径。GET /api/v1/memes/:id则以同样的元数据形状返回单条结果适合二次确认某个 ID。错误码速查表状态码含义与应对401令牌缺失、无效、过期或已吊销——重新创建令牌403令牌缺少search:read或media:read——新建一个带正确作用域的替换令牌404meme 或媒体不存在——重新扫描图库确认是普通非符号链接文件422查询/模式/标签/limit 违反契约——对照上表边界检查429超过每令牌 60 次/分钟——等待一分钟窗口不要共享令牌绕过归因所有错误都使用统一信封{error:{code:...,message:...}}。升级安装与迁移须知 ⚙️API 新增了api_tokens表升级前请先备份数据库。Docker 用户docker compose pull docker compose up -d docker compose exec meme_search bin/rails db:migrate:status容器入口脚本会先幂等执行bin/rails db:preparedb:migrate:status应显示20260728000000 Create api tokens为up。该迁移只新增令牌表不改变现有图库与搜索行为也不为 Web 路由添加认证。最佳实践清单 ✅保持 loopback 绑定不要把应用直接暴露公网令牌只走环境变量如MEME_SEARCH_API_TOKEN不要写进命令行参数或日志一个客户端一个令牌最小权限原则客户端忽略未知字段、固定使用/api/v1、拒绝跨源的content_url社区集成保持只读不绕过 API 直连数据库或文件系统。更多细节请查阅完整 API 指南 search-api.md以及随附的零依赖 Python CLI integrations/cli/README.md 和实验性浏览器扩展 integrations/browser-extension/README.md——用它们你的 Meme 库就能出现在任何你工作的地方。【免费下载链接】meme-searchThe open source Meme Search Engine and Finder. Free and built to self-host locally with Python, Ruby, and Docker.项目地址: https://gitcode.com/gh_mirrors/me/meme-search创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 meme-search Search API v1完整指南：创建作用域令牌、OpenAPI契约与curl实战示例
meme-search Search API v1完整指南创建作用域令牌、OpenAPI契约与curl实战示例【免费下载链接】meme-searchThe open source Meme Search Engine and Finder. Free and built to self-host locally with Python, Ruby, and Docker.项目地址: https://gitcode.com/gh_mirrors/me/meme-searchmeme-search 是一个可以自托管的开源 Meme 搜索引擎它用 AI 为表情包建立索引让你能用关键词或语义向量检索自己的图库。从 v2.3.0 开始它新增了带令牌认证的 Search API v1你的本地工具、CLI 或脚本可以像网页应用一样搜索图库、下载原图而完全不需要接触数据库、文件系统路径或 Docker 内部网络。本文带你从零创建作用域令牌读懂 OpenAPI 契约并用 curl 完成一次完整的搜索与下载。为什么需要 Search API v1 以前想把 Meme 库接入自己的启动器、Slack 机器人或 Shell 脚本你只能绕开 Web 界面直连 PostgreSQL既危险又脆弱。Search API v1 提供了一个稳定的兼容边界版本化 JSON客户端与 Rails 内部结构彻底解耦只读契约v1 永久只读未来写入能力需要独立的 v2最弱权限令牌哈希存储、按作用域授权、可设过期时间、可单独吊销媒体流式传输授权后按原字节流式返回绝不泄露本地挂载路径。⚠️ 官方支持边界为 loopback本机回环。令牌只保护 API 端点不能保护 Web UI请勿将应用直接暴露到公网。一键创建作用域令牌的步骤 进入网页应用Settings → API tokens创建一个命名令牌勾选一个或两个只读作用域可选地设置过期时间。原始令牌只在创建时的即时响应中出现一次——系统只保存其 SHA-256 摘要刷新页面就无法再看到所以请立即复制保存。不想用网页界面项目内置的 Rails 任务可以直接在终端创建。Docker 环境下docker compose exec meme_search bin/rails api_tokens:create \ NAMELocal CLI SCOPESsearch:read,media:read原生检出则先进入meme_search/meme_search_app再执行同一条bin/rails api_tokens:create ...命令。EXPIRES_AT必须是带时区的 ISO-8601 时间戳如2030-01-15T12:30:00-07:00无时区会被直接拒绝。v1 可用作用域只有两个作用域权限search:read搜索并获取单个 meme 的元数据media:read流式下载原始媒体字节v1 没有任何写入、上传、改标签或管理作用域。建议每个集成客户端使用独立令牌这样吊销某一个客户端时不会牵连其他工具。管理已有令牌不会暴露密钥# 列出安全前缀与作用域 docker compose exec meme_search bin/rails api_tokens:list # 按前缀吊销 docker compose exec meme_search bin/rails api_tokens:revoke PREFIXms_abcd1234读懂 OpenAPI 契约与本地校验 机器可读的 OpenAPI 3.1 契约位于 search-api-openapi.yml。它在文档层面就写清了所有约束/api/v1/searchq必填且最长 200 字符mode只接受keyword默认或vectortag可重复最多 10 个每个是一个精确标签limit范围 1–20限流每个令牌每分钟 60 次搜索兼容性策略changes: additive-only破坏性变更必须升/api/v2写操作never-in-v1。安装根目录依赖后无需联网即可本地校验整份契约npm run contract:openapiCLI 与浏览器扩展的测试套件还会共同消费 search-response-conformance.json 契约测试夹具包括“新增可选字段”夹具保证客户端对必填字段的校验始终与契约对齐。curl 实战搜索、取回与下载 第一步发起搜索curl --get http://127.0.0.1:3000/api/v1/search \ --header Authorization: Bearer $MEME_SEARCH_API_TOKEN \ --data-urlencode qproduction incident \ --data modekeyword \ --data limit5 \ --data-urlencode tagreaction成功时返回结构化 JSON每条结果包含id、filename、description、tags、media_type和content_url{ data: [ { id: 42, filename: ship-it.gif, description: A celebratory reaction after a successful deploy, tags: [reaction, work], media_type: image/gif, content_url: /api/v1/memes/42/content } ], meta: { query: production incident, mode: keyword, tags: [reaction], limit: 5, count: 1 } }注意content_url是相对路径这是有意为之请从同一实例、用同一个 Bearer 令牌去取回。客户端必须忽略未知响应字段以便未来无感增加新字段。第二步下载原始媒体curl http://127.0.0.1:3000/api/v1/memes/42/content \ --header Authorization: Bearer $MEME_SEARCH_API_TOKEN \ --output ship-it.gif媒体响应头携带Cache-Control: private和X-Content-Type-Options: nosniff字节原样保留。文件缺失、是符号链接或不在图库内时都会返回统一的 404 JSON 信封而不是暴露文件系统路径。GET /api/v1/memes/:id则以同样的元数据形状返回单条结果适合二次确认某个 ID。错误码速查表状态码含义与应对401令牌缺失、无效、过期或已吊销——重新创建令牌403令牌缺少search:read或media:read——新建一个带正确作用域的替换令牌404meme 或媒体不存在——重新扫描图库确认是普通非符号链接文件422查询/模式/标签/limit 违反契约——对照上表边界检查429超过每令牌 60 次/分钟——等待一分钟窗口不要共享令牌绕过归因所有错误都使用统一信封{error:{code:...,message:...}}。升级安装与迁移须知 ⚙️API 新增了api_tokens表升级前请先备份数据库。Docker 用户docker compose pull docker compose up -d docker compose exec meme_search bin/rails db:migrate:status容器入口脚本会先幂等执行bin/rails db:preparedb:migrate:status应显示20260728000000 Create api tokens为up。该迁移只新增令牌表不改变现有图库与搜索行为也不为 Web 路由添加认证。最佳实践清单 ✅保持 loopback 绑定不要把应用直接暴露公网令牌只走环境变量如MEME_SEARCH_API_TOKEN不要写进命令行参数或日志一个客户端一个令牌最小权限原则客户端忽略未知字段、固定使用/api/v1、拒绝跨源的content_url社区集成保持只读不绕过 API 直连数据库或文件系统。更多细节请查阅完整 API 指南 search-api.md以及随附的零依赖 Python CLI integrations/cli/README.md 和实验性浏览器扩展 integrations/browser-extension/README.md——用它们你的 Meme 库就能出现在任何你工作的地方。【免费下载链接】meme-searchThe open source Meme Search Engine and Finder. Free and built to self-host locally with Python, Ruby, and Docker.项目地址: https://gitcode.com/gh_mirrors/me/meme-search创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考