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 <cursoragent@cursor.com>
2026-06-04 10:02:08 +08:00
parent 5e694ff795
commit 02bc3c14bc
8 changed files with 174 additions and 25 deletions
@@ -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
 ```
@@ -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)
@@ -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
 ```