# 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）不受影响，仅机器人/投影暂停。