server-ops/智能体交接手册.md

# 栖云数字城堡 · 智能体交接手册

> 本手册专为**新接手智能体**编写，读完本手册应能独立完成日常运维和故障排查。
> 冯先生（用户）—— 90后四级副职培训班学员，严肃交易者，西安。
> 最后更新：2026-06-25

---

## 一、核心身份信息

| 信息 | 内容 |
|:---|:---|
| 称呼 | 冯先生 |
| 城市 | 西安 |
| 教育 | 上海交通大学 MEM（非全日制，在读） |
| 职业 | 国网陕西电力（工会+安全相关） |
| 交易风格 | 价格行为学，ETH/USDT 永续，1x 杠杆，中低频，趋势+波段 |
| 培训 | 90后四级副职培训班（6周分段式，非"浙大培训"） |

### 冯先生的铁律（不可违反）

1. **Token 头号杀手** — 所有下载/安装/批量操作必须重定向 stdout/stderr，禁止进度条、安装日志、大文件输出进入对话
2. **本地大模型只在 D 盘** — 不碰 C 盘，不移动模型文件
3. **删除任何文件前必须请示**
4. **不碰防火墙/安全组**

---

## 二、服务器清单与访问

### 东京服务器（主力）

| 项目 | 值 |
|:---|:---|
| 公网 IP | 43.163.225.30 |
| 内网 IP (Tailscale) | 100.111.102.100 |
| 用户 | ubuntu |
| SSH 密钥 | `C:\Users\32779\Desktop\保险箱\ssh_new.pem` |
| SSH 命令 | `ssh -i "密钥路径" ubuntu@43.163.225.30` |
| 规格 | 2C/4G |
| 角色 | Caddy 网关、Gitea、Memos、freqtrade、audiobookshelf、WebDAV、SS 代理 |
| 主机名 | vm-4-13-ubuntu |

### 北京服务器（知识库+备份）

| 项目 | 值 |
|:---|:---|
| 公网 IP | 81.70.93.78 |
| 内网 IP (Tailscale) | 100.104.225.62 |
| 用户 | ubuntu |
| SSH 密钥 | `C:\Users\32779\Desktop\保险箱\BJ.pem` |
| 规格 | 2C/4G |
| 角色 | Meilisearch（7700）、QA API（8100）、备份存储 |
| SSH 到东京密钥 | `~/.ssh/tokyo_key.pem`（放在北京服务器上） |

### 本机（Windows）

| 项目 | 值 |
|:---|:---|
| Tailscale IP | 100.99.151.78 |
| 主机名 | fxy |
| 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` |

---

## 三、Gitea 仓库清单

所有仓库在 **fxy** 用户下，访问：`gitea.xybkwd.top`

**Git Push URL 格式**：
```
http://beast:bb731ed7d0d267b98a1c7d082de6c8fc0329ac21@localhost:3000/fxy/<repo名>.git
```
*注：`localhost:3000` 指东京服务器内网的 Gitea 端口，本地机不可直连，需通过 SSH 到东京操作。*

### 仓库列表

| 仓库名 | 说明 | 关键词 |
|:---|:---|:---|
| `server-ops` | 服务器运维、配置归档、**全景架构手册**、CHANGELOG | **新智能体首先阅读** |
| `nav-page` | 导航页前端（`nav.xybkwd.top`） | 知识库搜索/问答界面 |
| `dashboard` | 控制面板（`dashboard.xybkwd.top`） | freqtrade 状态、策略切换 |
| `qiyun-portal` | 栖云个人门户 |
| `todo-system` | 待办系统 |
| `daily-brief` | **新闻管线**（国内/国际/政策/研报/行情） |
| `inspiration-collector` | 灵感收集器、AI 日报/周报、Memos 同步 |
| `weread-notes` | 微信读书笔记、阅读日报 |
| `work-docs` | 冯先生的工作文档归档 |
| `qa-archive` | 知识库问答记录归档（自动同步） |
| `freqtrade-strategies` | 交易策略 |
| `beast-trader-strategies` | Beast Trader 策略 |
| `boox-notes` | BOOX 阅读笔记 |
| `ebook-library` | 电子书库 |
| `obsidian-vault` | Obsidian 笔记库 |
| `culture-sports` | 文体部 |
| `qa-archive` | 问答记录归档 |

---

## 四、域名与服务

所有服务统一域名 `*.xybkwd.top`，经 **Caddy**（东京 `/etc/caddy/Caddyfile`）反向代理。
需要认证的域名由 `auth.xybkwd.top`（端口 9002）统一管理。

### 4.1 核心服务

| 域名 | 服务 | 端口 | 后端 | 需认证 |
|:---|:---|:---:|:---|:---:|
| nav.xybkwd.top | 导航页 + 知识库搜索/问答 | 静态 | `nav-page` 前端 | ✅ |
| auth.xybkwd.top | 统一登录 | 9002 | Tokyo auth_proxy | — |
| gitea.xybkwd.top | Git 仓库 | 3000 | Docker gitea | ✅ |
| dashboard.xybkwd.top | 控制面板 | 9000 | `dashboard` 前端 | ✅ |
| memo.xybkwd.top | 备忘录 | 5230 | Docker memos | — |
| search.xybkwd.top | 搜索 | →8100 | → Beijing:8100 | ✅ |

### 4.2 内容服务

| 域名 | 服务 | 端口 |
|:---|:---|:---:|
| brief.xybkwd.top | 每日简报 | 静态文件 |
| books.xybkwd.top | 在线阅读（Calibre-Web） | Docker 8083 |
| podcast.xybkwd.top | 播客（Audiobookshelf） | Docker 13378 |
| www.xybkwd.top | 主站（Halo） | Docker 8090 |

### 4.3 同步/存储/工具

| 域名 | 服务 | 端口 |
|:---|:---|:---:|
| dav.xybkwd.top | WebDAV 日记同步 | Docker 8766 |
| vault.xybkwd.top | 密码管理（Vaultwarden） | Docker 8088（仅 127.0.0.1） |
| ss.xybkwd.top | Shadowsocks 代理订阅 | 静态文件 |

### 4.4 本机 Docker 服务（通过 Tailscale 访问）

| 服务 | 端口 | 位置 |
|:---|:---:|:---|
| Immich（照片管理） | 2283 | `D:\immich\`，Docker |
| Ollama 本地模型 | 11434 | 本机服务 |

---

## 五、数据流

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

```
东京 /home/ubuntu/ 下的 repos + configs
  ↓ 每天凌晨 3:00 rsync（由北京 backup_tokyo_to_beijing.sh 触发）
北京 /home/ubuntu/backups/tokyo/
  ├── repos/          ← 最新的裸仓库
  ├── repos_working/  ← 工作副本
  ├── gitea_data/     ← 7轮滚动备份
  └── configs/
```

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

```
北京 /home/ubuntu/backups/tokyo/repos/
  ├── inspiration-collector/ai-insights/daily/
  ├── weread-notes/notes/
  ├── weread-notes/daily/
  └── work-docs/
      ↓ 每天凌晨 4:10（indexer.py）
Meilisearch（北京:7700）
```

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

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

### 5.4 新闻管线（东京）

| 时间 | 脚本 | 内容 |
|:---:|:---|:---|
| 每天 2/8/14/20 点 | `fetch_tencent_news.py` | 腾讯新闻 |
| 每天 2/8/14/20 点 | `fetch_domestic_politics.py` | 国内时政 |
| 每天 3/9/15/21 点 | `fetch_news.py` | 国际新闻 |
| 每天 3/9/15/21 点 | `fetch_policy.py` | 政策 |
| 每天 3/9/15/21 点 | `fetch_research.py` | 研报 |
| 每小时 | `fetch_market.py` | 行情 |
| 3/9/15/21 点+5分 | `cn_merge.py` | 汇总精选 80 条 |
| 22:40 | `archive_daily_brief.py` | 归档到 Gitea |
| 23:50 | `fetch_market_daily.py` | 指数/汇率/数字货币 |
| 22:00 | `run_daily_digest.sh` | 灵感日报 |
| 22:00 | `run_daily_work_report.sh` | 工作日报 |
| 周日 8:30 | `run_weekly_reading_report.sh` | 阅读周报 |
| 周日 9:00 | `run_weekly_work_report.sh` | 工作周报 |

---

## 六、知识库 RAG 问答

### 架构

```
浏览器 nav.xybkwd.top/search.html
  ├─ 搜索 → /search-api/* → Caddy（东京）→ Beijing:7700（Meilisearch）
  └─ 问答 → /api/ask → Caddy（东京）→ Beijing:8100（kb_server.py）
                                    ├─ Meilisearch 检索（3 搜索词 × 6 篇，去重得 top 12）
                                    └─ DeepSeek API → 基于资料回答
```

### 关键参数

| 参数 | 值 |
|:---|:---|
| Meilisearch API | `http://localhost:7700`（北京） |
| 索引名 | `knowledge` |
| API Key | `m42-s8k-xybkwd-search-2026` |
| DeepSeek Key | `sk-bbca4a0380d549389f0d27cdea0b5228` |
| 模型 | `deepseek-v4-flash` |
| 单次成本 | ≈ ¥0.02 |
| 服务名 | `kb-qa`（systemd，端口 8100） |
| 北京安全组 | 需开放 7700、8100 给东京 IP |

**铁律**：AI 仅从 Meilisearch 索引内容回答，不访问互联网。不知道说不知道。

---

## 七、Tailscale VPN

| 节点 | IP | 系统 |
|:---|:---|:---:|
| 东京 vm-4-13-ubuntu | 100.111.102.100 | Linux |
| 北京 vm-0-12-ubuntu | 100.104.225.62 | Linux |
| 本机 fxy | 100.99.151.78 | Windows（与北京 direct 连接） |

- 版本：1.98.4
- 用户：fengxy07@

---

## 八、本机本地工具

### Ollama

| 项目 | 值 |
|:---|:---|
| API | `http://localhost:11434` |
| 模型 | `qwen3.5:9b`（6.3GB，IQ4_NL 量化） |
| 模型路径 | `D:\ollama\model_data\models\` |
| 调用 | `ollama run qwen3.5:9b` |
| API 调用 | `curl http://localhost:11434/api/generate -d '{"model":"qwen3.5:9b","prompt":"...","stream":false}'` |
| 上下文 | 65536 tokens |

**踩坑**：Ollama pull 需清除代理 `HTTP_PROXY=""`；桌面端和 CLI 抢端口 11434；路径用 Windows 反斜杠。

### Word/PDF → Markdown 工具

- `DocFormatter.exe`（桌面，11MB，独立 exe，无需 Python）
- 功能：doc2md 转换 + Ollama 去水印/规整排版
- 输出目录可选，保留子目录结构

### A股数据工具

| 数据 | 方法 |
|:---|:---|
| K线/财务 | mootdx TCP 7709（首选，不限速） |
| 龙虎榜/解禁/融资融券/大宗 | `datacenter-web.eastmoney.com`（本机可直连） |
| 东财其他 | `push2.eastmoney.com` ❌ TLS 失败，走 WebFetch |
| 实时行情 | `qt.gtimg.cn`（腾讯） |

---

## 九、Docker 服务（东京）

| 容器 | 端口 | 状态 |
|:---|:---:|:---:|
| memos | 5230 | 运行 13 天 |
| halo | 8090 | 运行 13 天 |
| vaultwarden | 8088（仅本机） | 健康运行 11 天 |
| calibre-web | 8083 | 运行 10 天 |
| webdav | 8766 | 运行 8 天 |
| freqtrade | 8081 | 运行 6 天 |
| freqtrade-swing | 8082 | 运行 6 天 |
| audiobookshelf | 13378 | 运行 4 天 |

**重启顺序**：数据依赖的服务（postgres/redis）→ 应用服务。重启请用 `docker restart <容器名>`。

---

## 十、故障排查速查

### 如果用户说"网站打不开"
1. 查 Caddy：`ssh 东京 && sudo systemctl status caddy`
2. 查对应 Docker 容器是否运行：`docker ps | grep <服务名>`
3. 查端口监听：`ss -tlnp | grep <端口>`
4. 最严重情况：**检查是否有人误开防火墙/安全组**。UFW 绝对禁用。

### 如果用户说"知识库搜不到"
1. 查北京索引器：`ssh 北京 && ls /home/ubuntu/backups/tokyo/repos/work-docs/`
2. 手动触发索引：`ssh 北京 && cd /home/ubuntu/kb && python3 indexer.py`
3. 查 Meilisearch：`curl http://localhost:7700/health`

### 如果用户说"问答不回复"
1. 查北京 QA 服务：`ssh 北京 && sudo systemctl status kb-qa`
2. 查日志：`ssh 北京 && sudo journalctl -u kb-qa --no-pager -n 20`
3. 查 DeepSeek API Key 是否有效

### 如果用户说"问答没归档"
1. 查北京归档文件：`ssh 北京 && ls /home/ubuntu/kb/qa-archive/2026-06/`
2. 查东京同步：`ssh 东京 && ls /tmp/qa-archive/2026-06/`
3. 手动同步：`ssh 东京 && /home/ubuntu/scripts/sync_qa.sh`

### 如果 Ollama 不工作
1. 查服务：`curl http://localhost:11434/api/tags`
2. 查模型列表：`ollama list`
3. 常见原因：桌面版抢占端口 11434，退出桌面版重试

---

## 十一、踩坑汇总（新智能体必读）

| # | 坑 | 症状 | 修复 |
|:---:|:---|:---|:---|
| 1 | Caddy `handle_path` | API 代理路径不对 | 用 `@matcher` + `handle @matcher` |
| 2 | Caddy 规则顺序 | `/api/ask` 被 `/api/*` 拦截 | 精确匹配放前面 |
| 3 | 服务监听 127.0.0.1 | 跨服务器连不上 | 改 `0.0.0.0` |
| 4 | `rsync --delete` | 删掉 .git 目录 | 同步到 Git 仓库时去掉 `--delete` |
| 5 | Ollama pull 被代理阻断 | 下载失败 | `HTTP_PROXY=""` 清除后再 pull |
| 6 | 模型默认上下文 4096 | 长文本被无声截断 | 设 `OLLAMA_CONTEXT_LENGTH=65536` |
| 7 | Windows Python 编码 | 中文输出乱码 | 加 `PYTHONIOENCODING=utf-8` |
| 8 | Git Bash 路径 | Windows 下路径不识别 | 用绝对路径调用 Python |
| 9 | UFW 防火墙 | 启用后所有服务崩溃 | **绝对不碰防火墙**，通过云控制台安全组管理 |
| 10 | 助理模式覆盖 | 已有功能被助理模式覆盖 | 涉及 `search.html` 等前端文件时做好备份 |

---

## 十二、关键路径与凭证位置

| 资源 | 位置 |
|:---|:---|
| 东京 SSH 密钥 | `C:\Users\32779\Desktop\保险箱\ssh_new.pem` |
| 北京 SSH 密钥 | `C:\Users\32779\Desktop\保险箱\BJ.pem` |
| Gitea 访问 | `gitea.xybkwd.top`（需认证） |
| Gitea API | `http://beast:bb731e...@localhost:3000/api/v1/`（东京内网） |
| Caddy 配置 | 东京 `/etc/caddy/Caddyfile` |
| 北京备份脚本 | `backup_tokyo_to_beijing.sh` |
| 知识库索引器 | 北京 `/home/ubuntu/kb/indexer.py` |
| QA API 服务 | 北京 `/home/ubuntu/kb/kb_server.py` / systemd `kb-qa` |
| 新闻管线脚本 | 东京 `/home/ubuntu/scripts/` |
| cron 任务 | 东京 `crontab -l -u ubuntu` |
| 北京→东京 SSH 密钥 | 北京 `~/.ssh/tokyo_key.pem` |
| 全景架构手册 | Gitea `fxy/server-ops/栖云数字城堡_全景架构手册.md` |
| 智能体交接手册 | Gitea `fxy/server-ops/智能体交接手册.md` |
| 播客系统手册 | 文体部工作区 `Audiobookshelf-全生命周期手册.md` |
| 工作空间记忆 | 本机 `C:\Users\32779\.workbuddy\MEMORY.md` |
| 本机项目目录 | `C:\Users\32779\WorkBuddy\2026-06-20-00-28-14\` |

---

## 十四、服务凭证速查

> ⚠️ 敏感信息，仅在必要时使用。所有凭证可查阅对应仓库的 credentials/ 目录。

| 服务 | URL | 账号 | 密码 / 密钥位置 |
|:---|:---|:---|:---|
| **播客 (Audiobookshelf)** | `podcast.xybkwd.top` | `root` | Vaultwarden 生成，查 vault.xybkwd.top |
| **WebDAV 日记** | `dav.xybkwd.top` | — | `server-ops/credentials/diary-webdav.md` |
| **Telegram 机器人** | — | — | `server-ops/credentials/telegram-bots.md` |
| **Gitea API** | `localhost:3000` | `beast` | `bb731ed7d0d267b98a1c7d082de6c8fc0329ac21` |
| **东京 SSH** | 43.163.225.30 | ubuntu | 桌面 `保险箱/ssh_new.pem` |
| **北京 SSH** | 81.70.93.78 | ubuntu | 桌面 `保险箱/BJ.pem` |

---

## 十三、关于冯先生的重要背景

- 正在参加 **90后四级副职培训班**（不是"浙大培训"），六周分段式：
  1. 渭南党校
  2. 延安干部学院
  3. 清华大学
  4. 太行春天
  5. 浙江大学
  6. 渭南党校（即将）
- 交易品种：ETH/USDT 永续合约，1x 杠杆
- 交易平台：freqtrade + Binance
- 写作中不准笼统称"浙大培训"，要称"90后四级副职培训班"或标注具体地点

---

*本手册由 WorkBuddy 于 2026-06-25 生成，内容基于全景架构手册 + 工作空间记忆 + 服务器实时状态。*
*建议每次基础设施变更后同步更新。*