fxy/server-ops
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加全景架构手册（含所有服务/仓库/数据流/踩坑）

Browse Source
This commit is contained in:
fxy
2026-06-26 00:20:18 +08:00
parent 1937819f25
commit f1178ad2a2
1 changed files with 346 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

346
栖云数字城堡_全景架构手册.md Normal file
View File

@ -0,0 +1,346 @@
# 栖云数字城堡 · 全景架构手册
> 冯先生个人数字基建，始于 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+ 运行服务。*