diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..a36f642
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,21 @@
+# 本地真实配置（含 API 密钥），勿提交
+**/.env
+.env
+
+# 允许提交模板
+!**/.env.example
+!.env.example
+
+# Python
+**/__pycache__/
+**/*.pyc
+**/.venv/
+
+# 本地备份（可选，勿提交）
+**/.env.backup*
+**/.env.bak
+**/.env.local
+
+# 数据库与上传（运行时生成）
+**/*.sqlite
+**/crypto.db
diff --git a/README.md b/README.md
index 6e6977c..4f70f69 100644
--- a/README.md
+++ b/README.md
@@ -45,7 +45,12 @@ cd crypto_monitor
 | `crypto_monitor_gate_bot` | `GATE_*` | Gate 侧 **独立子账户 / 机器人**；文档中含 **趋势回调** 等策略说明 |
 | `crypto_monitor_okx` | `OKX_*` | OKX 永续；需 API Key / Secret / Passphrase |
 
-各目录根下配置 **`./.env`**（勿提交 Git），变量名以前缀区分，**不可混用**（例如在 Gate 项目中写 OKX 变量会导致代理与密钥不生效）。
+各目录根下：
+
+- **`.env.example`**：配置模板（**可** `git pull` 同步），新机执行 `cp .env.example .env` 后编辑。
+- **`.env`**：本机真实配置（**勿**提交 Git）；`app.py` 只读此文件。`git pull` **不会**覆盖 `.env`；升级前建议 `cp .env .env.backup.$(date +%Y%m%d)`。
+
+变量名以前缀区分，**不可混用**（例如在 Gate 项目中写 OKX 变量会导致代理与密钥不生效）。
 
 ---
 
@@ -74,15 +79,20 @@ cd crypto_monitor
 ## 六、推荐阅读顺序
 
 1. 克隆本仓库后，根据你实际交易的所，进入对应 **`crypto_monitor_*`** 目录。  
-2. 阅读该目录下的 **《部署文档.md》**（Ubuntu / PM2 / 代理 / `.env` 模板）。  
-3. 需要 **Gate 趋势回调** 规则时，阅读 [crypto_monitor_gate_bot/趋势回调策略说明.md](./crypto_monitor_gate_bot/趋势回调策略说明.md)。  
-4. 需要 **多账户一块看 + 紧急全平** 时，阅读 [manual_trading_hub](./manual_trading_hub/) 下 README 与部署文档。
+2. 在该目录执行 **`cp -n .env.example .env`** 并编辑 `.env`（填入 API 与密码等）。  
+3. 阅读该目录下的 **《部署文档.md》**（Ubuntu / PM2 / 代理 / 备份与升级说明）。  
+4. 需要 **Gate 趋势回调** 规则时，阅读 [crypto_monitor_gate_bot/趋势回调策略说明.md](./crypto_monitor_gate_bot/趋势回调策略说明.md)。  
+5. 需要 **多账户一块看 + 紧急全平** 时，阅读 [manual_trading_hub](./manual_trading_hub/) 下 README 与部署文档。
 
 ---
 
 ## 七、安全与合规
 
-- **切勿**将 `.env`、API Secret、SSH 私钥 `.pem` 等提交到版本库或公开渠道。  
+- **切勿**将 `.env`、`.env.backup*`、API Secret、SSH 私钥 `.pem` 等提交到版本库或公开渠道；仅 **`.env.example`** 可提交（占位符，无真实密钥）。
+
+### 从旧版仓库升级（曾把 `.env` 提交进 Git）
+
+在 **`git pull` 之前**，于每个策略目录备份：`cp .env .env.backup.$(date +%Y%m%d)`。pull 后若本地 `.env` 被误删，用备份恢复；再对照新的 **`.env.example`** 补全可能新增的变量名。  
 - 实盘前务必在 **`LIVE_TRADING_ENABLED=false`** 下验证页面与网络；API 权限与 IP 白名单遵循各交易所要求。  
 - 使用本仓库进行实盘交易的风险由使用者自行承担；请遵守当地法律法规与交易所用户协议。
 
diff --git a/crypto_monitor_binance/.env b/crypto_monitor_binance/.env.example
similarity index 89%
rename from crypto_monitor_binance/.env
rename to crypto_monitor_binance/.env.example
index dc645c4..bb71c57 100644
--- a/crypto_monitor_binance/.env
+++ b/crypto_monitor_binance/.env.example
@@ -1,3 +1,17 @@
+# =============================================================================
+# 环境配置模板（可提交 Git）。程序运行时只读取同目录下的 .env。
+#
+# 首次部署 / 新机：
+#   cp .env.example .env
+#   nano .env          # 填入真实密钥、端口、代理等
+#
+# 升级代码（git pull）前建议备份（.env 不在 Git 中，pull 不会覆盖）：
+#   cp .env .env.backup.$(date +%Y%m%d)
+#
+# 从备份恢复：
+#   cp .env.backup.YYYYMMDD .env
+# =============================================================================
+
 APP_ENV=production
 # 服务监听地址（云服务器通常用 0.0.0.0）
 APP_HOST=0.0.0.0
diff --git a/crypto_monitor_binance/README.md b/crypto_monitor_binance/README.md
index 844d44a..ecce38c 100644
--- a/crypto_monitor_binance/README.md
+++ b/crypto_monitor_binance/README.md
@@ -24,9 +24,12 @@ pip install flask requests ccxt werkzeug PySocks Pillow
 
 页面上的 **「当日资金(交易账户)」** 与 **「可开仓」可用 U** 仅统计 **Binance U 本位永续合约账户**（`fetch_balance` 的 `swap` / FAPI `assets` 中的 USDT），**不会**再用现货余额顶替。
 
-## 配置说明（`.env`）
+## 配置说明（`.env.example` → `.env`）
 
-项目启动时会加载**项目根目录**下的 `.env`。与 Binance 相关的常用变量：
+- **`.env.example`**：模板（可提交 Git）；首次：`cp .env.example .env` 后编辑。
+- **`.env`**：本机真实配置（勿提交）；`app.py` 只读此文件。`git pull` 不覆盖 `.env`；升级前可 `cp .env .env.backup.$(date +%Y%m%d)`。
+
+与 Binance 相关的常用变量：
 
 | 变量 | 说明 |
 |------|------|
@@ -39,7 +42,7 @@ pip install flask requests ccxt werkzeug PySocks Pillow
 | `EXCHANGE_DISPLAY_NAME` | 页面展示的交易所名称，默认 `Binance` |
 | `BINANCE_ACCOUNT_LABEL` | 推送文案中的账户备注 |
 
-其余变量（登录、企业微信、风控参数、数据库路径等）见仓库内 **`.env` 示例注释** 或 `app.py` 顶部默认值。
+其余变量（登录、企业微信、风控参数、数据库路径等）见 **`.env.example` 内注释** 或 `app.py` 顶部默认值。
 
 ## 本地运行
 
diff --git a/crypto_monitor_binance/ecosystem.config.cjs b/crypto_monitor_binance/ecosystem.config.cjs
index 65c1ffe..23e6255 100644
--- a/crypto_monitor_binance/ecosystem.config.cjs
+++ b/crypto_monitor_binance/ecosystem.config.cjs
@@ -27,7 +27,7 @@ module.exports = {
       autorestart: true,
       watch: false,
       max_memory_restart: "800M",
-      // app.py 会从项目根目录加载 .env，此处无需重复 env_file
+      // app.py 从项目根目录 .env 加载（由 .env.example 复制而来，勿提交 Git）
     },
   ],
 };
diff --git a/crypto_monitor_binance/使用说明.md b/crypto_monitor_binance/使用说明.md
index bf94b63..5897abc 100644
--- a/crypto_monitor_binance/使用说明.md
+++ b/crypto_monitor_binance/使用说明.md
@@ -24,7 +24,9 @@
 
 ## 2. 运行前必须配置（`.env`）
 
-至少检查以下项（具体键名以你仓库 `.env` 示例为准）：
+首次在本目录执行 **`cp .env.example .env`**，再编辑 `.env`（`.env` 勿提交 Git；`git pull` 不会改你的 `.env`，升级前建议 `cp .env .env.backup.$(date +%Y%m%d)`）。
+
+至少检查以下项（具体键名以 **`.env.example`** 为准）：
 
 | 类别 | 说明 |
 |------|------|
diff --git a/crypto_monitor_binance/部署文档.md b/crypto_monitor_binance/部署文档.md
index 49602e9..d9dd8ad 100644
--- a/crypto_monitor_binance/部署文档.md
+++ b/crypto_monitor_binance/部署文档.md
@@ -30,12 +30,18 @@
 ```bash
 mkdir -p /opt/crypto_monitor
 cd /opt/crypto_monitor
-# git clone ... 或解压同步的包
-cd crypto_monitor_binance
+git clone https://git.bz121.com/dekun/crypto_monitor.git
+cd crypto_monitor/crypto_monitor_binance
 ```
 
 下文用 **`/opt/crypto_monitor/crypto_monitor_binance`** 仅为示例，请换成你的实际绝对路径。
 
+拉取代码后，若目录下尚无 `.env`，先从模板生成（**勿**把填好密钥的 `.env` 提交 Git）：
+
+```bash
+cp -n .env.example .env    # -n：已存在 .env 时不覆盖
+```
+
 ---
 
 ## 2. 配置 SSH 私钥与 `~/.ssh/config`
@@ -112,11 +118,38 @@ export PYTHONDONTWRITEBYTECODE=1
 
 ---
 
-## 5. 配置 `.env`（关键：Binance + 代理）
+## 5. 配置环境变量（`.env.example` → `.env`）
 
-项目通过 `app.py` 启动时 **自动加载项目根目录的 `.env`**。与交易所相关的变量使用 **`BINANCE_`** 前缀（与代码一致）。
+| 文件 | 是否进 Git | 说明 |
+|------|------------|------|
+| **`.env.example`** | ✅ 是 | 变量模板与注释，可随 `git pull` 更新 |
+| **`.env`** | ❌ 否 | 本机真实配置；`app.py` **只读此文件** |
 
-至少确认：
+### 5.1 首次配置
+
+```bash
+cd /opt/crypto_monitor/crypto_monitor_binance
+
+cp -n .env.example .env    # 已存在 .env 时不覆盖
+nano .env                  # 填入 API、登录密码、端口、代理等
+```
+
+### 5.2 备份与 `git pull`
+
+- **`.env` 已被仓库根目录 `.gitignore` 忽略**：`git pull` **不会**覆盖或删除你本地的 `.env`。
+- 若远端更新了 **`.env.example`**（新增变量名），pull 后请对照模板，**手动把新行补进你的 `.env`**（不会自动合并进 `.env`）。
+- **建议在每次 `git pull` 或大批量改配置前备份**：
+
+```bash
+cp .env .env.backup.$(date +%Y%m%d)
+# 恢复示例：cp .env.backup.20260516 .env
+```
+
+- **换机 / 迁移**：用 `scp` 复制整份 `.env` 到新机器对应目录；或在新机重新 `cp .env.example .env` 后填写。
+
+### 5.3 必填项检查（Binance + 代理）
+
+与交易所相关的变量使用 **`BINANCE_`** 前缀（与代码一致）。至少确认：
 
 ```env
 APP_HOST=127.0.0.1
diff --git a/crypto_monitor_gate/.env b/crypto_monitor_gate/.env.example
similarity index 89%
rename from crypto_monitor_gate/.env
rename to crypto_monitor_gate/.env.example
index 42643b0..cf99c7c 100644
--- a/crypto_monitor_gate/.env
+++ b/crypto_monitor_gate/.env.example
@@ -1,3 +1,17 @@
+# =============================================================================
+# 环境配置模板（可提交 Git）。程序运行时只读取同目录下的 .env。
+#
+# 首次部署 / 新机：
+#   cp .env.example .env
+#   nano .env          # 填入真实密钥、端口、代理等
+#
+# 升级代码（git pull）前建议备份（.env 不在 Git 中，pull 不会覆盖）：
+#   cp .env .env.backup.$(date +%Y%m%d)
+#
+# 从备份恢复：
+#   cp .env.backup.YYYYMMDD .env
+# =============================================================================
+
 APP_ENV=production
 # 服务监听地址（云服务器通常用 0.0.0.0）
 APP_HOST=0.0.0.0
diff --git a/crypto_monitor_gate/README.md b/crypto_monitor_gate/README.md
index f400451..183f8c4 100644
--- a/crypto_monitor_gate/README.md
+++ b/crypto_monitor_gate/README.md
@@ -36,7 +36,10 @@ source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install flask requests ccxt werkzeug PySocks Pillow
 ```
 
-## 配置（`.env`）
+## 配置（`.env.example` → `.env`）
+
+- **`.env.example`**：模板（可提交 Git）；首次：`cp .env.example .env` 后编辑。
+- **`.env`**：本机真实配置（勿提交）；`git pull` 不覆盖；升级前建议备份（见《部署文档》§5.2）。
 
 项目启动时加载**仓库根目录**下的 `.env`。常用项：
 
@@ -51,7 +54,7 @@ pip install flask requests ccxt werkzeug PySocks Pillow
 | `WECHAT_WEBHOOK` | 企业微信机器人 |
 | `EXCHANGE_DISPLAY_NAME` / `GATE_ACCOUNT_LABEL` | 页面与推送展示的账户文案 |
 
-其余见 **`.env` 内注释** 或 **`app.py` 顶部默认值**。
+其余见 **`.env.example` 内注释** 或 **`app.py` 顶部默认值**。
 
 ## 本地运行
 
diff --git a/crypto_monitor_gate/ecosystem.config.cjs b/crypto_monitor_gate/ecosystem.config.cjs
index 3169e63..097bf52 100644
--- a/crypto_monitor_gate/ecosystem.config.cjs
+++ b/crypto_monitor_gate/ecosystem.config.cjs
@@ -27,7 +27,7 @@ module.exports = {
       autorestart: true,
       watch: false,
       max_memory_restart: "800M",
-      // app.py 会从项目根目录加载 .env，此处无需重复 env_file
+      // app.py 从项目根目录 .env 加载（由 .env.example 复制而来，勿提交 Git）
     },
   ],
 };
diff --git a/crypto_monitor_gate/使用说明.md b/crypto_monitor_gate/使用说明.md
index efa2164..118cfa1 100644
--- a/crypto_monitor_gate/使用说明.md
+++ b/crypto_monitor_gate/使用说明.md
@@ -24,7 +24,9 @@
 
 ## 2. 运行前必须配置（`.env`）
 
-至少检查以下项（具体键名以你仓库 `.env` 示例为准）：
+首次在本目录执行 **`cp .env.example .env`**，再编辑 `.env`（`.env` 勿提交 Git；`git pull` 不会改你的 `.env`，升级前建议 `cp .env .env.backup.$(date +%Y%m%d)`）。
+
+至少检查以下项（具体键名以 **`.env.example`** 为准）：
 
 | 类别 | 说明 |
 |------|------|
diff --git a/crypto_monitor_gate/部署文档.md b/crypto_monitor_gate/部署文档.md
index 35ee69a..36dcffa 100644
--- a/crypto_monitor_gate/部署文档.md
+++ b/crypto_monitor_gate/部署文档.md
@@ -27,12 +27,18 @@
 ```bash
 mkdir -p /opt/crypto_monitor
 cd /opt/crypto_monitor
-# git clone ... 或解压同步的包
-cd crypto_monitor_gate
+git clone https://git.bz121.com/dekun/crypto_monitor.git
+cd crypto_monitor/crypto_monitor_gate
 ```
 
 下文用 **`/opt/crypto_monitor/crypto_monitor_gate`** 仅为示例，请换成你的实际绝对路径。
 
+拉取代码后，若目录下尚无 `.env`：
+
+```bash
+cp -n .env.example .env
+```
+
 ---
 
 ## 2. 配置 SSH 私钥与 `~/.ssh/config`
@@ -109,11 +115,32 @@ export PYTHONDONTWRITEBYTECODE=1
 
 ---
 
-## 5. 配置 `.env`（关键：Gate + 代理）
+## 5. 配置环境变量（`.env.example` → `.env`）
 
-项目通过 `app.py` 启动时 **自动加载项目根目录的 `.env`**。与交易所相关的变量必须是 **Gate** 前缀（**不要**再写 OKX 变量，否则代理不会生效、密钥也不会被识别）。
+| 文件 | 是否进 Git | 说明 |
+|------|------------|------|
+| **`.env.example`** | ✅ 是 | 变量模板与注释，可随 `git pull` 更新 |
+| **`.env`** | ❌ 否 | 本机真实配置；`app.py` **只读此文件** |
 
-至少确认：
+### 5.1 首次配置
+
+```bash
+cd /opt/crypto_monitor/crypto_monitor_gate
+
+cp -n .env.example .env
+nano .env
+```
+
+### 5.2 备份与 `git pull`
+
+- **`.env` 不在 Git 中**：`git pull` **不会**覆盖本地 `.env`。
+- 远端若更新 **`.env.example`**，pull 后请**手动**把新增变量补进你的 `.env`。
+- **升级前备份**：`cp .env .env.backup.$(date +%Y%m%d)`；恢复：`cp .env.backup.YYYYMMDD .env`。
+- **换机**：`scp` 复制 `.env`，或新机 `cp .env.example .env` 后重填。
+
+### 5.3 必填项检查（Gate + 代理）
+
+与交易所相关的变量必须是 **Gate** 前缀（**不要**再写 OKX 变量，否则代理不会生效、密钥也不会被识别）。至少确认：
 
 ```env
 APP_HOST=127.0.0.1
diff --git a/crypto_monitor_gate_bot/.env b/crypto_monitor_gate_bot/.env.example
similarity index 86%
rename from crypto_monitor_gate_bot/.env
rename to crypto_monitor_gate_bot/.env.example
index bcb689a..2aac7e9 100644
--- a/crypto_monitor_gate_bot/.env
+++ b/crypto_monitor_gate_bot/.env.example
@@ -1,3 +1,17 @@
+# =============================================================================
+# 环境配置模板（可提交 Git）。程序运行时只读取同目录下的 .env。
+#
+# 首次部署 / 新机：
+#   cp .env.example .env
+#   nano .env          # 填入真实密钥、端口、代理等
+#
+# 升级代码（git pull）前建议备份（.env 不在 Git 中，pull 不会覆盖）：
+#   cp .env .env.backup.$(date +%Y%m%d)
+#
+# 从备份恢复：
+#   cp .env.backup.YYYYMMDD .env
+# =============================================================================
+
 APP_ENV=production
 # 服务监听地址（云服务器通常用 0.0.0.0）
 APP_HOST=0.0.0.0
@@ -119,6 +133,11 @@ AI_MODEL=huihui_ai/deepseek-r1-abliterated:latest
 # 开单风格默认值：trend / swing
 # DEFAULT_TRADE_STYLE=trend
 
+# 趋势回调策略（可选，见 趋势回调策略说明.md）
+# TREND_PULLBACK_DCA_LEGS=5
+# TREND_PULLBACK_PREVIEW_TTL_SECONDS=120
+# TREND_PREVIEW_MAX_BALANCE_DRIFT_PCT=5
+
 APP_TIMEZONE=Asia/Shanghai
 AUTO_TRANSFER_BJ_HOUR=8
 # TRADING_DAY_RESET_HOUR 现在表示「北京时间」整点，默认 8 点起算新交易日；开仓整点限制见 TRADING_DAY_RESET_OPEN_GUARD_ENABLED
diff --git a/crypto_monitor_gate_bot/ecosystem.config.cjs b/crypto_monitor_gate_bot/ecosystem.config.cjs
index f7ecf24..536fec5 100644
--- a/crypto_monitor_gate_bot/ecosystem.config.cjs
+++ b/crypto_monitor_gate_bot/ecosystem.config.cjs
@@ -27,7 +27,7 @@ module.exports = {
       autorestart: true,
       watch: false,
       max_memory_restart: "800M",
-      // app.py 会从项目根目录加载 .env，此处无需重复 env_file
+      // app.py 从项目根目录 .env 加载（由 .env.example 复制而来，勿提交 Git）
     },
   ],
 };
diff --git a/crypto_monitor_gate_bot/部署文档.md b/crypto_monitor_gate_bot/部署文档.md
index 0a84b24..79a76d5 100644
--- a/crypto_monitor_gate_bot/部署文档.md
+++ b/crypto_monitor_gate_bot/部署文档.md
@@ -27,12 +27,18 @@
 ```bash
 mkdir -p /opt/crypto_monitor
 cd /opt/crypto_monitor
-# git clone ... 或解压同步的包
-cd crypto_monitor_gate_bot
+git clone https://git.bz121.com/dekun/crypto_monitor.git
+cd crypto_monitor/crypto_monitor_gate_bot
 ```
 
 下文用 **`/opt/crypto_monitor/crypto_monitor_gate_bot`** 仅为示例，请换成你的实际绝对路径。
 
+拉取代码后，若目录下尚无 `.env`：
+
+```bash
+cp -n .env.example .env
+```
+
 ---
 
 ## 2. 配置 SSH 私钥与 `~/.ssh/config`
@@ -109,11 +115,32 @@ export PYTHONDONTWRITEBYTECODE=1
 
 ---
 
-## 5. 配置 `.env`（关键：Gate + 代理）
+## 5. 配置环境变量（`.env.example` → `.env`）
 
-项目通过 `app.py` 启动时 **自动加载项目根目录的 `.env`**。与交易所相关的变量必须是 **Gate** 前缀（**不要**再写 OKX 变量，否则代理不会生效、密钥也不会被识别）。
+| 文件 | 是否进 Git | 说明 |
+|------|------------|------|
+| **`.env.example`** | ✅ 是 | 变量模板与注释，可随 `git pull` 更新 |
+| **`.env`** | ❌ 否 | 本机真实配置；`app.py` **只读此文件** |
 
-至少确认：
+### 5.1 首次配置
+
+```bash
+cd /opt/crypto_monitor/crypto_monitor_gate_bot
+
+cp -n .env.example .env
+nano .env
+```
+
+### 5.2 备份与 `git pull`
+
+- **`.env` 不在 Git 中**：`git pull` **不会**覆盖本地 `.env`。
+- 远端若更新 **`.env.example`**，pull 后请**手动**把新增变量补进你的 `.env`。
+- **升级前备份**：`cp .env .env.backup.$(date +%Y%m%d)`；恢复：`cp .env.backup.YYYYMMDD .env`。
+- **换机**：`scp` 复制 `.env`，或新机 `cp .env.example .env` 后重填。
+
+### 5.3 必填项检查（Gate + 代理）
+
+与交易所相关的变量必须是 **Gate** 前缀（**不要**再写 OKX 变量，否则代理不会生效、密钥也不会被识别）。至少确认：
 
 ```env
 APP_HOST=127.0.0.1
@@ -134,7 +161,7 @@ GATE_SOCKS_PROXY=socks5h://127.0.0.1:1080
 
 说明：**推荐 `socks5h://`**，由 SOCKS 端解析域名，与 `curl --proxy socks5h://...` 行为一致。
 
-### 5.1 趋势回调策略（可选）
+### 5.4 趋势回调策略（可选）
 
 若使用「交易执行」页的 **趋势回调** 计划：
 
diff --git a/crypto_monitor_okx/.env b/crypto_monitor_okx/.env.example
similarity index 87%
rename from crypto_monitor_okx/.env
rename to crypto_monitor_okx/.env.example
index 62f9729..1c80cfe 100644
--- a/crypto_monitor_okx/.env
+++ b/crypto_monitor_okx/.env.example
@@ -1,3 +1,17 @@
+# =============================================================================
+# 环境配置模板（可提交 Git）。程序运行时只读取同目录下的 .env。
+#
+# 首次部署 / 新机：
+#   cp .env.example .env
+#   nano .env          # 填入真实密钥、端口、代理等
+#
+# 升级代码（git pull）前建议备份（.env 不在 Git 中，pull 不会覆盖）：
+#   cp .env .env.backup.$(date +%Y%m%d)
+#
+# 从备份恢复：
+#   cp .env.backup.YYYYMMDD .env
+# =============================================================================
+
 APP_ENV=production
 # 服务监听地址（云服务器通常用 0.0.0.0）
 APP_HOST=0.0.0.0
diff --git a/crypto_monitor_okx/ecosystem.config.cjs b/crypto_monitor_okx/ecosystem.config.cjs
index 0cff0d7..adf8ac4 100644
--- a/crypto_monitor_okx/ecosystem.config.cjs
+++ b/crypto_monitor_okx/ecosystem.config.cjs
@@ -27,7 +27,7 @@ module.exports = {
       autorestart: true,
       watch: false,
       max_memory_restart: "800M",
-      // app.py 会从项目根目录加载 .env，此处无需重复 env_file
+      // app.py 从项目根目录 .env 加载（由 .env.example 复制而来，勿提交 Git）
     },
   ],
 };
diff --git a/crypto_monitor_okx/部署文档.md b/crypto_monitor_okx/部署文档.md
index f9b6df4..b1a13b1 100644
--- a/crypto_monitor_okx/部署文档.md
+++ b/crypto_monitor_okx/部署文档.md
@@ -44,6 +44,7 @@ mkdir -p /opt/crypto_monitor/crypto_monitor_okx
 cd /opt/crypto_monitor
 tar -xzf crypto_monitor.tgz -C crypto_monitor_okx
 cd crypto_monitor_okx
+cp -n .env.example .env    # 若尚无 .env
 ```
 
 ---
@@ -127,14 +128,31 @@ export PYTHONDONTWRITEBYTECODE=1
 
 ---
 
-## 5. 配置 `.env`（本机）
+## 5. 配置环境变量（`.env.example` → `.env`）
 
-复制示例环境文件（仓库里通常有 `.env`；没有就自己创建）：
+| 文件 | 是否进 Git | 说明 |
+|------|------------|------|
+| **`.env.example`** | ✅ 是 | 变量模板与注释，可随 `git pull` 更新 |
+| **`.env`** | ❌ 否 | 本机真实配置；`app.py` **只读此文件** |
+
+### 5.1 首次配置
 
 ```bash
-cp .env .env.local  # 可选：备份
+cd /opt/crypto_monitor/crypto_monitor_okx
+
+cp -n .env.example .env    # 已存在 .env 时不覆盖
+nano .env
 ```
 
+### 5.2 备份与 `git pull`
+
+- **`.env` 不在 Git 中**：`git pull` **不会**覆盖本地 `.env`。
+- 远端若更新 **`.env.example`**，pull 后请**手动**把新增变量补进你的 `.env`。
+- **升级前备份**：`cp .env .env.backup.$(date +%Y%m%d)`；恢复：`cp .env.backup.YYYYMMDD .env`。
+- **换机**：`scp` 复制 `.env`，或新机 `cp .env.example .env` 后重填。
+
+### 5.3 必填项检查（OKX + 代理）
+
 至少确认/填写这些关键项（示例）：
 
 ```env
diff --git a/manual_trading_hub/README.md b/manual_trading_hub/README.md
index aa77bc1..6aeb436 100644
--- a/manual_trading_hub/README.md
+++ b/manual_trading_hub/README.md
@@ -30,7 +30,7 @@
 
 ### 与四个 `crypto_monitor_*` 目录的关系（已对照 `app.py`）
 
-各策略项目在**本目录**加载 `.env`（`load_env_file`），并用其中的 **`APP_HOST` / `APP_PORT`** 启动 **Flask 网页**（`app.py` 里 `HOST`、`PORT`）。这是你在浏览器里打开策略/监控后台用的端口，例如你截图里的 `APP_PORT=5001`。
+各策略项目在**本目录**用 **`.env`**（由 **`cp .env.example .env`** 生成，勿提交 Git；`git pull` 不覆盖）加载配置（`load_env_file`），并用其中的 **`APP_HOST` / `APP_PORT`** 启动 **Flask 网页**（`app.py` 里 `HOST`、`PORT`）。这是你在浏览器里打开策略/监控后台用的端口，例如 `APP_PORT=5001`。
 
 子代理 **不用 `APP_PORT`**，而是用环境变量 **`PORT`**（FastAPI/uvicorn 监听）。若子代理与 Flask 抢同一端口，后启动的会起不来，因此中控默认把子代理配在 **`15200`～`15203`**，与常见 `5000` 段 Flask 配置**错开**。
 
diff --git a/manual_trading_hub/scripts/start_agents_3screen.sh b/manual_trading_hub/scripts/start_agents_3screen.sh
index 6ed4c47..2a45f93 100644
--- a/manual_trading_hub/scripts/start_agents_3screen.sh
+++ b/manual_trading_hub/scripts/start_agents_3screen.sh
@@ -3,7 +3,7 @@
 # 用法：在任意目录执行  bash /path/to/manual_trading_hub/scripts/start_agents_3screen.sh
 # 若 hub 单独在 /opt/manual_trading_hub，四个策略目录在别的路径，请先：
 #   export MANUAL_TRADING_REPO_ROOT=/path/to/含_crypto_monitor_*_的目录
-# 依赖：各策略目录下存在 .env；manual_trading_hub/.venv 已 pip install -r requirements.txt
+# 依赖：各策略目录已 cp .env.example .env 并配置；manual_trading_hub/.venv 已 pip install -r requirements.txt
 # 日志：manual_trading_hub/logs/<会话名>.log（若 screen 里进程秒退，tail 该文件排查）
 # 查看：screen -ls    接入：screen -r mt-agent-bn   停：./stop_agents_3screen.sh
 
diff --git a/manual_trading_hub/scripts/后台运行-Ubuntu.md b/manual_trading_hub/scripts/后台运行-Ubuntu.md
index 0f2f25d..ffe5a73 100644
--- a/manual_trading_hub/scripts/后台运行-Ubuntu.md
+++ b/manual_trading_hub/scripts/后台运行-Ubuntu.md
@@ -1,5 +1,7 @@
 # Ubuntu 后台运行（中控 + 子代理）
 
+各 `crypto_monitor_*` 策略目录：首次 **`cp .env.example .env`** 并编辑；**`.env` 不进 Git**，`git pull` 不覆盖。升级前建议 `cp .env .env.backup.$(date +%Y%m%d)`。子代理启动前须 **`source` 该目录 `.env`**（见下文）。
+
 前台跑 `python agent.py` / `python hub.py` 时，关掉终端进程会结束。要**常驻后台**，可用下面三种之一（推荐 **systemd**）。
 
 ---
diff --git a/manual_trading_hub/部署文档.md b/manual_trading_hub/部署文档.md
index dc6f500..4253d93 100644
--- a/manual_trading_hub/部署文档.md
+++ b/manual_trading_hub/部署文档.md
@@ -15,7 +15,7 @@
 ## 二、前置条件
 
 1. 已安装 **Python 3.10+**，且 `pip` 可用。
-2. 各策略目录下已配置好交易所 API（与平时运行 Flask 时相同的 `.env` 或环境变量）。各项目 `app.py` 会读取同目录 `.env` 中的 **`APP_HOST` / `APP_PORT`** 用于 **Flask**；子代理使用环境变量 **`PORT`**，二者不能占用同一端口。
+2. 各策略目录下已配置好交易所 API：在对应 `crypto_monitor_*` 目录执行过 **`cp .env.example .env`** 并填好密钥（与平时运行 Flask 时同一份 **`.env`**，或等价环境变量）。各项目 `app.py` 会读取同目录 `.env` 中的 **`APP_HOST` / `APP_PORT`** 用于 **Flask**；子代理使用环境变量 **`PORT`**，二者不能占用同一端口。策略目录的 **`.env` 不在 Git 中**，`git pull` 不会覆盖；升级前建议在各策略目录 `cp .env .env.backup.$(date +%Y%m%d)`。
 3. 本机端口 **`15200`～`15203`、5100**（及你各策略 `.env` 里的 `APP_PORT`）无冲突；若被占用，须改子代理 `PORT` 并同步修改 `HUB_AGENTS`。
 4. **Linux 路径约定（可选）**：若部署在 Ubuntu 等环境，建议将整个代码树放在 **`/opt/crypto_monitor/`** 下（与 `scripts/后台运行-Ubuntu.md` 示例一致），例如策略目录为 `/opt/crypto_monitor/crypto_monitor_binance`、中控为 `/opt/crypto_monitor/manual_trading_hub`。
 
@@ -172,8 +172,9 @@ Windows 可将 `hub.py` 与各 `agent.py` 写入「启动」文件夹，或使
 
 ## 九、升级与回滚
 
-- **升级**：在 `manual_trading_hub` 下 `git pull`（若使用 Git）后，重新 `pip install -r requirements.txt` 即可。
-- **回滚**：恢复上一版本代码与依赖；配置仅环境变量与浏览器 localStorage，无数据库。
+- **升级**：在仓库根目录 `git pull` 后，于 `manual_trading_hub` 重新 `pip install -r requirements.txt`（若依赖有变）。**各策略目录 `.env` 不会被 pull 覆盖**；若 `.env.example` 有新增变量，请对照模板**手动补进**你的 `.env`。
+- **升级前备份（推荐）**：在每个用到的 `crypto_monitor_*` 目录执行 `cp .env .env.backup.$(date +%Y%m%d)`。
+- **回滚**：恢复上一版本代码与依赖；配置在各策略 `.env` 与浏览器 localStorage，无中控数据库。
 
 ---