跳转至

name: wiki-deploy category: devops description: Wiki 部署流程 — DB→渲染→mkdocs build→rsync。LanceDB 是唯一数据源 trigger: 用户要求部署/更新 wiki、涉及 wiki.koushui.online 内容变更，或排查 wiki 重建 cron

Wiki 部署流程（2026-06-09 重写）

架构（重要！）

LanceDB 是唯一数据源，wiki 是展示层。数据流：

SKILL.md / wiki md / memories
    ↓ sync_wiki_to_db.py（增量，hash 检测）
LanceDB (wiki_docs + memories 两张表)
    ↓ build_wiki_from_db.py（核心渲染器，DB→md）
docs-generated/ 目录
    ↓ mkdocs build -f mkdocs-generated.yml
site/ 静态文件
    ↓ rsync -a --delete site/ /var/www/wiki/
Caddy 服务 → wiki.koushui.online

环境信息

项目 路径/地址
Wiki 源码（项目根） /root/data/disk/wiki-docs/（/root/wiki-docs 是软链）
LanceDB /root/data/disk/.openclaw/memory/lancedb-pro
渲染输出 /root/data/disk/wiki-docs/docs-generated/
mkdocs 配置 mkdocs-generated.yml（docs_dir: docs-generated）
静态站点 /root/data/disk/wiki-docs/site/
Caddy 服务目录 /var/www/wiki/（不是 site/ 子目录！）
访问地址 https://wiki.koushui.online
Cron 任务 ID 752a045837e8，每天 04:00

完整部署命令（5 步必跑）

cd /root/data/disk/wiki-docs

# 1. 镜像 Hermes active skills 到 docs/skills/（2026-06-09 新增）
#    把 ~/.hermes/profiles/friend/skills/**/SKILL.md 拷成 docs/skills/<cat>/<name>.md
#    包含孤儿清理 + 自动生成 docs/skills/index.md
python3 sync_skills_to_docs.py

# 2. 增量同步磁盘 md → DB（无变更秒级退出，节省 embedding API）
python3 sync_wiki_to_db.py --batch-size 5

# 3. 从 DB 渲染 wiki（核心步骤，必跑——memories 实时变化）
python3 build_wiki_from_db.py
iki_to_db.py --batch-size 5

# 3. 从 DB 渲染 wiki（核心步骤，必跑——memories 实时变化）
python3 build_wiki_from_db.py# 4. mkdocs 构建静态站点（~35-45 秒）
mkdocs build -f mkdocs-generated.yml

# 5. 部署到 Caddy 服务目录（线上立即生效）
rsync -a --delete site/ /var/www/wiki/

# 6. 验证
curl -sI https://wiki.koushui.online/ | head -1
curl -sI https://wiki.koushui.online/skills/ | head -1

SKILL 镜像范围（2026-06-09）

  • 接入：Hermes friend profile 的 117 个 active skills（/root/.hermes/profiles/friend/skills/）
  • 不接：OpenClaw 遗留的 279 个 skill（多为废弃/重复，会污染检索）
  • 镜像脚本：sync_skills_to_docs.py
  • 用 sha256 hash 比对，未变化文件不重写（避免 sync 触发无意义增量）
  • 源文件被删除时同步删除目标（孤儿清理）
  • 自动生成 docs/skills/index.md 索引页（按 category 分组列表）
  • 目录映射规则：
    • <cat>/<name>/SKILL.md → docs/skills/<cat>/<name>.md
    • <name>/SKILL.md（无 category 子目录）→ docs/skills/_root/<name>.md
    • <cat>/<subcat>/<name>/SKILL.md → docs/skills/<cat>-<subcat>/<name>.md（合并多级）

如需扩展接入 OpenClaw skill，参考 skill-inventory-to-wiki skill 里的去重逻辑，新建 sync_openclaw_skills_to_docs.py 写到 docs/openclaw-skills/。

关键坑（吃过的亏）

  1. 不要因 sync "无变更" 就跳过 build——memories 表是实时变化的，即便磁盘 md 没变，DB 里的 memories 也可能新增/修改。memories 不动也要每日重建保持 freshness。
  2. deploy.sh 已过时——里面写的 /root/wiki-docs/（虽然是软链能跑通）+ mkdocs build（用的是 mkdocs.yml 不是 mkdocs-generated.yml），逻辑不对。不要用 deploy.sh，按上面 4 步手跑。
  3. git push 经常失败（网络问题），cron 里不要带 git push。
  4. build_wiki_from_db.py 默认 PREVIEW 模式输出到 docs-generated/，是对的。带 --deploy 会覆盖 docs/，不要乱用。
  5. sensitivity 默认 internal：渲染时按路径前缀自动判定 public/internal/sensitive（PATH_SENSITIVITY_MAP 在脚本里）。

排查 cron

认 internal**：渲染时按路径前缀自动判定 public/internal/sensitive（PATH_SENSITIVITY_MAP 在脚本里）。

## 排查 cron

```bash# 看最近一次输出
ls -t /root/.hermes/profiles/friend/cron/output/752a045837e8/ | head -1
# 全文
cat /root/.hermes/profiles/friend/cron/output/752a045837e8/<最新>.md

# 看 site/ 与 /var/www/wiki/ 时间是否同步
stat -c '%y %n' /root/data/disk/wiki-docs/site /var/www/wiki/
# 如果两者时间差大于 1 天且没新 sync 变更 → cron 没真跑通