# 栖云数字城堡 · 全景架构手册

> 冯先生个人数字基建，始于 2026 年 6 月 7 日
> 最后更新：2026-06-24

---

## 一、整体拓扑

```
                    ┌─────────────────────────────────────┐
                    │         东京 VPS（43.163.225.30）      │
                    │  Caddy 网关 → 各项服务 + 统一认证     │
                    │  主力运行：新闻管线、Gitea、Memos、    │
                    │  播客、阅读、日记、todo、代理          │
                    └──────────────┬──────────────────────┘
                                   │
                    ┌──────────────┴──────────────────────┐
                    │         北京 VPS（81.70.93.78）       │
                    │  知识库：Meilisearch + AI 问答        │
                    │  每天凌晨 3 点从东京备份              │
                    └─────────────────────────────────────┘
```

---

## 二、域名与服务清单

所有服务统一域名 `*.xybkwd.top`，经 Caddy 反向代理 + 统一认证（auth.xybkwd.top）。

### 2.1 核心服务

| 域名 | 服务 | 端口 | 需要认证 |
|:---|:---|:---:|:---:|
| nav.xybkwd.top | 导航页 + 知识库搜索/问答 | 静态文件 | ✅ |
| auth.xybkwd.top | 统一登录认证 | 9002 | — |
| chat.xybkwd.top | 旧 AI 对话（已弃用） | 8900 | — |
| gitea.xybkwd.top | Git 代码仓库 | 3000 | ✅ |
| dashboard.xybkwd.top | 控制面板 | 9000 | ✅ |
| memo.xybkwd.top | 备忘录 / 随手记 | 5230 | — |
| search.xybkwd.top | 搜索（原 Meilisearch 直连，现指向8100） | 8100 | ✅ |

### 2.2 内容与阅读

| 域名 | 服务 | 端口 |
|:---|:---|:---:|
| brief.xybkwd.top | 每日简报 | 静态文件 |
| books.xybkwd.top | 在线阅读 | 8083 |
| podcast.xybkwd.top | 播客服务器 | 13378 |

### 2.3 同步与存储

| 域名 | 服务 | 端口 |
|:---|:---|:---:|
| dav.xybkwd.top | WebDAV 日记同步 | 8766 |
| vault.xybkwd.top | 密码管理 | 8088 |

### 2.4 代理与工具

| 域名 | 服务 |
|:---|:---|
| ss.xybkwd.top | Shadowsocks 代理订阅 |
| www.xybkwd.top | 主站 | 8090 |

---

## 三、Gitea 仓库清单

全部在 **fxy** 用户下，共 **17 个仓库**：

### 核心系统
| 仓库名 | 说明 |
|:---|:---|
| `server-ops` | 服务器运维脚本、配置归档、daily 日志 |
| `nav-page` | 导航页前端代码 |
| `dashboard` | 控制面板 |
| `qiyun-portal` | 栖云个人门户 |
| `todo-system` | 待办系统 |
| `daily-brief` | 新闻采集管线（国内+国际+政策+研报） |

### 知识与笔记
| 仓库名 | 说明 |
|:---|:---|
| `inspiration-collector` | 灵感收集器（AI 日报/周报/随手记） |
| `weread-notes` | 微信读书笔记 + 每日阅读日报 |
| `obsidian-vault` | Obsidian 笔记库 |
| `ebook-library` | 电子书库 |
| `work-docs` | **工作文档归档**（2026-06-24 新增） |
| `qa-archive` | **知识库问答记录归档**（2026-06-24 新增，自动同步） |

### 投研与交易
| 仓库名 | 说明 |
|:---|:---|
| `freqtrade-strategies` | 交易策略代码 |
| `beast-trader-strategies` | Beast Trader 策略 |
| `boox-notes` | BOOX 阅读笔记 |

### 其他
| 仓库名 | 说明 |
|:---|:---|
| `culture-sports` | 文体部 |
| `boox-notes` | BOOX 同步笔记 |

---

## 四、数据流

### 4.1 知识库备份（东京 → 北京）

```
东京 server
  ├── repos/（灵感收集器、weread-notes、server-ops、daily-brief、nav-page、dashboard、work-docs）
  ├── configs/（Caddy 配置、脚本）
  ├── gitea_data/（数据库 + 仓库元数据）
  └── crontab/
      ↓ 每天凌晨 3:00 rsync
北京 /home/ubuntu/backups/tokyo/
  ├── repos/          ← 最新的裸仓库（供 indexer 索引）
  ├── repos_working/  ← 每日工作副本
  ├── gitea_data/     ← 7 轮滚动备份
  ├── configs/
  └── logs/           ← 30 天日志
```

### 4.2 知识库索引（北京）

```
北京 /home/ubuntu/backups/tokyo/repos/
  ├── inspiration-collector/ai-insights/daily/  → 灵感文章/灵感日报
  ├── weread-notes/notes/                       → 阅读卡片
  ├── weread-notes/daily/                       → 阅读日报
  └── work-docs/                                → 工作文档
      ↓ 每天凌晨 4:10 cron（indexer.py）
Meilisearch（localhost:7700） → 全文搜索引擎
```

### 4.3 问答归档（北京 → 东京 Gitea）

```
你提问 → kb_server.py（北京:8100）
  ↓ 实时
.md 文件写入 /home/ubuntu/kb/qa-archive/YYYY-MM/
  ↓ 每 30 分钟
Tokyo rsync 拉取 → git commit → git push
  ↓
Gitea: fxy/qa-archive
```

### 4.4 日报/新闻管线（东京）

```
每小时 fetch_tencent_news.py      → 腾讯新闻
每日 fetch_domestic_politics.py   → 国内时政
每日 fetch_policy.py              → 政策文件
每日 fetch_news.py                → 国际新闻
每日 fetch_market.py              → 行情数据
每日 fetch_research.py            → 研报摘要
    ↓
汇总 → cn_merge.py → 精选 80 条
    ↓
每天 22:40 archive_daily_brief.py → Gitea daily-brief 仓库
    ↓
每天 23:00 fetch_market_daily.py  → 指数/汇率/数字货币/宏观
```

---

## 五、服务器清单

### 5.1 东京服务器

| 项目 | 信息 |
|:---|:---|
| IP | 43.163.225.30 |
| 用户 | ubuntu |
| SSH 密钥 | `C:\Users\32779\Desktop\保险箱\ssh_new.pem` |
| 角色 | 主力服务 + Gitea + Caddy 网关 |
| 服务 | Caddy、Gitea、Memos、freqtrade、audiobookshelf、WebDAV、SS 代理等 |

### 5.2 北京服务器

| 项目 | 信息 |
|:---|:---|
| IP | 81.70.93.78 |
| 用户 | ubuntu |
| SSH 密钥 | `C:\Users\32779\Desktop\保险箱\BJ.pem` |
| 角色 | 知识库（Meilisearch + AI 问答）+ 备份 |
| 服务 | Meilisearch（7700）、QA API（8100）、rsync 备份 |
| SSH 到东京密钥 | `~/.ssh/tokyo_key.pem` |

### 5.3 安全规则

- **绝对不碰防火墙/安全组**。UFW 经验：启用后导致全部页面崩溃，直接禁用。
- 端口开放统一由云控制台安全组管理，需要开放端口时由冯先生自行操作。
- 腾讯云（北京）安全组允许东京 IP 访问 7700（Meilisearch）和 8100（QA API）。

---

## 六、本机环境（Windows）

### 6.1 Python

| 项目 | 路径 |
|:---|:---|
| 解释器 | `C:\Users\32779\.workbuddy\binaries\python\envs\default\Scripts\python.exe` |
| Git Bash | `/c/Users/32779/.workbuddy/binaries/python/envs/default/Scripts/python.exe` |
| 已装包 | mootdx, requests, pandas, stockstats, python-docx, PyMuPDF |
| 编码 | 中文输出需 `PYTHONIOENCODING=utf-8` |

### 6.2 Ollama 本地模型

| 项目 | 值 |
|:---|:---|
| 程序路径 | C 盘（Windows 安装默认，不可选） |
| 模型数据 | `D:\ollama\model_data\` |
| 环境变量 | OLLAMA_MODELS=`D:\ollama\model_data\models` |
|  | OLLAMA_HOST=`0.0.0.0:11434` |
|  | OLLAMA_IGPU_ENABLE=`1`（Intel Arc 加速） |
|  | OLLAMA_CONTEXT_LENGTH=`65536` |
| 已安装 | `qwen3.5:9b`（6.3GB，IQ4_NL 量化，来自 modelscope.cn） |
| 运行 | `ollama run qwen3.5:9b` |

### 6.3 A 股数据工具栈

| 数据 | 接口 | 方式 |
|:---|:---|:---|
| K线/财务 | mootdx TCP 7709 | 不封IP，首选 |
| 龙虎榜/解禁/融资融券/大宗 | datacenter-web.eastmoney.com | 可直连 |
| 东财其他API | push2.eastmoney.com | ❌ TLS握手失败，走WebFetch |
| 实时行情/PE/PB | qt.gtimg.cn（腾讯） | 待验证 |

### 6.4 doc2md 文档转换工具

| 项目 | 信息 |
|:---|:---|
| 位置 | `C:\Users\32779\WorkBuddy\Claw\doc2md.py` |
| GUI | `C:\Users\32779\WorkBuddy\Claw\doc2md_gui.py` |
| 启动 | 双击 `Claw\启动转换工具.bat` |
| 输入目录 | `Claw\input\` |
| 输出目录 | `Claw\output\` |
| 功能 | Word（标题+表格）→ MD，PDF（字号识别+表格提取）→ MD |

---

## 七、知识库 RAG 问答

### 7.1 架构

```
浏览器 nav.xybkwd.top/search.html
  │
  ├─ 搜索 → /search-api/* → Caddy（东京）→ Beijing:7700（Meilisearch）
  │
  └─ 问答 → /api/ask → Caddy（东京）→ Beijing:8100（kb_server.py）
                                    │
                                    ├─ Meilisearch 检索 top 8 × 3 轮搜索
                                    │
                                    └─ DeepSeek API → 基于资料生成回答
```

### 7.2 检索优化

| 优化项 | 之前 | 现在 |
|:---|:---:|:---:|
| 单次检索文档数 | 3 篇 | 12 篇（3 搜索词 × 6 篇，去重） |
| 搜索策略 | 单关键词 | 多轮检索：AI 自动拆成 3 个角度 |
| 每篇截取 | 2000 字 | 4000 字 |
| 提示词 | 简单指令 | 要求交叉验证多条资料 |
| 输出上限 | 2000 tokens | 4000 tokens |

### 7.3 成本

- 单次问答约 ¥0.02（一次 DeepSeek 生成搜索词 + 一次生成回答）
- 知识库增大不影响单次成本（始终只取 top 12）

### 7.4 前端功能

- 搜索/问答双标签切换
- Markdown 渲染（marked.js CDN）
- 保存按钮 → 下载 .md 文件到本地
- 自动归档 → 同步到 Gitea `fxy/qa-archive`

---

## 八、踩坑汇总（血的教训）

### 🔥 最高优先级
1. **不碰防火墙安全组** — UFW 启用后全部服务崩溃，彻底禁用
2. **Caddy `handle_path` 会剥离路径前缀** — 代理 API 要用 `@matcher` + `handle @matcher`，不能用 `handle_path`
3. **Caddy 规则顺序敏感** — `/api/ask` 必须在 `@api`（匹配 `/api/*`）之前，否则被拦截
4. **服务器端口必须监听 `0.0.0.0`** — `127.0.0.1` 只能本机访问，跨服务器必须 `0.0.0.0`

### ⚠️ 重要
5. **`rsync --delete` 会删 .git 目录** — 同步非 Git 目录到 Git 仓库时不能用 `--delete`
6. **Ollama pull 受系统代理干扰** — Clash（127.0.0.1:7890）会阻断 Ollama CLI 的模型下载，需 `HTTP_PROXY=""` 清空
7. **Ollama `OLLAMA_MODELS` 路径格式** — Windows 必须用反斜杠 `D:\ollama\...`，Git Bash 的 `/d/` 前缀不生效
8. **模型默认上下文仅 4096** — 长文本会被无声截断，必须设 `OLLAMA_CONTEXT_LENGTH=65536`
9. **服务端中文 URL 编码** — Python `http.server` 对 URL 中的中文编码处理脆弱，需 `urllib.parse` 手动解析

### 📝 常规注意事项
10. **Gitea API 不能自删用户** — 管理员用户也不能通过 API 删除自己
11. **Git 不跟踪空目录** — 需要 `.gitkeep` 占位文件
12. **Windows 下 Python 路径问题** — Git Bash 要用绝对路径调用 Python，且中文输出要设编码
13. **助理模式可能覆盖已有功能** — 修改 search.html 后，助理模式再次运行时可能覆盖 Q&A 代码

---

## 九、构建时间线

```
2026-06-07  WorkBuddy 首次下载
2026-06-08  ~ 初步搭建导航页 + Memos
2026-06-09  ~ Gitea 搭建 + 仓库迁移
2026-06-10  ~ Caddy 网关 + 统一认证
2026-06-11  ~ 待办系统 + 新闻管线初建
2026-06-12  ~ 微信公众号同步
2026-06-13  ~ Shadowsocks 代理
2026-06-14  ~ 播客服务器 + OpenBSD 防火墙踩坑
2026-06-15  ~ 北京服务器加入，两地备份
2026-06-16  ~ 日记 WebDAV 同步
2026-06-17  ~ 新闻管线完善 + 灵感收集器
2026-06-18  ~ 培训周报自动化
2026-06-19  ~ 北京服务器加固
2026-06-20  ~ A 股数据工具栈 + 交易策略回测
2026-06-21  ~ 90 后培训班文档分析
2026-06-22  ~ Ollama 本地模型部署
2026-06-23  ~ 知识库索引（Meilisearch）+ 文档转换工具
2026-06-24  ~ 知识库 AI 问答 + 问答归档 + 工作文档仓库
```

---

## 十、交接备忘

如果某天需要重装或迁移，关键步骤顺序：

1. **东京服务器** → 部署 Caddy、Gitea（Docker）、Memos、各脚本
2. **域名 DNS** → 指向东京 IP
3. **北京服务器** → 部署 Meilisearch、kb_server.py、备份脚本
4. **安全组** → 北京开放 7700、8100 给东京 IP
5. **本机** → 装 Python 环境、Ollama、Claw 工具
6. **SSH 密钥** → 东京→北京互信（保险箱文件夹有备份）

---

*文档生成于 2026-06-24，共 17 个 Gitea 仓库、2 台服务器、10+ 运行服务。*