binance-trading-bot 环境变量完全指南:从 `.env` 配置到源码级校验机制
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),相关行中会明确标注。
默认值一致性如何被源码保证
本项目的环境变量文档与真实解析行为之间有一套完整的"防漂移"机制,这是理解下表可信度的关键:
- 单一事实来源:ENV_CATALOGUE 拥有全部说明性文案(
description/when/expect为必填字段,生成器会拒绝输出空说明的条目),而 Zod schema 拥有真实的解析默认值(api 在 apps/api/src/env.ts,worker 在 apps/worker/src/env.ts)。 - 测试钉死:每个应用都有 env-docs 测试(参见 worker 侧测试、api 侧对应测试),用空环境走真实 schema 解析,逐一断言文档中声明的默认值与 schema 实际产出一致。凡是文档默认值与 schema 默认值存在合理差异的条目(例如布尔开关
LIVE_DEMO文档写off、schema 解析出false),必须声明defParsed让断言依然落到真实值上;文档标记为required的变量,测试会逐个删掉它再断言启动解析抛错。 - 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 静态扫描——于是"这份表格声称的默认值"与"进程实际解析出的默认值"在任意时刻都严格相等,缺失必填项在启动第一毫秒就失败,而不是以难以察觉的错误状态运行。