llms.txt · xianyan.cc
运维与部署 更新于 2026-08-15

文档站运维

职责：doc.xianyan.cc 文档中心的架构、更新接口、字段搜索原理、日常运维。

本页接口速览（5 个）
POST /api/search GET /api/search GET /api/weather/full POST /api/xxx/login GET /api/xxx/list

文档中心管理指南

创建: 2026-08-15 | 更新: 2026-08-15
维护: Xianyan 团队

职责：doc.xianyan.cc 文档中心的架构、更新接口、字段搜索原理、日常运维。

1. 架构

Cloudflare Worker "doc-xianyan"
  ├─ D1 "doc-xianyan" (id: ab6fbbd5-faac-4d81-b8ce-83ec23d53e9b)
  │   ├─ documents   (元信息 + Markdown 原文)
  │   ├─ endpoints   (接口清单)
  │   ├─ fields      (字段索引 — 用于字段级搜索)
  │   └─ config      (站点配置)
  ├─ HTML 输出：商务风 + Mermaid 图 + 深浅主题 + 代码块复制
  └─ API：/api/docs /api/docs/:id /api/search /api/import

本地维护：
  Scripts/doc-xianyan/import_docs.py    # 解析本地 .md → D1
  Scripts/doc-xianyan/reimport_doc.py   # 重写后批量重导入（按文件名）
  Scripts/doc-xianyan/verify_endpoints.py # 接口/字段一致性校验
  docs/toolsapi/docs/*.md               # 文档源（人手维护）

2. 资源

资源 值
Worker 名 doc-xianyan
Worker URL https://doc-xianyan.freetimeuu.workers.dev
域名 https://doc.xianyan.cc
D1 数据库 doc-xianyan
API Key（secret） doc_UEdRT52GvnqXuM5X5j9zg8IpNrOV9bT7
域名 Zone xianyan.cc（1e258e58...）

3. 接口

3.1 公共 API

接口 方法 说明
/api/docs GET 文档列表（按分类分组）
/api/docs/:id GET 文档详情（渲染后 HTML + 元信息 + 接口/字段）
/api/docs/:id.md GET 原始 Markdown
/api/search?q=... GET 字段级搜索（field + endpoint + doc）
/llms.txt GET AI 友好的文档索引
/health GET 健康检查

3.2 更新接口（需 Bearer Auth）

Authorization: Bearer doc_UEdRT52GvnqXuM5X5j9zg8IpNrOV9bT7
接口 方法 说明
/api/docs POST 创建/更新文档（JSON）
/api/docs/:id DELETE 删除文档
/api/docs/import POST 批量导入（dryRun 模式可预览）

3.3 POST /api/docs 数据格式

{
  "id": "API_OAUTH_DOC",
  "title": "OAuth 授权 API",
  "category": "用户与账号",
  "author": "Xianyan 团队",
  "version": "v1.0",
  "base_url": "https://tools.wktyl.com",
  "updated_at": "2026-08-15",
  "summary": "GitHub / Apple / Google 三方登录...",
  "content": "# 标题\n\n## 章节\n..."
}

4. 字段搜索原理

POST /api/search / GET /api/search 三层回退：

  1. 字段名精确匹配 — q="nickname" 命中 nickname 字段
  2. 字段名前缀匹配 — q="next" 命中 next_token、next_page
  3. 接口路径匹配 — q="/api/weather" 命中 GET /api/weather/full 等接口
  4. 文档标题/摘要匹配 — q="OAuth" 命中 OAuth 文档

排序：层级 1 > 2 > 3 > 4；同一层级中匹配度越高排越前。

5. 维护流程

5.1 新增文档

  1. 在 docs/toolsapi/docs/ 创建 API_xxx_DOC.md
  2. 在 import_docs.py 的 CATEGORY_MAP 加分类映射
  3. 运行：python3 Scripts/doc-xianyan/reimport_doc.py API_xxx_DOC
  4. 在 CLOUDFLARE_MANAGEMENT_GUIDE 加上链接

5.2 修改现有文档

  1. 直接编辑 .md 文件
  2. 运行：python3 Scripts/doc-xianyan/reimport_doc.py <DOC_ID>

5.3 字段搜索重导

# 重导所有文档（增量更新）
cd Scripts/doc-xianyan
python3 -c "from import_docs import *; import os, json; print('parse all docs')"

# 或直接用 wrangler 批量更新
wrangler d1 execute doc-xianyan --command "DELETE FROM fields; DELETE FROM endpoints;" --remote
python3 reimport_doc.py all  # 你的脚本需要支持 all 参数

5.4 校验

python3 Scripts/doc-xianyan/verify_endpoints.py
# 检查：接口重复 / 路径格式 / 字段类型异常 / 更新时间缺失

6. 部署

cd Scripts/doc-xianyan
wrangler deploy                    # 部署 Worker
wrangler secret put DOC_API_KEY    # 更新 API Key（如果换）

7. 文档写作约定

7.1 简洁标准

  • 6-8 节结构：通用约定 / 核心流程图 / 接口清单（按功能分组）/ 关键示例 / 设计要点 / 关联文档
  • 精简原则：删除 changelog 冗长段落、删除 SDK 文档重复内容
  • 保留重点：mermaid 流程图、对比表、统一响应格式、错误码表

7.2 Markdown 格式（被自动识别为接口）

- `POST /api/xxx/login` — 登录          ← 列表行（自动识别）
- **GET /api/xxx/list** — 列表           ← bold 名称（自动识别）
| 名 | GET | /api/xxx/list |         ← 表格行（自动识别）

**接口名** `GET /api/xxx/list`         ← heading 风格（自动识别）

8. 关联文档