84f7950589
- 完整的知识库框架（P0-P5 路线图） - 12篇治理文档 - 工具脚本（kb-init.sh, kb-lint-fm.py, feishu-sync.py, kb-bot） - 7个 Claude 命令 - 示例项目和测试项目（wanniu-l1） - 契约文件（meta/kb-contract.yaml） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
127 lines
5.5 KiB
Markdown
Executable File
127 lines
5.5 KiB
Markdown
Executable File
# 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）
|
||
|
||
```bash
|
||
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 同事接入（每人一次）
|
||
|
||
```bash
|
||
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 + 起长连接：
|
||
|
||
```bash
|
||
# 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 每日同步飞书呈现：
|
||
|
||
```cron
|
||
# 每天 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）不受影响，仅机器人/投影暂停。
|