这页不只是环境变量清单，而是帮你先决定三件事：
| 关注点 | 关键变量 | 默认值 | 什么时候该改 |
|---|---|---|---|
| 应用监听地址 | HTTP_BIND |
本地默认 127.0.0.1:8080；运行镜像默认 0.0.0.0:8080 |
本地开发、容器部署或反向代理拓扑不同时 |
| 数据库存放位置 | DATABASE_PATH |
codex_vibe_monitor.db |
想把 SQLite 和归档放到持久化卷时 |
| 上游代理目标 | OPENAI_UPSTREAM_BASE_URL |
OpenAI 官方默认地址 | 你接的是自建兼容上游或其他转发层时 |
| 账号池写能力 | UPSTREAM_ACCOUNTS_ENCRYPTION_SECRET |
无 | 只要你要新增账号、改账号或用 OAuth 登录，就必须配置 |
| 数据保留与归档 | RETENTION_ENABLED、ARCHIVE_DIR、各类 retention 天数 |
默认偏保守、默认不开启后台维护 | 想长期运行并控制主库体积时 |
如果你只是先把服务跑起来，通常先确认上表这 4 到 5 项就够了。
HTTP_BIND、DATABASE_PATH 基本就会先决定。OPENAI_UPSTREAM_BASE_URL。UPSTREAM_ACCOUNTS_ENCRYPTION_SECRET。RETENTION_ENABLED、ARCHIVE_DIR 和各类 retention 窗口。UPSTREAM_ACCOUNTS_ENCRYPTION_SECRET：启用号池写入与加密落库的必填密钥UPSTREAM_ACCOUNTS_OAUTH_CLIENT_IDUPSTREAM_ACCOUNTS_OAUTH_ISSUERUPSTREAM_ACCOUNTS_USAGE_BASE_URLUPSTREAM_ACCOUNTS_LOGIN_SESSION_TTL_SECSUPSTREAM_ACCOUNTS_SYNC_INTERVAL_SECSUPSTREAM_ACCOUNTS_REFRESH_LEAD_TIME_SECSUPSTREAM_ACCOUNTS_HISTORY_RETENTION_DAYS如果你不打算启用 Account Pool 的写入能力，这一组可以后置。
如果你准备让 OAuth 账号真正上线，不要把这组变量拖到最后才补。
RETENTION_ENABLEDRETENTION_DRY_RUNRETENTION_INTERVAL_SECSRETENTION_BATCH_ROWSARCHIVE_DIRINVOCATION_SUCCESS_FULL_DAYSINVOCATION_MAX_DAYSFORWARD_PROXY_ATTEMPTS_RETENTION_DAYSSTATS_SOURCE_SNAPSHOTS_RETENTION_DAYSQUOTA_SNAPSHOT_FULL_DAYS这些参数控制在线明细、离线 archive 与后台 maintenance 行为。
如果你希望数据库体积可控、raw 文件不无限增长、归档路径能备份，就不要只停在“默认值也能跑”这个阶段。
OPENAI_UPSTREAM_BASE_URL：OpenAI 兼容上游基址REQUEST_TIMEOUT_SECS：通用请求超时OPENAI_PROXY_HANDSHAKE_TIMEOUT_SECS：非 compact 路径的上游握手超时OPENAI_PROXY_COMPACT_HANDSHAKE_TIMEOUT_SECS：/v1/responses/compact 上游握手超时OPENAI_PROXY_IMAGE_HANDSHAKE_TIMEOUT_SECS：/v1/images/generations 与 /v1/images/edits 等待上游首字节的默认超时，默认 300 秒；运行时可由四层 timeout 策略覆盖OPENAI_PROXY_REQUEST_READ_TIMEOUT_SECS：请求体读取总超时OPENAI_PROXY_ENCRYPTED_SESSION_OWNER_ROUTING_ENABLED：加密对话路由绑定的首次初始化默认值；默认关闭，只有数据库里该设置还没初始化时才会吃 envOPENAI_PROXY_MAX_REQUEST_BODY_BYTES：请求体最大尺寸限制PROXY_RAW_DIR / PROXY_RAW_MAX_BYTES / PROXY_RAW_COMPRESSION / PROXY_RAW_HOT_SECS：原始 payload 落盘、热保留与冷压缩策略PROXY_ENFORCE_STREAM_INCLUDE_USAGE：是否在流式请求中强制补 include_usagePROXY_USAGE_BACKFILL_ON_STARTUP：历史补数兼容开关FORWARD_PROXY_ALGO：forward proxy 权重算法版本VITE_BACKEND_PROXY：前端开发服务器代理目标，默认 http://localhost:8080VITE_APP_RUNTIME：应用运行时，值只能是 live 或 demo；demo 只使用浏览器内存与 MSW mock，不回退到真实 APIVITE_DEPLOY_BASE：静态资源与 MSW worker 的部署基路径；GitHub Pages demo 使用 ${DOCS_BASE}demo/VITE_APP_PORT：Vite app/demo 的监听端口；demo 默认 60083，实际开发应使用 worktree 租约端口DOCS_PORT：docs-site 本地 dev/preview 端口，默认 60081DOCS_BASE：静态站部署基路径；GitHub Pages 项目页通常使用 /<repo>/VITE_STORYBOOK_DEV_ORIGIN：docs-site 本地 storybook.html 跳转到 Storybook dev server 时使用的完整 origin；默认 http://127.0.0.1:60082STORYBOOK_PORT：Storybook 本地开发端口，默认 600826008060083（开发时使用租约端口覆盖）60081600828080这些端口都允许通过 env 或命令行覆盖，但文档、脚本与 CI 默认按以上合同组织。
本地运行时建议把个人配置写入 .env.local。服务启动会以仓库根目录下的当前环境变量与 .env.local 为准。