This is an automated email from the ASF dual-hosted git repository.
Yilialinn pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git
The following commit(s) were added to refs/heads/master by this push:
new 2c97d6cbdea fix(seo): improve APISIX core search visibility and
metadata (#2127)
2c97d6cbdea is described below
commit 2c97d6cbdea834e770b0980d4a99721dd6e14a29
Author: Yilia Lin <[email protected]>
AuthorDate: Wed Sep 23 16:55:15 2026 +0800
fix(seo): improve APISIX core search visibility and metadata (#2127)
---
blog/en/blog/2025/03/06/what-is-an-ai-gateway.md | 8 ++-
doc/seo/semrush-on-page-seo-register.md | 35 +++++++++++
next/src/components/CollectionPages.astro | 5 +-
next/src/components/MainPages/AiGatewayPage.astro | 14 +++++
next/src/layouts/DocPage.astro | 2 +-
next/src/lib/content.ts | 67 ++++++++++++++++++++--
next/src/pages/learning-center/index.astro | 5 +-
next/tests/e2e/main-pages.spec.mjs | 42 +++++++++++++-
next/tests/e2e/seo-signals.spec.mjs | 59 +++++++++++++++++++
.../api-gateway-for-microservices.md | 2 +-
website/learning-center/api-gateway-security.md | 4 +-
.../api-gateway-vs-load-balancer.md | 2 +-
website/learning-center/what-is-an-api-gateway.md | 4 +-
website/learning-center/what-is-grpc.md | 2 +-
website/learning-center/what-is-mutual-tls.md | 4 +-
15 files changed, 232 insertions(+), 23 deletions(-)
diff --git a/blog/en/blog/2025/03/06/what-is-an-ai-gateway.md
b/blog/en/blog/2025/03/06/what-is-an-ai-gateway.md
index a2856fce72c..c963db885e8 100644
--- a/blog/en/blog/2025/03/06/what-is-an-ai-gateway.md
+++ b/blog/en/blog/2025/03/06/what-is-an-ai-gateway.md
@@ -18,7 +18,7 @@ keywords:
- data security
- AI traffic optimization
- hybrid cloud architecture
-description: "Learn what an AI Gateway is and how Apache APISIX can manage LLM
API traffic, model routing, token limits, security, and observability."
+description: "Learn how an AI gateway manages LLM traffic with provider
integrations, model routing, token limits, security, semantic caching, and
observability."
tags: [Ecosystem]
image:
https://static.api7.ai/uploads/2025/03/07/1W9olFmu_what-is-ai-gateway.webp
---
@@ -55,7 +55,9 @@ These controls can reduce the amount of provider-specific
failover logic in appl
Request counts alone do not describe LLM usage. A short completion and a long
completion can have very different token consumption. Token-aware limits allow
teams to place a usage boundary in front of model providers.
-The APISIX
[`ai-rate-limiting`](https://apisix.apache.org/docs/apisix/plugins/ai-rate-limiting/)
plugin tracks token consumption and can use local or Redis-backed counters. It
enforces the limits that operators configure; pricing, budgets, and billing
reconciliation remain responsibilities of external systems.
+The APISIX
[`ai-rate-limiting`](https://apisix.apache.org/docs/apisix/plugins/ai-rate-limiting/)
plugin tracks token consumption and can use local or Redis-backed counters.
Provider-reported usage may be recorded after the response, so concurrent
requests can overshoot a fixed window; treat this as a usage limit rather than
a prepaid hard budget. Pricing, budgets, and billing reconciliation remain
responsibilities of external systems. See the [shared Redis token quota
cookbook](/cookbook [...]
+
+Semantic caching is an optional, release- and provider-specific optimization
rather than a universal gateway capability. In current Apache APISIX
documentation, semantic matching is limited to plain-text OpenAI Chat requests;
tool calls and multimodal inputs are not supported. See the [Redis AI cache
cookbook](/cookbooks/redis-ai-cache/) for the supported flow and isolation
considerations.
### Prompt and Content Processing
@@ -66,7 +68,7 @@ AI gateways can modify or inspect request and response
content through separate,
-
[`ai-prompt-guard`](https://apisix.apache.org/docs/apisix/plugins/ai-prompt-guard/)
allows or denies prompts using configured regular-expression patterns.
-
[`ai-aws-content-moderation`](https://apisix.apache.org/docs/apisix/plugins/ai-aws-content-moderation/)
and
[`ai-aliyun-content-moderation`](https://apisix.apache.org/docs/apisix/plugins/ai-aliyun-content-moderation/)
integrate with their documented provider-specific moderation services.
-These plugins provide specific controls, not a complete security or compliance
guarantee. Teams still need application authorization, data classification,
secrets management, provider governance, and human review where required.
+These plugins provide specific controls, not a complete security or compliance
guarantee. Teams still need application authorization, data classification,
secrets management, provider governance, and human review where required. For a
broader defense-in-depth checklist, see [API gateway security best
practices](/learning-center/api-gateway-security/).
### Retrieval-Augmented Generation
diff --git a/doc/seo/semrush-on-page-seo-register.md
b/doc/seo/semrush-on-page-seo-register.md
new file mode 100644
index 00000000000..38ebf0185d7
--- /dev/null
+++ b/doc/seo/semrush-on-page-seo-register.md
@@ -0,0 +1,35 @@
+# Semrush On-page SEO Register
+
+本登记表把 Semrush desktop/mobile
报告转成可执行的页面决策。报告中的建议是分析证据，不是需要机械执行的指令；真实搜索意图、Apache APISIX 技术准确性和页面职责优先。
+
+来源：`ideas_apisix.apache.org_20260922-desktop.xlsx`（155 条建议）和
`ideas_apisix.apache.org_20260922-phone.xlsx`（154 条建议）。两份报告覆盖相同的 16 个 URL、29
个关键词。本轮将外链、Core Web Vitals 和服务器性能建议留给后续工作流。
+
+| URL | 设备 | 关键词/主题 | 问题类型 | 真实搜索意图 | 处理决定 | 目标 title / H1 / meta description
| 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `/` | desktop + mobile | Apache APISIX API gateway；open source API gateway |
title、H1、正文、meta、Schema | 了解并评估开源 API 网关 | 保留已对齐的首页定位；AI Gateway 作为次级入口；不添加评分标记
| `Apache APISIX - Open Source API Gateway & AI Gateway` / `The open-source API
Gateway & AI Gateway` / `Apache APISIX is a dynamic, high-performance,
open-source API gateway and AI gateway...` | 已复核 |
+| `/ai-gateway/` | desktop + mobile | open source AI gateway；LLM gateway |
title、H1、正文、内部链接 | 评估 LLM/AI agent 网关能力 | 保留产品页定位，补充 AI Gateway 解释型文章和 Learning
Center 路径 | `Open-Source AI Gateway for LLMs and AI Agents | Apache APISIX` /
同名 H1 / 覆盖 model routing、fallback、token rate limiting、security、observability |
已完成 |
+| `/learning-center/` | desktop + mobile | API gateway guides；Apache APISIX
tutorials；API gateway security/authentication | title、H1、meta | 学习 API 网关概念和实践
| 将版本/下载意图交给 `/downloads/`，首页聚焦指南和教程 | `API Gateway Guides & Tutorials | Apache
APISIX` / `API Gateway Guides & Tutorials` / `Apache APISIX guides to API
gateway concepts, authentication, security, Kubernetes, and gateway
comparisons.` | 已完成 |
+| `/learning-center/api-gateway-vs-load-balancer/` | desktop + mobile | api
gateway vs load balancer | 首段、语义词、可读性 | 比较两种流量组件的职责边界 | 只保留一个主目标词；首段和比较表使用自然定义
| `API Gateway vs Load Balancer: Key Differences Explained` / 同名 H1 / 现有比较型
description | 已完成 |
+| `/learning-center/api-gateway-for-microservices/` | desktop + mobile | API
gateway for microservices；API gateway architecture | title、首段、正文、可读性 |
设计微服务网关架构 | 补充 service discovery、high-traffic REST API、traffic
control、gateway/service mesh 边界 | `API Gateway for Microservices: Architecture,
Patterns & Best Practices` / 同名 H1 / 现有架构型 description | 已完成 |
+| `/learning-center/what-is-an-api-gateway/` | desktop + mobile | what is an
API gateway | 重复、首段、内部链接 | 获取 API 网关定义、工作方式和适用场景 | 用
routing、authentication、rate limiting、observability 等变体降低重复；链接 AI Gateway |
`What is an API Gateway? Definition, Benefits & Use Cases` / 同名 H1 / 现有定义型
description | 已完成 |
+| `/learning-center/api-gateway-security/` | desktop + mobile | API gateway
security best practices | 首段、语义词、可读性 | 学习 API 网关安全控制 | 补充 sensitive data、API
endpoints、unauthorized access、incoming requests、RBAC；不强行堆叠 `api security
gateway` | `API Gateway Security Best Practices` / 同名 H1 / 现有安全实践 description |
已完成 |
+| `/learning-center/what-is-mutual-tls/` | desktop + mobile | what is mutual
TLS；mTLS authentication | title、meta、正文、重复 | 了解双向 TLS 身份认证和证书校验 | 补充 public
key、TLS certificate、client certificate、certificate validation，减少 mTLS 重复 |
`What Is Mutual TLS (mTLS)? Authentication and Certificates` / 同名 H1 / 现有证书型
description | 已完成 |
+| `/learning-center/what-is-grpc/` | desktop + mobile | what is gRPC |
语义词、正文、视频 | 理解 gRPC、Protobuf、HTTP/2 和 streaming | 补充 gRPC clients、Protocol
Buffers、data structures；无真实视频资产则不嵌入视频 | `What is gRPC? Protocol Buffers,
Performance & API Gateway Integration` / 同名 H1 / 现有 gRPC description | 已完成 |
+| `/blog/2025/03/06/what-is-an-ai-gateway/` | desktop + mobile | AI gateway |
title、首段、正文、内部链接 | 解释 AI Gateway 的概念和核心能力 | 补充 API key、real-time
traffic、sensitive data、RBAC、semantic caching、provider integrations；链接产品页和安全指南 |
`What Is an AI Gateway? Concept and Core Features | Apache APISIX` / 同名 H1 /
`Learn how an AI gateway manages LLM traffic with provider integrations, model
routing, token limits, security, semantic caching, and observability.` | 已完成 |
+| `/docs/apisix/FAQ/` | desktop + mobile | apisix ingress（疑似蚕食） |
title、meta、关键词匹配 | 查找 APISIX 常见问题 | 用 FAQ 的真实职责覆盖 API gateway
routing、authentication、plugins、configuration、troubleshooting；不引入正文未覆盖的 Ingress
意图 | `Apache APISIX FAQ: API Gateway Questions | Apache APISIX` / `Apache
APISIX FAQ: API Gateway Questions` / FAQ 主题 description | 已完成 |
+| `/docs/ingress-controller/concepts/gateway-api/` | desktop + mobile |
Gateway API | title、meta、误匹配 | 学习 Kubernetes Gateway API 与 APISIX Ingress
Controller | 只按文档主题优化，不追逐 Semrush 拼写近似词 | `Kubernetes Gateway API with APISIX
Ingress Controller | Apache APISIX` / 同名主题 H1 / Gateway API 资源说明 | 待最终 overlay
验证 |
+| `/docs/apisix/http3/` | desktop + mobile | HTTP/3；QUIC | title、meta、误匹配 |
配置和理解 HTTP/3/QUIC | 说明 transport、TLS 和配置注意事项 | `HTTP/3 and QUIC in Apache
APISIX | Apache APISIX` / `HTTP/3 and QUIC in Apache APISIX` / HTTP/3 配置
description | 已完成 |
+| `/docs/apisix/plugins/lago/` | desktop + mobile | lagosec（误匹配） |
title、meta、关键词匹配 | 配置 Lago 用量/计费插件 | 不添加 `lagosec`；按插件功能提供准确 metadata | `Lago
Plugin | Apache APISIX` / `Lago Plugin` / Lago 用量和计费事件 description | 已完成 |
+| `/docs/apisix/plugins/ext-plugin-post-resp/` | desktop + mobile |
ext.to（误匹配） | title、meta、关键词匹配 | 配置响应阶段外部插件 | 不添加 `ext.to`；按 Plugin Runner 和
response phase 定义 metadata | `ext-plugin-post-resp | Apache APISIX` /
`ext-plugin-post-resp` / 外部响应阶段插件 description | 已完成 |
+| `/docs/ingress-controller/reference/apisix-ingress-controller/annotation/` |
desktop + mobile | cors proxy base64 url endpoint（误匹配） | title、meta、关键词匹配 | 查找
Ingress Controller annotation 参数 | 不污染页面；覆盖 annotation、routing、CORS、proxy 和
request behavior | `APISIX Ingress Controller Annotation Reference | Apache
APISIX` / 同名主题 H1 / annotation reference description | 待最终 overlay 验证 |
+
+## 拒绝或延后
+
+| 建议类别 | 处理决定 | 原因 |
+| --- | --- | --- |
+| 获取外链/反向链接（desktop 29 条、mobile 29 条） | 延后 | 属于 off-page SEO，不改变本轮页面意图和内容质量。 |
+| `yapix`、`apizel`、`apjax`、`ext.to`、`lagosec` | 拒绝 | 与 APISIX
页面主题不匹配，疑似拼写相似或低质量匹配；加入会造成关键词污染。 |
+| `cors proxy base64 url endpoint` | 拒绝 | 不是 annotation
文档的真实搜索意图，不能为了覆盖报告词组破坏文档可读性。 |
+| 视频嵌入建议 | 延后 | 只有在有真实、可维护且与页面直接相关的视频资产时才加入。 |
+| `aggregateRating` | 拒绝 | 当前没有可验证、可持续维护的评分来源；保留
WebSite、Organization、Article/BlogPosting、BreadcrumbList、FAQPage 等有依据的标记。 |
+| 版本发布/下载关键词放在 Learning Center 首页 | 拒绝 | 版本和下载意图由 `/downloads/`
承接，避免学习中心与下载页蚕食。 |
diff --git a/next/src/components/CollectionPages.astro
b/next/src/components/CollectionPages.astro
index 7ad7e7031c7..d2043dfbf55 100644
--- a/next/src/components/CollectionPages.astro
+++ b/next/src/components/CollectionPages.astro
@@ -13,6 +13,7 @@ interface Props {
posts: Post[];
urlBase: string; // e.g. "/learning-center"
heading: string;
+ title?: string;
sub?: string;
kicker?: string;
withTags?: boolean;
@@ -20,7 +21,7 @@ interface Props {
linkPrefix?: string;
}
const {
- locale, page, posts, urlBase, heading, sub, kicker, withTags = false,
linkPrefix,
+ locale, page, posts, urlBase, heading, title, sub, kicker, withTags = false,
linkPrefix,
} = Astro.props;
const prefix = localePrefix(locale);
// Where the archive/tags/pagination siblings live. Normally alongside this
@@ -31,7 +32,7 @@ const pages = paginate(posts);
const pagePosts = pages[page - 1] ?? [];
---
<ListPage
- title={heading}
+ title={title ?? heading}
heading={heading}
sub={sub}
kicker={kicker}
diff --git a/next/src/components/MainPages/AiGatewayPage.astro
b/next/src/components/MainPages/AiGatewayPage.astro
index d9e9a649f3c..0c9f63a390f 100644
--- a/next/src/components/MainPages/AiGatewayPage.astro
+++ b/next/src/components/MainPages/AiGatewayPage.astro
@@ -5,6 +5,11 @@ import { SITE, localePrefix, t, type Locale } from
'../../lib/site';
interface Props { locale: Locale }
const { locale } = Astro.props;
const p = localePrefix(locale);
+// The Learning Center article currently has no localized route, so keep the
+// Chinese product page's learning link pointed at the existing English page.
+const learningGuideHref = locale === 'zh'
+ ? '/learning-center/mcp-protocol-ai-gateway/'
+ : `${p}/learning-center/mcp-protocol-ai-gateway/`;
const features = [
{
@@ -319,6 +324,15 @@ const description = t(
<a class="text-link"
href={`${p}/blog/2025/02/24/apisix-ai-gateway-features/`}>
{t(locale, 'See the AI Gateway capabilities', '了解 AI 网关能力')} <span
aria-hidden="true">→</span>
</a>
+ <a class="text-link"
href={`${p}/blog/2025/03/06/what-is-an-ai-gateway/`}>
+ {t(locale, 'What is an AI gateway?', '什么是 AI 网关？')} <span
aria-hidden="true">→</span>
+ </a>
+ <a class="text-link" href={learningGuideHref}>
+ {t(locale, 'Read the AI Gateway learning guide', '阅读 AI 网关学习指南')}
<span aria-hidden="true">→</span>
+ </a>
+ <a class="text-link" href={`${p}/docs/apisix/plugins/ai-proxy/`}>
+ {t(locale, 'Explore the AI proxy plugin docs', '查看 AI 代理插件文档')}
<span aria-hidden="true">→</span>
+ </a>
</div>
<img
src="/img/ai-gateway/providers.avif"
diff --git a/next/src/layouts/DocPage.astro b/next/src/layouts/DocPage.astro
index 145d4f2dd01..724a3d5f36f 100644
--- a/next/src/layouts/DocPage.astro
+++ b/next/src/layouts/DocPage.astro
@@ -43,7 +43,7 @@ const jsonLd = [{
* edition of the same hub, so zh pages canonicalise there instead.
*/
const ZH_HUB = 'https://docs.apiseven.com';
-const rawCanonical = entry.mod.frontmatter.canonical;
+const rawCanonical = entry.canonical ?? entry.mod.frontmatter.canonical;
const canonicalOverride = locale === 'zh'
? rawCanonical?.startsWith('https://docs.api7.ai/')
? rawCanonical.replace('https://docs.api7.ai', ZH_HUB)
diff --git a/next/src/lib/content.ts b/next/src/lib/content.ts
index 94c5cebdcf2..a076f5b588d 100644
--- a/next/src/lib/content.ts
+++ b/next/src/lib/content.ts
@@ -260,6 +260,8 @@ export interface DocEntry {
url: string;
title: string;
description: string;
+ /** Cross-site canonical inherited from the English source when a translated
page omits it. */
+ canonical?: string;
mod: MdModule;
}
@@ -306,6 +308,57 @@ function docTitle(mod: MdModule, id: string): string {
return mod.frontmatter.title ?? id.split('/').pop()!;
}
+/**
+ * Site-level metadata for a small set of high-value docs whose upstream
+ * titles are implementation-oriented or too generic for search results.
+ * These overrides affect the current Astro docs surface only; the synced
+ * source files remain untouched so the next docs refresh does not erase the
+ * intent mapping. Chinese translations keep their own authored metadata.
+ */
+const SEO_DOC_OVERRIDES: Record<string, { title: string; description: string
}> = {
+ 'apisix/FAQ': {
+ title: 'Apache APISIX FAQ: API Gateway Questions',
+ description: 'Answers to common Apache APISIX questions about API gateway
routing, authentication, plugins, configuration, and troubleshooting.',
+ },
+ 'apisix/http3': {
+ title: 'HTTP/3 and QUIC in Apache APISIX',
+ description: 'Learn how Apache APISIX supports HTTP/3 and QUIC, including
transport behavior, TLS requirements, and configuration considerations.',
+ },
+ 'apisix/plugins/lago': {
+ title: 'Lago Plugin',
+ description: 'Configure the Apache APISIX Lago plugin to report API usage
and billing events to Lago.',
+ },
+ 'apisix/plugins/ext-plugin-post-resp': {
+ title: 'ext-plugin-post-resp',
+ description: 'Configure ext-plugin-post-resp to run an external
response-phase plugin through the Apache APISIX Plugin Runner.',
+ },
+ 'ingress-controller/concepts/gateway-api': {
+ title: 'Kubernetes Gateway API with APISIX Ingress Controller',
+ description: 'Use Kubernetes Gateway API resources with the Apache APISIX
Ingress Controller to manage gateways, listeners, routes, and backend
services.',
+ },
+ 'ingress-controller/reference/apisix-ingress-controller/annotation': {
+ title: 'APISIX Ingress Controller Annotation Reference',
+ description: 'Reference for APISIX Ingress Controller annotations,
including routing, CORS, proxy, and request behavior settings.',
+ },
+};
+
+function docMetadata(
+ key: string,
+ mod: MdModule,
+ locale: Locale,
+ hasTranslation: boolean,
+ id: string,
+): { title: string; description: string } {
+ const authored = {
+ title: docTitle(mod, id),
+ description: mod.frontmatter.description ?? excerpt(mod),
+ };
+ // A translated page owns its own title and description. If Chinese falls
+ // back to English, use the English SEO mapping rather than the raw filename.
+ if (locale === 'zh' && hasTranslation) return authored;
+ return SEO_DOC_OVERRIDES[key] ?? authored;
+}
+
export function getGeneralDocs(locale: Locale): DocEntry[] {
return Object.entries(docsGeneralModules)
.filter(([p]) => !p.endsWith('sidebars.json'))
@@ -335,14 +388,17 @@ export function getApisixDocs(locale: Locale): DocEntry[]
{
const hasTranslation = isMeaningfulTranslation(mod, zhMod);
const translated = locale === 'zh' && hasTranslation ? zhMod : undefined;
const effective = translated ?? mod;
+ const metadata = docMetadata(`apisix/${id}`, effective, locale,
hasTranslation, id);
+ const canonical = effective.frontmatter.canonical ??
mod.frontmatter.canonical;
return {
id,
pathId,
sourceLocale: translated ? 'zh' : 'en',
hasTranslation,
url: `${localePrefix(locale)}/docs/apisix/${id}/`,
- title: docTitle(effective, id),
- description: effective.frontmatter.description ?? excerpt(effective),
+ title: metadata.title,
+ description: metadata.description,
+ canonical,
mod: effective,
};
});
@@ -363,14 +419,17 @@ export function getSubprojectDocs(project: string,
locale: Locale): DocEntry[] {
const hasTranslation = isMeaningfulTranslation(mod, zhMod);
const translated = locale === 'zh' && hasTranslation ? zhMod : undefined;
const effective = translated ?? mod;
+ const metadata = docMetadata(`${project}/${id}`, effective, locale,
hasTranslation, id);
+ const canonical = effective.frontmatter.canonical ??
mod.frontmatter.canonical;
return {
id,
pathId,
sourceLocale: (translated ? 'zh' : 'en') as Locale,
hasTranslation,
url: `${localePrefix(locale)}/docs/${project}/${id}/`,
- title: docTitle(effective, id),
- description: effective.frontmatter.description ?? excerpt(effective),
+ title: metadata.title,
+ description: metadata.description,
+ canonical,
mod: effective,
};
});
diff --git a/next/src/pages/learning-center/index.astro
b/next/src/pages/learning-center/index.astro
index 79498f59306..ec769a748d8 100644
--- a/next/src/pages/learning-center/index.astro
+++ b/next/src/pages/learning-center/index.astro
@@ -7,8 +7,9 @@ import { getLearningPosts } from '../../lib/content';
page={1}
posts={getLearningPosts()}
urlBase="/learning-center"
- heading="Learning Center"
+ heading="API Gateway Guides & Tutorials"
+ title="API Gateway Guides & Tutorials"
kicker="Learning Center"
- sub="Guides to API gateway concepts, security, Kubernetes, and gateway
comparisons."
+ sub="Apache APISIX guides to API gateway concepts, authentication, security,
Kubernetes, and gateway comparisons."
withTags
/>
diff --git a/next/tests/e2e/main-pages.spec.mjs
b/next/tests/e2e/main-pages.spec.mjs
index 351b68568ad..87cc96fa392 100644
--- a/next/tests/e2e/main-pages.spec.mjs
+++ b/next/tests/e2e/main-pages.spec.mjs
@@ -127,7 +127,7 @@ test('AI Gateway has complete responsive content and valid
footer links', async
await Promise.all(documentedPlugins.map((plugin) => (
expect(page.locator(`main
a[href="/docs/apisix/plugins/${plugin}/"]`).first()).toBeVisible()
)));
- await expect(page.locator('main
a[href="/blog/2025/03/06/what-is-an-ai-gateway/"]'))
+ await expect(page.locator('main
a[href="/blog/2025/03/06/what-is-an-ai-gateway/"]').first())
.toBeVisible();
await expect(page.locator('main
a[href="/blog/2025/03/21/ai-gateway-vs-api-gateway-differences-explained/"]'))
.toBeVisible();
@@ -156,6 +156,44 @@ test('AI Gateway has complete responsive content and valid
footer links', async
await expect(page.locator('footer
a[href="/docs/general/events/"]')).toHaveText('Events');
await expect(page.locator('footer a[href="/user-stories/"]')).toHaveCount(0);
+ await expect(page.getByRole('link', { name: /What is an AI gateway/i }))
+ .toHaveAttribute('href', '/blog/2025/03/06/what-is-an-ai-gateway/');
+ await expect(page.getByRole('link', { name: 'Read the AI Gateway learning
guide' }))
+ .toHaveAttribute('href', '/learning-center/mcp-protocol-ai-gateway/');
+ await expect(page.getByRole('link', { name: 'Explore the AI proxy plugin
docs' }))
+ .toHaveAttribute('href', '/docs/apisix/plugins/ai-proxy/');
+});
+
+test('Learning Center and AI Gateway article expose aligned search metadata',
async ({ page }) => {
+ await page.goto('/learning-center/');
+ await expect(page).toHaveTitle('API Gateway Guides & Tutorials | Apache
APISIX');
+ await expect(page.locator('meta[name="description"]')).toHaveAttribute(
+ 'content',
+ 'Apache APISIX guides to API gateway concepts, authentication, security,
Kubernetes, and gateway comparisons.',
+ );
+ await expect(page.getByRole('heading', { level: 1, name: 'API Gateway Guides
& Tutorials' })).toBeVisible();
+
+ await page.goto('/learning-center/what-is-an-api-gateway/');
+ await expect(page).toHaveTitle('What is an API Gateway? Definition, Benefits
& Use Cases | Apache APISIX');
+ await
expect(page.locator('meta[name="description"]')).toHaveAttribute('content',
/API Gateway/);
+ await expect(page.getByRole('link', { name: /AI gateway/i }).first())
+ .toHaveAttribute('href', '/ai-gateway/');
+
+ await page.goto('/blog/2025/03/06/what-is-an-ai-gateway/');
+ await expect(page).toHaveTitle('What Is an AI Gateway? Concept and Core
Features | Apache APISIX');
+ await expect(page.locator('meta[name="description"]')).toHaveAttribute(
+ 'content',
+ 'Learn how an AI gateway manages LLM traffic with provider integrations,
model routing, token limits, security, semantic caching, and observability.',
+ );
+ await expect(page.getByRole('link', { name: 'Apache APISIX AI Gateway'
})).toHaveAttribute('href', '/ai-gateway/');
+ await expect(page.getByRole('link', { name: 'API gateway security best
practices' }))
+ .toHaveAttribute('href', '/learning-center/api-gateway-security/');
+});
+
+test('Chinese AI Gateway keeps English-only learning links resolvable', async
({ page }) => {
+ await page.goto('/zh/ai-gateway/');
+ await expect(page.getByRole('link', { name: '阅读 AI 网关学习指南' }))
+ .toHaveAttribute('href', '/learning-center/mcp-protocol-ai-gateway/');
});
test('Chinese AI Gateway preserves localized ownership and documented
capabilities', async ({ page }) => {
@@ -173,7 +211,7 @@ test('Chinese AI Gateway preserves localized ownership and
documented capabiliti
await expect(page.locator('link[rel="canonical"]'))
.toHaveAttribute('href', 'https://apisix.apache.org/zh/ai-gateway/');
await expect(page.locator('main
a[href="/zh/docs/apisix/plugins/ai-proxy/"]').first()).toBeVisible();
- await expect(page.locator('main
a[href="/zh/blog/2025/03/06/what-is-an-ai-gateway/"]'))
+ await expect(page.locator('main
a[href="/zh/blog/2025/03/06/what-is-an-ai-gateway/"]').first())
.toBeVisible();
await expect(page.locator('main')).not.toContainText('MCP Gateway');
await expect(page.locator('main')).not.toContainText('MCP support');
diff --git a/next/tests/e2e/seo-signals.spec.mjs
b/next/tests/e2e/seo-signals.spec.mjs
index 01d59f54e1d..1243b3fc4d6 100644
--- a/next/tests/e2e/seo-signals.spec.mjs
+++ b/next/tests/e2e/seo-signals.spec.mjs
@@ -58,6 +58,65 @@ APISIX_OWNED_DOCS.forEach((path) => {
});
});
+test('selected APISIX docs use intent-specific SEO metadata', async ({ page })
=> {
+ const cases = [
+ {
+ path: '/docs/apisix/FAQ/',
+ title: 'Apache APISIX FAQ: API Gateway Questions | Apache APISIX',
+ description: 'Answers to common Apache APISIX questions about API
gateway routing, authentication, plugins, configuration, and troubleshooting.',
+ },
+ {
+ path: '/docs/apisix/http3/',
+ title: 'HTTP/3 and QUIC in Apache APISIX | Apache APISIX',
+ description: 'Learn how Apache APISIX supports HTTP/3 and QUIC,
including transport behavior, TLS requirements, and configuration
considerations.',
+ },
+ {
+ path: '/docs/apisix/plugins/lago/',
+ title: 'Lago Plugin | Apache APISIX',
+ description: 'Configure the Apache APISIX Lago plugin to report API
usage and billing events to Lago.',
+ },
+ {
+ path: '/docs/apisix/plugins/ext-plugin-post-resp/',
+ title: 'ext-plugin-post-resp | Apache APISIX',
+ description: 'Configure ext-plugin-post-resp to run an external
response-phase plugin through the Apache APISIX Plugin Runner.',
+ },
+ ];
+
+ for (const entry of cases) {
+ await page.goto(entry.path);
+ await expect(page).toHaveTitle(entry.title);
+ await
expect(page.locator('meta[name="description"]')).toHaveAttribute('content',
entry.description);
+ await expect(page.getByRole('heading', { level: 1
})).toHaveText(entry.title.replace(' | Apache APISIX', ''));
+ }
+});
+
+test('selected Ingress docs use intent-specific SEO metadata', async ({ page
}) => {
+ test.skip(
+ process.env.EXPECT_DOCUSARUS_ROUTES !== 'true',
+ 'Ingress Controller docs are synced only in the final overlaid tree',
+ );
+
+ const cases = [
+ {
+ path: '/docs/ingress-controller/concepts/gateway-api/',
+ title: 'Kubernetes Gateway API with APISIX Ingress Controller | Apache
APISIX',
+ description: 'Use Kubernetes Gateway API resources with the Apache
APISIX Ingress Controller to manage gateways, listeners, routes, and backend
services.',
+ },
+ {
+ path:
'/docs/ingress-controller/reference/apisix-ingress-controller/annotation/',
+ title: 'APISIX Ingress Controller Annotation Reference | Apache APISIX',
+ description: 'Reference for APISIX Ingress Controller annotations,
including routing, CORS, proxy, and request behavior settings.',
+ },
+ ];
+
+ for (const entry of cases) {
+ await page.goto(entry.path);
+ await expect(page).toHaveTitle(entry.title);
+ await
expect(page.locator('meta[name="description"]')).toHaveAttribute('content',
entry.description);
+ await expect(page.getByRole('heading', { level: 1
})).toHaveText(entry.title.replace(' | Apache APISIX', ''));
+ }
+});
+
test('blog hreflang exists only for verified source pairs', async ({ page })
=> {
const en =
'https://apisix.apache.org/blog/2026/07/31/2026-jul-monthly-report/';
const zh =
'https://apisix.apache.org/zh/blog/2026/07/31/2026-jul-monthly-report/';
diff --git a/website/learning-center/api-gateway-for-microservices.md
b/website/learning-center/api-gateway-for-microservices.md
index b15e88b2a7f..b829111435e 100644
--- a/website/learning-center/api-gateway-for-microservices.md
+++ b/website/learning-center/api-gateway-for-microservices.md
@@ -7,7 +7,7 @@ tags: [microservices, architecture, api-gateway]
hide_table_of_contents: false
---
-Microservices architectures often use an [API
gateway](/learning-center/what-is-an-api-gateway/) as a single entry point for
API consumers and to route requests to the correct backend services. The
gateway centralizes access control, authentication and authorization, protocol
translation, rate limiting, and observability, so each microservice does not
have to implement these cross-cutting concerns independently.
+Microservices architectures often use an [API
gateway](/learning-center/what-is-an-api-gateway/) as a single entry point for
API consumers and to route requests to the correct backend services. For
high-traffic REST APIs, the gateway can keep a stable client-facing endpoint
while it applies routing, load balancing, retries, and traffic control behind
the scenes. It also centralizes access control, authentication and
authorization, protocol translation, rate limiting, and observability, s [...]
## Why Microservices Need a Gateway
diff --git a/website/learning-center/api-gateway-security.md
b/website/learning-center/api-gateway-security.md
index 387585fc745..6d19a87e6da 100644
--- a/website/learning-center/api-gateway-security.md
+++ b/website/learning-center/api-gateway-security.md
@@ -45,11 +45,11 @@ A defense-in-depth approach applies multiple security
controls at the gateway la
### Authentication
-For routes that require identity, the gateway can verify credentials before
forwarding a request. Common mechanisms include JWT validation, OAuth 2.0 token
introspection, API key verification, and [mutual TLS
(mTLS)](/learning-center/what-is-mutual-tls/) for service-to-service
communication. Centralizing [API gateway
authentication](/learning-center/api-gateway-authentication/) can reduce
inconsistent edge enforcement, while explicitly public routes remain
unauthenticated by design.
+For routes that require identity, the gateway can verify credentials before
forwarding incoming requests. Common mechanisms include JWT validation, OAuth
2.0 token introspection, API key verification, and [mutual TLS
(mTLS)](/learning-center/what-is-mutual-tls/) for service-to-service
communication. Centralizing [API gateway
authentication](/learning-center/api-gateway-authentication/) can reduce
inconsistent edge enforcement, while explicitly public routes remain
unauthenticated by design.
### Authorization
-Beyond verifying identity, the gateway can enforce route-, consumer-, role-,
attribute-, or scope-based access policies before forwarding a request. These
gateway-level checks complement rather than replace authorization in the
application: backend services must still verify resource ownership and other
business rules to prevent BOLA.
+Beyond verifying identity, the gateway can enforce route-, consumer-, role-,
attribute-, or scope-based access policies, including role-based access control
(RBAC), before forwarding a request. These gateway-level checks complement
rather than replace authorization in the application: backend services must
still verify resource ownership and other business rules to prevent BOLA.
### Rate Limiting and Throttling
diff --git a/website/learning-center/api-gateway-vs-load-balancer.md
b/website/learning-center/api-gateway-vs-load-balancer.md
index d184bd80b6a..a2ae752a18a 100644
--- a/website/learning-center/api-gateway-vs-load-balancer.md
+++ b/website/learning-center/api-gateway-vs-load-balancer.md
@@ -17,7 +17,7 @@ faq:
Assign a bounded retry budget to the layer that has the best view of
each failure boundary. Uncoordinated retries at both layers can multiply
requests, increase latency, and replay operations that are not safe to repeat.
Test timeout and retry behavior together under partial failures.
---
-A load balancer distributes traffic across healthy backend instances. An API
gateway controls how clients use APIs through routing and policies such as
authentication, rate limiting, transformation, and observability. Their
capabilities overlap at Layer 7, but they solve different architectural
problems. Many production systems use both: a network or cloud load balancer
exposes a highly available gateway cluster, and the gateway applies API
policies before balancing requests across services.
+A load balancer distributes incoming traffic across multiple healthy backend
instances. An API gateway controls how clients use APIs through routing and
policies such as authentication, rate limiting, transformation, and
observability. Their capabilities overlap at Layer 7, but they solve different
architectural problems. Many production systems use both: a network or cloud
load balancer exposes a highly available gateway cluster, and the gateway
applies API policies before balancing req [...]
## What Is a Load Balancer?
diff --git a/website/learning-center/what-is-an-api-gateway.md
b/website/learning-center/what-is-an-api-gateway.md
index 487a123d917..1887ff8f43c 100644
--- a/website/learning-center/what-is-an-api-gateway.md
+++ b/website/learning-center/what-is-an-api-gateway.md
@@ -25,7 +25,7 @@ faq:
An API gateway is a server that sits between clients and backend services,
acting as an entry point for the APIs placed behind it. It accepts incoming
requests, applies policies such as authentication, rate limiting, and
transformation, then routes each request to the appropriate upstream service
and returns the response to the caller.
-The main benefits of an API gateway are consistent edge policy enforcement,
less duplicated infrastructure logic, and a stable entry point as backend
services change. Teams can centralize access control, traffic shaping, and
gateway-level observability while leaving business authorization and
service-specific behavior in the applications that own them.
+The main benefits of an API gateway are consistent edge policy enforcement,
less duplicated infrastructure logic, and a stable entry point as backend
services change. Teams can centralize access control, traffic shaping, and
gateway-level observability while leaving business authorization and
service-specific behavior in the applications that own them. For teams routing
LLM requests, an [AI gateway](/ai-gateway/) extends the same policy model to
model providers and AI applications.
## How Does an API Gateway Work?
@@ -182,7 +182,7 @@ The gateway and backend services scale independently.
During a traffic surge, te
**Extensible policy layer.** The APISIX [plugin ecosystem](/plugins/) covers
authentication, traffic control, observability, security, and transformation.
Native plugins use Lua, while external plugin runners provide additional
extension models where their operational tradeoffs are appropriate.
-**Dynamic configuration.** Routes match request attributes, execute configured
plugins, and forward traffic to an upstream. In traditional and decoupled
deployment modes, APISIX stores configuration in etcd and exposes an Admin API,
allowing route, upstream, consumer, and plugin changes to propagate without
restarting gateway processes. Standalone mode can instead load declarative
configuration without etcd.
+**Dynamic configuration.** Routes match request attributes, execute configured
plugins, and forward traffic to an upstream. In traditional and decoupled
deployment modes, APISIX stores configuration in etcd and exposes an Admin API,
allowing route, upstream, consumer, and plugin changes to propagate in real
time without restarting gateway processes. Standalone mode can instead load
declarative configuration without etcd.
**Open governance.** Apache APISIX is an Apache Software Foundation top-level
project developed under community governance and released under the Apache
License 2.0.
diff --git a/website/learning-center/what-is-grpc.md
b/website/learning-center/what-is-grpc.md
index 5050f2a9351..e7c4da251a1 100644
--- a/website/learning-center/what-is-grpc.md
+++ b/website/learning-center/what-is-grpc.md
@@ -40,7 +40,7 @@ message OrderResponse {
}
```
-The `protoc` compiler generates client and server code in many languages from
this definition. For many schemas, binary serialization produces more compact
payloads than an equivalent JSON representation, but the exact size and
processing cost depend on the data model and implementation.
+The `protoc` compiler, together with a language-specific gRPC plugin,
generates gRPC clients and server code in many languages from this definition.
The generated clients use the declared data structures and service methods,
while the gateway can apply transport-level policies without changing the
contract. For many schemas, binary serialization produces more compact payloads
than an equivalent JSON representation, but the exact size and processing cost
depend on the data model and imple [...]
### HTTP/2 Transport
diff --git a/website/learning-center/what-is-mutual-tls.md
b/website/learning-center/what-is-mutual-tls.md
index ee46e88c2aa..6ba1579f9c2 100644
--- a/website/learning-center/what-is-mutual-tls.md
+++ b/website/learning-center/what-is-mutual-tls.md
@@ -1,5 +1,5 @@
---
-title: "Mutual TLS (mTLS): Authentication and Certificates"
+title: "What Is Mutual TLS (mTLS)? Authentication and Certificates"
description: "Learn how mutual TLS (mTLS) authentication uses client and
server certificates, how TLS vs mTLS differs, and how Apache APISIX enforces
mTLS."
slug: what-is-mutual-tls
date: 2026-04-14
@@ -7,7 +7,7 @@ tags: [mtls, security, tls]
hide_table_of_contents: false
---
-Mutual TLS (mTLS) authentication is a security protocol where both the client
and server authenticate each other using X.509 digital certificates during the
TLS handshake. Unlike standard TLS, which only verifies the server's identity,
mTLS provides mutual authentication: both parties prove their identities before
exchanging application data over a secure connection.
+Mutual TLS (mTLS) authentication is a security protocol where both the client
and server authenticate each other using X.509 digital certificates during the
TLS handshake. The certificate binds an identity to a public key, and each side
verifies the peer's certificate chain before accepting the connection. Unlike
standard TLS, which only verifies the server's identity, mTLS provides mutual
authentication: both parties prove their identities before exchanging
application data over a secur [...]
## Why Mutual TLS Matters
