binance-trading-bot 环境变量完全指南:从 `.env` 配置到源码级校验机制

原创2026-10-14 08:40:251,396 阅读
文章标签:金融科技后端前端任务调度人工智能

binance-trading-bot 环境变量完全指南:从 .env 配置到源码级校验机制

本篇指南系统讲解 binance-trading-bot(一个基于插拔策略、支持历史回测并提供实时仪表盘的自动化 Binance 交易机器人)的全部进程级环境变量:如何写入 .env、每个变量的取值、默认值与生效时机,以及项目如何通过环境目录(env catalogue)、Zod schema 与 CI 门禁保证文档与真实解析行为永不漂移。读完本文,你将能独立完成本项目的部署配置、角色拆分、单点登录、MCP 控制面、并发调优与可观测性接入,并理解每一条配置在源码中的落点。

环境变量在项目中的定位

本项目的配置体系刻意做了分层:交易策略类配置(网格层级、指标参数、通知器、技术面门槛)不是环境变量,它们存放在数据库中,并在应用内编辑,参见 配置指南。而进程级配置则统一放在 .env 文件中:复制 .env.example 为 .env,编辑取值后重启整个栈即可生效。

# 复制示例文件
cp .env.example .env
# 编辑取值后重启(Docker Compose 方式)
docker compose -f deploy/compose/docker-compose.yml --env-file .env up

设置任何变量的通用方法:在 .env 中按 KEY=value 每行一条,然后重启。所有取值都会在启动时被校验:非法或缺失的必填值会以精确的错误信息中止启动,而不是让进程带病运行。

默认值从哪来:本文所有默认值并非手写维护,而是由代码中的环境目录(packages/core/src/env/catalogue.ts 中的 ENV_CATALOGUE)生成,并由 生成脚本 输出为 docs/_generated/config/env.md,再被本指南通过 include 机制引入。目录中标记为 _required_ 的变量没有默认值——缺失即启动失败。

值得强调的是:少部分变量并非由应用解析,而是被 Docker Compose 读取(如 POSTGRES_PASSWORD),或是在构建期被 Vite 打进 Web bundle(如 VITE_API_BASE_URL),相关行中会明确标注。

默认值一致性如何被源码保证

本项目的环境变量文档与真实解析行为之间有一套完整的"防漂移"机制,这是理解下表可信度的关键:

  1. 单一事实来源:ENV_CATALOGUE 拥有全部说明性文案(description / when / expect 为必填字段,生成器会拒绝输出空说明的条目),而 Zod schema 拥有真实的解析默认值(api 在 apps/api/src/env.ts,worker 在 apps/worker/src/env.ts)。
  2. 测试钉死:每个应用都有 env-docs 测试(参见 worker 侧测试、api 侧对应测试),用空环境走真实 schema 解析,逐一断言文档中声明的默认值与 schema 实际产出一致。凡是文档默认值与 schema 默认值存在合理差异的条目(例如布尔开关 LIVE_DEMO 文档写 off、schema 解析出 false),必须声明 defParsed 让断言依然落到真实值上;文档标记为 required 的变量,测试会逐个删掉它再断言启动解析抛错。
  3. CI 门禁:no-phantom-env-var.sh 用 TypeScript AST 静态扫描全仓库的 process.env 读取点,任何未登记进 ENV_CATALOGUE 的"幽灵变量"都会让 CI 变红;no-stale-env-contract.sh 则钉住 env-contract.json(供 Helm chart 检查其 ConfigMap/Secret 是否覆盖全部环境变量面)。

因此本文表中的任何默认值,都等价于"应用实际会应用的值"。

必填变量(Required)

变量 作用 取值 默认值 何时设置 预期效果
AUTH_SECRET 签名登录会话 Cookie 64 位十六进制字符 required 每次部署都必须设置。用 openssl rand -hex 32 生成,绝不在实例间复用 无默认值。长度不足 32 字符时启动失败。修改它会令所有既有会话失效,你会被强制登出
WEB_ORIGIN 允许 CORS、登录 CSRF 与 WebSocket 升级的浏览器来源(逗号分隔、精确匹配、不支持通配符) 逗号分隔的 origin,无通配符 required 始终设置。设为你在浏览器打开应用的地址,如 https://bot.example.com;多 origin 时逗号分隔 无默认值。为空或含 * 时启动失败——带凭证的 CORS 禁止通配符。配置不匹配的典型症状是页面能加载但无法登录
DATABASE_URL Postgres 连接串,每个进程都会读取 Postgres 连接串 required 始终设置,除非使用内置 Compose Postgres(compose 文件提供网络内默认值) 无默认值。未设置时启动崩溃,而不是悄悄连到 localhost
REDIS_URL 作业队列与缓存的 Redis 连接串 Redis 连接串 required 始终设置,除非使用内置 Compose Redis。Redis 需要认证时包含密码:redis://:pw@host:6379 无默认值。未设置时启动崩溃,原因与数据库连接串相同
POSTGRES_PASSWORD 内置 Postgres 容器初始化时使用的密码 任意字符串 postgres(生产 overlay 改用 secret 文件) 任何 Compose 部署都应设置,并在暴露前改掉出厂值 .env.example 出厂值为 postgres。生产 overlay 改读 deploy/secrets/* 文件并忽略此变量。首次启动后再修改不会改变既有数据库密码——容器只初始化一次

源码侧印证:AUTH_SECRET 的 32 字符下限由 apps/api/src/env.ts 的 z.string().min(32) 强制;WEB_ORIGIN 先按逗号拆分、trim、过滤空项,再拒绝任何含 * 的条目(Better Auth 会把 trustedOrigins 中的 * 当成 CSRF 通配符,而 CORS 与 WS 检查是字面匹配,通配符只会悄悄放松认证这一道门);DATABASE_URL / REDIS_URL 由共享字段 packages/core/src/env/schema.ts 的 z.string().min(1) 解析——注释明确写道"缺失值必须让启动崩溃,而不是用 ?? 兜底悄悄连到 localhost"。

运行时(Runtime)

变量 作用 取值 默认值 何时设置 预期效果
NODE_ENV 选择开发/生产框架行为 development、test、production development 很少需要——容器镜像已设置。在镜像外运行应用时设为 production 开发模式输出更冗长的框架日志并禁用部分缓存
LOG_LEVEL worker(栈中最吵的进程)的日志详细度 fatal、error、warn、info、debug、trace info 调试期间使用,之后调回 debug/trace 会淹没 stdout,繁忙账户下可能写满磁盘;warn 及以上会隐藏你通常需要的例行决策日志
ROLE 本进程运行哪些监听器与消费者 all、api、worker、study all 仅在跨容器拆分栈时使用。单机默认在一个进程里跑全部 all 在一个事件循环上运行 api、实时 worker 与回测消费者,这正是下方调优默认值偏保守的原因。拆成 api + worker + study 能让长回测不占用交易循环。只有 api 角色执行数据库迁移
LIVE_DEMO 将实例变成公开、免登录的沙箱 1 或 true 开启,其他值关闭 off(布尔解析,schema 默认 false) 仅在一次性公开演示机上使用,绝不在持有密钥的实例上使用 为每个匿名请求注入 demo operator;封锁凭据、通知器、备份/恢复、账户创建、账户重命名/删除、留存变更、诊断启动、费用对账与归档回填等路由;抑制所有通知发送;若存在任何连接真实 Binance 的账户则拒绝启动。交易仍可在 Binance testnet 交互。只有 1/true 能开启
MCP_ENABLED 挂载经过认证的 MCP 控制面,供 AI Agent 驱动机器人 1 或 true 开启 off 仅当你希望 Claude Code 或 ChatGPT 读取并交易此实例时。它是公网可达的交易面,开启前请先读 MCP 架构文档 关闭时 /api/mcp 路由根本不挂载、不发布任何受保护资源元数据——不存在需要防守的 Agent 面。开启后路由挂在 OAuth 2.1 bearer 授权之后,并要求 MCP_RESOURCE_URL。LIVE_DEMO 开启时强制拒绝此选项
MCP_RESOURCE_URL Agent 绑定访问令牌的规范资源标识,通常为 https://<your-host>/api/mcp 无查询串/片段/内嵌凭据、无尾斜杠的绝对 https URL required(MCP_ENABLED 关闭时可省,开启时必填) 只要 MCP_ENABLED 为真 必须是 Agent 实际能访问的 URL,而非内部或容器地址:令牌按此精确字符串绑定受众,与公网主机名不一致会得到毫无解释的 401。尾斜杠自动去除。必须 https——此值同时也是认证基础 URL,issuer、JWKS 文档与每个授权端点都跟随它;仅当主机为 loopback(localhost、127.0.0.0/8、[::1])时允许明文 http(本地开发场景,字节不出机器)。MCP_ENABLED 为真而缺失、URL 非法、非 loopback 主机上的明文 http、或携带查询串/片段/userinfo,均启动失败
PUBLIC_WEB_URL 用于在操作者通知里构建点开链接的基础 URL 无尾斜杠的绝对 URL required(可选:不设置则通知不带链接) 当你希望 Slack 或 Telegram 告警直接链到相关页面时 可选。不设置通知照常发送,只是没有链接。尾斜杠自动去除。非法 URL 启动失败

源码侧印证:布尔开关统一走 packages/core/src/env/schema.ts 的 booleanEnvFlag()——只有字面量 1 或 true(大小写不敏感)解析为真,false、0、未设置乃至任何其他字符串都是假,这是对 z.coerce.boolean()(会把任意非空字符串视为真)的刻意修正。MCP_RESOURCE_URL 的校验链在 apps/api/src/env.ts 中层层 refine:isSecureResourceOrigin(https 或 loopback 上的 http)、isBareResourceIdentifier(无 query/hash/userinfo)、尾斜杠修剪,以及 MCP_ENABLED && LIVE_DEMO 互斥(demo 模式为匿名请求注入 operator 身份,挂载 MCP 等于把整套 OAuth 授权服务器暴露在无需证明任何身份的门前)。

登录(Sign-in)

变量 作用 取值 默认值 何时设置 预期效果
PASSWORD_SIGN_IN_ENABLED 登录页是否提供邮箱+密码表单 1、true、0、false;任何其他值启动失败 on(布尔解析,schema 默认 true) 当 SSO 已可用、你希望身份提供商(及其 MFA)成为唯一入口时关闭 关闭后表单隐藏,密码登录/注册端点返回 404。拼错的值直接启动失败而非悄悄关掉表单。此变量与 SINGLE_SIGN_ON_ENABLED 至少一个为真。若 SSO 在启动时不可达且无其他方式可登录,本次运行会自动回退启用密码登录并发出安全告警——实例永不会被锁死。reset-password 命令两种情况下都可用
SINGLE_SIGN_ON_ENABLED 通过 OpenID Connect 提供商(如 Auth0)提供"SSO 登录" 1 或 true 开启 off 当你希望身份提供商及其 MFA 守护登录时 开启时要求 SINGLE_SIGN_ON_ISSUER_URL、SINGLE_SIGN_ON_CLIENT_ID、SINGLE_SIGN_ON_CLIENT_SECRET 与 PUBLIC_BASE_URL,并与 LIVE_DEMO 互斥。提供商在启动时以 5 秒为限探测:不可达时应用仍会启动但按钮禁用、发出安全告警,待提供商恢复响应后进程退出重启以完成注册——这依赖容器重启策略(prod/scale compose 中的 restart: unless-stopped),无策略时 api 会保持停止。只有创建 operator 的身份(或之后在 Settings > Security 中关联的身份)能登录,他人无法通过它注册账户
SINGLE_SIGN_ON_ISSUER_URL 身份提供商的 issuer,例如 https://your-tenant.auth0.com/ 与提供商发布内容逐字符一致的绝对 https URL required(SSO 关闭时可省) 只要 SINGLE_SIGN_ON_ENABLED 开启 与提供商发现文档及每个 ID token 中的 issuer 逐字符比对,所以保留 Auth0 的尾斜杠。不一致会在启动时禁用 SSO。仅 loopback 主机允许明文 http
SINGLE_SIGN_ON_CLIENT_ID 向身份提供商标识本应用 在提供商处创建的应用 client ID required(SSO 关闭时可省) 只要 SINGLE_SIGN_ON_ENABLED 开启 错误值会让提供商拒绝登录;应用记录失败,登录页显示普通错误
SINGLE_SIGN_ON_CLIENT_SECRET 向提供商证明登录请求确实来自本应用 在提供商处创建的应用 client secret required(SSO 关闭时可省) 只要 SINGLE_SIGN_ON_ENABLED 开启 只存在于环境中、绝不入库,被偷的会话也无法读取或修改它。在提供商侧轮换后需重启应用加载新值
SINGLE_SIGN_ON_BUTTON_LABEL SSO 按钮文案,例如 Sign in with Auth0 1 到 40 个字符 Single sign-on 想让按钮显示你的提供商名称时 仅当 SSO 开启时显示。为空或超过 40 字符启动失败
PUBLIC_BASE_URL 浏览器视角访问本应用的地址 仅 origin,如 https://bot.example.com:scheme、host 与可选端口,不含路径 required(SSO 关闭时可省) 只要 SINGLE_SIGN_ON_ENABLED 开启。在提供商侧注册 <PUBLIC_BASE_URL>/api/auth/callback/oidc 为回调 URL SSO 回调地址由此值构建、绝不取自请求头,因此代理或伪造的 Host 头无法把登录重定向到别处。除 loopback 外必须 https;与 MCP_RESOURCE_URL 同时设置时二者 origin 必须一致

源码侧印证:PASSWORD_SIGN_IN_ENABLED 用 z.enum(['0','1','true','false']).default('1') 严格解析(注释强调"默认开启时宽松解析会把 yes 这种拼错悄悄变成关闭,唯一症状是表单消失");SSO 四项联动、与 LIVE_DEMO 的互斥、以及 PUBLIC_BASE_URL 必须为纯 origin(parseUrl(v)?.origin === v)均由 apps/api/src/env.ts 的多个 .refine() 在启动期强制;SINGLE_SIGN_ON_ISSUER_URL 特意"原样保留(含尾斜杠)"以逐字节匹配 iss 声明。完整的登录与安全操作说明见 sign-in-and-security.md。

HTTP 与管理端口

变量 作用 取值 默认值 何时设置 预期效果
PORT 服务 API 与单页应用的端口 端口号 3000 当 3000 在宿主机上被占用时 必须与管理端口不同,否则以清晰报错启动失败而非端口占用崩溃
ADMIN_PORT api 的健康与指标端点端口 端口号 9100 当 9100 被占用时。与公网端口分离,避免慢速抓取饿死它 提供 /healthz、/readyz、/metrics,全部无需认证
ADMIN_HOST api 管理服务器绑定的网卡 接口地址 127.0.0.1 在 Kubernetes 上设为 0.0.0.0 以便 kubelet 探针访问 Pod IP 默认只绑 loopback,把无需认证的管理端点留在局域网外。若放开,请用 NetworkPolicy 限制端口——Service 不是防火墙
WORKER_ADMIN_PORT worker 的健康与指标端点端口 端口号 9101 当 9101 被占用时 默认比 api 大 1,便于开发时两者共宿主机。Compose 内每个容器有自己的 loopback,因此理论上可共享端口
WORKER_ADMIN_HOST worker 管理服务器绑定的网卡 接口地址 127.0.0.1 在 Kubernetes 上,原因同上 默认 loopback;放宽时同样适用 NetworkPolicy 提醒
APP_HTTP_PORT Compose 下应用发布的宿主机端口 宿主机端口号 80——未设置时基础/scale compose 发布 3000,production 文件发布 80 想在非默认端口发布时(如反向代理后面的 8080) 仅 Compose 读取,应用本身从不读它

源码侧印证:PORT !== ADMIN_PORT 的互斥由 api schema 的 .refine() 在环境解析期强制(见 apps/api/src/env.ts),其注释说明两个监听器(公网 PORT 与管理 ADMIN_PORT)的端口冲突会在解析时报清晰错误而非 EADDRINUSE。worker 侧 schema 在 apps/worker/src/env.ts 中默认 9101,注释点明与 api 的 9100 错开是让 bun run dev 宿主机开发开箱即用。

数据库

变量 作用 取值 默认值 何时设置 预期效果
POSTGRES_DB 内置 Postgres 首次启动时创建的数据库名 Postgres 标识符 binance_trading_bot(仅 Compose) 很少需要。只能在首次启动前修改——之后无效 仅 Compose。应用从连接串读取库名而非此处,只改其一不改另一会断连
POSTGRES_USER 内置 Postgres 首次启动时创建的超管用户 Postgres 标识符 postgres(仅 Compose) 很少需要,且只能在首次启动前 仅 Compose,与库名同样受"仅首启生效"限制
PGSSLMODE 备份/恢复命令使用的 libpq SSL 模式 disable、allow、prefer、require、verify-ca、verify-full prefer 当 Postgres 位于 TLS 之后、希望备份要求或校验 TLS 时 仅作用于 pg_dump / pg_restore——应用自身驱动的 SSL 配置独立,完全忽略此变量。.env.example 为本地明文 Postgres 出厂 disable
API_DB_POOL_MAX api 进程最多打开的 Postgres 连接数 正整数 10——硬编码于 packages/db/src/pool.ts,无 zod schema 解析 当 Postgres 报 too many clients,或 api 在负载下于自己池后排队时 直接读环境变量,仅接受纯数字串:10.5、1e3、+5 都直接令池创建失败,而空串/纯空白回退默认值。每个副本都开这么多连接,因此服务端上限=本值×副本数。池耗尽不再挂起:等待超过 packages/db/src/pool.ts 中 5 秒时限的 checkout 失败,请求以 503 SERVICE_UNAVAILABLE 应答并打出含路径的 db_pool_checkout_timeout warn——所以只有看到该日志名时才应调大此值。其姊妹指标 db_connect_timeout 是同 5 秒时限耗在新连接握手上的表现,意味着池尚有空间,加连接只会把更多并发尝试指向一个已应答失败的服务器
WORKER_DB_POOL_MAX worker 进程最多打开的 Postgres 连接数 正整数 25——硬编码,无 zod schema 原因同 api 池。worker 默认更大因为 tick 作业并发执行 与 TICK_CONCURRENCY 挂钩:设得比它小会让 tick 在连接 checkout 处串行化,而非受你配置的并发上限约束。解析规则同 api
ADMIN_DB_POOL_MAX 迁移与维护池最多打开的连接数 正整数 2——硬编码,无 zod schema 几乎不需要。此池跑迁移与管理任务,天然串行 刻意设小,避免维护任务饿死交易池。这里无并行,调大毫无收益。解析规则同上

源码侧印证:packages/db/src/pool.ts 是这三者的唯一实现:DEFAULT_MAX 定义 api:10 / worker:25 / admin:2;envMaxFor 用 /^\d+$/ 整体数字串校验(注释指出 Number.parseInt 会把 1e3 读成 1、10abc 读成 10——静默缩小池,所以宁可启动失败);POOL_CHECKOUT_TIMEOUT_MS = 5_000 是常量而非环境变量("能设置它的操作者也能设出重新引入挂死的值");poolCheckoutTimeoutKind 精确匹配 pg-pool 两种超时消息并区分 queue-wait(容量问题,加连接有帮助)与 cold-connect(握手问题,加连接更糟)。

留存(以天计的清理窗口)

变量 作用 取值 默认值 何时设置 预期效果
DISCOVERY_SNAPSHOT_RETENTION_DAYS 自动发现(discovery)universe 快照保留时长 正整数 180 在运行 discovery net-edge 回测(需要长序列)前调大 刻意慷慨,此序列本就要积累。窗口太短会使其失去意义且无法回填
EQUITY_SNAPSHOT_RETENTION_DAYS 盈利对比持有(profit-vs-hold)图表背后的每个 profile 权益序列保留时长 正整数 365 想保留多年权益曲线时调大 每个 profile 每天约 96 行,存储成本适中。裁剪会永久缩短图表

源码侧印证:worker schema(apps/worker/src/env.ts)以 z.coerce.number().int().positive().default(180 / 365) 解析,字段注释说明了各自对应的裁剪 cron(discovery-snapshot-prune 按 captured_at < now - retention 删除)与"权益快照每 15 分钟一点、约 96 行/天"的数据量来源。注意 .env.example 明确提醒:操作日志与审计日志的留存不是环境变量,它们位于 retention_config 表中、在 Settings → Retention 编辑——历史上正是因为同一窗口存在两个所有者,表被清空的时间比仪表盘报告的早了好几天。

Worker 调优

变量 作用 取值 默认值 何时设置 预期效果
BACKTEST_CONCURRENCY 可同时运行的回测回放数 正整数 1 在专用回测机上调大;与实盘共享内核时保持 1–2 回放是 CPU 密集型的,共享机上调大会给仪表盘与交易循环增加尾延迟。.env.example 为专用 study 机出厂 4
STUDY_CPU_SHARE 一次回测回放可消耗的内核份额 (0, 1] 内的数 required——启动时解析:ROLE=all 下为 0.5,否则 1.0 当回测与实盘共享进程时权衡回测速度与实时响应 未设置时按角色自动取 0.5/1.0,默认行为已正确。runner 在 yield 点按份额休眠,值越小回测按比例越慢
TICK_CONCURRENCY 每符号 tick 作业的最大并发数 正整数 25 ROLE=all 下多符号活跃、仪表盘感觉卡顿时调低 无论取值如何,(profile, symbol) 级排序都强制生效,调低只降吞吐、绝不损害正确性
KLINE_CONCURRENCY technicals 作业每个周期并发抓取 Binance K 线的数量 正整数 8 技术评级计算独占事件循环、或想降低突发请求权重时调低 每个抓取到的符号随后执行同步指标运算,此值约束堆叠的突发数量
TICK_PERSIST_TIMEOUT_MS 持久化逐 tick 策略状态写入的时间预算 正整数,毫秒 100 在网络复制存储上(提交是跨节点往返)调大 超时后 tick 回退到降级缓存路径——安全但理应罕见。在慢存储上设太小会让降级路径成为常态。默认适配本地 SSD
WORKER_FRAME_TRACE 将实盘 tick 输入与决策记录为 JSONL 以支持确定性回放 1 开启,其他值关闭 off(由 frame-recorder 工厂直读,未设置即关) 仅在诊断回放漂移时开启,随后关闭并保护/删除 trace 每个完成的策略 tick 追加余额、持仓、输入与决策。trace 含财务状态,严禁提交到仓库
WORKER_FRAME_TRACE_FILE 可选 worker frame trace 的输出路径 可写文件路径 未设置时由 tmpdir() 在运行时解析为操作系统临时目录下的 worker-frame-trace.jsonl 默认临时路径不适合短时诊断采集时 仅 WORKER_FRAME_TRACE=1 时使用。写失败会报告但不中断交易 tick
WORKER_REPLICAS scale compose 文件中实时 worker 的副本数 正整数 1(仅 Compose) 保持 1。多副本扩展已合并但处于休眠态 Compose 将其插值进服务副本数;应用代码从不读取。现在调大会运行未经测试的并发路径

源码侧印证:resolveStudyCpuShare 在 apps/worker/src/env.ts 中实现——override ?? (role === 'all' ? 0.5 : 1),与文档所述"未设置按角色解析"完全一致;TICK_CONCURRENCY 默认 25、KLINE_CONCURRENCY 默认 8、TICK_PERSIST_TIMEOUT_MS 默认 100 均在该文件 schema 中(.env.example 的注释还给出了 KLINE 估算依据:每个符号约 7.6ms 同步指标运算)。

可观测性(OpenTelemetry)

变量 作用 取值 默认值 何时设置 预期效果
OTEL_SERVICE_NAME 导出 trace 上盖章的服务名 任意字符串 binance-trading-bot(仅 Compose) 导出 trace 且运行多实例时 未设置下面的 OTLP 端点时被忽略
OTEL_EXPORTER_OTLP_ENDPOINT OTLP collector 端点;设置它即启用 trace 导出 collector URL required(仅 Compose;空值禁用导出器) 有 collector 可发送时 默认空,导出器关闭,遥测不出机器
OTEL_EXPORTER_OTLP_HEADERS 附加到 OTLP 导出请求的额外头 key=value 对 required(仅 Compose;默认空) 你的 collector 需要认证时 视同凭据对待——通常携带 token。目录中分类为 secret
OTEL_EXPORTER_OTLP_TIMEOUT 单次 OTLP trace 导出请求的超时 毫秒 3000——导出启用时由 OpenTelemetry bootstrap 直接读取 仅在可达 collector 常规需要 3 秒以上时调大 超时的导出计为丢弃的 span 批次。交易工作继续,不等待遥测
DEPLOY_ENV 附加到导出 trace 的部署环境 环境名,如 development、staging、production development——直接读取;未设置回退 NODE_ENV,再回退 development 部署名需要与 NODE_ENV 区分时 production 启用采样 trace;其他值保持常开的开发采样器(除非代码显式提供环境)

构建与部署

变量 作用 取值 默认值 何时设置 预期效果
IMAGE_TAG Docker Compose 拉取的镜像标签 Docker tag latest(仅 Compose) 想固定某个发行版而非跟随移动的 latest 默认随每次发布移动,未钉住时下次 pull 部署可能悄然变化
BACKUP_DIR 定时备份写入 dump 文件的目录 绝对路径 /backups 想写到内置卷之外的地方时 备份任务缺目录时自动创建,备份界面列出其中内容。指向容器卷之外时,dump 不会在容器重建后存活
GIT_SHA 打进镜像的构建提交号,展示于状态端点 git commit sha "" 绝不要手改——Docker 构建注入 本地构建为空,启动回退到本地 git 提交或 unknown。状态栏靠它发现 api/worker 版本错位
WEB_DIST_DIR api 服务的已构建 Web 应用目录 目录路径 apps/web/dist 绝不要手改——容器镜像设置 目录缺失时 api 完全不提供 Web 应用;开发期(Vite 服务)与 CDN 之后的 api 均属正常

生产部署的工作流细节(含 deploy/secrets/* 三个密钥文件、.env 修补命令与 TLS 边缘配置)见 部署运维文档:生产 overlay 让内置 Postgres/Redis 直接从 deploy/secrets/* 读取密码,api 所需的 AUTH_SECRET 与带密码的 REDIS_URL 则需从密钥文件镜像进 .env,参见 docker-compose.prod.yml。

Web 构建(仅构建期)

变量 作用 取值 默认值 何时设置 预期效果
VITE_API_BASE_URL Web 应用调用的基础 URL URL 路径或绝对 URL /api(仅构建期) 仅当 API 挂在不同基础路径下时 构建期打进 bundle。构建后修改无效——必须重新构建
VITE_PWA 将应用构建为可安装的渐进式 Web 应用 0 或 1 0(仅构建期) 想把仪表盘装到手机主屏时 仅构建期。开启会增加 service worker,缓存激进——部署后预期要硬刷新

这两者由 Vite 在 bun run build / compose build 时盖章进 bundle(.env.example 明确注明"构建后修改无效果"),因此目录标记为 parsed: false 的 build 类条目。

实战配置建议

综合以上表格与源码,落地配置时有几条高频经验:

  • 本地开发:bun run setup(scripts/setup.ts)会自动把 .env.example 复制为 .env,其中 DATABASE_URL/REDIS_URL 指向本地 compose 映射出的 5 前缀端口(55432/56379),WEB_ORIGIN 默认 http://localhost:5173(Vite 开发服务器端口),bun run dev 会自动拉起 ROLE=worker 与 ROLE=study 两个进程并各自绑定管理端口。
  • Compose 部署:删除 .env 中的 DATABASE_URL/REDIS_URL 行即可回落到 docker-compose.yml 内置的网络内默认值(postgres://postgres:postgres@postgres:5432/binance_trading_bot、redis://redis:6379);APP_HTTP_PORT 决定对外发布端口。
  • 生产安全基线:AUTH_SECRET 用 openssl rand -hex 32 生成且每实例独立;POSTGRES_PASSWORD 在首启前改掉;WEB_ORIGIN 永远精确匹配、禁 *;ADMIN_HOST/WORKER_ADMIN_HOST 保持 loopback;开放时配 NetworkPolicy。
  • 性能调优"只看证据":调大 API_DB_POOL_MAX 的唯一正当理由是对应日志名 db_pool_checkout_timeout(503 响应);BACKTEST_CONCURRENCY 在共享机上保持 1–2;TICK_PERSIST_TIMEOUT_MS 只在网络复制存储上提高。
  • AI 集成与演示:MCP 控制面(MCP_ENABLED + MCP_RESOURCE_URL)与 LIVE_DEMO 互斥,两者都开启会在启动时被拒;公共演示机还必须确保没有任何连接真实 Binance 的账户。

整个环境变量体系的设计哲学可以用一句话概括:文档由目录生成、目录被 schema 钉死、schema 被测试断言、读取点被 CI 静态扫描——于是"这份表格声称的默认值"与"进程实际解析出的默认值"在任意时刻都严格相等,缺失必填项在启动第一毫秒就失败,而不是以难以察觉的错误状态运行。

登录后查看全文
binance-trading-bot