Dashboard Icons Web 应用图标浏览、MCP 服务与外部源集成完全指南【免费下载链接】dashboard-iconsYour definitive source for dashboard icons.项目地址: https://gitcode.com/GitHub_Trending/da/dashboard-iconsDashboard Icons Web 应用位于仓库web/目录是一个基于 Next.js 15 的全栈 Web 应用用于浏览、搜索和下载 Dashboard Icons 图标集合。它不仅是图标的展示层还内置了用户认证、图标提交审核、管理员后台以及面向 AI 助手的 MCPModel Context ProtocolHTTP 服务端。本文将以web/README.md为骨架结合仓库源码与配置完整讲解该应用的功能架构、本地开发环境搭建、GitHub OAuth 配置、MCP 服务端的使用与限流实现以及 selfh.st 和 Simple Icons 两个第三方图标源的接入方式帮助你快速上手部署并深度定制。一、项目定位与核心功能web/README.md将该项目定位为 Dashboard Icons 图标集合的官方 Web 应用核心价值在于把仓库中 3366 个 SVG 源文件、4066 个 WebP 预览图以及完整的metadata.json元数据根目录 metadata.json转化为可浏览、可检索、可下载的在线服务。其功能清单涵盖了从查看到协作的完整链路图标浏览以卡片网格形式展示经过人工筛选的图标集合多维搜索支持按图标名称、别名aliases或分类categories搜索对应源码中的 web/src/lib/icons/search.ts详情查看展示作者、可用格式SVG/PNG/WebP与变体信息多格式下载SVG、PNG、WebP 三种格式URL 复制一键复制图标 CDN URL 到剪贴板响应式设计兼容移动端、平板与桌面端且支持深色模式用户认证支持邮箱/密码与 GitHub OAuth 两种登录方式图标提交已认证用户可向集合提交新图标管理后台管理员可审批、驳回与管理图标提交MCP 服务端通过 HTTP 提供 MCP 端点让 AI 助手无需抓取网页即可搜索图标、获取元数据并解析 CDN URL。从web/src/app/的目录结构可以印证这些功能均有对应实现api/icons/search/route.ts是图标搜索 API、api/mcp/route.ts是 MCP 端点、icons/[icon]/page.tsx是图标详情动态页、submit/page.tsx是提交页、dashboard/page.tsx是管理后台页。二、技术栈全景README 明确列出了该应用的技术选型结合 web/package.json 可以核实各依赖版本与作用技术版本以 package.json 为准职责Next.js16.2.12README 描述为 Next.js 15 体系React 框架App Router支持 Turbopack 开发模式TypeScript~5.9.3全栈类型安全Tailwind CSS^4.2.4原子化 CSS 框架Shadcn UI / Radix UIradix-ui ^1.4.3 等可复用组件库web/src/components/ui/下可见大量 shadcn 风格组件PocketBase^0.26.8后端认证与数据存储web/backend/目录内置服务端二进制PostHogposthog-js ^1.408.2、posthog-node ^5.32.1产品分析与用户追踪MCPmcp-handler ^2.0.1、modelcontextprotocol/server ^2.0.0HTTP 传输的 MCP 服务端React^19.2.5UI 运行时zod^4.4.1参数校验搜索、MCP 工具等场景sharp^0.35.3服务端图像处理如 PNG 生成tanstack/react-query / react-table^5.100.7 / ^8.21.3数据请求与表格管理后台值得注意的工程细节package.json中声明engines.node 22.22.0包管理器为pnpm10.18.2并且scripts.dev通过turbo run dev:backend dev:web同时启动 PocketBase 后端与 Next.js 前端实现一体化开发体验。项目还内置了 Vitest 单元测试pnpm test与 Playwright 端到端测试pnpm test:e2e两套测试体系测试文件分布在web/src/**/__tests__/与web/tests/。三、项目结构与代码地图README 给出了精简的目录树结合仓库实际目录可得到更完整的代码地图以下路径均以仓库根目录为起点web/ ├── src/ │ ├── app/ # Next.js App Router │ │ ├── api/ │ │ │ ├── icons/ # 图标搜索 API 与外部图标路由 │ │ │ └── mcp/route.ts # MCP HTTP 端点 │ │ ├── icons/ # 图标浏览与详情页 │ │ │ ├── [icon]/page.tsx # 原生图标动态详情页 │ │ │ └── page.tsx # 图标浏览页 │ │ ├── icons/external/[slug]/page.tsx # 外部图标静态详情页 │ │ ├── community/ # 社区画廊 │ │ ├── dashboard/ # 管理后台 │ │ ├── submit/ # 图标提交页 │ │ ├── globals.css # 全局样式 │ │ ├── layout.tsx # 根布局 │ │ └── page.tsx # 首页 │ ├── components/ # 共享组件icon-card、icon-search、icon-details、command-menu 等 │ ├── lib/ │ │ ├── api.ts # 应用级图标 API 辅助函数 │ │ ├── icon-url.ts # 图标 URL 解析区分原生/外部 │ │ ├── external-icons.ts # 外部图标数据层多源拉取与缓存 │ │ ├── external-icon-urls.ts # 外部图标 URL 模板解析 │ │ └── icons/ # 图标服务、搜索、校验、限流 │ ├── mcp/ # MCP handler、工具注册、分析 │ └── types/ # TypeScript 类型定义 ├── backend/ │ ├── pb_hooks/ # PocketBase 服务端钩子如提交更新邮件 │ └── pb_migrations/ # PocketBase 迁移users、submission、external_icons 等集合 ├── docs/ │ ├── MCP.md # MCP 服务端详细文档 │ └── ADDING_EXTERNAL_SOURCES.md # 新增外部图标源完整指南 ├── scripts/ # 导入脚本import-selfhst.ts、import-simple-icons.ts 等 ├── tests/ # Playwright 端到端测试 ├── package.json ├── next.config.ts └── Dockerfile / docker-compose.yml其中web/src/lib/icon-url.ts展示了原生与外部图标的 URL 解析逻辑若图标属于外部源source ! native则调用getExternalIconPreviewUrl()否则基于base字段svg/png/webp调用buildIconUrl()构造 URL若base本身是 HTTP 地址则直接返回。这是理解多源图标如何统一渲染的关键入口。四、本地开发环境搭建4.1 环境要求README 要求Node.js 18实际以 web/package.json 的engines为准要求 Node.js 22.22.0pnpm包管理器锁文件为web/pnpm-lock.yaml4.2 安装步骤克隆仓库git clone本仓库后进入web/目录安装依赖pnpm install创建.env文件配置以下变量GITHUB_TOKENyour_github_token NEXT_PUBLIC_POCKETBASE_URLhttp://127.0.0.1:8090GITHUB_TOKEN用于拉取外部源元数据例如 GitHub raw 内容 API 的鉴权NEXT_PUBLIC_POCKETBASE_URL指定 PocketBase 实例地址开发环境下默认为http://127.0.0.1:8090。4.3 启动开发服务器pnpm dev该命令会通过 turbo 同时启动 PocketBase 后端cd backend ./pocketbase serve与 Next.js 前端next dev --turbopack --port 3005。前端默认运行在3005 端口——这一点与 MCP 本地端点的http://localhost:3005/api/mcp相互呼应。其余常用脚本来自web/package.json脚本说明pnpm dev:backend仅启动 PocketBase./pocketbase servepnpm dev:web仅启动 Next.js 开发服务器pnpm buildNext.js 生产构建pnpm start启动生产服务器pnpm backend:start同dev:backend用于单独管理后端pnpm seed运行seed-db.ts填充种子数据pnpm test运行 Vitest 单元测试pnpm test:e2e运行 Playwright 端到端测试pnpm lint/pnpm formatBiome 代码检查与格式化4.4 生产构建pnpm build该应用针对Vercel 部署进行了优化README 明确说明同时仓库中也提供了 web/Dockerfile 与 web/docker-compose.yml 作为容器化部署选项另有 web/netlify.toml 支持 Netlify 平台。五、GitHub OAuth 登录配置可选README 给出了完整的 GitHub OAuth 接入流程分三步a. 创建 GitHub OAuth App进入 GitHub 开发者设置 → OAuth Apps → New OAuth AppApplication name 填写 Dashboard Icons或自定义名称Homepage URL 填http://localhost:3000开发环境Authorization callback URL 填http://localhost:8090/api/oauth2-redirect创建成功后记录Client ID并生成Client Secret。b. 在 PocketBase 中配置 OAuth启动后端pnpm run backend:start打开 PocketBase 管理后台http://127.0.0.1:8090/_/进入 Settings → Auth providers启用 GitHub provider填入 Client ID 与 Client Secret保存设置。c. 生产环境适配将 Authorization callback URL 更新为生产 PocketBase 的回调地址形如https://pb.你的域名/api/oauth2-redirect在生产 PocketBase 实例上配置同样的 OAuth 设置。从源码看GitHub OAuth 相关逻辑位于 web/src/app/actions/github.ts前端登录入口组件为 web/src/components/login-modal.tsx 与 web/src/components/user-button.tsx。六、MCP 服务端让 AI 助手直接检索图标这是该 Web 应用最具特色的能力。README 指出应用在/api/mcp暴露了一个 native-icons MCP 服务端AI 客户端无需抓取网页即可搜索图标集合、获取元数据并解析 CDN URL。详细端点、客户端配置、工具 schema、环境变量、分析与限流说明见 web/docs/MCP.md。6.1 端点地址生产环境https://dashboardicons.com/api/mcp本地开发http://localhost:3005/api/mcp6.2 客户端接入配置支持 HTTP 的客户端如 Cursor在 MCP 配置中加入{ mcpServers: { dashboard-icons: { url: https://dashboardicons.com/api/mcp } } }仅支持 stdio 的客户端通过mcp-remote桥接{ mcpServers: { dashboard-icons: { command: npx, args: [-y, mcp-remote, https://dashboardicons.com/api/mcp] } } }6.3 可用工具MCP 服务端提供四个核心工具其参数 schema 定义在 web/src/mcp/tools.tssearch_icons—— 按名称、别名或分类搜索图标参数类型默认值上限querystring必填100 字符limitnumber2050categorystring可选50 字符get_icon—— 获取单个图标的完整元数据与 CDN URL参数类型namekebab-case 形式的 slugget_icon_url—— 获取单个图标的直接 CDN URL参数类型默认值namestring必填formatsvg|png|webpsvgthemedefault|light|darkdefaultsuggest_icon—— 根据自然语言服务名做模糊匹配例如Plex media server→plex参数类型默认值上限service_namestring必填100 字符limitnumber5206.4 限流策略作用域限制所有 MCP 请求每 IP 每分钟 60 次工具调用tools/call每 IP 每分钟 30 次超限时服务端返回 HTTP429并携带Retry-After响应头。从 web/src/app/api/mcp/route.ts 的源码可以看到限流与防护的实际实现细节通过checkRateLimit(ip, request)与checkRateLimit(ip, tool)分别对全部请求与tools/call请求做两级限流限流逻辑封装在 web/src/lib/icons/rate-limit.ts对 POST 请求体进行字节数有界读取readBoundedPostRequest超限返回413 Payload Too Large防止超大请求体攻击所有响应统一附加安全头Cache-Control: no-store、X-Content-Type-Options: nosniff、X-Frame-Options: DENY路由声明runtime nodejs与maxDuration 30并在每次调用结束后冲刷 MCP 分析数据flushDashboardIconsMcpAnalytics()。6.5 环境变量变量说明MCP_RATE_LIMIT_ENABLED设为false可关闭限流仅限本地开发MCP_VERBOSE_LOGS设为true开启 MCP handler 详细日志MCP_WARM_CACHE设为true在服务启动时预热元数据缓存DASHBOARD_ICONS_METADATA_PATH本地metadata.json路径仅开发环境生产环境禁用NEXT_PUBLIC_POSTHOG_KEY使用现有项目 key 开启 PostHog MCP 分析NEXT_PUBLIC_POSTHOG_HOST客户端 PostHog 采集端点如https://hog.homarr.devNEXT_PUBLIC_DISABLE_POSTHOG设为true完全禁用 PostHog 采集当分析开启时官方posthog/mcpSDK 会采集 MCP 生命周期事件、工具调用、延迟、响应与错误并在每次 serverless 调用结束后冲刷数据。6.6 当前范围MCP v1 仅覆盖metadata.json中的原生图标native icons外部源selfh.st、LobeHub、Simple Icons暂不包含。这一点在 web/docs/MCP.md 中有明确说明。七、第三方图标源集成一selfh.stDashboard Icons 可以从 selfh.st/icons 展示外部图标元数据而无需把图标文件复制进原生集合。7.1 存储模型external_iconsPocketBase 集合负责存储外部图标的 slug、名称、分类、可用格式、变体元数据、jsDelivr URL 模板以及许可证归属信息。外部图标文件保留在 jsDelivr 上遵循以下模式https://cdn.jsdelivr.net/gh/selfhst/icons/format/slug.format集合访问规则为公开只读PocketBase 规则为listRule: 和viewRule: 而 create/update/delete 仅限超级管理员。每一个外部图标卡片与详情页都必须展示Icons by selfh.st/icons (CC BY 4.0)归属声明。7.2 首次导入集合 schema如果external_icons集合尚不存在需要在 PocketBase 管理后台的 Collections 界面导入 web/backend/pb_migrations/1777632695_created_external_icons.js 对应的集合定义README 描述为导入data/sources/selfhst/external_icons.collection.json该 JSON 定义了external_icons的字段、公开 list/view 规则、禁用公开写入以及(source, slug)唯一索引然后再运行导入器。7.3 刷新元数据并导入mkdir -p data/sources/selfhst curl -fsSL https://raw.githubusercontent.com/selfhst/icons/main/index.json -o data/sources/selfhst/index.json curl -fsSL https://raw.githubusercontent.com/selfhst/icons/main/index-consolidated.json -o data/sources/selfhst/index-consolidated.json curl -fsSL https://raw.githubusercontent.com/selfhst/icons/main/tags.json -o data/sources/selfhst/tags.json PB_ADMINadminexample.com PB_ADMIN_PASSyour-password \ NEXT_PUBLIC_POCKETBASE_URLhttp://127.0.0.1:8090 \ bun run scripts/import-selfhst.ts上述命令先下载上游的 manifest 文件到web/data/sources/selfhst/再以超级管理员身份运行 web/scripts/import-selfhst.ts 将元数据导入 PocketBase。该脚本是一个独立的 ETL抽取-转换-加载流程读取 CSV manifest → 转换为external_icons记录 → 按 slug upsert存在则更新、不存在则创建。八、第三方图标源集成二Simple Icons外部目录还收录了 Simple Icons 中的独立品牌图标。8.1 同步机制与元数据保留每周一Monday自动同步解析最新发布的 npm 版本导入版本锁定version-pinned的元数据slug 去重跳过已被 Dashboard Icons 原生集合或其他外部源占用的 slug每条导入记录保留官方 slug、品牌色、来源、使用指南、逐图标许可证元数据以及所有可搜索的别名类别。8.2 渲染与下载详情页会并排展示SVG 与 PNG 卡片对应品牌色、黑色浅色模式与白色深色模式三种变体SVG 由官方 colorable CDN 托管遵循模式https://cdn.simpleicons.org/slug/brand-colorPNG 下载为按需生成的透明 640 × 640 图片由对应官方 SVG 转换而来服务端使用 sharp 完成光栅化参考 web/src/lib/rasterize-svg.ts浏览页与主详情预览直接跟随网站主题浅色模式用黑色、深色模式用白色来源详情页会链接回原始品牌来源与使用指南并把彩色 SVG 送入现有的图标自定义器icon customizer。8.3 许可证说明Simple Icons 集合以CC0-1.0发布但品牌名称与商标仍受其所有者的许可证、商标与使用指南约束README 指向 Simple Icons 官方的 DISCLAIMER 声明作为参考。8.4 本地运行锁定版本导入器PB_ADMINadminexample.com PB_ADMIN_PASSyour-password \ PB_URLhttp://127.0.0.1:8090 SIMPLE_ICONS_VERSION16.28.0 \ bun run scripts/import-simple-icons.ts通过SIMPLE_ICONS_VERSION环境变量指定要导入的 Simple Icons npm 发布版本实现可复现的版本锁定导入。九、外部源架构一处注册全站生效从 web/docs/ADDING_EXTERNAL_SOURCES.md 可以了解到所有外部源共享同一个external_icons集合通过source字段区分来源UI 层遍历EXTERNAL_SOURCE_IDS自动渲染过滤器、徽章与标签——新增一个外部源无需改动任何组件。以下是自动联动的主要环节均为真实源码路径层级文件行为源注册表web/src/constants.tsExternalSourceId联合类型 EXTERNAL_SOURCES配置对象单一事实来源数据层web/src/lib/external-icons.tsfetchAllExternalIcons()按源并行查询 PocketBase 并做内存 TTL 缓存URL 解析web/src/lib/external-icon-urls.ts优先匹配url_templates精确键如png_dark否则回退到{cdnBase}/{format}/{slug}.{format}卡片徽章web/src/components/icon-card.tsx悬停显示来源图标与 from {label} 横幅详情页web/src/components/icon-details.tsx徽章、归属声明、View on 链接、格式/变体区块、SVG 自定义器搜索过滤web/src/components/icon-search.tsx来源过滤下拉框CMDKweb/src/components/command-menu.tsx结果带来源徽章并路由到/icons/external/[slug]浏览页web/src/app/icons/page.tsx合并原生与外部图标副标题动态列出所有来源静态详情页web/src/app/icons/external/[slug]/page.tsxgenerateStaticParams()覆盖所有注册来源Sitemapweb/src/app/sitemap.ts为每个外部图标生成带image标签的 URL 条目统计web/src/lib/api.tsgetTotalIcons()返回按源拆分的sourceCounts架构上采取适配器模式每个外部源 constants.ts配置项 PocketBase 集合 导入脚本 GitHub Actions 定时同步工作流。若你计划为仓库新增一个第三方图标目录web/docs/ADDING_EXTERNAL_SOURCES.md 提供了从常量注册、PocketBase 迁移、导入脚本编写、CI 工作流到 Playwright 测试的完整分步指南并总结了 LobeHub 集成中的经验教训如显式 URL 模板、变体合并、sitemap 去重、认证头透传等。十、部署与贡献部署应用针对 Vercel 做了部署优化web/next.config.ts也可使用仓库自带的 web/Dockerfile 与 web/docker-compose.yml 容器化部署数据库PocketBase 后端与前端一体化迁移文件位于 web/backend/pb_migrations/服务端钩子位于 web/backend/pb_hooks/测试单元测试Vitest覆盖搜索、限流、URL 解析、MCP 工具与分析集成等模块端到端测试Playwright覆盖浏览、过滤与详情页渲染等关键用户路径贡献README 明确欢迎社区提交 Pull Request图标新增流程可参考仓库根目录的 docs/add-icon-workflow.md。结语web/README.md所描绘的 Dashboard Icons Web 应用是图标集合 检索服务 AI 可编程接口 社区协作四位一体的完整产品。对使用者而言它提供了直观的浏览搜索与多格式下载体验对开发者而言其 MCP 服务端让任何 AI 客户端都能通过四个标准工具直接消费图标元数据对贡献者而言外部源适配器模式让新增图标目录变得声明式、可复用。结合 web/docs/MCP.md 与 web/docs/ADDING_EXTERNAL_SOURCES.md 两份深度文档即可将该应用扩展为你自己的 dashboard 图标基础设施。【免费下载链接】dashboard-iconsYour definitive source for dashboard icons.项目地址: https://gitcode.com/GitHub_Trending/da/dashboard-icons创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dashboard Icons Web 应用：图标浏览、MCP 服务与外部源集成完全指南
Dashboard Icons Web 应用图标浏览、MCP 服务与外部源集成完全指南【免费下载链接】dashboard-iconsYour definitive source for dashboard icons.项目地址: https://gitcode.com/GitHub_Trending/da/dashboard-iconsDashboard Icons Web 应用位于仓库web/目录是一个基于 Next.js 15 的全栈 Web 应用用于浏览、搜索和下载 Dashboard Icons 图标集合。它不仅是图标的展示层还内置了用户认证、图标提交审核、管理员后台以及面向 AI 助手的 MCPModel Context ProtocolHTTP 服务端。本文将以web/README.md为骨架结合仓库源码与配置完整讲解该应用的功能架构、本地开发环境搭建、GitHub OAuth 配置、MCP 服务端的使用与限流实现以及 selfh.st 和 Simple Icons 两个第三方图标源的接入方式帮助你快速上手部署并深度定制。一、项目定位与核心功能web/README.md将该项目定位为 Dashboard Icons 图标集合的官方 Web 应用核心价值在于把仓库中 3366 个 SVG 源文件、4066 个 WebP 预览图以及完整的metadata.json元数据根目录 metadata.json转化为可浏览、可检索、可下载的在线服务。其功能清单涵盖了从查看到协作的完整链路图标浏览以卡片网格形式展示经过人工筛选的图标集合多维搜索支持按图标名称、别名aliases或分类categories搜索对应源码中的 web/src/lib/icons/search.ts详情查看展示作者、可用格式SVG/PNG/WebP与变体信息多格式下载SVG、PNG、WebP 三种格式URL 复制一键复制图标 CDN URL 到剪贴板响应式设计兼容移动端、平板与桌面端且支持深色模式用户认证支持邮箱/密码与 GitHub OAuth 两种登录方式图标提交已认证用户可向集合提交新图标管理后台管理员可审批、驳回与管理图标提交MCP 服务端通过 HTTP 提供 MCP 端点让 AI 助手无需抓取网页即可搜索图标、获取元数据并解析 CDN URL。从web/src/app/的目录结构可以印证这些功能均有对应实现api/icons/search/route.ts是图标搜索 API、api/mcp/route.ts是 MCP 端点、icons/[icon]/page.tsx是图标详情动态页、submit/page.tsx是提交页、dashboard/page.tsx是管理后台页。二、技术栈全景README 明确列出了该应用的技术选型结合 web/package.json 可以核实各依赖版本与作用技术版本以 package.json 为准职责Next.js16.2.12README 描述为 Next.js 15 体系React 框架App Router支持 Turbopack 开发模式TypeScript~5.9.3全栈类型安全Tailwind CSS^4.2.4原子化 CSS 框架Shadcn UI / Radix UIradix-ui ^1.4.3 等可复用组件库web/src/components/ui/下可见大量 shadcn 风格组件PocketBase^0.26.8后端认证与数据存储web/backend/目录内置服务端二进制PostHogposthog-js ^1.408.2、posthog-node ^5.32.1产品分析与用户追踪MCPmcp-handler ^2.0.1、modelcontextprotocol/server ^2.0.0HTTP 传输的 MCP 服务端React^19.2.5UI 运行时zod^4.4.1参数校验搜索、MCP 工具等场景sharp^0.35.3服务端图像处理如 PNG 生成tanstack/react-query / react-table^5.100.7 / ^8.21.3数据请求与表格管理后台值得注意的工程细节package.json中声明engines.node 22.22.0包管理器为pnpm10.18.2并且scripts.dev通过turbo run dev:backend dev:web同时启动 PocketBase 后端与 Next.js 前端实现一体化开发体验。项目还内置了 Vitest 单元测试pnpm test与 Playwright 端到端测试pnpm test:e2e两套测试体系测试文件分布在web/src/**/__tests__/与web/tests/。三、项目结构与代码地图README 给出了精简的目录树结合仓库实际目录可得到更完整的代码地图以下路径均以仓库根目录为起点web/ ├── src/ │ ├── app/ # Next.js App Router │ │ ├── api/ │ │ │ ├── icons/ # 图标搜索 API 与外部图标路由 │ │ │ └── mcp/route.ts # MCP HTTP 端点 │ │ ├── icons/ # 图标浏览与详情页 │ │ │ ├── [icon]/page.tsx # 原生图标动态详情页 │ │ │ └── page.tsx # 图标浏览页 │ │ ├── icons/external/[slug]/page.tsx # 外部图标静态详情页 │ │ ├── community/ # 社区画廊 │ │ ├── dashboard/ # 管理后台 │ │ ├── submit/ # 图标提交页 │ │ ├── globals.css # 全局样式 │ │ ├── layout.tsx # 根布局 │ │ └── page.tsx # 首页 │ ├── components/ # 共享组件icon-card、icon-search、icon-details、command-menu 等 │ ├── lib/ │ │ ├── api.ts # 应用级图标 API 辅助函数 │ │ ├── icon-url.ts # 图标 URL 解析区分原生/外部 │ │ ├── external-icons.ts # 外部图标数据层多源拉取与缓存 │ │ ├── external-icon-urls.ts # 外部图标 URL 模板解析 │ │ └── icons/ # 图标服务、搜索、校验、限流 │ ├── mcp/ # MCP handler、工具注册、分析 │ └── types/ # TypeScript 类型定义 ├── backend/ │ ├── pb_hooks/ # PocketBase 服务端钩子如提交更新邮件 │ └── pb_migrations/ # PocketBase 迁移users、submission、external_icons 等集合 ├── docs/ │ ├── MCP.md # MCP 服务端详细文档 │ └── ADDING_EXTERNAL_SOURCES.md # 新增外部图标源完整指南 ├── scripts/ # 导入脚本import-selfhst.ts、import-simple-icons.ts 等 ├── tests/ # Playwright 端到端测试 ├── package.json ├── next.config.ts └── Dockerfile / docker-compose.yml其中web/src/lib/icon-url.ts展示了原生与外部图标的 URL 解析逻辑若图标属于外部源source ! native则调用getExternalIconPreviewUrl()否则基于base字段svg/png/webp调用buildIconUrl()构造 URL若base本身是 HTTP 地址则直接返回。这是理解多源图标如何统一渲染的关键入口。四、本地开发环境搭建4.1 环境要求README 要求Node.js 18实际以 web/package.json 的engines为准要求 Node.js 22.22.0pnpm包管理器锁文件为web/pnpm-lock.yaml4.2 安装步骤克隆仓库git clone本仓库后进入web/目录安装依赖pnpm install创建.env文件配置以下变量GITHUB_TOKENyour_github_token NEXT_PUBLIC_POCKETBASE_URLhttp://127.0.0.1:8090GITHUB_TOKEN用于拉取外部源元数据例如 GitHub raw 内容 API 的鉴权NEXT_PUBLIC_POCKETBASE_URL指定 PocketBase 实例地址开发环境下默认为http://127.0.0.1:8090。4.3 启动开发服务器pnpm dev该命令会通过 turbo 同时启动 PocketBase 后端cd backend ./pocketbase serve与 Next.js 前端next dev --turbopack --port 3005。前端默认运行在3005 端口——这一点与 MCP 本地端点的http://localhost:3005/api/mcp相互呼应。其余常用脚本来自web/package.json脚本说明pnpm dev:backend仅启动 PocketBase./pocketbase servepnpm dev:web仅启动 Next.js 开发服务器pnpm buildNext.js 生产构建pnpm start启动生产服务器pnpm backend:start同dev:backend用于单独管理后端pnpm seed运行seed-db.ts填充种子数据pnpm test运行 Vitest 单元测试pnpm test:e2e运行 Playwright 端到端测试pnpm lint/pnpm formatBiome 代码检查与格式化4.4 生产构建pnpm build该应用针对Vercel 部署进行了优化README 明确说明同时仓库中也提供了 web/Dockerfile 与 web/docker-compose.yml 作为容器化部署选项另有 web/netlify.toml 支持 Netlify 平台。五、GitHub OAuth 登录配置可选README 给出了完整的 GitHub OAuth 接入流程分三步a. 创建 GitHub OAuth App进入 GitHub 开发者设置 → OAuth Apps → New OAuth AppApplication name 填写 Dashboard Icons或自定义名称Homepage URL 填http://localhost:3000开发环境Authorization callback URL 填http://localhost:8090/api/oauth2-redirect创建成功后记录Client ID并生成Client Secret。b. 在 PocketBase 中配置 OAuth启动后端pnpm run backend:start打开 PocketBase 管理后台http://127.0.0.1:8090/_/进入 Settings → Auth providers启用 GitHub provider填入 Client ID 与 Client Secret保存设置。c. 生产环境适配将 Authorization callback URL 更新为生产 PocketBase 的回调地址形如https://pb.你的域名/api/oauth2-redirect在生产 PocketBase 实例上配置同样的 OAuth 设置。从源码看GitHub OAuth 相关逻辑位于 web/src/app/actions/github.ts前端登录入口组件为 web/src/components/login-modal.tsx 与 web/src/components/user-button.tsx。六、MCP 服务端让 AI 助手直接检索图标这是该 Web 应用最具特色的能力。README 指出应用在/api/mcp暴露了一个 native-icons MCP 服务端AI 客户端无需抓取网页即可搜索图标集合、获取元数据并解析 CDN URL。详细端点、客户端配置、工具 schema、环境变量、分析与限流说明见 web/docs/MCP.md。6.1 端点地址生产环境https://dashboardicons.com/api/mcp本地开发http://localhost:3005/api/mcp6.2 客户端接入配置支持 HTTP 的客户端如 Cursor在 MCP 配置中加入{ mcpServers: { dashboard-icons: { url: https://dashboardicons.com/api/mcp } } }仅支持 stdio 的客户端通过mcp-remote桥接{ mcpServers: { dashboard-icons: { command: npx, args: [-y, mcp-remote, https://dashboardicons.com/api/mcp] } } }6.3 可用工具MCP 服务端提供四个核心工具其参数 schema 定义在 web/src/mcp/tools.tssearch_icons—— 按名称、别名或分类搜索图标参数类型默认值上限querystring必填100 字符limitnumber2050categorystring可选50 字符get_icon—— 获取单个图标的完整元数据与 CDN URL参数类型namekebab-case 形式的 slugget_icon_url—— 获取单个图标的直接 CDN URL参数类型默认值namestring必填formatsvg|png|webpsvgthemedefault|light|darkdefaultsuggest_icon—— 根据自然语言服务名做模糊匹配例如Plex media server→plex参数类型默认值上限service_namestring必填100 字符limitnumber5206.4 限流策略作用域限制所有 MCP 请求每 IP 每分钟 60 次工具调用tools/call每 IP 每分钟 30 次超限时服务端返回 HTTP429并携带Retry-After响应头。从 web/src/app/api/mcp/route.ts 的源码可以看到限流与防护的实际实现细节通过checkRateLimit(ip, request)与checkRateLimit(ip, tool)分别对全部请求与tools/call请求做两级限流限流逻辑封装在 web/src/lib/icons/rate-limit.ts对 POST 请求体进行字节数有界读取readBoundedPostRequest超限返回413 Payload Too Large防止超大请求体攻击所有响应统一附加安全头Cache-Control: no-store、X-Content-Type-Options: nosniff、X-Frame-Options: DENY路由声明runtime nodejs与maxDuration 30并在每次调用结束后冲刷 MCP 分析数据flushDashboardIconsMcpAnalytics()。6.5 环境变量变量说明MCP_RATE_LIMIT_ENABLED设为false可关闭限流仅限本地开发MCP_VERBOSE_LOGS设为true开启 MCP handler 详细日志MCP_WARM_CACHE设为true在服务启动时预热元数据缓存DASHBOARD_ICONS_METADATA_PATH本地metadata.json路径仅开发环境生产环境禁用NEXT_PUBLIC_POSTHOG_KEY使用现有项目 key 开启 PostHog MCP 分析NEXT_PUBLIC_POSTHOG_HOST客户端 PostHog 采集端点如https://hog.homarr.devNEXT_PUBLIC_DISABLE_POSTHOG设为true完全禁用 PostHog 采集当分析开启时官方posthog/mcpSDK 会采集 MCP 生命周期事件、工具调用、延迟、响应与错误并在每次 serverless 调用结束后冲刷数据。6.6 当前范围MCP v1 仅覆盖metadata.json中的原生图标native icons外部源selfh.st、LobeHub、Simple Icons暂不包含。这一点在 web/docs/MCP.md 中有明确说明。七、第三方图标源集成一selfh.stDashboard Icons 可以从 selfh.st/icons 展示外部图标元数据而无需把图标文件复制进原生集合。7.1 存储模型external_iconsPocketBase 集合负责存储外部图标的 slug、名称、分类、可用格式、变体元数据、jsDelivr URL 模板以及许可证归属信息。外部图标文件保留在 jsDelivr 上遵循以下模式https://cdn.jsdelivr.net/gh/selfhst/icons/format/slug.format集合访问规则为公开只读PocketBase 规则为listRule: 和viewRule: 而 create/update/delete 仅限超级管理员。每一个外部图标卡片与详情页都必须展示Icons by selfh.st/icons (CC BY 4.0)归属声明。7.2 首次导入集合 schema如果external_icons集合尚不存在需要在 PocketBase 管理后台的 Collections 界面导入 web/backend/pb_migrations/1777632695_created_external_icons.js 对应的集合定义README 描述为导入data/sources/selfhst/external_icons.collection.json该 JSON 定义了external_icons的字段、公开 list/view 规则、禁用公开写入以及(source, slug)唯一索引然后再运行导入器。7.3 刷新元数据并导入mkdir -p data/sources/selfhst curl -fsSL https://raw.githubusercontent.com/selfhst/icons/main/index.json -o data/sources/selfhst/index.json curl -fsSL https://raw.githubusercontent.com/selfhst/icons/main/index-consolidated.json -o data/sources/selfhst/index-consolidated.json curl -fsSL https://raw.githubusercontent.com/selfhst/icons/main/tags.json -o data/sources/selfhst/tags.json PB_ADMINadminexample.com PB_ADMIN_PASSyour-password \ NEXT_PUBLIC_POCKETBASE_URLhttp://127.0.0.1:8090 \ bun run scripts/import-selfhst.ts上述命令先下载上游的 manifest 文件到web/data/sources/selfhst/再以超级管理员身份运行 web/scripts/import-selfhst.ts 将元数据导入 PocketBase。该脚本是一个独立的 ETL抽取-转换-加载流程读取 CSV manifest → 转换为external_icons记录 → 按 slug upsert存在则更新、不存在则创建。八、第三方图标源集成二Simple Icons外部目录还收录了 Simple Icons 中的独立品牌图标。8.1 同步机制与元数据保留每周一Monday自动同步解析最新发布的 npm 版本导入版本锁定version-pinned的元数据slug 去重跳过已被 Dashboard Icons 原生集合或其他外部源占用的 slug每条导入记录保留官方 slug、品牌色、来源、使用指南、逐图标许可证元数据以及所有可搜索的别名类别。8.2 渲染与下载详情页会并排展示SVG 与 PNG 卡片对应品牌色、黑色浅色模式与白色深色模式三种变体SVG 由官方 colorable CDN 托管遵循模式https://cdn.simpleicons.org/slug/brand-colorPNG 下载为按需生成的透明 640 × 640 图片由对应官方 SVG 转换而来服务端使用 sharp 完成光栅化参考 web/src/lib/rasterize-svg.ts浏览页与主详情预览直接跟随网站主题浅色模式用黑色、深色模式用白色来源详情页会链接回原始品牌来源与使用指南并把彩色 SVG 送入现有的图标自定义器icon customizer。8.3 许可证说明Simple Icons 集合以CC0-1.0发布但品牌名称与商标仍受其所有者的许可证、商标与使用指南约束README 指向 Simple Icons 官方的 DISCLAIMER 声明作为参考。8.4 本地运行锁定版本导入器PB_ADMINadminexample.com PB_ADMIN_PASSyour-password \ PB_URLhttp://127.0.0.1:8090 SIMPLE_ICONS_VERSION16.28.0 \ bun run scripts/import-simple-icons.ts通过SIMPLE_ICONS_VERSION环境变量指定要导入的 Simple Icons npm 发布版本实现可复现的版本锁定导入。九、外部源架构一处注册全站生效从 web/docs/ADDING_EXTERNAL_SOURCES.md 可以了解到所有外部源共享同一个external_icons集合通过source字段区分来源UI 层遍历EXTERNAL_SOURCE_IDS自动渲染过滤器、徽章与标签——新增一个外部源无需改动任何组件。以下是自动联动的主要环节均为真实源码路径层级文件行为源注册表web/src/constants.tsExternalSourceId联合类型 EXTERNAL_SOURCES配置对象单一事实来源数据层web/src/lib/external-icons.tsfetchAllExternalIcons()按源并行查询 PocketBase 并做内存 TTL 缓存URL 解析web/src/lib/external-icon-urls.ts优先匹配url_templates精确键如png_dark否则回退到{cdnBase}/{format}/{slug}.{format}卡片徽章web/src/components/icon-card.tsx悬停显示来源图标与 from {label} 横幅详情页web/src/components/icon-details.tsx徽章、归属声明、View on 链接、格式/变体区块、SVG 自定义器搜索过滤web/src/components/icon-search.tsx来源过滤下拉框CMDKweb/src/components/command-menu.tsx结果带来源徽章并路由到/icons/external/[slug]浏览页web/src/app/icons/page.tsx合并原生与外部图标副标题动态列出所有来源静态详情页web/src/app/icons/external/[slug]/page.tsxgenerateStaticParams()覆盖所有注册来源Sitemapweb/src/app/sitemap.ts为每个外部图标生成带image标签的 URL 条目统计web/src/lib/api.tsgetTotalIcons()返回按源拆分的sourceCounts架构上采取适配器模式每个外部源 constants.ts配置项 PocketBase 集合 导入脚本 GitHub Actions 定时同步工作流。若你计划为仓库新增一个第三方图标目录web/docs/ADDING_EXTERNAL_SOURCES.md 提供了从常量注册、PocketBase 迁移、导入脚本编写、CI 工作流到 Playwright 测试的完整分步指南并总结了 LobeHub 集成中的经验教训如显式 URL 模板、变体合并、sitemap 去重、认证头透传等。十、部署与贡献部署应用针对 Vercel 做了部署优化web/next.config.ts也可使用仓库自带的 web/Dockerfile 与 web/docker-compose.yml 容器化部署数据库PocketBase 后端与前端一体化迁移文件位于 web/backend/pb_migrations/服务端钩子位于 web/backend/pb_hooks/测试单元测试Vitest覆盖搜索、限流、URL 解析、MCP 工具与分析集成等模块端到端测试Playwright覆盖浏览、过滤与详情页渲染等关键用户路径贡献README 明确欢迎社区提交 Pull Request图标新增流程可参考仓库根目录的 docs/add-icon-workflow.md。结语web/README.md所描绘的 Dashboard Icons Web 应用是图标集合 检索服务 AI 可编程接口 社区协作四位一体的完整产品。对使用者而言它提供了直观的浏览搜索与多格式下载体验对开发者而言其 MCP 服务端让任何 AI 客户端都能通过四个标准工具直接消费图标元数据对贡献者而言外部源适配器模式让新增图标目录变得声明式、可复用。结合 web/docs/MCP.md 与 web/docs/ADDING_EXTERNAL_SOURCES.md 两份深度文档即可将该应用扩展为你自己的 dashboard 图标基础设施。【免费下载链接】dashboard-iconsYour definitive source for dashboard icons.项目地址: https://gitcode.com/GitHub_Trending/da/dashboard-icons创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考