本站是一套基于 VuePress + Plume 主题、部署在 Cloudflare Workers 上的静态 Wiki。本文档面向开发者与内容作者，包含三部分：

1. HTTP API：由 Cloudflare Worker 暴露的只读 JSON 接口，可用于把文章数据接入到你的程序或第三方应用中。
2. 配置 API：docs/.vuepress/config.ts 中的主题与插件配置项。
3. 自定义组件 API：本站内置的三个 Vue 组件及其依赖的数据文件格式。

---

一、HTTP API

概述

• Base URL：https://my-wiki.catkinr-93f.workers.dev
• 协议：HTTPS / 只读（GET），支持跨域（Access-Control-Allow-Origin: *）。
• 响应格式：所有接口返回统一 JSON 信封：

{
  "code": 0,        // 0 表示成功，非 0 表示失败（与 HTTP 状态码一致）
  "msg": "ok",      // 错误描述
  "data": ...        // 具体数据
}

• 缓存：响应带 Cache-Control: public, max-age=60, s-maxage=300。
• 鉴权：读接口公开；写接口需 Authorization: Bearer <WRITE_KEY>。

方法	路径	说明	鉴权
GET	/api	接口概览（版本与端点列表）	无
GET	/api/health	健康检查	无
GET	/api/articles	文章列表（支持查询）	无
GET	/api/articles/:slug	单篇文章（按标识符）	无
GET	/api/updates	文章更新日历数据	无
POST	/api/articles	新建文章（写回 GitHub）	需密钥
PUT	/api/articles/:slug	更新文章（写回 GitHub）	需密钥
DELETE	/api/articles/:slug	删除文章（写回 GitHub）	需密钥

写接口安全说明

写操作会在 你的 GitHub 仓库直接提交，并触发 CI 重新构建部署。所有写请求必须携带请求头 Authorization: Bearer <WRITE_KEY>，其中的 WRITE_KEY 与 GITHUB_TOKEN 均通过 Cloudflare Worker Secret 注入，不会出现在代码里。请勿公开或泄露这两个密钥。

GET /api

返回接口名称、版本与所有端点。

请求

curl https://my-wiki.catkinr-93f.workers.dev/api

响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "name": "my-wiki API",
    "version": "1.0.0",
    "endpoints": [
      { "method": "GET", "path": "/api/health" },
      { "method": "GET", "path": "/api/articles" },
      { "method": "GET", "path": "/api/articles/:slug" },
      { "method": "GET", "path": "/api/updates" }
    ]
  }
}

GET /api/health

健康检查，用于探测接口是否在线。

请求

curl https://my-wiki.catkinr-93f.workers.dev/api/health

响应

{
  "code": 0,
  "msg": "ok",
  "data": { "status": "up", "time": "2026-08-30T07:30:00.000Z" }
}

GET /api/articles

返回全部文章列表。支持以下可选查询参数：

参数	类型	说明	示例
group	string	按栏目分组过滤（博客文章/使用指南/开发笔记）	?group=博客文章
tag	string	按标签过滤	?tag=教程
q	string	关键字模糊搜索（匹配标题、栏目、标签）	?q=markdown

请求 1

curl "https://my-wiki.catkinr-93f.workers.dev/api/articles"

请求 2（按栏目）

curl "https://my-wiki.catkinr-93f.workers.dev/api/articles?group=博客文章"

请求 3（按标签）

curl "https://my-wiki.catkinr-93f.workers.dev/api/articles?tag=教程"

请求 4（搜索）

curl "https://my-wiki.catkinr-93f.workers.dev/api/articles?q=markdown"

响应

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "title": "欢迎来到博客",
      "group": "博客文章",
      "link": "/posts/hello/",
      "date": "2026-08-30",
      "tags": ["随笔"]
    },
    {
      "title": "Markdown 格式与功能全览",
      "group": "博客文章",
      "link": "/posts/markdown-guide/",
      "date": "2026-08-30",
      "tags": ["教程", "Markdown"]
    }
  ],
  "total": 5
}

字段说明

字段	类型	说明
title	string	文章标题
group	string	所属栏目
link	string	站内相对路径（用于跳转）
date	string	发布日期（YYYY-MM-DD，可能为空）
tags	string[]	文章标签列表

GET /api/articles/:slug

返回单篇文章。slug 接受多种写法，均可命中同一篇文章：

• 纯标识：hello
• 完整路径（含或不含尾斜杠）：posts/hello、posts/hello/

请求

curl https://my-wiki.catkinr-93f.workers.dev/api/articles/posts/hello

响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "title": "欢迎来到博客",
    "group": "博客文章",
    "link": "/posts/hello/",
    "date": "2026-08-30",
    "tags": ["随笔"]
  },
  "slug": "posts/hello"
}

未找到文章时返回 404：

{ "code": 404, "msg": "article not found: nope", "data": null }

GET /api/updates

返回最近一年文章更新数据，键为日期（YYYY-MM-DD），值为当日更新次数。供"文章更新日历"热力图使用。

请求

curl https://my-wiki.catkinr-93f.workers.dev/api/updates

响应

{
  "code": 0,
  "msg": "ok",
  "data": { "2026-08-30": 9 }
}

---

写接口（写回 GitHub 仓库）

写接口通过 GitHub Contents API 直接向仓库 main 分支提交，提交会自动触发 CI 重新构建部署。所有写请求需带请求头：

Authorization: Bearer <WRITE_KEY>

通用请求字段

字段	类型	说明	必要性
slug	string	文章标识/相对路径（仅 POST 必填）	新增必填
title	string	标题	可选
tags	string[]	标签	可选
categories	string[]	分类	可选
date	string	日期 YYYY-MM-DD（缺省用当天）	可选
permalink	string	访问路径（缺省按 slug 自动生成）	可选
draft	boolean	是否草稿	可选
body	string	Markdown 正文	可选

POST /api/articles — 新建文章

文件写入路径为 docs/{slug}.md。

请求

curl -X POST https://my-wiki.catkinr-93f.workers.dev/api/articles \
  -H "Authorization: Bearer $WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "posts/api-demo",
    "title": "API 示例",
    "tags": ["教程"],
    "categories": ["博客"],
    "body": "# 你好\n\n这是一篇通过 API 创建的文章。"
  }'

响应

{
  "code": 0,
  "msg": "article created",
  "data": { "path": "docs/posts/api-demo.md", "slug": "posts/api-demo", "commit": "3f6a..." }
}

PUT /api/articles/:slug — 更新文章

更新为全量覆盖语义：请求中省略的字段沿用文章现有 frontmatter，提供了 body 则覆盖正文。支持已有 /foo.md 与 /foo/README.md 两种文件形态。

请求（仅改正文）

curl -X PUT https://my-wiki.catkinr-93f.workers.dev/api/articles/posts/hello \
  -H "Authorization: Bearer $WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "# 更新后的标题\n\n新内容" }'

响应

{
  "code": 0,
  "msg": "article updated",
  "data": { "path": "docs/posts/hello.md", "slug": "posts/hello", "commit": "9c21..." }
}

DELETE /api/articles/:slug — 删除文章

请求

curl -X DELETE https://my-wiki.catkinr-93f.workers.dev/api/articles/posts/api-demo \
  -H "Authorization: Bearer $WRITE_KEY"

响应

{
  "code": 0,
  "msg": "article deleted",
  "data": { "path": "docs/posts/api-demo.md", "slug": "posts/api-demo" }
}

写接口常见错误

状态码	说明
401	缺少或错误的 WRITE_KEY
404	要更新/删除的文章不存在
500	GitHub 提交失败（如 token 无写入权限）

部署与密钥

部署前需为 Worker 配置两个 Secret：

# GITHUB_TOKEN：需对 maoxinhe/my-wiki 有 contents 写权限的 PAT
npx wrangler secret put GITHUB_TOKEN

# WRITE_KEY：写接口共享密钥（自定义强随机字符串）
npx wrangler secret put WRITE_KEY

错误码

code	含义
0	成功
400	请求错误（如 JSON 非法）
401	未授权（写接口密钥缺失/错误）
404	接口或资源不存在
405	请求方法不支持
500	GitHub 提交失败

实现位置

Worker 入口在 src/index.js（在新窗口打开），数据源为构建期生成的静态 JSON 文件：

• docs/.vuepress/public/article-directory.json
• docs/.vuepress/public/updates.json

---

二、配置 API

站点全局配置在 docs/.vuepress/config.ts（在新窗口打开）。以下为主要配置项。

VuePress 顶层配置

配置项	类型	说明	本示例值
lang	string	站点语言	zh-CN
title	string	站点标题	我的 Wiki
description	string	站点描述	我的知识库 / Wiki 网站

主题组件覆盖（alias）

用自定义组件替换主题内置组件：

alias: {
  '@theme/VPDocFooter.vue': path.resolve(__dirname, './components/VPDocFooter.vue'),
},

插接件（plugins）

插件	说明	本示例关键配置
feedPlugin	生成 RSS / Atom / JSON 订阅源	rss:true, atom:true, json:true, count:100

Plume 主题选项（theme）

plumeTheme({ ... }) 支持以下常用配置：

配置项	类型	说明	本示例值
hostname	string	部署域名（SEO/站点地图）	https://...workers.dev
home	string	主页路径	'/'
avatar	{name,url}	导航栏头像与昵称	见源码
author	{name,url}	站点作者（署名/版权）	{ name:'maoxinhe' }
profile	{...}	博主资料（文章侧边栏）	见源码
social	[]	社交账号（导航栏右侧）	GitHub
sidebar	object	全局侧边栏	见下方示例
footer	{message,copyright}	页脚	猫慧云提供服务
copyright	{license,author,creation}	文章许可证	CC-BY-4.0

侧边栏结构（每个分组用 items 承载子项，link 指向文章）：

sidebar: {
  '/': [
    {
      text: '博客文章',
      icon: 'lucide:file-text',
      items: [
        { text: '欢迎来到博客', link: '/posts/hello/' },
        // ...更多文章
      ],
    },
    // ...
  ],
},

布尔功能开关

配置项	说明	本示例值
contributors	显示贡献者	true
changelog	版本更新日志	true
lastUpdated	最后更新时间	true
createTime	创建时间	true
readingTime	阅读时间/字数	true
copyCode	代码复制按钮	true
editLink	编辑此页链接	true
prevPage	上一篇/下一篇	true

---

三、自定义组件 API

全局组件在 client.ts（在新窗口打开） 中通过 app.component(...) 注册：

import { defineClientConfig } from 'vuepress/client'
import UpdateCalendar from './components/UpdateCalendar.vue'
import ArticleDirectory from './components/ArticleDirectory.vue'

export default defineClientConfig({
  enhance({ app }) {
    app.component('UpdateCalendar', UpdateCalendar)
    app.component('ArticleDirectory', ArticleDirectory)
  },
})

UpdateCalendar（文章更新日历）

GitHub 风格热力图，展示最近一年每天的更新情况。

• 用法：在任意 Markdown 页面中直接写 <UpdateCalendar />。
• 数据源：/updates.json，格式 { "YYYY-MM-DD": 更新次数 }。
• 无 props，仅展示。

ArticleDirectory（文章目录）

按栏目分组展示全部文章（标题、日期、标签）。

• 用法：在 Markdown 页中写 <ArticleDirectory />（详见 docs/directory.md）。
• 数据源：/article-directory.json，格式为 Article[]（见下方）。
• 无 props，仅展示。

VPDocFooter（覆盖主题页脚）

覆盖 @theme/VPDocFooter.vue，用于自定义"贡献者名称"样式等。通过 alias 注册，可自由编写。

---

四、构建期数据生成 API

generate-updates.mjs（在新窗口打开） 在 npm run build 的 prebuild 阶段执行，扫描 docs/posts 与 docs/wiki 下的 Markdown，通过 git log 聚合更新日期，输出两个 JSON 文件到 public/：

输出文件	格式	用途
updates.json	{ "YYYY-MM-DD": number }	更新日历
article-directory.json	[{ title, group, link, date, tags }]	文章目录 / HTTP API

相关脚本与钩子：

// package.json
"scripts": {
  "prebuild": "node docs/.vuepress/generate-updates.mjs",
  "build": "vuepress build docs"
}

Frontmatter 字段（会被解析进 article-directory.json）：

字段	类型	说明
title	string	标题（缺省取文件名）
permalink	string	文章路径（缺省自动生成）
date	string	日期（缺省用 createTime）
tags	string[]	标签（支持内联或 YAML 列表）

版权所有

版权归属：maoxinhe

许可证：署名 4.0 国际 (CC-BY-4.0)

上一页开发笔记

下一页文章目录