ITADN
fleek-platform/website
代码 动态 Issues 合并请求581 版本
fleek-platform/website · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

⚡️Fleek.xyz 网站

Conventional Commits

本仓库包含 Fleek.xyz 网站的源代码和资源，该网站使用 Astro.js 框架 构建，以实现增强的性能和速度。该项目利用 Tailwind CSS 进行样式设计，提供现代且响应式的设计，并使用 TypeScript 确保类型安全和可扩展性，从而保证代码库的健壮性和可维护性。

📒 内容

安装

⚙️ 要求

  • Nodejs + Bun
  • NPM, Yarn or PNPM
  • 一些 CLI 经验
  • Docker（可选，如果你想在本地运行搜索服务器）

按照此处的说明学习如何在你的操作系统中安装 NodeJS，以及按照此处的说明安装 Bun。

🤖 安装

在你的本地环境中安装项目依赖。

npm install

👷‍♀️开发

启动一个用于开发工作的本地 HTTP 服务器。它支持热重载，因此每次保存文件时你都能看到你的编辑：

npm run dev

环境变量

如果你将与服务进行交互，则需要设置环境变量。

创建一个名为 .env 的本地文件，并声明以下内容

PUBLIC_MEILISEARCH_HOST=https://meilisearch-prod-eu-lon-1-01.flkservices.io
PUBLIC_MEILISEARCH_INDEX_BLOG="fleekxyz_website_blog"
PUBLIC_MEILISEARCH_INDEX_DOCS="fleekxyz_website_docs"
PUBLIC_MEILISEARCH_INDEX_GUIDES="fleekxyz_website_guides"
PUBLIC_MEILISEARCH_INDEX_REFERENCES="fleekxyz_website_references"
PRIVATE_MEILISEARCH_MASTER_KEY=***
PRIVATE_MEILISEARCH_DOCUMENTS_ADMIN_API_KEY=***
PUBLIC_MEILISEARCH_DOCUMENTS_CLIENT_API_KEY=***
PUBLIC_SUPPORT_API_HOST="support-prod-eu-lon-1-01.flkservices.io"
SUPPORT_ALLOW_ORIGIN_ADDR="http://localhost:4321,https://fleek.xyz"
SUPPORT_RATE_LIMIT_WINDOW_MINUTES=60
SUPPORT_RATE_LIMIT_MAX_REQ=15
SUPPORT_RATE_LIMIT_PATHS="/tickets"
NODE_ENV=develop
PUBLIC_BEHIIV_API_KEY=***
PUBLIC_BEHIIV_SUBSCRIBE_URL=***
PUBLIC_BEEHIIV_PROXY_SERVER_URL=***
PUBLIC_GRAPHQL_ENDPOINT="https://graphql.service.fleek.xyz/graphql"
PUBLIC_DYNAMIC_ENVIRONMENT_ID="de23a5f0-aaa5-412e-8212-4fb056a3b30d"
PUBLIC_APP_HOSTING_URL="https://fleek.xyz/dashboard"
PUBLIC_APP_AGENTS_URL="https://fleek.xyz/agents"
PUBLIC_APP_ELIZA_URL="https://eliza.fleek.xyz"
PUBLIC_APP_NEW_HOSTING_URL="https://hosting.fleek.xyz"
PUBLIC_APP_RESOURCES_URL="https://resources.fleek.xyz"
PUBLIC_POSTHOG_HOST="https://us.i.posthog.com"
PUBLIC_POSTHOG_API_KEY="phc_SdvLWEagL7nAauyEBun0ZF6v59DxMIk8ofzI91gpIUw"
PUBLIC_OPEN_API_ENDPOINT="https://api.fleek.xyz/api/openapi.json"
PUBLIC_FLEEK_WEBSITE_URL="https://fleek.xyz"
PUBLIC_PERSONA_GENERATOR_API_URL="https://persona-generator.flkservices.io"

💡 SUPPORT_ALLOW_ORIGIN_ADDR 和 SUPPORT_RATE_LIMIT_PATHS 是逗号分隔的值（csv）。在查询 staging、production 环境时，需要提供 MEILISEARCH_DOCUMENTS_CLIENT_API_KEY，该值应包含在请求头中。

🏗️ 构建

运行构建命令以创建发行版本。默认情况下，文件将保存在 /dist 目录中。

npm run build

💡 默认情况下，开发服务器可在地址 http://localhost:4321 访问。

调整环境设置（src/settings.json），例如站点 URL。声明值为 prod 或 production 的 NODE_ENV 以切换环境目标设置。

或者，您可以跳过构建检查并仅构建资源：

npm run build:static_assets

请注意，Fleek 网站在其分布式文件中托管单页应用程序。每次构建时，请确保已运行 npm install，以确保在构建之前完成包及相关副作用！

要了解更多信息，请阅读 单页应用程序设置。

单页应用程序设置 (SPA)

应用程序 Agents-UI 和 Hosting dashboard 托管在与站点相同的域名下。

截至撰写本文时，Fleek 的站点基于静态站点生成器 (SSG)，而应用程序是单页应用程序 (SPA)。

未来，我们可以预期会有一些中间件（一个 HTTP 代理，用于将请求路由到特定应用程序或回退到站点）。但目前，我们通过站点的分发来提供应用程序，这是静态完成的。

Agents 和 Dashboard SPA 通过包版本安装在站点中。我们的托管站点可以覆盖并发环境（例如 staging）的预构建环境变量。

有一个 npm install 钩子为您处理该过程，例如，将 SPA 包的分发文件复制到本地并设置环境变量覆盖。

[!IMPORTANT]
在更新 SPA Agents-UI 或 Dashboard 时，运行 "npm install" 命令至关重要。原因是 npm install 钩子仅在 install 时发生，而不在 install 时发生。

SPA 放置在 astrojs public 目录中，当 astro build 发生时，它会将应用程序复制到分发中，例如 out 目录。

因此，SPA 的路径 /agents 和 /dashboard 是保留的；这些路径不作为 SSG 目录或文件提供服务，而是路由到 SPA 基础路径。这意味着，当对 /agents 发起请求时，它会路由到 /agents/index.html，然后由应用程序运行时路由器解析，例如可能由于重定向设置。

理解应用程序中静态路由发生的过程非常重要。您可以使用 build preview 在本地进行测试。

本地预览

预览服务器是一个用于本地测试的自定义静态站点生成器 (SSG) HTTP 服务器，不用于生产环境。其目的是处理 SSG 项目主机站点，以及在该域名下提供的应用程序，其保留路由为 /agents 和 /dashboard。您可以阅读 此处 了解有关站点中单页应用程序设置方式的更多信息。

您可以通过启动预览 HTTP 服务器在本地预览分发构建：

npm run preview

🤖 Server running at http://localhost:3002
🚀 SPA routes configured are /agents, /dashboard

💡 默认情况下，本地站点将在地址 http://localhost:3002 可用。你可以通过声明环境变量 DEV_PREVIEW_PORT 和所需的端口号来覆盖它。

如果你正在本地测试，你可能有兴趣调整你的环境变量为：

PUBLIC_APP_HOSTING_URL="http://localhost:3002/dashboard"
PUBLIC_APP_AGENTS_URL="http://localhost:3002/agents"
PUBLIC_APP_ELIZA_URL="http://localhost:3002/docs/ai-agents"
PUBLIC_APP_NEW_HOSTING_URL="http://localhost:3002/docs/platform"
PUBLIC_APP_RESOURCES_URL="http://localhost:3002/docs"

请注意，preview 是一个感知站点托管应用程序的自定义进程。它不支持 Astrojs 预览器功能！相反，这是一个用于本地目的、支持单页应用程序的自定义 HTTP 服务器。要了解更多信息，请阅读 Single page applications setup。

如果您正在寻找 Astrojs 默认预览，其可用形式为：

npm run preview:astro

👀 预览 staging

你可以通过访问此处](https://fleek-xyz-staging.fleeksandbox.xyz)预览 develop 分支的版本。

🎀 代码格式化器

通过执行以下命令即可使用代码格式化器：

npm run fmt

更改将写入文件。或者，您可以通过运行 dry-run 来执行代码格式检查，该操作不会对文件进行更改：

npm run fmt:check

更新外部应用

该网站托管外部静态应用，例如 Dashboard。

要安装特定版本，请选择一个 prerelease 版本。

npm install -E @fleek-platform/dashboard@prerelease

或者，更具体地说：

npm install -E @fleek-platform/dashboard@0.9.1-rc.d996275

在生产环境发布时，-rc* 后缀会被移除，应用程序将部署生产版本。

🙏 贡献指南

从 develop 分支创建分支，并按照 conventional commits 的规范命名，参见此处。

以下是一个示例：

test: 💍 Adding missing tests
feat: 🎸 A new feature
fix: 🐛 A bug fix
chore: 🤖 Build process or auxiliary tool changes
docs: ✏️ Documentation only changes
refactor: 💡 A code change that neither fixes a bug or adds a feature
style: 💄 Markup, white-space, formatting, missing semi-colons...

了解更多关于贡献的信息 TODO:OPEN-SOURCE-CONTRIBUTION-DOC，请！

🎓 说明

常见任务的说明。

📝 博客

🚩新文章

博客文章组织为一个目录，该目录应包含所有必要的图像资源。

目录应以 slug 命名，slug 是系统友好的名称，例如 "My short title" 将变为 "my-short-title"。此外，包含所有文本的 markdown 文件名应命名为 "index.md"。

例如，假设创建一个名为 "My Blog post" 的假设博客文章。

1) 在 src/content/blog 位置创建具有相应 slug "my-blog-post" 的目录，如下所示：

src/content/blog/my-blog-post

2) 在该目录中创建名为 "index.md" 的文件。

src/content/blog/my-blog-post/index.md

“index.md” 是一个 Markdown 文件，用于存储文本内容和故事。

3) 设置 “index.md” 的 Markdown 头部值，包括标题、类别、日期等

---
title: My Blog post
slug: my-blog-post
category: Announcements
date: 2024-01-31
desc: A short description about my blog post
thumbnail: './thumbnail.jpg'
image: './main-image.jpg'
author: 'Fleek'
---

4) 编写内容，包括任何图像引用

---
title: My Blog post
slug: my-blog-post
category: Announcements
date: 2024-01-31
desc: A short description about my blog post
thumbnail: './thumbnail.jpg'
image: './main-image.jpg'
author: 'Fleek'
---

Dive into a world of concise knowledge and thought-provoking ideas. Whether you're a seasoned reader or a curious newcomer, this blog post promises to captivate your mind and leave you pondering long after you've finished reading. So grab your favorite beverage, find a cozy spot, and let's explore together!

## My subtitle 1

In the world where text is text, I show you an image:

![My image](./my-image.jpg)

💡 想要放置静态视频内容？了解如何处理视频内容，请参见此处。

🚩链接页面的新博客图片

前往文件 src/settings.json 并将以下行更改为您想要展示的文章的 slug：

  "linksPage": {
    "featuredPostSlug": "announcements/introducing-fleek-edge-sgx"
  }

📝 Docs

在 Docs 部分创建文档与 Blog 类似。请按照 blog 的说明学习如何创建文档。

编辑菜单和侧边栏至关重要。这些元素是访客的主要导航，引导他们浏览您的内容。

要重新排序菜单项，请编辑位于 src/settings.json 的设置文件中的 docs -> menu -> order 部分。

以下是一个示例，我们通过指定类别名称和顺序数值来对 accounts、projects 和 storage 类别进行排序。如果您未进行排序，系统将回退到按字母顺序或随机排序。

"docs": {
  "menu": {
    "order": [
      {
        "category": "accounts",
        "order": 1,
      }, {
        "category": "projects",
        "order": 2,
      }, {
        "category": "Storage",
        "order": 3,
      }
    ]
  }
}

💡 在上面的示例中，类别是“目录”，而内容文档（.md 文件）具有一个数值 order 值，该值在排序侧边栏项时也会被计算。例如，src/content/docs/index.md 是落地页文档，而 src/content/Accounts 是一个包含一个或多个 markdown 文档的目录。

📠 覆盖类别标题

你可以覆盖文档侧边栏的标题，但由于内容自动化流程生成最终 URL 等方式，不建议这样做。我们应优先遵循约定而非配置！

假设你有以下目录名称：

├── CLI
│   ├── Applications
│   └── verify-domain.png
├── My-Menu-Item
│   ├── index.mdx
│   └── Sites
└── index.mdx

假设您希望将名称 "My-Menu-Item" 覆盖为 "Custom name"。

您需要在 src/settings.json 文件中定位 docs -> customTitlesByDirectoryName 字段，并声明一个新的属性名称及其值，例如 "My-Menu-Item" 和 "Custom Name"，如下所示：

"docs": {
  "menu": {
    "customTitlesByDirectoryName": {
      "My-Menu-Item": "Custom name"
    }
  }
}

不建议这样做，因为最终 URL 将包含原始目录名，例如 https://fleek.xyz/docs/my-menu-item 而不是 https://fleek.xyz/docs/custom-name。

考虑到目录名的规范化约定，更建议将原始目录重命名为 "custom_name"。

├── CLI
│   ├── Applications
│   └── verify-domain.png
├── Custom_name
│   ├── index.mdx
│   └── Sites
└── index.mdx

💡 请注意，下划线（_）在默认人性化处理时会被替换为空格。破折号会被保留以符合术语或名称，例如 "pre-release"。

🥷 创建 Pull request

你可以通过编程方式或使用 GitHub 网页界面来创建 PR（pull request）。

为了创建 pull request（PR），你必须理解该项目具有文件结构架构，包含组件、图像、样式表等的源文件。

在我们的示例中，我们将创建新内容。内容放置在 src/content 目录中，用于博客或文档。

以下是如何使用 GitHub 网页界面创建新的博客文章内容：

1) 在 GitHub 文件资源管理器中导航内容源文件 (src/content)

src/content/blog
├── announcements
├── changelog-march-11
│   ├── fleekchangelog01mar11.png
│   └── index.md
└── fleek-release-notes-v004
    ├── Log-in-connections.png
    ├── fleekreleasenotes06.jpg
    └── index.md

4 directories, 5 files

2) 展开已折叠的文件树

点击文件树图标以展开它。

File tree

展开后，您应该能看到文件树。

File tree expanded

3) 创建分支

点击下拉菜单并输入一个新名称。请确保遵循贡献指南中的命名约定。

例如，在图中我们看到创建了一个名为 docs/my-new-branch 的分支

New branch

点击“从 develop 创建分支 docs/my-new-branch”。

4) 为帖子内容文件创建目录

要在仓库中创建新目录，请单击“create a new file”。在输入文件名的区域输入新目录的名称，并在文件名末尾输入“/”以将其初始化为目录。之后，您可以在该目录中创建新文件。

Create directory

5) 创建 "index.md"

输入新文件名 "index.md"。

Create new file

6) 提交更改

输入一条简短的提交信息，遵循贡献指南，例如：

docs: ✏️ Created document in post directory

如果您愿意，您可以在“扩展描述”中添加更多详细信息。

选择“直接提交到 docs/my-new-branch 分支”选项，并按下“提交更改”进行提交。

7) 点击文件名以打开它

Click filename to open

8) 点击选项 "Edit this file" 进行编辑

在窗口右侧，找到铅笔图标并点击它以开始编辑文件。

Edit this file

9) 开始向文件添加内容

向文件添加内容。例如，这里我们添加了 Markdown 标题和一些文本。

---
title: "Put a title here"
slug: "put-a-title-here"
category: "Name of category"
date: 2024-03-11
desc: "A short description"
thumbnail: "./a-local-image.png"
image: "./a-local-image.png"
author: "Your name"
---

The content goes here

阅读 New post 部分以了解更多信息。

10) Commit your changes

每次有新的更改时，你都可以提交它。它会将更改存储在你创建的仓库分支中。

11) Once happy create a pull request

你可以通过访问 compare 来创建一个 pull request。

使用第二个下拉框选择你刚刚为你的帖子内容创建的分支名称。

Use compare to create a new pull request

按下 "Create pull request" 并通过提供 pull request 的标题和描述来填写以下字段。

要完成，请选择 "Create pull request"。

Pull request form

🚀 发布到生产环境

您可以按照线性策略发布到生产环境。这假设 "main" 分支遵循线性历史约定，并且是 "develop" 分支提交历史的子集。例如，团队乐于将 "develop" 作为项目最新版本所在之处，并且 "main" 不应分叉，仅包含来自 "develop" 的提交。

用例示例：

  • 团队已将一些功能分支合并到 develop 中，其提交哈希标识为 "abc123"，并希望将提交历史哈希 "abc123" 之前的内容发布到 "main"。通过这样做，他们期望构建过程发生并部署到 Fleek Platform
  • 团队已将多个功能分支按此历史顺序合并到 develop 中，其提交哈希标识为 commitFeat1、commitFeat2 和 commitFeat3。已决定发布直到 commitFeat1 的所有提交历史，但不包括 commitFeat2 和 commitFeat3。不过，更明智的做法是将功能分支保持在待定状态，因为 "develop" 应始终处于可测试和可发布的就绪状态，因为团队可能希望发布一些快速的热修复等

要发布到生产环境，请打开 此处 的操作选项卡。

在左侧边栏中选择 "🚀 Release by develop hash" 作业。接下来，选择 "Run workflow" 下拉菜单并提供所需详细信息。

🧐 拼写检查器（语法）

拼写检查器将验证 markdown (.md, .mdx) 文件内容中的任何拼写错误。拼写检查器是一个自动化过程，在拉取请求 (PR) 期间处于活动状态。

在 Github 拉取请求（PR）仪表板中，找到位于对话选项卡最底部的 checks 组件下的拼写检查器（spell checker）。要了解有关拼写检查流程的更多信息，请打开“details”。

它应该类似于以下内容：

Locate the spell checker in CI/CD

公告

公告跑马灯

公告跑马灯放置在网站的最顶部。要启用

  1. 打开位于 /src/settings.json 的配置文件。
  2. 在 "site" 下找到 announcementMarquee
"site": {
  ...
  "announcementMarquee": {
    "message": "Introducing Fleek Functions: lightning-fast edge functions built on Fleek Network’s onchain cloud infrastructure. Read more here.",
    "url": "/blog/announcements/introducing-fleek-functions",
    "visible": true
  },
  ...
}
  1. 编辑消息和 url
  2. 将 "visible" 设置为 true

公告模态框

公告模态框是一个可定制的弹出窗口，可以显示在整站或特定页面上。它支持关闭跟踪，以避免向已关闭该公告的用户重复显示相同的公告。

配置

  1. 打开位于 /src/settings.json 的配置文件。
  2. 在 "site" 下找到 announcementModal 部分：
"site": {
  ...
  "announcementModal": {
    "generic": {
      "visible": false,
      "title": "Announcement Modal title",
      "message": "Announcement Modal message. Lorem ipsum dolor sit amet",
      "button": "Button label"
    },
    "perPath": [
      {
        "visible": true,
        "title": "Announcement Modal on Eliza",
        "message": "Announcement Modal message on Eliza. Lorem ipsum dolor sit amet",
        "button": "Button label on Eliza",
        "path": "/eliza"
      }
    ]
  },
  ...
}

使用选项

公告模态框设置

每个模态框条目具有以下属性：

  • id: (可选) 用于唯一标识模态框的 String - 对于识别用户已关闭或未关闭的模态框至关重要
  • visible: 用于控制显示的 Boolean
  • title: 显示为模态框标题的 String
  • message: 显示为模态框正文的 String
  • button: 显示为模态框按钮标签的 String
  • expiresInDays: (可选) 模态框被关闭后应再次显示的天数 Number
  • modalDelayInSeconds: (可选) 模态框应显示后的秒数 Number
  • path: (在 perPath 上必填) 模态框应出现的 URL 路径 String (支持部分匹配)
全站模态框

要在整个站点显示模态框：

  1. 定位 settings.json 的 announcementModal 的 generic 属性
  2. 配置 模态框的结构

:::warn 通用模态框优先于特定路径的模态框 :::

特定路径模态框

要在特定页面上显示模态框：

  1. 向 perPath 数组添加条目
  2. 每个条目应采用 模态框的结构

Agents 管理通知

Agents 应用可以为所有用户显示管理通知。管理团队可以提供原始文本消息并切换 enabled 属性。一旦设置被修改，必须部署网站才能在 Agents 应用消费的静态 API 中反映这些更改。

要了解如何消费它，请阅读 此处

自定义管理员通知

打开 settings.json 并定位属性 agentsAdminNotification。

"agentsAdminNotification": {
  "authenticatedUsers": {
    "message": "When we have capacity to deploy new AI agents you will be first in line. Please try again later!",
    "enable": false      
  },
  "default": {
    "message": "We're currently over capacity and unable to deploy new AI agents. Sign in now to save time and try again later!",
    "enable": false
  }
}

创建一个新 PR，使其获得批准、合并、测试，如果满意则发布。

行为

  • 模态框在 5 秒延迟后出现
  • 当用户关闭模态框时，7 天内不会再次出现
  • 通用和特定路径的关闭操作分别跟踪
  • 特定路径的关闭操作仅适用于该特定路径

🎯 提示框

提示框的概念常用于文档和内容创作中，以独特的方式突出显示重要说明、警告、提示或其他类型的信息。

以下是在 markdown 内容（例如文档文章）中创建提示框的语法：

:::note
This is a note
:::

:::success
This is a success
:::

:::warn
This is a warning
:::

:::danger
This is a danger
:::

:::info
This is a info
:::

To learn more read the directives here

导航栏

🎰 配置

主导航栏可以通过编辑位于 src/components/NavBar/config.ts 的文件进行配置。

每个菜单项由一个具有以下属性的对象表示：

  • label: 一个字符串，定义菜单项显示的文本。
  • url: 一个字符串，指定点击菜单项时要导航到的 URL。
  • open in new tab (optional): 一个布尔值（true 或 false），决定链接是否在新浏览器标签页中打开。

基本菜单项的示例：

{
 "label": "Blog",
 "url": "/blog",
 "openInNewTab": true
}

对于更复杂的菜单，您可以包含子菜单。子菜单由一个包含 label 和 items 数组的对象定义，该数组包含一个菜单项列表。

带有子菜单的菜单项示例：

{
 "label": "Products",
 "items": [
    {
      "label": "Product A",
      "url": "/products/a"
    },
    {
      "label": "Product B",
      "url": "/products/b"
    }
 ]
}

菜单配置分为两个主要部分：main 和 side。这两个部分都是包含表示菜单类别的对象的数组。每个类别对象可以包含一个 label 和一个 items 数组，类似于上述子菜单示例。

  • main：此部分用于主要菜单项。它是一个类别对象数组。
  • side（可选）：此部分用于次要或附加菜单项。它遵循与 main 部分相同的结构。

包含 main 和 side 部分的菜单配置示例：

{
 "main": [
    {
      "label": "Products",
      "items": [
        {
          "label": "About Us",
          "url": "/about"
        }
      ]
    },
    {
      "label": "Resources",
      "items": [
        {
          "label": "Templates",
          "url": "/templates"
        }
      ],
    },
 ],
 "side": [
    {
      "label": "Protocols",
      "items": [
        {
          "label": "Fleek Network",
          "url": "https://fleek.network",
          "openInNewTab": true,
        }
      ]
    }
 ]
}

除了主菜单和侧边菜单，你还可以定义一个 Call to Action (CTA) 项目列表。这些通常用于促销或重要操作。每个 CTA 是一个包含 label 和 url 的对象。

CTA 配置示例：

{
 "ctas": [
    {
      "label": "Sign Up",
      "url": "/signup"
    }
 ]
}

在配置菜单时，请确保对象的结构和属性符合所提供的指南。这有助于保持一致性，并确保菜单正确显示。请记住，菜单的外观受您使用的样式或组件的限制，因此请相应地调整配置或业务逻辑。

元数据

元数据对于搜索引擎、社交媒体平台及其他方理解页面的内容和目的至关重要。

元数据的主要位置位于页面主基础布局的 head 元素中。在撰写本文时，它位于 src/layouts 中的 BaseHtml.astro：

src/layouts
├── ...
└── BaseHtml.astro

您将在 HTML 文档的 HEAD 部分中找到这些元素。例如：

...

<head>
    ...

    <meta property="og:url" content={`${baseUrl}/${ogMeta?.slug || ''}`} />
    <meta property="og:type" content="website" />
    <meta
      property="og:title"
      content={ogMeta?.title || settings.site.metadata.title}
    />

    ...

    <meta
      name="twitter:title"
      content={ogMeta?.title || settings.site.metadata.title}
    />

    ...
</head>

HTML 元数据的关键组件之一是 Open Graph meta 标签，最初由 Facebook 创建，以使其能够在社交图谱中成为富对象。

通过使用 Open Graph meta 标签，您可以控制网站链接在 Facebook、Twitter、LinkedIn 等社交媒体平台上分享时的显示方式。

Open Graph 预览

要发现社交媒体平台如何感知站点页面，请使用 meta 标签预览器。

例如，假设您想预览“Introducing Fleek Functions”的博文。您可以复制 URL https://fleek.xyz/blog/announcements/introducing-fleek-functions 并将其粘贴到您首选的预览器地址中，例如 opengraph.xyz。

排查 Open Graph 问题

需要注意的是，如果您遇到 Open Graph meta 标签在某个平台上未正确显示的问题，第一步应该是使用验证工具，类似于上述 URL 中提供的工具。这是因为我们的系统会自动提供元数据内容，但如果平台忽略了某些要求（例如，持久缓存），可能会出现差异。此外，如果特定 URL 因先前的问题而出现问题，您可以通过在 URL 末尾添加查询参数来绕过缓存。例如，将 https://fleek.xyz/blog/announcements/introducing-fleek-functions 修改为 https://fleek.xyz/blog/announcements/introducing-fleek-functions?202406101836。建议将此方法作为初步故障排除步骤，以识别问题来源。

自定义博客分类

您可以通过编辑 [./src/settings.json] 中的设置文件来自定义博客分类列表页的元数据字段。

"blog": {
  ...
  "category": {
    "category-name-here": {
      "title": "My title",
      "description": "My description"
    }
  }

您可以使用任何类别名称扩展 category 字段。请注意，类别名称应与系统名称或目录名称匹配，例如 announcements。

"blog": {
  ...
  "category": {
    "announcements": {
      "title": "Announcements",
      "description": "The announcements description"
    }
  }

模板

本节提供有关在系统中管理和验证模板的指导。

管理模板

管理模板涉及向系统中添加、更新和删除模板。请按照以下步骤有效管理模板：

  • 添加模板：

    • 在 src/templates.json 中克隆现有模板并添加所有必需字段。
    • 确保所有必要的资源（例如横幅图片、图标）放置在正确的目录中。

  • 更新模板：

    • 在 src/templates.json 中定位现有的模板条目。
    • 更新必要的字段，例如描述或 URL。
    • 根据需要替换或更新任何关联的资源。

  • 删除模板：

    • 从 src/templates.json 中删除模板条目。
    • 从文件系统中删除所有关联的资源。
    • 更新系统中其他部分对该模板的任何引用。

验证模板

  • 构建项目以确保没有构建问题。
  • 运行本地开发服务器进行预览
  • 验证模板出现在列表中且所有资源正确加载。
  • 确保所有链接（例如演示、部署）功能正常。
  • 确认过滤和相似模板显示正确。

👷‍♀️开发

服务

项目服务遵循以下命名约定：

<service-type>-<environment>-<region>-<instance-number>.<domain>

支持

支持服务基于 ZenDesk，作为一个提供 API 以与服务交互的外部提供商。以下文档提供了与代理服务器交互的信息。

设置服务

应用程序应从名为 PUBLIC_SUPPORT_API_HOST 的环境变量中获取端点 URL。

通过阅读 环境变量 部分了解如何设置。

令牌

环境应为相应的账户设置以下变量。

您可能希望创建一个 .env 文件来保存这些环境变量，或者在您的 shell 配置文件中设置。

PRIVATE_ZENDESK_EMAIL="xxxx"
PRIVATE_ZENDESK_API_KEY="xxxx"
PRIVATE_ZENDESK_HOSTNAME="xxxx"

⚠️ 正在设置 ZenDesk 代理服务？有关 ZenDesk 代理服务的更多信息，请参见此处

本地 API

有一个可用于与 ZenDesk 交互的代理服务，并且可以在本地运行。

通过运行以下命令启动本地 API：

npm run support:local_api

💡 在实现过程中，API URL 应作为环境变量提供。

与 API 交互

/health

访问 /health 端点进行健康检查

curl -X GET 'localhost:3331/health

/ticket

调用 /ticket 端点，为用户 email、特定 topic 和评论 query 创建工单。

curl \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "email=<CLIENT-EMAIL-ADDRESS>&subject=<SYSTEM-TOPIC>&comment=<USER-QUERY>"" http://localhost:3331/ticket

email 是一个有效的电子邮件地址，topic 应与 query 模板相关。query 应对应且为一种众所周知的格式或模板。

以下是 query 模板的示例：

subject: <System Support Topic> | <User title>
description: <User text>
attachments: <User attachments>

结果票据可能如下所示：

subject: Billing | Inquiry Regarding Unprocessed USDC Token Transfer
description: Dear Fleek, I hope this message finds you well. I am writing to seek clarification regarding an outstanding transaction related to my account. On xxx, I initiated a transfer of xxx USDC tokens from my account to xxx. However, upon checking my transaction history, it appears that this transfer has not been processed.
attachments: https://fleek-storage/user-file.png

生产服务配置

支持服务的主机名为 support-prod-eu-lon-1-01.flkservices.io（端点 URL）。

应设置生产环境变量。声明主机名：

PUBLIC_SUPPORT_API_HOST="https://support-prod-eu-lon-1-01.flkservices.io"

服务文件的默认位置是 /lib/systemd/system/support-prod-eu-lon-1-01.flkservices.io.service。

要在云托管实例中通过环境变量配置 Support，请修改 Support 的 env 文件。其默认位置是 ~/fleek-platform/website/.env。

编辑完配置选项后，重新加载守护进程：

sudo systemctl daemon-reload

重启服务：

sudo systemctl restart support-prod-eu-lon-1-01.flkservices.io.service

检查状态：

sudo systemctl status support-prod-eu-lon-1-01.flkservices.io.service

⚠️ 正在排查 ZenDesk 的代理问题？点击此处]了解更多。

🔎 搜索

搜索服务基于 Meilisearch here]。

搜索服务的主机名为 meilisearch-prod-eu-lon-1-01.flkservices.io。服务文件的默认位置为 /etc/systemd/system/meilisearch.service。

要在云托管实例中通过环境变量配置 Meilisearch，请修改 Meilisearch 的 env 文件。其默认位置为 /var/opt/meilisearch/env。

DNS 记录

A	meilisearch-prod-eu-lon-1-01.flkservices.io	165.232.41.164

编辑完配置选项后，重新启动 Meilisearch 服务：

systemctl restart meilisearch

健康检查

curl \
  -X GET 'http://localhost:7700/health'

否则：

curl \
  -X GET '<PROTOCOL>://<ADDRESS>:<PORT>/health'

Indexer

Indexer 的工作被称为索引化，是指以结构化方式组织和存储数据，以便高效搜索和检索的过程。

Put markdown content (Development)

如果你通过 Docker 容器运行搜索服务器，则必须对数据进行索引。

通过运行以下命令提供数据：

npm run search:index_all

通过 cURL 查询

使用 cURL 是查询服务器的一种快速方式。

在以下示例中，我们在本地服务器上查询索引名称为 blog 的 changelogs，该服务器运行在端口 7700 上。

curl "localhost:7700/indexes/blog/search?q=changelogs"

否则，对于生产服务器：

curl \
  -X POST '<PROTOCOL>://<ADDRESS>:<PORT>/indexes/<INDEX_NAME>/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>' \
  --data-binary '{ "q": "<SEARCH_QUERY>" }'

多索引搜索

以下是如何在单个或多个索引上执行多个搜索查询的示例：

curl \
  -X POST 'http://localhost:7700/multi-search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "queries": [
      {
        "indexUid": "fleekxyz_website_docs",
        "q": "something",
        "limit": 5
      },
      {
        "indexUid": "fleekxyz_website_guides",
        "q": "something",
        "limit": 5
      },
      {
        "indexUid": "fleekxyz_website_references",
        "q": "something",
        "limit": 5
      }
    ]
  }'

💣 删除索引

运行以下命令删除索引数据：

npm run search:delete_indexes

Serve（开发）

搜索由 Meilisearch 提供。本地搜索服务器以 Docker 镜像的形式提供，您需要安装并运行它。

您可以通过运行以下命令在本地启动服务器：

npm run search:serve

⚠️ 您会看到一条警告信息“未找到主密钥”，在本地环境开发工作中可以忽略此信息。如果出于某种原因您希望拥有主密钥，请修改 search:serve 脚本以包含它。

手动索引（CI/CD）

索引服务应在 push 到 main 分支上触发。或者，仓库管理员可以手动触发该作业。

  1. 在此处打开作业运行器

  2. 找到“This workflow has a workflow_dispatch event trigger.”这一行，并打开 Run workflow 下拉菜单。在“Use workflow from”选项中，选择 main 分支。

该作业将索引所选 main 分支中存在的 数据。了解如何发布到生产环境（main 分支），请参见此处。

📸 图片（优化）

构建过程可以优化图片，但这要求用户使用正确的图片组件。请使用提供的说明来优化图片。

Beehiiv 代理

通过向以下端点发送 HTTP POST 请求来创建新订阅：

https://faas-lon1-917a94a7.doserverless.co/api/v1/web/fn-5aaf2a72-1b
5b-4ac6-8c42-a2e735a32d8b/main/create-subscription

这是一个示例：

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
});

const result = await response.json();

console.log(result);

了解更多，请参见此处。

🪐 Astro

对于 astro 组件（.astro），请执行以下操作：

---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="A bird sitting on a nest of eggs." />

要了解更多信息，请阅读此处

🎁 Reactjs

在可能的情况下，本地图片会保留在 src/images 中，以便构建过程能够对其进行转换、优化和打包。/public 目录中的文件总是按原样提供或复制到构建文件夹中，不进行任何处理。

导入图片时，必须提供诸如宽度、高度和格式等查询参数。这些设置由构建过程用于生成优化后的图片。此外，优化器不支持 Typescript，这意味着你必须使用 // @ts-ignore 来忽略导入行。

导入名称约定为驼峰式命名法，并使用前缀 img，例如 imgMyImage。

// @ts-ignore
import imgFleekLogo from '@images/globe-with-bolt.jpg?w=480&h=480&format=webp';

将图片放置在 source 字段中：

<img src="{imgFleekLogo}" alt="Image text replacement" />

要生成响应式图像，例如 SrcSet:

// @ts-ignore
import avif from '@images/example.jpg?w=500;900;1200&format=avif&as=srcset';
// @ts-ignore
import webp from '@images/example.jpg?w=500;900;1200&format=webp&as=srcset';
// @ts-ignore
import fallback from 'example.jpg?w=700';

const html = `<picture>
    <source srcset="${avif}" type="image/avif" />
    <source srcset="${webp}" type="image/webp" />
    <img src="${fallback}" />
</picture>
`;

了解更多，请参见此处

🤖 迁移

迁移 Gatsby 内容

本节提供了关于如何执行脚本以将 Markdown 文件从一个位置迁移到另一个位置的详细说明。该脚本旨在根据从文件内容中提取的类别，将 Markdown 文件组织到结构化的目录中。

要执行该脚本，您需要传递两个参数：源路径和目标路径。源路径是您的源 Markdown 文件所在的位置，目标路径是您希望迁移后的文件放置的位置。

使用示例：

./scripts/migration/blog_content_from_gatsby \
  ../gatsby-blog/src/posts/post \
  ./src/content/blog

自定义数据

自定义数据以静态数据的形式提供。该数据由一个静态文件端点提供，放置在 /api 目录内。

请注意，自定义数据是静态的，因为该项目是完全静态的（这意味着数据是预先计算好的，而不是在运行时动态生成的），但它可以像其他任何端点一样被外部应用程序使用。例如，Fleek Platform 应用程序仪表板需要最新的博文数据。

获取最新博文

针对目标环境（例如 production）的路径 /api/latestBlogposts.json 发起 HTTP GET 请求，例如 https://fleek.xyz。

在示例中，我们发起 HTTP GET 请求，并将 解析 响应体文本为 JSON 数据。

const res = await fetch('https://fleek.xyz/api/latestBlogPosts.json');
const json = await res.json();

console.log(json);

你将获得一个用于迭代的列表，如下所示：

{
  data: [
    {
      date: "1972-01-01",
      path: "/blog/my-category/my-blog-post-1",
      title: "My title 1",
      description: "My description 1"
      slug: "my-title-1"
    },
    {
      date: "1972-01-02",
      path: "/blog/my-category/my-blog-post-2",
      title: "My title 2"
      description: "My description 2"
      slug: "my-title-2"
    },
    ...
  ]
}

每次构建发生时，静态 JSON 数据都应更新。

获取 Agents UI Admin 通知

针对目标环境（例如 production 为 https://fleek.xyz）向路径 /api/agentsAdminNotification.json 发起 HTTP GET 请求。

在示例中，我们发起 HTTP GET 请求并 解析 响应体文本为 JSON 数据。

const res = await fetch('https://fleek.xyz/api/agentsAdminNotification.json');
const json = await res.json();

console.log(json);

您将获得类似的响应：

{
  "authenticatedUsers": {
    "message": "When we have capacity to deploy new AI agents you will be first in line. Please try again later!",
    "enable": false
  },
  "default": {
    "message": "We're currently over capacity and unable to deploy new AI agents. Sign in now to save time and try again later!",
    "enable": false
  }
}

每次构建发生时，静态 JSON 数据都应更新。

视频内容

将视频内容相对于内容放置。由于可移植性，我们必须将其保持在内容的上下文中。在撰写本文时，Astro 不优化视频，并建议将这些文件放置在 public 目录中，这将破坏可移植性要求。

💡 视频应针对 Web 进行优化。保持简短。在撰写本文时，最大视频文件大小为 6 MB。如果较长，更建议在 YouTube 或类似平台上分发。

为了缓解这一问题，Fleek Website 构建流程包括对视频文件（mp4）的处理。它将内容复制到分发目录中，以便我们相对访问。它不优化文件，因此视频文件应由作者进行 Web 编码。例如，如果你使用 MacOS，请使用 Handbrake 优化视频，或在任何操作系统上使用 ffmpeg。

视频可以在 markdown 中如下声明：

<video width="100%" height="auto" autoplay loop>
  <source src="./ens_automatic_setup.mp4" type="video/mp4" />
  Your browser does not support the video tag.
</video>

💡 包含一个 ./，这意味着相对于当前文件，该路径将被替换为其绝对路径名。

当访问站点内容时，该文件将以绝对路径形式呈现，例如 <source src="https://fleek.xyz/blog/announcements/fleek-release-notes-v004/ens_automatic_setup.mp4" type="video/mp4">。

<video width="100%" height="auto" autoplay loop>
  <source src="ens_automatic_setup.mp4" type="video/mp4" />
  Your browser does not support the video tag.
</video>

❌ 如果缺少末尾斜杠，它将在错误的位置查找文件。在撰写本文时，解析站点部分不需要末尾斜杠，因此最佳实践是使用 ./ 声明文件位置，如 <source src="./my-video-filename.mp4"> 所示，以避免混淆。

💡 在撰写本文时，假设视频文件被放置在名为 index.md(x) 的 Markdown 文件所在的目录中，例如 src/content/guides/my-guide/index.md 和 src/content/guides/my-guide/my-video.mp4。同时，预期基础路径是内容所在的目录，而非跨内容。为了可移植性，遵守此约定至关重要，否则您可能会遇到意外结果。

Promotekit

Stripe 的 PromoteKit 是一款帮助企业在 Stripe 支付系统中集成和管理促销活动（如折扣和推荐）的工具，以提升客户参与度和销售额。如需了解更多信息，请阅读此处]的文档。

如何设置？

TLDR; 访问 https://fleek.xyz/?via=Helder 以在 window.promotekit_referral 中启用推荐链接

  1. Visit refer.fleek.xyz to create an account
  2. Copy the referral link, which will include the account ID, e.g. https://fleek.xyz/?via=Helder
  3. Visit the referral link, e.g. https://fleek.xyz/?via=Helder
  4. Access the promotekit on runtime, e.g. window.promotekit_referral
  5. As a fallback, you can also get the promotekit_referral

变更日志资源

这些仓库包含一个 CHANGELOG.md 文件，该文件是自动生成的。查找仓库根目录下的文件，例如对于 @fleek-platform/cli:

  • SDK 更新日志