sync: upstream + our customizations (dashboard, healthcheck, docs)

Synced from github/main: aebcfa2d copybot: live paper feed [skip ci] Our additions: serve_dashboard.py, bot_dashboard.html, mihomo-healthcheck.sh, 中文文档, 我们的钱包配置
2026-07-21 07:35:48 +08:00
parent aebcfa2d24
commit 125470b24a
388 changed files with 116727 additions and 14 deletions
@@ -0,0 +1,204 @@
+
+
+## 全局地图
+
+```
+服务器
+│
+├── /opt/winning-wallet-finder/          ← 项目代码（git clone 来的）
+│   ├── copybot.py                        ← bot 主程序
+│   ├── copybot.paper.json                ← paper 配置（跟哪些钱包、金额）
+│   ├── config.live.json                  ← live 配置（跟哪些钱包、金额）
+│   ├── copybot_state.json                ← paper bot 的账本（自动生成）
+│   ├── copybot_state.live.json           ← live bot 的账本（自动生成）
+│   ├── copybot_fills.jsonl               ← paper 成交记录
+│   ├── copybot_fills.live.jsonl          ← live 成交记录
+│   └── live/
+│       ├── serve_dashboard.py            ← 网页 dashboard 程序
+│       ├── bot_dashboard.html            ← 中文界面
+│       ├── copybot_live.json             ← paper bot 的实时 feed
+│       ├── copybot_live_real.json        ← live bot 的实时 feed
+│       ├── portfolio.py                  ← 回测程序
+│       ├── backtest.json                 ← 回测配置
+│       ├── daily.sh                      ← 每日流水线
+│       └── cache.duckdb                  ← 钱包历史数据缓存
+│
+├── /etc/systemd/system/                  ← systemd 服务定义（4 个）
+│   ├── copybot-paper.service             ← paper bot 服务
+│   ├── copybot-live.service              ← live bot 服务
+│   ├── copybot-dashboard.service         ← dashboard 服务
+│   └── mihomo.service                    ← 代理服务
+│
+├── /etc/copybot/                         ← 环境变量文件（密钥、代理）
+│   ├── paper.env                         ← paper bot 的环境变量
+│   └── live.env                           ← live bot 的环境变量
+│
+├── /etc/mihomo/                          ← 代理配置
+│   ├── config.yaml                       ← Clash 订阅配置
+│   └── cache.db                          ← 记住上次选的节点
+│
+├── /usr/local/bin/mihomo                 ← 代理程序本体（二进制）
+├── /opt/mihomo-healthcheck.sh            ← 代理健康检查脚本
+├── /opt/winning-wallet-finder/.netrc     ← Gitea PAT 认证（wwf 用户用，bot 自动 push 时读）
+│
+└── crontab                               ← 定时任务
+    ├── 0 2 * * * daily.sh                ← 每日 10:00 北京时间跑回测
+    └── */5 * * * * mihomo-healthcheck.sh ← 每 5 分钟检查代理
+```
+
+> `.netrc` 不在目录树里显示是因为它是隐藏文件（以 `.` 开头）。用 `ls -la` 才能看到。
+
+## 三个文件夹的分工
+
+| 文件夹                        | 放什么                     | 为什么在这                         |
+| ----------------------------- | -------------------------- | ---------------------------------- |
+| `/opt/winning-wallet-finder/` | 项目代码 + 配置 + 状态     | git clone 来的，所有代码在这       |
+| `/etc/systemd/system/`        | 服务定义（.service 文件）  | Linux 约定俗成，systemd 服务都放这 |
+| `/etc/copybot/`               | 环境变量（密钥、代理地址） | 敏感文件不放代码仓库，独立管理     |
+| `/etc/mihomo/`                | 代理配置                   | mihomo 的数据目录                  |
+
+> `/opt` 是你的代码，`/etc` 是系统配置。分开是因为**密钥不应该跟代码放一起**（怕 commit 到 Gitea 泄露）。
+
+## live.env 和 config.live.json 怎么连起来的
+
+它们**不在一个文件夹**，但 systemd 是桥梁：
+
+```
+/etc/systemd/system/copybot-live.service
+    │
+    │  ExecStart=python3 copybot.py --config config.live.json --live
+    │                                          ↑
+    │                              读 /opt/winning-wallet-finder/config.live.json
+    │                              （跟哪些钱包、金额、风险参数）
+    │
+    │  EnvironmentFile=/etc/copybot/live.env
+    │                    ↑
+    │              读 /etc/copybot/live.env
+    │              （私钥、代理地址、确认短语）
+    │
+    ▼
+copybot.py 启动时：
+  1. 从 EnvironmentFile 读 LIVE_PRIVATE_KEY -> 放进 config["live"]["private_key"]
+  2. 从 EnvironmentFile 读 HTTPS_PROXY -> 所有网络请求走代理
+  3. 从 --config 读 config.live.json -> 知道跟哪些钱包、bankroll 多少
+  4. 合并两者 -> 完整配置
+```
+
+简单说：
+
+| 文件               | 内容                       | 在哪                          | 谁读                                       |
+| ------------------ | -------------------------- | ----------------------------- | ------------------------------------------ |
+| `config.live.json` | 跟哪些钱包、金额、风险参数 | `/opt/winning-wallet-finder/` | `--config` 参数传给 copybot.py             |
+| `live.env`         | 私钥、代理、确认短语       | `/etc/copybot/`               | systemd `EnvironmentFile` 自动注入环境变量 |
+
+**为什么要分开**：config.live.json 可以 commit 到 Gitea（里面没有密钥），live.env 绝不能 commit（里面有私钥）。
+
+## 每个服务的完整启动链
+
+```
+paper bot:
+  systemd -> copybot.py --config copybot.paper.json
+           + EnvironmentFile: paper.env (ALCHEMY_RPC_URL)
+           = 直连 Polymarket，不走代理
+
+live bot:
+  systemd -> copybot.py --config config.live.json --live
+           + EnvironmentFile: live.env (LIVE_PRIVATE_KEY + HTTPS_PROXY + TRADE LIVE)
+           = 走代理绕 geo-block，真钱下单
+
+dashboard:
+  systemd -> serve_dashboard.py
+           = 读本地 JSON 文件（不涉及 Gitea），网页展示
+           - /api/feed  -> live/copybot_live.json (paper)
+           - /api/live  -> live/copybot_live_real.json (live)
+           - /          -> live/bot_dashboard.html (中文界面)
+
+mihomo:
+  systemd -> mihomo -d /etc/mihomo
+           = 代理服务，监听 127.0.0.1:7890
+```
+
+## bot 自动推 Gitea（自动备份 + 远程可读）
+
+bot 和 daily.sh 会自动把状态文件 commit + push 到 Gitea，**不需要你手动操作**。
+
+### 推什么
+
+| 推什么 | 频率 | 谁推的 | 目的 |
+|---|---|---|---|
+| `copybot_state.json` / `copybot_state.live.json` | 有状态变化时（节流） | bot 自动（`publish_feed()`） | 备份账本 |
+| `live/copybot_live.json` / `live/copybot_live_real.json` | 有状态变化时 | bot 自动 | 备份 feed |
+| `copybot_fills.jsonl` / `copybot_fills.live.jsonl` | 有成交时 | bot 自动 | 备份成交记录 |
+| `live/watch_sharps.json` + `watch_skilled.json` + `dashboard.html` + `portfolio.json` | 每天 1 次 | daily.sh 自动 | 刷新钱包池 |
+
+### 认证方式
+
+wwf 用户的 `.netrc` 文件（`/opt/winning-wallet-finder/.netrc`）里有 Gitea PAT，git push 时自动读，不需要手动输密码。
+
+### git log 里你会看到
+
+```
+copybot: live paper feed [skip ci]    ← bot 自动推的（每次有状态变化）
+fix: re-query order after cancel...    ← 你手动推的（改代码）
+docs: add 日常使用.md...               ← 你手动推的（改文档）
+```
+
+`[skip ci]` 表示跳过 CI（这个项目没配 CI，只是习惯标记）。
+
+### 这导致的副作用
+
+你在本地改完代码 `git push` 时经常被拒：
+
+```
+! [rejected] main -> main (fetch first)
+```
+
+因为服务器上的 bot 已经自动 commit 了新的 state。解决方法：
+
+```bash
+# 方法 1：rebase（推荐，保留你的改动）
+git pull --rebase --autostash origin main && git push origin main
+
+# 方法 2：强制用远程版本（会丢本地未提交的改动，慎用）
+git fetch origin && git reset --hard origin/main
+```
+
+### 远程读 JSON（不用 SSH 上服务器）
+
+Gitea 提供 raw URL，浏览器直接访问就能看 bot 的实时数据：
+
+```
+# paper bot feed
+https://code.aifunny.ltd/gavindiaz/winning-wallet-finder/raw/branch/main/live/copybot_live.json
+
+# live bot feed
+https://code.aifunny.ltd/gavindiaz/winning-wallet-finder/raw/branch/main/live/copybot_live_real.json
+
+# 钱包候选列表
+https://code.aifunny.ltd/gavindiaz/winning-wallet-finder/raw/branch/main/live/watch_sharps.json
+```
+
+> 但 raw JSON 不好看，建议还是用 dashboard（`http://45.207.206.36:18080/`）。
+
+### ⚠️ 注意：本地 Clash 会拦截直连 IP
+
+如果你本地开了 Clash Verge 系统代理，访问 `http://45.207.206.36:18080/` 可能被拦截（Clash 把直连 IP 也走了代理）。解决方法：
+
+1. **关掉 Clash 系统代理**（最简单）
+2. 或在 Clash 规则里加 `IP-CIDR,45.207.206.36/32,DIRECT`（让这个 IP 直连不走代理）
+
+---
+
+## 你日常改东西去哪改
+
+| 想改什么                    | 改哪个文件                                 | 在哪                          |
+| --------------------------- | ------------------------------------------ | ----------------------------- |
+| 跟哪些钱包 / 金额           | `copybot.paper.json` 或 `config.live.json` | `/opt/winning-wallet-finder/` |
+| 私钥 / 代理地址 / 确认短语  | `live.env`                                 | `/etc/copybot/`               |
+| Alchemy RPC                 | `paper.env`                                | `/etc/copybot/`               |
+| bot 程序参数（poll 间隔等） | `.service` 文件                            | `/etc/systemd/system/`        |
+| 代理节点 / 订阅             | `config.yaml`                              | `/etc/mihomo/`                |
+| 每日 cron 时间              | `crontab -e`                               | 系统                          |
+| dashboard 端口              | `.service` 文件加 `Environment="PORT=xxx"` | `/etc/systemd/system/`        |
+
+改完任何东西记得 `systemctl restart 对应服务`。