# 本地部署说明（含 SOCKS5 代理 `socks5h://127.0.0.1:1080`） > **云服务器部署**：若主机在境外且可直连 `api.gateio.ws`，请将 `config.yaml` 中 `proxy.enabled` 设为 **`false`**，无需 SOCKS。详见 [`交易系统部署说明.md`](../交易系统部署说明.md) §8 与 [`多执行器与信号转发归档.md`](./多执行器与信号转发归档.md) §7。 本文说明如何在**本机**部署 **onchain_scout_gate**（Gate USDT 永续监控 + 可选 Gemma 漏斗 + Web 看板），并在访问 Gate 行情、企业微信等外网接口时使用 **本地 SOCKS5 代理**。环境变量统一使用 `**socks5h://127.0.0.1:1080`**（**h** = 主机名在代理端解析，等同 curl 的 `socks5h`，推荐）。端口 `**1080`** 与 Clash / v2rayN / Sing-box 等本地 SOCKS 入站一致。 --- ## 1. 前置条件 ### 1.1 系统与软件 | 项目 | 说明 | | ------ | ---------------------------------------------------------------------------- | | 操作系统 | Windows 10/11 或 Linux / macOS 均可 | | Python | **3.10+**（推荐 3.11 / 3.12） | | 代理客户端 | 本机已运行 **SOCKS5** 监听 `**127.0.0.1:1080`**（常见为 Clash / v2rayN 的「本地 SOCKS5 端口」） | | 浏览器 | 用于打开 `http://127.0.0.1:8088`（或你在 `config.yaml` 中配置的端口） | ### 1.2 代理必须可用（自检） 在启动本服务前，请先确认 **1080 端口 SOCKS5 已连通外网**（否则 Gate 行情请求会超时或 TLS 失败）。 **Windows PowerShell**（若已安装 `curl` 且 curl 支持 socks5h）： ```powershell curl -x socks5h://127.0.0.1:1080 -I "https://api.gateio.ws" --max-time 15 ``` 期望看到 HTTP 状态行（如 `HTTP/1.1 200` 或 `HTTP/2 302` 等），而不是长时间卡住或 `Connection refused`。 **说明**：`socks5h` 表示把 **DNS 也走代理**（推荐，避免 DNS 污染）。Python 侧下文使用等价思路。 --- ## 2. 获取代码与目录 将仓库（或 `onchain_scout` 目录）放到本机任意路径，例如： - Windows：`C:\opt\onchain_scout` - Linux：`/opt/onchain_scout` 下文以 `**onchain_scout` 为项目根目录**（即包含 `config.yaml`、`requirements.txt`、`app/` 的那一层）。 --- ## 3. Python 虚拟环境 ### 3.1 Windows（PowerShell） ```powershell cd C:\opt\onchain_scout python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -U pip pip install -r requirements.txt ``` 若执行策略禁止激活脚本： ```powershell Set-ExecutionPolicy -Scope CurrentUser RemoteSigned ``` ### 3.2 Linux / macOS ```bash cd /opt/onchain_scout python3 -m venv .venv source .venv/bin/activate pip install -U pip pip install -r requirements.txt ``` ### 3.3 SOCKS5 与 httpx 本项目通过 **httpx** 访问 Gate 行情（及按需的企业微信 Webhook）。走 **SOCKS5** 需要安装带 socks 依赖的 httpx。`requirements.txt` 中已使用： ```text httpx[socks]==0.27.2 ``` 若你曾单独安装过无 extras 的 `httpx`，请在本虚拟环境中重新执行： ```bash pip install -r requirements.txt ``` --- ## 4. 配置文件 `config.yaml` 1. 若不存在，从示例复制： ```bash copy config.example.yaml config.yaml ``` 2. 至少修改： - `auth.username` / `auth.password`：登录 Web 看板用（生产环境请使用强密码）。 - `wecom.webhook`：企业微信群机器人 Webhook（若暂不用推送，可先填占位，但**触发类推送**仍可能失败，可先关相关逻辑或接受报错日志）。 - `monitor.min_24h_quote_volume_usdt`：成交额过滤（默认一千万量级，按 README 说明）。 - `**gemma`**：若本机已装 Ollama 且要跑漏斗，将 `enabled: true` 并设置 `model`；否则保持 `enabled: false`。 - `**proxy**`：访问 Gate 行情需走本机 SOCKS 时，设 `proxy.enabled: true`，`proxy.url` 一般为 `**socks5h://127.0.0.1:1080**`（与 Clash 等本地 SOCKS 端口一致）。**本机 Ollama 不会使用该代理**。 3. **不要将** `config.yaml` **提交到公开仓库**（内含密钥与 Webhook）。 --- ## 5. 代理写入 `config.yaml`（推荐，无需环境变量） 在 `config.yaml` 根级增加或修改 `**proxy`** 段（与 `config.example.yaml` 一致）： ```yaml proxy: enabled: true url: "socks5h://127.0.0.1:1080" ``` 说明： - `**socks5h://**`：配置里可继续写（与 curl 习惯一致）。程序在创建 httpx 客户端时会**自动改成 `socks5://`**，因部分环境下 httpx/socksio 不认 `socks5h` 会报 `Unknown scheme`；改为 `socks5` 后由**本机解析 DNS** 再走 SOCKS。若仍异常，可直接在配置里写 `**socks5://127.0.0.1:1080`**。 - **作用范围**：**Gate 行情**相关 httpx 请求使用 `config.yaml` 中的 `proxy`；企业微信当前实现为直连。**不会**对 `gemma.ollama_base_url`（本机 Ollama）套代理。 - `**proxy.enabled: false`**：Gate 客户端仍可使用系统环境变量中的 `HTTP_PROXY` / `ALL_PROXY`（`trust_env=True`）；启用配置代理后则**固定走 `proxy.url`**，并 `trust_env=False`，避免与环境变量冲突。 --- ## 6. PM2 守护进程（推荐） ### 6.1 安装 PM2 需已安装 **Node.js**，然后全局安装 PM2： ```bash npm install -g pm2 ``` ### 6.2 准备虚拟环境与配置 1. 项目根目录已创建 `.venv` 且 `pip install -r requirements.txt` 完成。 2. `config.yaml` 已按上文填写（含 `proxy`、`app.port` 等）。 3. 确保存在目录 `**runtime/**`（用于日志与 SQLite；首次启动会自动创建亦可）。 ### 6.3 使用仓库内 `ecosystem` 启动 仓库提供 `**deploy/ecosystem.config.cjs**`： - `**cwd**`：自动设为项目根（`deploy` 的上一级）。 - `**script**`：根据操作系统选择 `**.venv/Scripts/python.exe`（Windows）** 或 `**.venv/bin/python`（Linux/macOS）**。 - `**args`**：`python -m app.main`，**监听地址与端口完全由 `config.yaml` 的 `app.host` / `app.port` 决定**，无需改 ecosystem 里的端口。 在项目根目录执行： ```bash cd /opt/onchain_scout # 或你的实际路径 pm2 start deploy/ecosystem.config.cjs pm2 status pm2 logs onchain-scout ``` 常用维护命令： | 命令 | 说明 | | --------------------------- | --------------------------- | | `pm2 restart onchain-scout` | 热重启（改 `config.yaml` 后需重启生效） | | `pm2 stop onchain-scout` | 停止 | | `pm2 delete onchain-scout` | 从进程列表移除 | | `pm2 save` | 保存当前进程列表 | | `pm2 startup` | 生成开机自启脚本（按屏幕提示执行一次） | 标准输出与错误会写入项目 `**runtime/pm2-out.log**`、`**runtime/pm2-error.log**`（见 ecosystem 内配置）。 ### 6.4 Windows 说明 在 **PowerShell** 或 **cmd** 中同样可使用 `pm2 start deploy\ecosystem.config.cjs`。若 `python.exe` 路径不对，请确认虚拟环境目录名为 `.venv` 且位于项目根。 --- ## 7. 前台启动（调试用） 不经过 PM2、仅本地调试时，**无需**再设置 `ALL_PROXY` 等环境变量（代理已由 `config.yaml` 的 `proxy` 段控制）： ```powershell cd C:\opt\onchain_scout .\.venv\Scripts\Activate.ps1 python -m app.main ``` `app.host` / `app.port` 以 `config.yaml` 为准。 --- ## 8. 验证 1. **代理**：本机 SOCKS 入站已监听；`config.yaml` 中 `proxy.enabled: true`。 2. **Web**：浏览器访问 `http://127.0.0.1:`，登录后「监控池配置」JSON 中应出现 `**proxy`** 字段（`enabled` / `url`）。 3. **Gate**：等待一个 `poll_interval` 周期，看日志是否仍有 TLS/连接错误；若有，尝试 `socks5` 或检查端口。 4. **Ollama**：`gemma.enabled: true` 时，访问 `127.0.0.1:11434` **不**走 `proxy.url`，一般无需 `NO_PROXY`。 --- ## 9. 常见问题（FAQ） ### Q1：`Connection refused` 连 Gate / 代理 - 本机代理未开或端口不是 **1080**。 - `proxy.enabled` 未设为 `true` 或 `proxy.url` 写错。 ### Q2：改了 `config.yaml` 不生效 - PM2 下需执行 `**pm2 restart onchain-scout`** 重新加载进程与配置。 ### Q3：企业微信推送失败 - 多为 Webhook 无效；若走代理仍失败，检查代理是否允许访问 `qyapi.weixin.qq.com`。 ### Q4：pip / git 走代理 - 与应用程序无关；可在安装依赖的终端自行 `export HTTPS_PROXY=...`（**不必**写进应用 `config.yaml`）。 --- ## 10. 备忘 ```bash cd /opt/onchain_scout pm2 start deploy/ecosystem.config.cjs && pm2 save ``` --- 文档版本：与仓库 `onchain_scout_gate` 当前结构对应；请以 `README.md`、`deploy/ecosystem.config.cjs`、`app/main.py` 为准。