四系统总览：MySQL · xgb-wiki · TOS · WeKnora

一页看懂四个系统各自是什么、放在哪、谁写谁读，以及全部数据流程怎么串起来。本文只做关系地图：各环节的操作细节见 §5 流程表指向的专门文档，不在此重复。依据：2026-10-03 实测（TOS 通道已验证打通，tos_preflight.py --check 对比成功）。

1. 总图

                        ┌────────────────────────── 工作机（Windows，conda xgb-wiki）──────────────────────────┐
                        │  持有全部凭据（MySQL 内网 VPN / LLM / TOS / GitHub）                                    │
                        │  ①镜像 ②ETL ③图谱 ④TOS备份 —— F1 日常同步链（docs/data-sync/staging-sync.md §1）      │
                        └───────┬──────────────────────────────┬───────────────────────────┬──────────────────┘
                                │ VPN 只读 SELECT               │ git push（代码+db 快照）    │ TOS 上传
                                ▼                              ▼                           ▼
   ┌────────────────┐   ┌───────────────┐            ┌──────────────┐          ┌──────────────────────┐
   │ MySQL 生产库    │   │ 火山 TOS 上海桶 │            │ GitHub 私有仓 │          │ Cloudflare Pages     │
   │ 10.0.46.53     │   │ arkclaw-tos-…  │            │ seuzxh/xgb_wiki│        │ 静态研报站（CI 产物） │
   │ xuangubao 5 源表│   │ backup/{ts}/×6 │            └──────┬───────┘          └──────────────────────┘
   │（只读，内网）    │   │ latest.json    │                   │ CI：测试+构建
   └────────────────┘   └───────┬───────┘                   │
                                │ ⓪预检按需下载三库（md5 校验）  │ git pull / clone
                                ▼                              ▼
                        ┌────────────────────────── 服务器（Linux，WeKnora 部署机）───────────────────────────┐
                        │  data/xgb_wiki.db（本体库） + staging.db + graph.db                                │
                        │  F2 TOS 取数对齐（tos_preflight.py）  ← 服务器更新数据的主通道（分钟级，免 git 大文件）│
                        │  F4 WeKnora 内容推送（push_to_weknora.py，读本体库 → REST 导入）                     │
                        │  部署 7.weknora：6 容器（app/frontend/docreader/postgres/redis/neo4j）              │
                        │  凭据：WEKNORA_* + TOS_*（有意不放 MySQL 凭据——服务器不跑同步链）                    │
                        └──────────────────────────────┬──────────────────────────────────────┘
                                                       │ 篇级 Markdown + 月份标签（进度标记幂等）
                                                       ▼
                                              ┌──────────────────┐
                                              │ WeKnora v0.8.2    │
                                              │ 后台核心知识库     │
                                              │ 检索/问答/图谱/Agent│
                                              └──────────────────┘

2. 四系统角色

系统	是什么	位置	存什么	谁写	谁读
MySQL 生产库	选股宝脱水研报的源头业务库（内网，只读账号）	10.0.46.53:3306 / `xuangubao`	5 张源表（live_tuoshui_news、tuoshui_msgs、两张 tag 关联表、plate_rank_infos）	选股宝业务侧（与本项目无关）	仅工作机的 `sync_staging.py`（①镜像步）
xgb-wiki	本仓库：同步工具链 + 本体库 + Web/静态站	工作机与服务器各一份	三个 SQLite：`staging.db`（MySQL 原样镜像）→ `xgb_wiki.db`（本体库 23 表，事实源）→ `graph.db`（图谱）；代码与文档	F1 同步链（工作机）、F2 预检恢复（服务器）	ETL/图谱/站点构建/WeKnora 推送
火山 TOS	对象存储，数据出 git 的分发与备份通道	上海桶 `arkclaw-tos-2101988067-cn-shanghai`	`xgb-wiki/backup/{时间戳}/`：三库快照 + `.env` + manifest（滚动 6 份），顶层 `latest.json` 指向最新	工作机 `backup_tos.py`（④备份步）	任何机器 `tos_preflight.py`（⓪预检/恢复）；`xgb-wiki/staging` 前缀为分片通道预留（未启用）
WeKnora	腾讯开源 RAG 知识平台，本项目后台核心知识库（双核定位见融合方案 v0.2）	服务器本机 Docker（API 18080 / UI 18081，6 容器含 Neo4j）	知识库 `xgb-研报`：4844 篇篇级 Markdown、月份标签、检索/问答会话	仅服务器的 `push_to_weknora.py`	WeKnora UI / ZCode（MCP，规划 S1）/ Agent 工具箱（规划 S3）

分层要点：MySQL 是唯一上游事实源头；staging.db 是它的原样搬运层（出错环节极少）；xgb_wiki.db 是本体化加工层（唯一结构化事实源）；graph.db 与 WeKnora 是两个消费端加工层（前者本地浏览、后者语义检索）；TOS 与 git 是两条并行的分发通道（TOS 分钟级拉三库，git 随代码走但 860MB 偏重，data-distribution-design.md §6 规划数据出 git）。

3. 各层数据新鲜度记录（对账口径）

每层独立记一份进度，出现不一致时按下表定位：

记录	位置	含义
staging_log	`staging.db`	①镜像进度（大表按主键）与最近一次 success 时间（备份前置校验用它，24h 内才算新鲜）
etl_meta（同步进度标记）	`xgb_wiki.db`	②ETL 增量进度；`sync_log` 最新 success 时间 = 本地 `data_as_of`，与 TOS `latest.json` 对比的口径
weknora_push.json（推送进度标记）	服务器 `data/`（gitignore）	已推 WeKnora 的 report_id 清单，幂等唯一防线
latest.json	TOS `xgb-wiki/backup/` 顶层	最新备份的数据截止（`data_as_of`）与各文件 md5，取数端先拿它

4. 两台机器的凭据与职责

	工作机（Windows）	服务器（Linux，WeKnora 部署机）
`.env` 凭据	MySQL（DB_*）+ LLM + TOS + GitHub	WEKNORA_ + TOS_；有意不放 MySQL（服务器不跑同步链，内网也不可达）
跑什么	F1 同步链全四步、链映射 LLM、图片 LAS 解析、git push 发布	F2 TOS 取数、F4 WeKnora 推送、WeKnora 实例运维
数据怎么新	自己同步	`tos_preflight.py`（TOS 新则自动恢复三库）或 `git pull`

5. 全部流程一览

#	流程	触发	步骤（执行机）	产物
F1	日常数据更新	手动（工作机，需 VPN）	⓪`tos_preflight.py`（他机备份新则先恢复）→ ①`sync_staging.py` 镜像 → ②`sync_data.py` ETL（先停 5010 Web）→ ③`build_graph.py` + `kg_recluster.py` → ④`backup_tos.py` 上云	三库更新 + TOS 新备份；细节：staging-sync.md §1
F2	服务器取数对齐	手动或定时（服务器，无需 VPN）	`tos_preflight.py`：对比 latest.json 与本地 → 下载三库（md5 校验，旧库移入 `data/backups/preflight-*/`）	本服务器三库对齐工作机最新基线（2026-10-03 实测通道可用，当前两端同为 2026-10-01T12:48 基线）
F3	站点发布	工作机 git push master	GitHub Actions（`.github/workflows/deploy-site.yml`）：全量测试 → 观点单元重建 → 静态站构建 → Cloudflare Pages	公网静态站快照；细节：publishing.md
F4	WeKnora 内容更新	手动（服务器）	`push_to_weknora.py --since <日>`（限速分批 10 篇/90s）：读本体库组装篇级 MD → REST manual 导入 → 月份标签 + `weknora_map.json` 映射留存	WeKnora 文档库增量（本轮 34 篇补推中）；幂等靠推送进度标记
F5	语义消费（规划，未实施）	—	S1 问答迁离（WeKnora MCP→ZCode）、S2 图谱接管（Wiki 本体页 + Neo4j 直写）、S3 xgb MCP→WeKnora 工具箱、S4 内容回流	见 weknora-integration-plan.md S0–S4

流程间的依赖：F4 依赖 F2/F1 产出的新本体库；F3 与 F4 相互独立；F5 的 S2 依赖 F4 的存量文档（chunk 挂载）。

6. 常见问题定位

服务器数据旧了 → 跑 F2（tos_preflight.py --check 先看云端是否有更新；没有说明工作机还没跑 F1）。
WeKnora 里缺新研报 → F2 对齐后跑 F4；推送失败多为 Ark embedding 账号级 429，等限速窗口补跑即可（进度标记自动跳过已推）。
TOS 有备份但拉不下来 → 查 .env 五项 TOS 配置与 tos SDK（pyproject.toml 尚未声明该依赖，需 pip install tos）。
git 与 TOS 数据不一致 → 正常现象：git 里的 db 是上次 push 的快照，TOS 是上次 F1④ 的备份，以 data_as_of 新者为准。