company-kb/docs/10-部署与运维.md

10 · 部署与运维

物理拓扑 + 部署步骤 + 运维手册。回答「仓库在哪、处理逻辑在哪跑、同事怎么接入」。 核心：仓库家 + 常驻处理都在公司 NAS；交互处理在各人本机。

---

一、物理拓扑

┌──────────────────────────────────────────────────────────────┐
│  公司 NAS（数据的家 + 常驻处理节点）                            │
│  ├─ Gitea 仓库 company-kb.git ★唯一真相源★                     │
│  ├─ 常驻：kb-bot 飞书群机器人长连接（subscribe + handle）        │
│  └─ 定时：feishu-render 投影（云文档 + 多维表格）               │
└──────────────────────────────────────────────────────────────┘
      ▲ git clone/push (内网/VPN)        │ 投影(只读)
      │                                  ▼
┌─────────────┐                   ┌──────────────┐
│ 各人本机     │                   │ 飞书三层呈现  │
│ 本地 clone   │                   │ 文档/表格/机器人│
│ CC 交互处理  │                   └──────────────┘
│ /kb-ingest   │
│ /kb-ask      │      ┌────────────────────────────┐
│ /kb-link     │◀─────│ NAS 同步盘：各人工作目录↔投递区│
└─────────────┘       │ （采集通道，单向投递，无冲突）│
                      └────────────────────────────┘

两条 NAS 用途，各司其职，不冲突：

NAS 角色	机制	用途	为何不冲突
Gitea 仓库	Git 协作	知识库本体（提炼后真相源）	多人共享，Git 管合并/审计/回滚
同步盘	Synology Drive / SMB	采集通道（投递原始物料）	单向投递，无多人同改

---

二、处理逻辑落点

处理类型	跑在哪	触发	说明
交互处理 /kb-ingest//kb-ask//kb-link	各人本机	人触发	CC 读本地 clone，天然分布式，无需中心
常驻处理 飞书群机器人长连接	NAS	常驻	读 Git 真相源实时回答，无需公网
定时处理 feishu-render 投影	NAS	定时/手动	md→飞书云文档+多维表格

关键：常驻/定时处理需要一台常开机 = NAS。交互处理分散在各人机器，NAS 不是单点瓶颈。

---

三、部署步骤

3.1 接 Gitea remote（需内网/VPN）

cd ~/奇域/智能体开发/公司AI
# 在 Gitea Web (192.168.0.101:3002/robert) 建空 repo: company-kb
git remote add origin http://192.168.0.101:3002/robert/company-kb.git
git push -u origin main

现不在内网时 Gitea 不可达，本地提交先攒着，回公司网络再 push。

3.2 同事接入（每人一次）

git clone http://192.168.0.101:3002/robert/company-kb.git
cd company-kb
# CC: cd 进来即可用 /kb-ask /kb-ingest（读项目级 CLAUDE.md 自动感知）
# Obsidian: Open folder as vault 打开本目录（个人主编辑器）

日常同步：干活前 git pull，产出后 git add/commit/push（或让 CC 代跑）。

3.3 NAS 常驻机器人（Gitea 通后）

NAS 上 clone 一份 + 装 lark-cli + 起长连接：

# NAS 上（Container/SSH）
git clone <gitea-url> && cd company-kb
lark-cli auth status                      # 确认 bot 身份
nohup bash tools/kb-bot/subscribe.sh > /tmp/kb-sub.log 2>&1 &
nohup python3 tools/kb-bot/handle.py --watch > /tmp/kb-handle.log 2>&1 &

稳定后包成 NAS 的开机自启（Synology「任务计划」或 systemd）。NAS 侧仓库定时 git pull 保证机器人读到最新。

3.4 定时投影（可选）

NAS 上 crontab 每日同步飞书呈现：

# 每天 08:07 投影到飞书（错开整点）
7 8 * * * cd /path/company-kb && git pull -q && python3 tools/feishu-render.py --bitable

---

四、运维手册

备份

• Gitea 仓库随 NAS 备份策略走（NAS 快照/RAID）。
• Git 本身即分布式备份：每个同事的本地 clone 都是全量副本。

冲突处理

• 多人改同一页 → Git 合并；_index.md 等导航文件已设计为低冲突。
• 编译产物（hot/index/wiki）已 gitignore，不进 Git，无合并冲突（见 docs/04 §3）。

权限（MVP → 演进）

• MVP：5 人皆可直接 push main，靠 Gitea Web review + /kb-check 把关。
• 演进：Gitea 上给 main 加保护分支 + PR review（团队变大或误操作增多时）。

健康检查

• python3 tools/kb-lint-fm.py — frontmatter 合规（exit 0 为健康）。
• /kb-status — 源计数 / type 分布 / 红线观察（见 docs/05 P5）。
• 机器人存活：看 /tmp/kb-sub.log、/tmp/kb-handle.log。

凭据安全

• lark-cli 凭据由其自身管理，不入库（.gitignore 已挡 .env）。
• 飞书 App Secret 等走环境变量或 lark-cli 配置，绝不提交。

故障恢复

• 机器人挂 → NAS 上重跑 3.3 的两条 nohup。
• 仓库损坏 → 从任一同事本地 clone git push 恢复 Gitea。
• Gitea 不可用 → 交互处理（各人本机 CC）不受影响，仅机器人/投影暂停。