binance-trading-bot 快速上手全指南：从空服务器到首个实盘 Profile 的部署、配置与上线

• 金融科技
• 后端
• 前端

导读

本文是 binance-trading-bot 的官方入门路径（docs/get-started/index.md）的完整展开，按「安装部署 → 配置首个 Profile → 安全上线实盘」的有序三步带你走通从空服务器到一台真实运行的交易机器人的全过程。读完你将掌握：如何用 Docker Compose 一键拉起 Postgres、Redis 与主应用，如何创建 Binance API 密钥并正确绑定、如何理解 Profile / Symbol / Strategy / Order / Tick 这组核心概念、如何通过 Live gate 与预检清单安全地开启真实资金交易，以及如何用三级 Kill switch 在任何异常时紧急停机。

一、三步路线总览：从上到下依次完成

官方文档给出的路径强调「有序执行、自上而下」：不需要任何金融背景，每一步都链接着对应的用户指南（User Guide）做界面级细节讲解。三步总览如下：

二、第一步：安装与部署（约 30 分钟）

安装页（docs/get-started/install.md）承诺在一台干净机器上约 30 分钟完成首次部署，所有命令都集中在这一页，不需要跳到别处。部署完成后，生产环境叠加层与日常运维命令见 生产部署与运维，全部.env配置项见 环境变量。

2.1 前置条件

• 一台小型 Linux 服务器（便宜的虚拟机即可）：2 vCPU、4 GB 内存、20 GB 磁盘。
• Docker 24+ 与 Docker Compose 2.20+：应用运行在隔离容器中，无需手工安装任何依赖。
• 可访问的出站 HTTPS：到api.binance.com和wss://stream.binance.com（后者是推送行情的 WebSocket 地址）。
• 一个 Binance 账户：API 密钥在第 6 步创建。

2.2 Step 1 — 克隆仓库

git clone https://github.com/chrisleekr/binance-trading-bot.git cd binance-trading-bot

2.3 Step 2 — 创建.env

cp .env.example .env

.env是一个纯文本文件，存放设置与机密，应用在启动时读取。它包含密码，绝不能提交到版本库或对外分享。

编辑.env，把WEB_ORIGIN设置为你将打开应用的地址，例如WEB_ORIGIN=https://bot.example.com。在 Docker Compose 部署下，DATABASE_URL和REDIS_URL保持默认即可——compose 文件会提供网络内部的值（deploy/compose/docker-compose.yml 第 68-69 行即为app服务注入的默认连接串，指向postgres/redis两个服务名）。其余变量都有可用默认值，需要修改时参考 环境变量。

从仓库根目录的 .env.example 可以看到关键默认值（如第 24 行WEB_ORIGIN=http://localhost:5173面向本地开发），文件注释还说明了它的设计原则：占位值刻意很短（第 37 行AUTH_SECRET=REPLACE_ME），这样一份未编辑就直接使用的副本会在启动时失败，而不是带着一个公开已知的密钥启动。

2.4 Step 3 — 生成会话密钥

AUTH_SECRET用于对登录 Cookie 签名。启动时如果它短于 32 个字符，进程会直接失败，因此必须生成一个真正的密钥：

sed -i.bak "s|^AUTH_SECRET=.*|AUTH_SECRET=$(openssl rand -hex 32)|" .env && rm .env.bak

（openssl rand -hex 32生成 64 个十六进制字符，满足 Zod 校验的最小 32 字符要求，同时.env.example第 33-37 行的注释也印证了这一点。）

2.5 Step 4 — 启动整个技术栈

docker compose -f deploy/compose/docker-compose.yml --env-file .env up -d

注意：在仓库根目录直接执行裸docker compose up不生效——根目录没有 compose 文件，必须显式指定-f deploy/compose/docker-compose.yml。Postgres 和 Redis 会先启动，app服务会等待它们就绪（docker-compose.yml 第 94-98 行的depends_on使用condition: service_healthy，而不是简单的「已运行」）；数据库迁移在启动时自动执行，无需手工操作。

迁移自动化的实现位于 apps/server/docker-entrypoint.sh：容器入口在 exec 应用之前先运行幂等的迁移 runner（bun /app/dist/migrate.js），第 17-25 行显示只有SKIP_MIGRATIONS=1|true|yes时才跳过。多角色并发启动是安全的——迁移 runner 通过 Postgres advisory lock 串行化并发调用者（详见 生产部署与运维 的「Database migrations: boot vs. manual」小节）。

检查是否健康启动：

docker compose ps # 每个服务都显示 (healthy) curl -fsS http://127.0.0.1:9100/healthz # api 存活探针 curl -fsS http://127.0.0.1:9100/readyz # api 就绪探针（依赖 DB + Redis）

9100是 API 的ADMIN_PORT（默认值见 .env.example 第 78 行），专门承载未认证的/healthz、/readyz与/metrics，与公开端口分离，避免慢速抓取拖垮业务请求（环境变量 中ADMIN_PORT一行的说明）。

2.6 Step 5 — 创建运营者账号

在浏览器打开WEB_ORIGIN指向的地址，首次运行界面会引导你创建主账号。这是一个单运营者应用：没有邮件验证，也没有内置第二因素，其威胁模型详见 认证与威胁模型。从源码结构看，单运营者在每一层都被强制——onboarding 路由、user.create.beforehook、单点登录的disableImplicitSignUp以及数据库唯一索引（migration 0097）各自拒绝第二个运营者。

登录方式有两种，可在.env中切换：邮箱 + 密码（PASSWORD_SIGN_IN_ENABLED，默认开，密码至少 12 字符，仅存 scrypt 哈希），或通过 OpenID Connect 身份提供商（如 Auth0、Okta、Microsoft Entra）的单点登录（SINGLE_SIGN_ON_ENABLED，需要SINGLE_SIGN_ON_ISSUER_URL/CLIENT_ID/CLIENT_SECRET/PUBLIC_BASE_URL四个变量）。完整操作见 登录与安全。

2.7 Step 6 — 创建 Binance API 密钥

API 密钥是一对长字符串（一个 key 和一个 secret），让机器人可以在不接触你密码的情况下代你在 Binance 账户上操作。步骤如下：

1. 在 Binance 打开API Management，创建一个新密钥。
2. 同时开启"Enable Reading"（让机器人读取钱包余额与账户快照）和"Enable Spot & Margin Trading"（让它下单与撤单）。保持 "Enable Withdrawals" 关闭——机器人永远不需要它。权限的权威参考见 API 密钥页。
3. 开启Restrict access to trusted IPs only并添加你服务器的出口 IP（在 VM 上执行curl -s ifconfig.me获取）。这是最重要的安全步骤：即使密钥泄露，它也只在你的服务器上可用。

危险提示：机器人以明文存储 API 密钥。密钥以纯文本保存在数据库中，上面配置的 IP 白名单正是让泄露的密钥变得无用的关键防线。这一取舍在 认证与威胁模型 中有完整解释——系统默认不提供静态加密，缓解措施是操作者侧的「无提现权限 + IP 白名单」双保险：泄露的密钥既不能把资金转出交易所，也无法从其他 IP 下单。REST 客户端也只为需要签名的调用附加X-MBX-APIKEY头，未签名的市场数据读取在 worker 与 Binance 之间的任何代理或日志中都不携带凭据。

2.8 Step 7 — 在仪表盘绑定密钥

打开你账户的API keys页面，粘贴 key 与 secret。机器人会立即向 Binance 校验，通过则显示绿色状态。密钥绑定后服务端存储，界面永远不会再次显示完整 secret，只显示后 4 位字符；可以随时用Replace原位替换新密钥（API 密钥页）。

整个密钥配置流程端到端如下：

2.9 部署时最常调整的 env 变量速查

下表摘自 docs/operations/env-vars.md（由代码中的 env 目录自动生成，每个默认值都被断言过，因此不会声称应用并未应用的默认值）：

三、第二步：配置你的第一个 Profile

现在你要创建一个Profile（配置档）——一套独立的交易设置——并告诉它交易哪些币、投入多少钱。这是 docs/get-started/configure.md 的内容。

3.1 Profile 是什么

一个Profile打包了四样东西：

1. 一个策略（Strategy）——它遵循的交易规则书，见 策略对比。
2. 一份币种列表——允许交易的交易对，例如BTCUSDT、ETHUSDT。
3. 一份预算——它可以动用的资金上限。
4. 它自己的状态——每个 Profile 独立跟踪自己的持仓。

每个 Binance 账户可以同时运行多个 Profile，各自拥有独立的策略、币种和预算。它们共享账户的钱包，但独立决策：一个稳健的 Bitcoin Profile 和一个更活跃的山寨币 Profile 互不干扰。官方文档的示意图如下：

3.2 创建第一个 Profile（两步向导）

在仪表盘打开你的账户，选择New profile，一个两步向导带你完成创建。

第一步：为 Profile 命名。图为种子演示数据，并非真实账户。

• Name（名称）——任何好记的名字，例如 "BTC cautious"。

第二步：选择策略，然后点击Create profile。图为种子演示数据，并非真实账户。

• Strategy（策略）——它遵循的交易规则书。可以 对比三种策略 后选择与你的市场预期相匹配的那一种。

Profile 会以该策略的默认设置创建，所以两步就能得到一个可工作的 Profile。之后在其专属页面上微调：

• Strategy settings（策略设置）——所选策略特有的旋钮。表单由策略自身的 schema 渲染，所以你只会看到适用于当前选择的字段（这一点在 docs/concepts/strategies/index.md 与 Profile → Strategy 均有印证）。
• Coins（币种）——要交易的交易对。你也可以让机器人自动发现（discover）币种（见 Discovery），而不是手工罗列。

3.3 三种策略怎么选

官方策略总览（docs/concepts/strategies/index.md）给出三种策略的速览对比：

每种策略都只做「决策」，真正下单的是一个独立组件（executor），它保证即使进程崩溃订单也绝不会被重复放置。每种策略都假定一种不同的市场形态，选择你对该币种持有的预期即可：没有哪种策略在抽象意义上是「最安全」的，每种都承担着它所适配市场的风险。你之后可以更换策略，也可以在不同的 Profile 里同时运行不同策略。

3.4 通知（可选但强烈推荐）

Notifier（通知器）会在机器人买入、卖出或遇到问题时给你发消息。支持 Slack、Telegram 和 Webhook。配置一个，这样你就不必时刻盯着仪表盘——详见 Notifiers。

两类独立选择控制你的告警：通知发到哪里（你配置的 notifier）和哪些事件会触发（每个 Profile 的订阅设置，notify_events）。默认所有类别都开启（除order-filled——活跃网格的成交很频繁，默认关闭）。其中有几个是资金安全告警（daily-loss-halt日亏损熔断、loss-guard-halt亏损连胜与回撤保护），务必保持开启；edge-decay-warning是纯咨询性的——它从不暂停买入，只是提醒。

四、第三步：正式上线实盘

配置好 Profile 后，最后一步就是把它切换到真实资金交易。docs/get-started/go-live.md 这一页告诉你如何安全地开启、以及如何停止它。

警告：真实资金。一个上线 Profile 会在你的 Binance 账户上放置真实的买卖订单。第一次运行务必慢一点：一个 Profile、小预算、一两个你了解的币种。

4.1 预检清单

在启用一个实盘 Profile 之前，确认以下事项：

• API 密钥是绿色状态。账户的 API-keys 页面显示健康状态。红色密钥意味着权限错误或 IP 白名单不匹配——见 故障排查。
• Binance IP 白名单已开启（在安装时设置）。密钥万一泄露，这是你的主要防护。
• 已配置通知器。配置 Slack、Telegram 或 Webhook，这样不必盯屏也能知道交易与错误。一个没有任何通知器的实盘 Profile 会在仪表盘上警告你，因为真实资金的紧急情况否则将完全无声（worker 会额外写入一条 warn 级 action-log 记录「real-money ... fired but this profile has no enabled notifier」）。
• 预算足够小（首次运行），币种是你了解的。

4.2 检查 Live gate

每个 Profile 都有一个咨询性质的Live gate（上线门槛）——一种就绪检查，在你投入真实资金之前按你的质量标准给配置打分。它永远不会阻止你上线：它只是一个质量信号，而不是一把锁，即使检查失败或缺失你也可以实盘——门槛只是告诉你配置是否先被证明过自己。建议在 Backtest（回测） 之后查看 Profile 的 Live gate 小节。

Live gate 的核心字段（默认值均取自 docs/user-guide/profile/live-gate.md）：

上线之后还有Edge-decay monitor（边缘衰减监视器）持续观察：把实盘盈利因子与固定的回测基线比较。它从不为边缘衰减暂停买入——最多在仪表盘标记并发出一条提醒（默认Off，Warn模式在实盘盈利因子低于基线 ×0.85 时告警，低于 ×0.6 视为 breach）。

4.3 启用 Profile

新 Profile 默认禁用且不持有仓位。预检没问题后，从 Profile 的 Profile settings（Profile 设置） 小节启用它。此后 worker 会对 Profile 的币种逐 tick 执行策略并放置订单，从该币种的下一条来自 Binance 的行情更新开始。

观察第一笔实盘交易落地，然后在 仪表盘 和该币种的Logs标签页阅读机器人做了什么、为什么。仪表盘上每个买卖动作都带有原因说明（例如「价格跌至下一个网格档位」或「回调 3% 后追踪止损触发」），这是「为什么买/为什么卖」的第一查询位置。

4.4 知道如何停止它：三级 Kill switch

在第一次实盘交易之前，请阅读Kill switch（急停开关）。它是紧急停止：针对单币、单 Profile 或整个账户。它停止放置新的买卖订单，但不会卖出你已持有的仓位，也不会取消已挂在 Binance 上的订单（那些订单保持有效直到成交或你手动取消）。

几点值得注意：

• 单币 Pause 的7 天上限是刻意的：一个被遗忘的暂停不可能默默比你记住它的时间更久。暂停时币种页面会显示横幅，可随时提前释放。
• 账户级停止是客户端向每个 Profile 发起的「逐一禁用」扇出，并非单一原子操作，部分失败可能让某些 Profile 仍在交易。
• 自动入场熔断器——日亏损上限、连胜保护、回撤保护——是独立于 Kill switch 的另一套机制，它们会自动暂停新入场。
• 停止生效后你会在多处看到它：被停止 Profile 的仪表盘卡片显示kill-switch徽章、Profile 切换器与侧边导航标记、通过 MCP 读取时可见killSwitch字段、每次开/关都会写入该 Profile 的审计日志。

4.5 暂停 vs 删除 Profile

与 Kill switch 分开，Profile 还有自己的enable/disable开关。两者都会停止新订单；Kill switch 是快速的紧急停止，disable 是正常的关闭开关：

• Disable 一个 Profile——它停止做出新决策，但按设计保留 Binance 上已挂出的订单继续生效。适合临时暂停。
• Delete 一个 Profile——删除时会主动取消该 Profile 的实盘订单再移除它，因此不会留下「幽灵订单」。如果 Profile 仍有实盘订单或未平仓，应用会升级到处置步骤，提供两种安全选择：「先取消挂单再删除」或「把持仓移交另一个 Profile」。

4.6 保持安全与出问题时

• 保持 Binance IP 白名单开启。
• 配置 Notifier，不盯屏也能知道交易与错误。
• 定期备份——见 备份与恢复。
• 出问题时见故障排查的常见症状与修复。

五、一次讲清的核心术语

这些术语贯穿整个文档（源自 docs/get-started/index.md）：

• Profile（配置档）——一套独立设置：一个策略加上它适用的币种与预算。一个 Binance 账户可以同时运行多个 Profile。
• Symbol / pair（交易对）——一种币对另一种币计价，写作一个词。BTCUSDT表示「以 Tether（一种美元稳定币）计价的比特币价格」。
• Strategy（策略）——决定何时买入卖出的规则书。三种策略的对比见 概念 → 策略。
• Order（订单）——发给 Binance 的买入或卖出指令。可能立即成交，也可能挂在订单簿上等待价格到达。
• Tick（逐次行情处理）——机器人对某个币的一次完整决策周期，每次该币从 Binance 收到一条新的行情更新就执行一次。

从源码结构看，tick 正是 worker 的核心执行单元：worker 进程维护tick队列（worker/src/tick 目录承载逐 symbol 的 tick 处理），每次决策都「收集输入（最新价格、近期 K 线、钱包、你的设置）→ 运行策略规则 → 决定买入/卖出/等待 → 保存结果」，以便重启后干净恢复。策略只负责决策，单独的 executor 负责下单并保证即使跨崩溃也绝不重复下单——这就是每个策略都相同的 tick 形状（示意图见 策略总览）。

六、运行之后：常看页面与常见问题

• 用户指南——记录每一个界面与字段。
• 仪表盘——观察交易、阅读机器人为什么行动的窗口。顶栏的账户健康条（Account health）每 15 秒刷新，回答「我的钱现在是否安好」：Bot live / Bot down / N paused / N near limit / 今日已实现盈亏。
• 看起来不对时，使用Kill switch或查阅故障排查。

故障排查页（docs/operations/troubleshooting.md）的「机器人不交易」清单值得先背下来：Profile 是否启用？API 密钥是否绿色？买入条件是否真的满足（「什么都不做」也是合法且常见的决策，去 History → Logs 看每条 tick 的决定与依据数字）？是否有预算和余额？而对于「必须立刻停下」的场景，Kill switch 永远是第一答案——它立即暂停新交易，让你从容调查。

下一步：完成本指南的三步后，从 生产部署与运维 补齐生产叠加层（deploy/secrets/*三个密钥文件、TLS at the edge、TimescaleDB 升级、迁移机制与 Prometheus 告警规则），并在 用户指南 中逐一熟悉 Profile 的每个设置页，即可把这台机器人纳入正式的日常运维。

• 金融科技
• 后端
• 前端