From 02bc3c14bcf52ef0722fa05f40f77696a39170d4 Mon Sep 17 00:00:00 2001 From: dekun Date: Thu, 4 Jun 2026 10:02:08 +0800 Subject: [PATCH] docs: document four-exchange env sync script usage Add docs/env-sync-scripts.md; cross-link from deploy README, feature docs, README, and script headers. Co-authored-by: Cursor --- README.md | 4 +- deploy/README.md | 40 +++--- docs/auto-transfer-daily.md | 14 ++- docs/env-sync-scripts.md | 116 ++++++++++++++++++ docs/position-sizing-mode.md | 19 ++- scripts/sync_four_exchange_env.py | 2 + .../sync_four_exchange_position_sizing_env.py | 2 + scripts/sync_four_exchange_transfer_env.py | 2 + 8 files changed, 174 insertions(+), 25 deletions(-) create mode 100644 docs/env-sync-scripts.md diff --git a/README.md b/README.md index 7b27276..3276f2b 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,9 @@ cd crypto_monitor 会为各子项目创建 `.venv`、安装依赖、从 `.env.example` 生成 `.env`（不覆盖已有）。详见 **[deploy/README.md](./deploy/README.md)**。 -计仓模式（以损定仓 / 全仓杠杆，四所统一）：见 **[docs/position-sizing-mode.md](./docs/position-sizing-mode.md)**。 +四所 `.env` 同步脚本（计仓 + 自动划转）：见 **[docs/env-sync-scripts.md](./docs/env-sync-scripts.md)**。 +计仓模式（以损定仓 / 全仓杠杆）：见 **[docs/position-sizing-mode.md](./docs/position-sizing-mode.md)**。 +每日自动划转（双向归集至目标 U）：见 **[docs/auto-transfer-daily.md](./docs/auto-transfer-daily.md)**。 --- diff --git a/deploy/README.md b/deploy/README.md index 6eb7f8d..c523f82 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -85,31 +85,37 @@ bash deploy/setup_env.sh 3. 服务器长期运行见各目录 **《部署文档.md》**（SSH SOCKS、PM2）。 4. **多账户中控**（`manual_trading_hub`）：编辑 `manual_trading_hub/.env`（`HUB_PASSWORD`、`HUB_BRIDGE_TOKEN` 等与四实例一致），再 `pm2 start ecosystem.config.cjs`；验收 `bash manual_trading_hub/scripts/verify_hub_deploy.sh`。详见 [manual_trading_hub/部署文档.md](../manual_trading_hub/部署文档.md)、[常见问题.md](../manual_trading_hub/常见问题.md)。 -## 四所 `.env` 自动划转项（已有 .env 时） +## 四所 `.env` 同步脚本（已有 .env 时） -`AUTO_TRANSFER_AMOUNT` 等为交易账户目标余额（北京时间 8 点自动划入/划出，**持仓中不划转**并微信通知），与 `DAILY_START_CAPITAL` **独立**。若服务器上已有 `.env`，可合并写入（不覆盖 API 密钥）： +在仓库根目录用 Python 脚本**补全或更新**四所 `crypto_monitor_*` 下的 `.env`（不覆盖 API 密钥；无 `.env` 的目录会跳过）。 ```bash -# 计仓 + 划转一次同步（缺项补全，不覆盖已有 API 与自定义值） +cd /path/to/crypto_monitor +git pull + +# 推荐：计仓 + 自动划转 一次补全 python scripts/sync_four_exchange_env.py -# 或仅划转：缺 AUTO_TRANSFER_AMOUNT 时默认 50（否则沿用已有 / DAILY_START_CAPITAL） -python scripts/sync_four_exchange_transfer_env.py --set-amount 50 --enable-auto-transfer + +# 预览 +python scripts/sync_four_exchange_env.py --dry-run + +# 常见：划转目标 50U 并开启 + 计仓补全 +python scripts/sync_four_exchange_env.py --set-transfer-amount 50 --enable-auto-transfer + +# 无仓后切全仓杠杆 +python scripts/sync_four_exchange_env.py --set-mode full_margin + pm2 restart crypto-monitor-binance crypto-monitor-okx crypto-monitor-gate crypto-monitor-gate-bot ``` -详见 [docs/auto-transfer-daily.md](../docs/auto-transfer-daily.md)。 +| 脚本 | 作用 | +|------|------| +| `scripts/sync_four_exchange_env.py` | 一键：计仓 + 划转 | +| `scripts/sync_four_exchange_transfer_env.py` | 仅自动划转 | +| `scripts/sync_four_exchange_position_sizing_env.py` | 仅计仓模式 | -## 四所 `.env` 计仓模式项（已有 .env 时） - -`POSITION_SIZING_MODE` / `FULL_MARGIN_BUFFER_RATIO` 仅能通过 env 切换；切换模式前须**无持仓**： - -```bash -python scripts/sync_four_exchange_position_sizing_env.py -# 无仓后切全仓：python scripts/sync_four_exchange_position_sizing_env.py --set-mode full_margin -pm2 restart crypto-monitor-binance crypto-monitor-okx crypto-monitor-gate crypto-monitor-gate-bot -``` - -详见 [docs/position-sizing-mode.md](../docs/position-sizing-mode.md)。 +**完整参数、缺项默认值与示例**见 **[docs/env-sync-scripts.md](../docs/env-sync-scripts.md)**。 +功能说明：[计仓模式](../docs/position-sizing-mode.md)、[每日自动划转](../docs/auto-transfer-daily.md)。 ## 依赖说明 diff --git a/docs/auto-transfer-daily.md b/docs/auto-transfer-daily.md index 86aa402..db45d97 100644 --- a/docs/auto-transfer-daily.md +++ b/docs/auto-transfer-daily.md @@ -21,17 +21,25 @@ AUTO_TRANSFER_TO=swap AUTO_TRANSFER_BJ_HOUR=8 ``` +`AUTO_TRANSFER_AMOUNT` 与 `DAILY_START_CAPITAL`（每日开仓基数）**独立**。 + API Key 须具备万向划转权限（与手动划转相同）。 -## 部署 +## 用脚本更新四所 `.env` + +详见 **[env-sync-scripts.md](./env-sync-scripts.md)**。常用命令： ```bash git pull -# 四所补全划转项（已有值保留） + +# 仅补全划转相关项 python scripts/sync_four_exchange_transfer_env.py + # 目标 50U 并开启自动划转 python scripts/sync_four_exchange_transfer_env.py --set-amount 50 --enable-auto-transfer -# 计仓 + 划转一并同步 + +# 计仓 + 划转一并补全 python scripts/sync_four_exchange_env.py --set-transfer-amount 50 --enable-auto-transfer + pm2 restart crypto-monitor-binance crypto-monitor-okx crypto-monitor-gate crypto-monitor-gate-bot ``` diff --git a/docs/env-sync-scripts.md b/docs/env-sync-scripts.md new file mode 100644 index 0000000..5e4018f --- /dev/null +++ b/docs/env-sync-scripts.md @@ -0,0 +1,116 @@ +# 四所 `.env` 同步脚本说明 + +在**仓库根目录**执行。仅处理四所实例目录下的 `.env`，**不覆盖** API 密钥与已存在的自定义值；若某目录无 `.env` 会 `SKIP`（需先 `cp .env.example .env`）。 + +| 目录 | +|------| +| `crypto_monitor_binance` | +| `crypto_monitor_okx` | +| `crypto_monitor_gate` | +| `crypto_monitor_gate_bot` | + +修改 `.env` 后须 **`pm2 restart`** 对应实例后生效。 + +--- + +## 一键同步（推荐） + +`scripts/sync_four_exchange_env.py`：依次执行**计仓** + **自动划转** 两个子脚本。 + +```bash +cd /path/to/crypto_monitor +git pull + +# 仅补全缺失项（已有值保留） +python scripts/sync_four_exchange_env.py + +# 预览，不写文件 +python scripts/sync_four_exchange_env.py --dry-run + +# 划转目标 50U 并开启自动划转（计仓仍只补缺失项） +python scripts/sync_four_exchange_env.py --set-transfer-amount 50 --enable-auto-transfer + +# 无仓后切换全仓杠杆（须先确认交易所无持仓） +python scripts/sync_four_exchange_env.py --set-mode full_margin +``` + +| 参数 | 说明 | +|------|------| +| `--dry-run` | 只打印将做的变更，不写 `.env` | +| `--set-mode risk\|full_margin` | 强制四所 `POSITION_SIZING_MODE` | +| `--set-transfer-amount U` | 强制四所 `AUTO_TRANSFER_AMOUNT` | +| `--enable-auto-transfer` | 强制四所 `AUTO_TRANSFER_ENABLED=true` | + +--- + +## 仅自动划转 + +`scripts/sync_four_exchange_transfer_env.py` + +行为说明见 [auto-transfer-daily.md](./auto-transfer-daily.md)。 + +```bash +# 补全缺失项 +python scripts/sync_four_exchange_transfer_env.py +python scripts/sync_four_exchange_transfer_env.py --dry-run + +# 目标 50U 并开启 +python scripts/sync_four_exchange_transfer_env.py --set-amount 50 --enable-auto-transfer +``` + +| 参数 | 说明 | +|------|------| +| `--dry-run` | 预览 | +| `--set-amount U` | 强制 `AUTO_TRANSFER_AMOUNT` | +| `--enable-auto-transfer` | 强制 `AUTO_TRANSFER_ENABLED=true` | + +**缺项默认**（未使用 `--set-amount` 且文件中无该键时）： + +1. 若已有 `AUTO_TRANSFER_AMOUNT` → 保留 +2. 否则若存在 `DAILY_START_CAPITAL` → 沿用其值 +3. 否则 → **50** + +补全时会写入（若缺失）：`AUTO_TRANSFER_FROM=funding`、`AUTO_TRANSFER_TO=swap`、`TRANSFER_CCY=USDT`、`AUTO_TRANSFER_BJ_HOUR=8`；币安额外补 `BINANCE_FUNDING_INCLUDE_SPOT=false`。 + +--- + +## 仅计仓模式 + +`scripts/sync_four_exchange_position_sizing_env.py` + +行为说明见 [position-sizing-mode.md](./position-sizing-mode.md)。 + +```bash +# 补全缺失项（默认 risk、FULL_MARGIN_BUFFER_RATIO=0.98） +python scripts/sync_four_exchange_position_sizing_env.py +python scripts/sync_four_exchange_position_sizing_env.py --dry-run + +# 无仓后切全仓 +python scripts/sync_four_exchange_position_sizing_env.py --set-mode full_margin + +# 无仓后切回以损定仓 +python scripts/sync_four_exchange_position_sizing_env.py --set-mode risk + +# 强制缓冲比例 +python scripts/sync_four_exchange_position_sizing_env.py --set-buffer 0.98 +``` + +| 参数 | 说明 | +|------|------| +| `--dry-run` | 预览 | +| `--set-mode risk\|full_margin` | 强制 `POSITION_SIZING_MODE`（**须无持仓**后 restart） | +| `--set-buffer RATIO` | 强制 `FULL_MARGIN_BUFFER_RATIO` | + +--- + +## 部署后重启 + +```bash +pm2 restart crypto-monitor-binance crypto-monitor-okx crypto-monitor-gate crypto-monitor-gate-bot +``` + +## 相关文档 + +- [计仓模式](./position-sizing-mode.md) +- [每日自动划转](./auto-transfer-daily.md) +- [部署说明](../deploy/README.md) diff --git a/docs/position-sizing-mode.md b/docs/position-sizing-mode.md index 3c4d24c..eb2eb5f 100644 --- a/docs/position-sizing-mode.md +++ b/docs/position-sizing-mode.md @@ -32,13 +32,24 @@ FULL_MARGIN_BUFFER_RATIO=0.98 - 关键位：箱体突破、收敛突破、斐波自动单（添加时拒绝；已存在则启动时撤销）。 - 趋势回调、顺势加仓（策略入口返回明确错误）。 -## 部署 +## 用脚本更新四所 `.env` + +详见 **[env-sync-scripts.md](./env-sync-scripts.md)**。常用命令： ```bash git pull -# 四所 .env 补全计仓 + 划转（已有值不覆盖） + +# 仅补全计仓相关项（缺省 risk、缓冲 0.98） +python scripts/sync_four_exchange_position_sizing_env.py + +# 无仓后切换全仓 +python scripts/sync_four_exchange_position_sizing_env.py --set-mode full_margin + +# 无仓后切回以损定仓 +python scripts/sync_four_exchange_position_sizing_env.py --set-mode risk + +# 计仓 + 划转一并补全 python scripts/sync_four_exchange_env.py -# 或仅计仓：python scripts/sync_four_exchange_position_sizing_env.py -# 无仓后切换全仓：python scripts/sync_four_exchange_position_sizing_env.py --set-mode full_margin + pm2 restart crypto-monitor-binance crypto-monitor-okx crypto-monitor-gate crypto-monitor-gate-bot ``` diff --git a/scripts/sync_four_exchange_env.py b/scripts/sync_four_exchange_env.py index 4e4cde7..2723f06 100644 --- a/scripts/sync_four_exchange_env.py +++ b/scripts/sync_four_exchange_env.py @@ -10,6 +10,8 @@ 子脚本可单独运行： python scripts/sync_four_exchange_position_sizing_env.py python scripts/sync_four_exchange_transfer_env.py + +完整说明见 docs/env-sync-scripts.md """ from __future__ import annotations diff --git a/scripts/sync_four_exchange_position_sizing_env.py b/scripts/sync_four_exchange_position_sizing_env.py index 9011bc3..fe38410 100644 --- a/scripts/sync_four_exchange_position_sizing_env.py +++ b/scripts/sync_four_exchange_position_sizing_env.py @@ -10,6 +10,8 @@ 切换 POSITION_SIZING_MODE 须在交易所无持仓后执行，并 pm2 restart 对应实例。 不修改 API 密钥与其它自定义项；若 .env 不存在则跳过（请先从 .env.example 复制）。 + +完整说明见 docs/env-sync-scripts.md """ from __future__ import annotations diff --git a/scripts/sync_four_exchange_transfer_env.py b/scripts/sync_four_exchange_transfer_env.py index 85aad53..59c2cb0 100644 --- a/scripts/sync_four_exchange_transfer_env.py +++ b/scripts/sync_four_exchange_transfer_env.py @@ -9,6 +9,8 @@ python scripts/sync_four_exchange_transfer_env.py --enable-auto-transfer 不修改 API 密钥与其它自定义项；若 .env 不存在则跳过（请先从 .env.example 复制）。 + +完整说明见 docs/env-sync-scripts.md """ from __future__ import annotations